Define Custom Authentication Providers using JavaScript

You can define your own custom authentication provider and specify it for your API instead of using the built-in authentication provider.
calac41
You can define your own custom authentication provider and specify it for your API instead of using the built-in authentication provider. The authentication provider can authorize users using existing security data from a third-party authentication provider, such as StormPath, Lightweight Directory Access Protocol (LDAP), Microsoft Azure Active Directory (AD), OAuth, a SQL database, or any other authentication mechanism, provided that an authentication provider exists or that you write one for it.
A custom authentication provider is a plug-in JavaScript module that you include in a JavaScript library and add to API Server. API Server calls this library when it authenticates API users using the 
@authentication
 RESTful endpoint. API Server is passed the credentials (for example, user and login) and returns the list of roles it uses for authorization.
For more information:
Use the following process to define your own custom authentication provider using JavaScript:
 
3
Define the Code for your Custom Authentication Provider
Define your custom authentication provider (the piece of JavaScript code) in compliance with the JavaScript code conventions. Identity management requires that the custom authentication provider (the JavaScript code) follow a specific pattern and return specific properties. Your 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
}
};
Given this, the following image shows the details of the authentication provider in API Creator:
  CA Technologies  
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 API user is authenticated. The argument passed in contains whatever values were provided to the 
@authentication
 RESTful endpoint. 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
};
}
Add your Custom Authentication Provider to your TeamSpace
You register your authentication provider by adding a new authentication provider to your TeamSpace.
Follow these steps:
 
  1. In API Creator, from the Your Libraries page, click 
    APIs
    .
    The APIs page appears.
  2. Click the 
    Auth Providers
     tab.
    The Authentication Providers page appears.
  3. Above the list of authentication providers, click 
    Add
    .
    The 
    New Provider
     authentication provider is created. 
  4. Complete the following fields, and then save your changes:
    Name
     
    Enter a name for your custom authentication provider. 
    Authentication Method
     
    Select 
    JavaScript Auth Provider
     as the authentication method. The page refreshes.
    Name for Create Function
     
    Enter a name for your create function.
    Example: 
     
    myAuthProvider
     
    Comments
     
    Enter a comment for your custom authentication provider.
    Optional:
     Yes
Your custom authentication provider is added to your TeamSpace.
Add your Custom Authentication Provider to your API
Add the plug-in JavaScript module (the JavaScript file) that contains your custom authentication provider as a JavaScript library to your API and mark it as used.
Follow these steps:
 
  1. Log in to API Creator and open your API.
  2. In the Create section, click 
    API Properties
    .
    The Details tab displays by default.
  3. Click the 
    Libraries
     tab.
    The Your libraries tab appears by default.
  4. Click 
    Create New Library
    .
    The Logic library window opens.
  5. Upload the custom JavaScript library that you created into your API, and then save your changes.
    The authentication provider is loaded into your API as a library.
  6. Select the 
    Used
     checkbox for the library, and then save your changes.
The JavaScript library that contains your custom authentication provider is added to API Server.
(Optional) 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 how to debug authentication providers, see Debug.
Specify the Custom Authentication Provider as the Authentication Provider for your API
When you define the code for your custom authentication provider, add it to your TeamSpace, add JavaScript library that contains the authentication provider to your API, and then specify it as the authentication provider for your API, the API users that you define in API Creator are not used.
Follow these steps:
 
  1. From the Authentication Providers page, click 
    APIs
    .
    The APIs page appears.
  2. Open the API for which you want to specify the authentication provider.
    The API Properties page appears.
  3. Select the custom authentication provider that you want to define for your API from the 
    Authentication provider
     drop-down, and then save your changes.
    By default, the built-in authentication provider is selected.
    For more information about the fields on this tab, see API Properties.
The custom authentication provider is specified as the authentication provider for your API.
Next Steps
Now that you have created your custom authentication provider, you can do the following:
  • Use this custom authentication provider by calling the 
    @authentication
     resource endpoint.
    An easy way to test this service is using the command line.
    For more information about this resource endpoint, see System REST Endpoints.
  • Use this custom authentication providers for the CA Live API Creator Admin project API (Admin API).