Authenticate API Users using an LDAP Authentication Provider

Authenticate API Users using an LDAP Authentication Provider
lac42
You can define and specify a Lightweight Directory Access Protocol (LDAP) authentication provider as the authentication provider for your API. LDAP authentication providers are custom JavaScript authentication providers that contain LDAP authentication provider code. This authentication provider uses the 
JavaScript Auth Provider
 authentication method.
CA Live API Creator
includes authentication provider samples that you can use as a starting point to creating your JavaScript authentication provider, such as the 
SimpleLDAPAuthProvider
 sample LDAP authentication provider (the
SimpleLDAPAuthProvider.js
file). This authentication provider sample uses a public LDAP. This sample authentication provider demonstrates how to write your own authentication provider using Java's JNDI API and a public LDAP server.
For more information:
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
    CA Live API Creator
    to run as cluster or, if you have configured
    CA 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, configure, and specify a custom LDAP JavaScript authentication provider:
2
Verify the Prerequisites
Before you define an LDAP authentication provider for your API, ensure that you have completed the following prerequisite steps: 
  • You are familiar with JNDI.
  • You are familiar with the 
    SimpleLDAPAuthProvider
    sample LDAP authentication provider.
Download the SimpleLDAPAuthProvider Sample Authentication Provider
Download the 
SimpleLDAPAuth.js
 sample authentication provider from GitHub.
Add your LDAP Authentication Provider
  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
    .
    The JavaScript authentication provider is created.
  5. On the 
    Details
     tab, enter 
    SimpleLDAPAuthProvider
     as the name for the create function in the 
    Name for Create Function
     field, and then save your changes. The authentication provider uses this create function to identify API user login.
    Your configuration parameters appear.
  6. Enter the LDAP-specific parameters, and then click 
    Save
    .
  7. Click the
    Code
    tab, copy the JavaScript text from the 
    SimpleLDAPAuth.js
    file, paste it as the code for your LDAP authentication provider, and then click
    Save
    .
    The code for your authentication provider uses the code from the 
    SimpleLDAPAuth.js
     sample authentication provider.
Your custom LDAP JavaScript authentication provider is added.
Configure your LDAP Authentication Provider
CA Live API Creator
 requires that the authentication provider supply the roles for a given API user defined in 
CA Live API Creator
. Define how the data that is contained in LDAP is mapped to the information 
CA Live API Creator
 needs by configuring your LDAP authentication provider to your LDAP schema.
Follow these steps:
  1. Complete the following changes in the 
    authenticate
     code:
    • Update the path to the LDAP server.
       Update the code to use your LDAP server within the following code segment:
      var Hashtable = Java.type("java.util.Hashtable");
      var env = new Hashtable();
      env.put("java.naming.factory.initial", "com.sun.jndi.ldap.LdapCtxFactory");
      env.put("java.naming.provider.url", "
      ldap://ldap.forumsys.com
      ");
    • Map group memberships to roles. 
      Determine how you want to map group memberships to roles, and then add this information to the code. For example:
      // Here we loop over all the values of the "groups" attribute and map the relevant groups to roles
      attrs = ctx.getAttributes(userCN, ["groups"]);
      attrsEnum = attrs.getAll();
      if (attrsEnum.hasMore()) {
          var mvAttr = attrsEnum.next();
          var attrEnum = mvAttr.getAll();
          while (attrEnum.hasMore()) {
              var groupName = attrEnum.next();
              if (groupName.startsWith("LAC-")) {
                  authResponse.roleNames.push(groupName.substring(4));
              }
          }
      }
      You can also define which roles an API user should have using a different mechanism. For example, you can use the attribute values from LDAP or based on an external system.
    • Define the permissions in 
      CA Live API Creator
       for API users.
      Define the 
      roleNames
       collection in the response. If an API user does not have permissions in 
      CA Live API Creator
      , you can have the authentication provider return an error. For example:
      if ( ! authResponse.roleNames.length) {
          java.lang.System.out.println("API user " + payload.username + " gets no access");
          return {
              errorMessage: "API user " + payload.username + " is not authorized to access this system."
          }
      }
    • (Optional) Attach additional LDAP information to the authentication result.
       Map the LDAP data that the authentication provider might be using to determine access. For example, employee ID or region. Edit the following section in the code:
      var attrs = ctx.getAttributes(userCN, ["employeeID", "region"]); var attrsEnum = attrs.getAll(); while (attrsEnum.hasMore()) { var attrib = attrsEnum.next(); authResponse.userData[attrib.getID()] = attrib.get().toString(); }
      You can use these values in your API permissions, for example, to restrict API users to viewing only the data in their region.
  2. Click 
    Save
    .
    Your changes to the JavaScript code are saved.
Your custom LDAP JavaScript authentication provider is configured.
Specify your LDAP 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 page appears.
  3. Select the LDAP authentication provider that you defined and registered 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 LDAP authentication provider is specified as the authentication provider for your API.
Authentication Failure Message
When you specify the credentials (username/password) that API users use for authentication, 
CA Live API Creator
 attempts to log in to your LDAP server. If the credentials are correct, then the authentication provider logs in successfully. Otherwise, the authentication provider can return an error message, for example:
Unable to authenticate with LDAP server
The following code snippet shows the portion of the code of the authentication provider connecting to LDAP and, if the authentication is unsuccessful, returning an error message:
var Hashtable = Java.type("java.util.Hashtable");
var env = new Hashtable();
env.put("java.naming.factory.initial", "com.sun.jndi.ldap.LdapCtxFactory");
env.put("java.naming.provider.url", "ldap://ldap.forumsys.com");
var userCN = "uid=" + payload.username + ",dc=example,dc=com";
env.put("java.naming.security.authentication", "simple");
env.put("java.naming.security.principal", userCN);
env.put("java.naming.security.credentials", payload.password);
env.put("java.naming.referral", "follow");
var InitialDirContext = Java.type("javax.naming.directory.InitialDirContext");
try {
    ctx = new InitialDirContext(env);
}
catch(e) {
    return {
        errorMessage: "Unable to authenticate with LDAP server: " + e.getMessage()
    }
}
Next Steps
Now that you have specified your custom LDAP JavaScript authentication provider as the authentication provider for your API, you can authentication API users and obtain an authentication token by POSTing to the 
@authentication
 system REST endpoint.
An easy way to test this endpoint is using the command line.
For more information about how to authentication using this endpoint, see System REST Endpoints.