Docs‎ > ‎CA Live API Creator‎ > ‎Security‎ > ‎Authentication‎ > ‎

Custom authentication provider

A custom authentication provider is a piece of JavaScript code, which must follow certain conventions.  This piece of code must be loaded as a JavaScript library in your project.

You then register your authentication provider by creating a new authentication provider in the API Creator, under Home > Authentication Providers

When you select "JavaScript Auth Provider" as the Authentication Method, you will be prompted for "Name for Create Function". This should be the name of your authentication provider function (myAuthProvider in the sample below).

Configure

You can configure a Custom Auth Provider, so you can use the same code in different API Servers.  As described below, your Auth Provider defines these configuration parameters, including defaults.  Below is an example of the B2B Custom Auth Provider (configuration parameters shown in red box):



1 - Organization

Ultimately, an authentication provider is a JavaScript function, which must return an object containing four functions, each with a specific name and behavior.

So the general structure is:

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

Each function is described in more detail below.

2 - getConfigInfo

This function is the first one to get called when API Server instantiates your authentication provider.
It 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 authentication provider will look like this in the API Creator


3 - configure

This function is called by API Creator when the user enters a value for the parameters specified by getConfigInfo and clicks Save.
configure: function(values) {
    param1value = values.param1;
    param2value = values.param2;
}


4 - getLoginInfo

This function is called by API Server when a client needs to know what kind of information is required for authentication.
Basically, this 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'
   }
]
  };
}


5 - authenticate

This function is called by API Server when a client is attempting to authenticate. This is obviously the crux of the authentication provider.
There is no constraint on exactly how the user is authenticated.

The argument passed in will contain whatever values were provided to the @authentication service. If the caller is well-behaved, this should correspond to the parameters described by getLoginInfo, but you should not depend on that.

This 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 project.

    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
    };
}

6 - Debugging your authentication provider

Since it can be difficult to debug server-side code, API Creator providers a simple environment to debug your authentication provider. See the Hello World example for details.

7.  Authentication Samples


API Creator has published several different authentication provider services.  These can be found on our GitHub account.  These samples include Stormpath, Windows Azure Active Directory, SQL Server database, LDAP call to third party JDBC driver.