Authenticate API Users using a JavaScript Authentication Provider

Custom JavaScript authentication providers are plug-in JavaScript modules that you include in JavaScript code and specify as the authentication provider for your API in API Creator. They use existing security data from third-party authentication providers, such as Lightweight Directory Access Protocol (LDAP), Microsoft Azure Active Directory (Azure AD), OAuth, an SQL database. This authentication provider use the JavaScript Auth Provider authentication method.
lac52
Custom JavaScript authentication providers are plug-in JavaScript modules that you include in JavaScript code and specify as the authentication provider for your API in API Creator. They use existing security data from third-party authentication providers, such as Lightweight Directory Access Protocol (LDAP), Microsoft Azure Active Directory (Azure AD), OAuth, an SQL database. This authentication provider use the 
JavaScript Auth Provider
 authentication method.
For more information about how to authenticate API users using a custom LDAP JavaScript authentication provider, see Authenticate API Users using an LDAP Authentication Provider.
Layer7 Live API Creator
 includes authentication provider samples that you can use as a starting point to creating your JavaScript authentication provider, such as the  file.
For more information about the other authentication provider samples, see GitHub.
Specifying an authentication provider that uses the 
JavaScript Auth Provider
 authentication method as the authentication provider for your API can require that you create a database for your authentication tokens. Create a database if 
any
 of the following cases are true:
  • You are not securing your published APIs using API Gateway.
  • You plan to configure 
    Layer7 Live API Creator
     to run as cluster or, if you have configured 
    Layer7 Live API Creator
     to run as a single node, you want to persist your authentication tokens.
For more information:
Use the following process to add, define, and specify a custom JavaScript authentication provider:
 
 
3
 
 
Add your JavaScript Authentication Provider to your TeamSpace
  1. In API Creator, from the APIs page, click the 
    Auth Providers
     tab.
    The Authentication Providers page appears.
  2. Above the list of authentication providers, click 
    Add
    .
    The Add Authentication Provider window opens.
  3. Select 
    JavaScript Auth Provider
     as the authentication method and enter a name for the authentication provider, and then click 
    Add
    .
  4. Click 
    Save
    .
    Your JavaScript authentication provider is created.
  5. On the 
    Details
     tab, enter a name for your create function in the 
    Name for Create Function
     field, and then save your changes. For example, 
    myAuthProvider
     . The authentication provider uses this create function to identify API user login.
  6. Click the 
    Code
     tab.
  7. Select 
    JavaScript
     from the drop-down.
  8. Define the JavaScript code for your JavaScript authentication provider in the code editor, and then click 
    Save
    .
    For more information about how to define the code, see the "Define the Code for your JavaScript Authentication Provider" section.
Your JavaScript authentication provider is added to your TeamSpace.
Define the Code for your JavaScript Authentication Provider
You define the code for your JavaScript authentication provider by adding the JavaScript code that contains the authentication provider. Define the code for the JavaScript authentication provider in compliance with JavaScript code conventions. Identity management requires that the JavaScript authentication provider (the JavaScript code) follow a specific pattern and return specific properties. Your JavaScript authentication provider must return an object that contains the 
getConfigInfo
configure
getLoginInfo
, and 
authenticate
 functions, each with a specific name and behavior.
The following sections detail how to define the code for your authentication provider:
The following code snippet shows the general structure of the object:
function
<the name for your Create function>
() {
return {
getConfigInfo: function() {...},
configure: function(values) {...},
getLoginInfo: function() {...},
authenticate: function(payload) {...}
};
}
Example:
 
function myAuthProvider() {
return {
getConfigInfo: function() {...},
configure: function(values) {...},
getLoginInfo: function() {...},
authenticate: function(payload) {...}
};
}
authenticate Function
If the authentication fails, the 
authenticate
 function must return an object containing only an error message. If the authentication succeeds, then the function must return an object with the following properties:
authenticate: function(payload) {
// Authenticate API 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 the getLoginInfo function
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: Live API Creator attaches these properties to the API key
userInfo: { email: "[email protected]acme.com" }, // Optional: Live API Creator returns these properties 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
};
}
getConfigInfo Function
API Server calls the 
getConfigInfo
 function when it instantiates your authentication provider. API Server must return a description of the parameters that are needed for configuration and 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
}
};
configure Function
API Server calls the following 
configure
 function when a user enters a value for the parameters that the 
getConfigInfo
 function specifies and saves their changes:
configure: function(values) {
param1value = values.param1;
param2value = values.param2;
}
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 shows an example of the login dialog and assumes that 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 authenticate code when a client attempts to authenticate. This is the crux of the authentication provider. The argument that API Server passes in contains the values that the API user provides to the 
@authentication
 resource endpoint. The argument must correspond to the parameters that the 
getLoginInfo
 function describes.
Specify your JavaScript Authentication Provider as the Authentication Provider for your API
  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 Overview page appears.
  3. Click the 
    Details 
    tab. 
  4. Select the JavaScript authentication provider that you added as the authentication provider for your API from the 
    Authentication provider
     drop-down, and then save your changes.
    For more information about the other fields on this tab, see API Properties.
Your JavaScript authentication provider is specified as the authentication provider for your API.
Next Steps
Now that you have created your JavaScript authentication provider, you can do the following:
  • Authenticate API users by calling the 
    @authentication
     resource endpoint.
    For more information about this endpoint, see System REST Endpoints.
  • Specify this JavaScript authentication provider as the authentication provider for the 
    Layer7 Live API Creator
     Admin API (Admin API).
    For more information, see Authenticate TeamSpace Users.