Create Custom Authentication Providers using JavaScript

Create Custom Authentication Providers using JavaScript
lac31
The custom authentication provider is a plug-in JavaScript module that API Server 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. Custom authentication providers apply to application security. You can also create admin auth providers for admin security.
For more information about how to create admin auth providers for admin security, see Admin Authentication Providers.
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 authentication provider using JavaScript:
  1. Create the custom authentication provider (the piece of JavaScript code) in compliance with the JavaScript code conventions.
In this article:
 
2
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 
getConfigInfo
configure
getLoginInfo
, and 
authenticate
 functions, each with a specific name and behavior.
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
}
};
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'
}
]
};
}
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 the 
getLoginInfo
 function, but you should not depend on that.
The authenticate Function
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: "[email protected]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 your 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. Under the Create menu, click 
    API Properties
    Libraries.
    The Your libraries tab appears by default.
  3. Click 
    Create New Library
    .
    The Logic library window opens.
  4. Upload the custom JavaScript authentication provider you created and click 
    Save
    .
    The authentication provider is loaded into your API as a library. 
  5. Select the 
    Used
     checkbox for the library, and then 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.
  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 Define a Custom Hello World Authentication Provider using JavaScript.
Next Steps
Now that you have created your custom authentication provider, you can specify this authentication provider as your authentication provider for your API.
For more information about how to choose your authentication provider for your API, see API Properties.