Authentication

Components that require authentication from the user must implement an authentication module for the service/module they belong to. The authentication module must be named auth.js and must be stored under either the service or module directory (i.e. [vendor]/[service]/auth.js or [vendor/[service]/[module]/auth.js. Appmixer currently supports three types of authentication mechanisms that are common for today's APIs: API key, OAuth 1 and OAuth 2.

Appmixer provides an easy way to configure authentication modules. Most of the time, it's just about configuring a 3rd party service provider URLs for authentication, requesting access tokens and token validation.

Authentication Module Structure

Each authentication module is a NodeJS module that returns an object with type and definition properties. type can be either apiKey, oauth (for OAuth 1) and oauth2 (for OAuth 2). definition is either an object or a function (useful in cases where there's a code that you need to run dynamically).

type

The type of the authentication mechanism. Any of apiKey, oauth and oauth2.

definition

The definition of the authentication mechanism specific to the API service provider. An object or a function. This differs significantly between authentication mechanisms.

If the definition property is specified as a function, it that case it has one argument context. It is an object that contains either consumerKey, consumerSecret (OAuth 1) or clientId, clientSecret (OAuth 2) and it always contains callbackUrl property. This will be shown later in the examples.

Authentication mechanisms

As it was mentioned in the beginning, Appmixer authentication supports three mechanisms: API Key, OAuth 1 and OAuth 2. Each of them has a different definition.

function, object or a URL string

In the following examples we will show how a particular property of the definition object can be specified as a function, object or string. Let's demonstrate that on a requestProfileInfo property, that one is common for all authentication mechanisms.

// or any library you want to perform API requests
const request = require('request-promise');

module.exports = {

    // there will be some other properties based on authenication mechanism
    // defined prior requestProfileInfo
    
    definition: {
    
        // requestProfileInfo can be defined as a function. In this case, you
        // can do whatever you need in here and return object with user's
        // profile information (in promise)
        requestProfileInfo: async context => {
    
            // curl https://mydomain.freshdesk.com/api/v2/agents/me \
            //  -u myApiKey:X'
            return request({
                method: 'GET',
                url: `https://${context.domain}.acme.com/api/v2/agents/me`,
                auth: {
                    user: context.apiKey  // 'context' will be explained later
                },
                json: true
            });
        },
        
        // or you can specify it as an object. In this case, the object follows
        // the 'request' javascript library options.
        requestProfileInfo: {
            method: 'GET',
            url: 'https://acme.com/get-some-records/app_id={{appId}}',
            headers: {
                'Authorization': 'Basic {{apiKey}}'  // {{apiKey}} explained later
            }
        },
        
        // the last way is to specify just the URI. In this case Appmixer
        // will perform GET request to that URI.
        requestProfileInfo: 'https://acme.com/get-profile-info?apiKey={{apiKey}}'    
    }
}

API key

This is the most basic type of third party authentication, since you only need to provide a sort of ID and a key provided by the app in concern. In order to use this mechanism, type property must be set to apiKey. Here is an example from Freshdesk components:

module.exports = {

    type: 'apiKey',

    definition: {

        tokenType: 'authentication-token',

        auth: {
            domain: {
                type: 'text',
                name: 'Domain',
                tooltip: 'Your Freshdesk subdomain - e.g. if the domain is <i>https://example.freshdesk.com</i> just type <b>example</b> inside this field'
            },
            apiKey: {
                type: 'text',
                name: 'API Key',
                tooltip: 'Log into your Freshdesk account and find <i>Your API Key</i> in Profile settings page.'
            }
        },

        accountNameFromProfileInfo: 'contact.email',

        requestProfileInfo: async context => {

            // curl https://mydomain.freshdesk.com/api/v2/agents/me \
            //  -u myApiKey:X'
            return request({
                method: 'GET',
                url: `https://${context.domain}.freshdesk.com/api/v2/agents/me`,
                auth: {
                    user: context.apiKey,
                    password: 'X'
                },
                json: true
            });
        },

        validate: async context => {

            // curl https://mydomain.freshdesk.com/api/v2/agents/me \
            //  -u myApiKey:X'
            const credentials = `${context.apiKey}:X`;
            const encoded = (new Buffer(credentials)).toString('base64');
            await request({
                method: 'GET',
                url: `https://${context.domain}.freshdesk.com/api/v2/agents/me`,
                headers: {
                    'Authorization': `Basic ${encoded}`
                }
            });
            // if the request doesn't fail, return true (exception will be captured in caller)
            return true;
        }
    }
};

Now we explain the fields inside the definition object:

auth (object)

This is basically the definition for the form that will be displayed to the user to collect the data required by the third party application. Freshdesk requires the domain name and the API key in order to authenticate Appmixer. So we define two fields representing those items and we define the label and tooltip that will appear in the form for each field. In this case, the auth definition will make Appmixer to render a form like this:

Authentication form for Freshdesk, defined by auth object

The values introduced by the user will be exposed in the context object with the same keys as in the auth object. In this case we will be able to access the values as context.domain and context.apiKey.

requestProfileInfo (function, object or string) (optional)

While this field is optional, is recommended for a better UX. This field can be a function which returns a promise, object or a string. It is about calling an endpoint from the third party app which returns the current user info. This will be used to display a name for this account in Appmixer.

accountNameFromProfileInfo (function or string)

This field is the path in the object returned by requestProfileInfo that points to the value that will be used as account name. Following the example, the object returned by requestProfileInfo would have an structure like this:

{
    contact: {
        email: '[e-mail]',
        name: 'Appmixer example',
        // More properties here...
    }
    // There can be more properties here as well...
}

We want to use the email to identify the Freshdesk accounts in Apmmixer, so we set accountNameFromProfileInfo as contact.email.

If requestProfileInfo is not defined, the auth object will be used instead. The account name will be the resolved value for the property specified by accountNameFromProfileInfo.

validate (function, object or string)

Similar to requestProfileInfo. This is used to validate if the authentication data entered by the user is correct. For this purpose you can call any endpoint that requires authentication, you can even use the same endpoint as requestProfileInfo. If the data is correct, this function should resolve to any non-false value. Otherwise throw an error or resolve to false. You can define validate as an object. In that case, that object has the same structure as object passed into request library. In that case it will look like this:

'use strict';

module.exports = {

    type: 'apiKey',

    definition: {

        tokenType: 'apiKey',

        accountNameFromProfileInfo: 'appId',

        auth: {
            appId: {
                type: 'text',
                name: ' APP ID',
                tooltip: 'Log into your account and find Api key.'
            },
            apiKey: {
                type: 'text',
                name: 'REST API Key',
                tooltip: 'Found directly next to your App ID.'
            }
        },

        // In the validate request we neet the appId and apiKey specified by user.
        // All properties defined in the previous 'auth' object will be
        // available in the validate call. Just use {{whatever-key-from-auth-object}}
        // anywhere in the next object. Appmixer will replace these with the
        // correct values.
        validate: {
            method: 'GET',
            url: 'https://acme.com/get-some-records/app_id={{appId}}',
            headers: {
                'Authorization': 'Basic {{apiKey}}'
            }
        }
    }
};

HTTP Basic Authentication

The apiKey type can be used for the HTTP Basic Authentication. Here's a sample code:

'use strict';
const axios = require('axios');

module.exports = {

    type: 'apiKey',

    definition: {

        auth: {
            username: {
                type: 'text',
                name: 'Username',
                tooltip: 'Username'
            },
            password: {
                type: 'password',
                name: 'Password',
                tooltip: 'Password'
            }
        },

        accountNameFromProfileInfo: 'username',

        validate: async context => {

            await axios.get('https://postman-echo.com/basic-auth', {
                auth: {
                    username: context.username,
                    password: context.password
                }
            });
        }
    }
}

Then the username and password is available in the components:

'use strict';
const axios = require('axios');

module.exports = {

    async start(context) {

        await axios.get('https://postman-echo.com/basic-auth', {
            auth: {
                username: context.auth.username,
                password: context.auth.password
            }
        });
    }
}

OAuth 1

In order to use this mechanism, type property must be set to oauth. Here is an example from Trello components:

'use strict';
const OAuth = require('oauth').OAuth;
const Promise = require('bluebird');

module.exports = {

    type: 'oauth',

    // In this example, 'definition' property is defined as a function. 
    definition: context => {

        let trelloOauth = Promise.promisifyAll(new OAuth(
            'https://trello.com/1/OAuthGetRequestToken',
            'https://trello.com/1/OAuthGetAccessToken',
            context.consumerKey,
            context.consumerSecret,
            '1.0',
            context.callbackUrl,
            'HMAC-SHA1'
        ), { multiArgs: true });

        return {

            accountNameFromProfileInfo: 'id',

            authUrl: context => {

                return 'https://trello.com/1/OAuthAuthorizeToken' +
                    '?oauth_token=' + context.requestToken +
                    '&name=AppMixer' +
                    '&scope=read,write,account' +
                    '&expiration=never';
            },

            requestRequestToken: () => {

                return trelloOauth.getOAuthRequestTokenAsync()
                    .then(result => {
                        return {
                            requestToken: result[0],
                            requestTokenSecret: result[1]
                        };
                    });
            },

            requestAccessToken: context => {

                return trelloOauth.getOAuthAccessTokenAsync(
                    context.requestToken,
                    context.requestTokenSecret,
                    context.oauthVerifier
                ).then(result => {
                    return {
                        accessToken: result[0],
                        accessTokenSecret: result[1]
                    };
                });
            },

            requestProfileInfo: context => {

                return trelloOauth.getProtectedResourceAsync(
                    'https://api.trello.com/1/members/me',
                    'GET',
                    context.accessToken,
                    context.accessTokenSecret
                ).then(result => {
                    if (result[1].statusCode !== 200) {
                        throw new Error(result[1].statusMessage);
                    }
                    result = JSON.parse(result[0]);
                    // get rid of limits for now
                    // may and will contain keys with dots - mongo doesn't like it
                    delete result.limits;
                    return result;
                });
            },

            validateAccessToken: context => {

                return trelloOauth.getProtectedResourceAsync(
                    'https://api.trello.com/1/tokens/' + context.accessToken,
                    'GET',
                    context.accessToken,
                    context.accessTokenSecret
                ).then(result => {
                    if (result[1].statusCode === 401) {
                        throw new context.InvalidTokenError(result[1].statusMessage);
                    }
                    if (result[1].statusCode !== 200) {
                        throw new Error(result[1].statusMessage);
                    }

                    result = JSON.parse(result[0]);
                    if (result['dateExpires'] === null) {
                        return;
                    }
                    throw new context.InvalidTokenError('Invalid token.');
                });
            }
        };
    }
};

Note that in this case the definition is a function instead of an object, but it still returns an object with the items needed for OAuth 1 authentication, similar to API key authentication. Now we explain the fields from definition object:

accountNameFromProfileInfo (function or string)

Works exactly the same way as described on API Key section.

requestRequestToken (function, object or string)

This must be a function (or an object, or just a string URL as explained here) that returns a promise which must resolve to an object containing requestToken and requestTokenSecret the same way that is showed on the example. Those are needed to get the access token and become exposed by the context - context.requestToken and context.requestTokenSecret.

requestAccessToken (function, object or string)

This must be a function (or an object, or just a string URL as explained here) that returns a promise which must resolve to an object containing accessToken and accessTokenSecret the same way that is showed on the example. Usually you will be using the requestToken and requestTokenSecret inside this function as they are required by the OAuth 1 flow in this step. Similarly to requestRequestToken function, accessToken and accessTokenSecret will become exposed by the context - context.accessToken and context.accessTokenSecret.

authUrl (function, object or string)

Function, object or a string URL returning auth URL. Appmixer will then use this URL to redirect the user to proper login page. The requestToken is available in the context. The example shows the authUrl declaration using the token provided by the context.

requestProfileInfo (function, object or string) (optional)

Works exactly the same way as described in the API Key section.

validateAccessToken (function or object)

This property serves the same purpose as validate property in the API Key mechanism. This is used by Appmixer to test if the access token is valid and accepted by the third party app. You have access to context.accessToken and context.accessTokenSecret to make authenticated requests. If the token is valid, this function should resolve to any non-false value. Otherwise throw an error or resolve to false.

OAuth 2

The latest OAuth protocol and industry-standard, OAuth 2.0 improved many things from the first version in terms on usability and implementation, while maintaining a high degree of security. It is easier to implement in Appmixer as well. In order to use this mechanism, type property must be set to oauth2. Here is an example from Asana auth.js:

'use strict';
const request = require('request-promise');

module.exports = {

    type: 'oauth2',

    // function definition is used in this case because of the 'profileInfo'
    // property. It is set in the 'requestAccessToken' function and then
    // later returned in 'requestProfileInfo' function.
    definition: () => {

        let profileInfo;

        return {

            accountNameFromProfileInfo: context => {

                return context.profileInfo['email'] || context.profileInfo['id'].toString();
            },

            authUrl: 'https://app.asana.com/-/oauth_authorize',

            requestAccessToken: context => {

                // don't put params into post body, won't work, have to be in query
                let tokenUrl = 'https://app.asana.com/-/oauth_token?' +
                    'grant_type=authorization_code&code=' + context.authorizationCode +
                    '&redirect_uri=' + context.callbackUrl +
                    '&client_id=' + context.clientId +
                    '&client_secret=' + context.clientSecret;

                return request({
                    method: 'POST',
                    url: tokenUrl,
                    json: true
                }).then(result => {
                    profileInfo = result['data'];
                    let newDate = new Date();
                    newDate.setTime(newDate.getTime() + (result['expires_in'] * 1000));
                    return {
                        accessToken: result['access_token'],
                        refreshToken: result['refresh_token'],
                        accessTokenExpDate: newDate
                    };
                });
            },

            requestProfileInfo: () => {

                return profileInfo;
            },

            refreshAccessToken: context => {

                // don't put params into post body, won't work, have to be in query
                let tokenUrl = 'https://app.asana.com/-/oauth_token?' +
                    'grant_type=refresh_token&refresh_token=' + context.refreshToken +
                    '&redirect_uri=' + context.callbackUrl +
                    '&client_id=' + context.clientId +
                    '&client_secret=' + context.clientSecret;

                return request({
                    method: 'POST',
                    url: tokenUrl,
                    json: true
                }).then(result => {
                    profileInfo = result['data'];
                    let newDate = new Date();
                    newDate.setTime(newDate.getTime() + (result['expires_in'] * 1000));
                    return {
                        accessToken: result['access_token'],
                        accessTokenExpDate: newDate
                    };
                });
            },

            validateAccessToken: {
                method: 'GET',
                url: 'https://app.asana.com/api/1.0/users/me',
                auth: {
                    bearer: '{{accessToken}}'
                }
            }
        };
    }
};

Notice that there is no requestRequestToken method in OAuth 2, but we there is the requestAccessToken used to get the token and refreshAccessToken method, which is used by Appmixer to refresh the access tokens. Now we explain the definition object properties:

accountNameFromProfileInfo (function or string)

Works exactly the same way as described in the API Key section.

authUrl (function, object or string)

Similar to OAuth 1, we should provide the authentication url for the third party app. However, due to the different authentication flows supported by OAuth 2, the way this is defined may vary according to the third party implementation. If the OAuth 2 implementation is standard, you can define the authUrl with just a string like:

authUrl: 'https://www.dropbox.com/oauth2/authorize'

Standard means, there is a response_type parameter set to code, then there is the client_id, redirect_uri, state and scope parameter. If the OAuth 2 implementation requires any other parameters (or the standard ones use different names), then you have to define this property as a function and provide all the additional parameters. The same logic applies to the following property requestAccessToken.

requestAccessToken (function, object or string)

This function should return a promise with an object which contains accessToken, refreshToken (optional, some OAuth 2 implementations do not have refresh tokens) and accessTokenExpDate or expires_in (also options if the implementation does not have tokens that expire). Inside this function we call the endpoint which handles out the access tokens for the application. Inside this function you have access to context properties you need: clientId, clientSecret, callbackUrl and authorizationCode.

requestProfileInfo (function, object or string) (optional)

Works exactly the same way as described in the API Key section.

refreshAccessToken (function, object or string)

Part of the OAuth 2 specification is the ability to refresh short lived tokens via a refresh token that is issued along with the access token. This function should call the refresh token endpoint on the third party app and resolve to an object with accessToken and accessTokenExpDate properties, as shown in the example. You have access to context properties clientId, clientSecret, callbackUrl and refreshToken.

validateAccessToken (function or object)

Has the exact same purpose as the same method in the OAuth 1.

There are more ways the OAuth 2 can be implemented. It always depends on the third party server and its OAuth 2 implementation.

This is an example of Dropbox auth.js module:

'use strict';

module.exports = {

    type: 'oauth2',

    definition: {

        accountNameFromProfileInfo: 'email',

        authUrl: 'https://www.dropbox.com/oauth2/authorize',

        requestAccessToken: 'https://api.dropbox.com/oauth2/token',

        requestProfileInfo: {
            'method': 'POST',
            'uri': 'https://api.dropboxapi.com/2/users/get_current_account',
            'headers': {
                'authorization': 'Bearer {{accessToken}}'
            }
        }
    }
};

It can be that simple, if the third party API implements OAuth 2 according to standards. And in this Dropbox case, their OAuth 2 implementation does not contain refresh tokens.

Sometimes the OAuth 2 needs a scope or a different scope delimiter. Here is a full example of Microsoft authentication module with such features:

'use strict';
const TENANT = 'common';

module.exports = {

    type: 'oauth2',

    definition: {

        scope: ['offline_access', 'user.read'],

        scopeDelimiter: ' ',

        authUrl: `https://login.microsoftonline.com/${TENANT}/oauth2/v2.0/authorize`,

        requestAccessToken: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',

        refreshAccessToken: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',

        accountNameFromProfileInfo: 'displayName',

        emailFromProfileInfo: 'mail',

        requestProfileInfo: 'https://graph.microsoft.com/v1.0/me',

        validateAccessToken: {
            method: 'GET',
            url: 'https://graph.microsoft.com/v1.0/me',
            auth: {
                bearer: '{{accessToken}}'
            }
        }
    }
};

scope

String or an array of strings.

scopeDelimiter

String. The default one is , and you can change it to ' ' for example.

Setting OAuth 1,2 secrets

The OAuth applications need some secrets: consumerKey, consumerSecret (OAuth 1), or clientId, clientSecret (OAuth 2).

You can use the Backoffice to do that. This is the preferable way.

Another way is the credentials.json file which has to be located where your auth.js file is.

credentials.json

Then when you pack and publish your component archive, Appmixer will read the file and store the values into Mongo DB. Later it will use them to create the context object for your auth.js module.