Create Custom Authentication Providers using JavaScript

The custom authentication provider is a plug-in JavaScript module that API Servers calls when a user authenticates using the special endpoint @authenticate. It is passed the credentials (user, login, etc), and returns the list of roles used for authorization.

Note: When you use a custom authentication provider, the users you define in API Creator are not used.

Use the following process to create your own custom JavaScript authentication provider:

  1. Create the custom authentication provider (the piece of JavaScript code) in compliance with the JavaScript code conventions.
  2. Upload the user-defined JavaScript library into your API.
  3. Register your custom authentication provider.
  4. Choose the authentication provider for your API.

Note: This applies to app security. You can also create admin auth providers for admin security. For more information about creating admin auth providers for admin security, see Admin Auth Providers.

JavaScript Code Conventions

Identity management requires that the custom authentication provider (the JavaScript code) follow a specific pattern and return specific properties. The custom authentication provider must return an object containing the following functions, each with a specific name and behavior:
  • getConfigInfo
  • configure
  • getLoginInfo
  • authenticate

The following code snippet shows the general structure of the object:

function myAuthProvider() {
   return {
          getConfigInfo: function() {...},
          configure: function(values) {...},
          getLoginInfo: function() {...},
          authenticate: function(payload) {...}
   };
}

The getConfigInfo Function

API Server calls the getConfigInfo function when it instantiates your authentication provider. API Server must return a description of the parameters needed for configuration, as well as the current value for these parameters.

The format for this object is:

return {
   fields: [
    {
       name: "param1",
       display: "Parameter 1", // The caption for the field in the API Creator
       description: "Blah blah", // Optional: a short description of this parameter
       length: 40, // Optional: maximum length for the value of this parameter
       helpURL: "http://www.acme.com/help1" // Optional: a URL to a page describing this parameter
    },
    {
       name: "param2",
       display: "Parameter 2",
       length: 40,
       helpURL: "http://www.acme.com/help2"
    }
    ],
       current: { // The current (or default) values for the parameters
       param1: valueOfParam1,
       param2: valueOfParam2
    }
};

Given this, the following image shows the details of the authentication provider in API Creator:

The configure Function

API Server calls the following configure function when a user enters a value for the parameters specified by the getConfigInfo function and saves their changes.

configure: function(values) {
    param1value = values.param1;
    param2value = values.param2;
}

The getLoginInfo Function

API Server calls the following getLoginInfo function when a client needs to know what kind of information is required for authentication. The following code snippet describes what the login dialog should look like (assuming the client is an interactive application):

 getLoginInfo: function() {
   return {
     fields: [ // Here we only have one field, but it's common to have e.g. username and password
   {
     name: 'password',
     display: 'Your password',
     description: 'Enter your password. This is case-sensitive.',
     type: 'text',
     length: 30
   },
 ],
// You can optionally include up to two links here, which might describe how
// to reset a password, or how to obtain a login.
links: [
    {
     display: 'Forgot Password?',
     href : 'http://en.wikipedia.org/wiki/Password'
    }
   ]
 };
}

The authenticate Function

API Server calls the following authenticate function when a client is attempting to authenticate. This is the crux of the authentication provider. There is no constraint on exactly how the user is authenticated. The argument passed in contains whatever values were provided to the @authentication service. If the caller is well-behaved, the argument should correspond to the parameters described by getLoginInfo, but you should not depend on that.

The authenticate function must return an object containing just an error message if the authentication failed. If the authentication succeeded, then it must return an object with the following properties:

authenticate: function(payload) {
    // Authenticate user here. Could be using LDAP, a database, a web service, etc...
    // If the client is well-behaved, payload should have the properties described by getLoginInfo
    // This code has access to all the libraries selected for the API.
    if ( ... authentication failed ... )
       return {
           errorMessage: "Authentication failed etc..."
       };
    return {
       errorMessage: null, // Indicates success
       roleNames: ['role1', 'role2'], // This cannot be empty, otherwise the user will have no permissions
       userData: { employeeId: "12345", region: "US-West"}, // Optional: these properties will be attached to the API key
       userInfo: { email: "jdoe@acme.com" }, // Optional: these properties will be returned along with the API key
       keyLifetimeSeconds: 3600, // How long the API should be valid for, 0 for perpetual
       lastLogin: new Date(2013, 11, 31), // Optional: last time user logged in (caution: JS Date has 0-based month)
       lastLoginIP: "12.34.56.78" // Optional : the IP from which the user last logged in
    };
}

Upload the Authentication Provider

Upload the user-defined JavaScript authentication provider as a library into your API and mark it as used.
  1. Log in to API Creator and open your API.
  2. Go to the Create, API Properties, Libraries, Your Libraries tab.
  3. Upload the custom JavaScript authentication provider you created, select the Used checkbox for the library, and save your changes.

Register your Custom JavaScript Authentication Provider

You register your authentication provider by adding a new authentication provider. 
  1. In API Creator, from the Home page, click the Authentication Providers tab. The following image shows this tab:
  2. Click Add.
    A new authentication provider called New Provider is created. 
  3. Complete the following fields and save your changes:
    Authentication Method
    Select JavaScript Auth Provider as the authentication method. The page refreshes. The following image shows the fields on the tab:
    Name for Create Function
    Enter myAuthProvider as the name for create function.
Your custom JavaScript authentication provider is registered.

Debug your Authentication Provider

To ease debugging server-side code, you can debug your authentication provider using API Creator's environment.

For more information about this environment, see the Hello World example.

Next Steps

Now that you have created your custom authentication provider, you can specify this authentication provider for your API.

For more information about choosing your authentication provider, see API Properties.