Creating an LDAP user registry in API Manager

You can use the API Manager UI to configure an organization-specific LDAP user registry to provide user authentication and onboarding for the Developer Portal. APIs can also be secured with an LDAP user registry.

Before you begin

To configure an LDAP user registry as a resource in API Manager, the LDAP directory must be created and populated for use with your API Connect ecosystem.

LDAP registries can be used to secure APIs, or for securing a Catalog to authenticate Developer Portal users.

Important: If you are using an LDAP registry to secure APIs, the STARTTLS protocol, which upgrades an insecure protocol to a secure one by applying TLS security, is not supported.

One of the following roles is required to configure an LDAP user registry:

  • Organization Administrator
  • Owner
  • Topology Administrator
  • Custom role with the Settings: Manage permissions

About this task

You can create an LDAP user registry that is specific to a provider organization, or one that can be shared and available to all of the provider organizations in your API Connect environment. An organization-specific LDAP user registry can be used for authenticating Developer Portal users in a specific provider organization. While a shared LDAP user registry can be used across the Cloud Manager, the API Manager, and the Developer Portal components in your environment.

This topic describes how to configure an organization-specific LDAP user registry. If you want to create a shared registry, see Configuring an LDAP user registry in the Cloud Manager for more information.
Note:

You create an LDAP user registry by configuring a set of properties in the API Manager UI. If you want to enable writable LDAP, you must complete the Attribute Mapping section by selecting the User Managed checkbox, and providing the mapping of your source LDAP attribute names to the target API Connect values. You can also change a registry to be read-only again by clearing the User Managed checkbox. To make the registry available to the Developer Portal, you must define the registry for consumer onboarding in the associated Catalog. To secure APIs with an LDAP registry, you must configure security definitions.

For general information about authenticating with LDAP, see LDAP authentication.

Procedure

Follow these steps to configure a new LDAP user registry as a Resource in the API Manager UI.

Note: If you are using an Active Directory, you must indicate this by using the property "directory_type": "ad" in the LDAP config.

  1. In the API Manager, click Resources Resources.
  2. Click Create in the User Registries section.
    Important: Do not share user registries between the API Manager and the Developer Portal, or between Developer Portal sites when self-service onboarding is enabled or account deletions in any of the sites are expected. You should create separate user registries for them, even if the separate registries point to the same backend authentication provider (for example, an LDAP server). This separation enables the Developer Portal to maintain unique email addresses across the catalog, without API Manager needing the same requirement. It also avoids problems with users deleting their accounts from the Developer Portal that then affects their API Manager access.
  3. Select LDAP User Registry for the user registry type, and enter the following information:
    Field Description
    Title Enter a descriptive name to display on the screen.
    Name The name that is used in CLI commands. The name is auto-generated. For details of the CLI commands for managing user registries, see the toolkit CLI reference documentation.
    Display Name (required) The name that is displayed for selection by the user when logging in to a user interface, or activating their API Manager account.

    For details of user interface log in, and account activation, see Accessing the Cloud Manager user interface, Accessing the API Manager user interface, and Activating your API Manager user account.

    Note: The Developer Portal uses the Title of the User Registries when rendering them at the login page, rather than the Display Name.
    Summary (optional) Enter a brief description.
    Address Enter the IP address or host name of the LDAP server.
    Port Enter the Port number that API Connect can use to communicate with the LDAP registry. For example, 389.
    Select a TLS Client Profile (optional) Select the TLS Client Profile that the LDAP server requires.
    Select a protocol version Select the version number for the LDAP protocol that you are using.
    Remote directory is Microsoft Active Directory Select this option if you use Active Directory.
    Case sensitive To ensure proper handling of user name capitalization, you must ensure that your case-sensitivity setting here matches the setting on your backend LDAP server:
    • Only select Case sensitive if your backend LDAP server supports case-sensitivity.
    • Do not select Case sensitive if your backend LDAP server does not support case-sensitivity.
    Note: The Developer Portal does not support case sensitive usernames.
    Note: After at least one user has been onboarded into the registry, you cannot change this setting.
    Email required Select this checkbox if an email address is required as part of the user onboarding process. If selected, the source identity provider must supply the email address as part of the authentication process during onboarding.
    Note: An email address is not required by default for onboarding to the Cloud Manager or the API Manager, but it is required for onboarding to the Developer Portal.
    Unique email address Select this checkbox if email addresses must be unique within the user registry.
    Note: Every account in the Developer Portal, including across different user registries for the same site, must have a unique email address, including the site Admin account.
  4. Click Next and enter the authentication information, which will vary depending on the selected Authentication Method. The choices are:
    • Compose DN - Select this format if you want users to login with a username that is also part of their LDAP Distinguished Name (DN). For example, using `uid` for user login where the user's LDAP DN is: uid=<username>,ou=People,dc=company,dc=com. If you are unsure whether Compose (DN) is the correct option, contact your LDAP administrator. If you are using an LDAP registry to secure APIs, Compose DN is not supported with the DataPower API Gateway.
    • Compose UPN - Select this format if your LDAP directory supports binding with User Principal Names such as john@acme.com. The Microsoft Active Directory is an example of an LDAP directory that supports Compose UPN authentication. If you are unsure whether your LDAP directory supports binding with UPNs, contact your LDAP administrator.
      Note: The Admin Bind DN and Admin Bind Password are not used with this authentication method.
    • Search DN - Select this format if you want users to login with a username that is not part of their LDAP DN. For example, if the user's LDAP DN was: {{uid=<username>,ou=People,dc=company,dc=com but }} you want them to login with the email. This format might require an administrator DN and password to search for users in the LDAP directory. If your LDAP directory permits anonymous binds, you can omit the admin DN and password. If you are unsure if your LDAP directory permits anonymous binds, contact your LDAP administrator.
      Optionally select a scope to specify which part of the directory information tree is examined:
      • Whole subtree (default)
      • Base object
      • Single level

    For all of the authentication methods:

    If you are creating an LDAP registry to authenticate users of an API, you can specify an LDAP authorization group to restrict API access. To be able to call an API that is secured by the LDAP registry, a user must successfully authenticate with their LDAP user ID and password and they must be a member of the specified authorization group. The authorization group can be a Static Group or Dynamic Group. A static group is one in which the individual members of the group are explicitly listed. A dynamic group is one which is defined according to the set of attributes that the group members share in common.

  5. For authentication method Compose DN, enter the following:
    Field Description
    Bind Method Anonymous or Authenticated. If specific permissions are not needed to search the registry, select Anonymous Bind. Or, if specific permissions are necessary, select Authenticated Bind.
    Admin DN For Authenticated Bind, enter the Distinguished Name of a user authorized to perform searches in the LDAP directory. For example cn=admin,dc=company,dc=com.
    Admin Password For Authenticated Bind, enter the user password for the Admin DN.
    Prefix Part of the DN that comes before the username for binding or authentication. For example, bind_prefix: 'uid='.
    Suffix

    Part of the DN that follows the username, specifying the user's location in the LDAP tree. For example, bind_suffix: ',ou=users,dc=apic,dc=com'.

    uid=<username>,ou=People,dc=company,dc=com.
    Base DN (optional)

    Enter a base DN in the Base DN field, or click Get Base DN to populate the field with a retrieved base DN. The base DN where the LDAP server starts its search for user entries. For example,

    search_dn_base:'dc=apic,dc=com'.
    Use group authentication (optional) Static or Dynamic. For Static Group, enter the Group Based DN, Prefix, and Suffix. For Dynamic Group, enter the Filter condition for the group.
  6. For authentication method Compose UPN, enter the following:
    Field Description
    Bind Method Anonymous or Authenticated. If specific permissions are not needed to search the registry, select Anonymous Bind. Or, if specific permissions are necessary, select Authenticated Bind.
    Admin DN For Authenticated Bind, enter the Distinguished Name of a user authorized to perform searches in the LDAP directory. For example cn=admin,dc=company,dc=com.
    Admin Password For Authenticated Bind, enter the user password for the Admin DN.
    Suffix Part of the DN that follows the username for constructing the UPN. For example, @domain.com.
    Use group authentication (optional) Enter the Filter condition for the group.
  7. For authentication method Search DN, enter the following:
    Field Description
    Bind Method Anonymous or Authenticated. If specific permissions are not needed to search the registry, select Anonymous Bind. Or, if specific permissions are necessary, select Authenticated Bind.
    Admin DN For Authenticated Bind, enter the Distinguished Name of a user authorized to perform searches in the LDAP directory. For example cn=admin,dc=company,dc=com.
    Admin Password For Authenticated Bind, enter the user password for the Admin DN.
    Prefix Part of the search filter that comes before the username. The last attribute must be the one you chose to use for login. For example, '(&(uid='.
    Suffix Part of the search filter that follows the username. For example, ')(objectClass=organizationalPerson)'. Notice how it always begins with a ')' which is meant to close the attribute filter for the last attribute specified in search_dn_filter_prefix.
    Base DN (optional)

    Enter a base DN in the Base DN field, or click Get Base DN to populate the field with a retrieved base DN. The base DN where the LDAP server starts its search for user entries. For example,

    search_dn_base:'dc=apic,dc=com'.
    Use group authentication (optional) Static or Dynamic. For Static Group, enter the Group Based DN, Prefix, and Suffix. For Dynamic Group, enter the Filter condition for the group.
  8. Optional: Click Test configuration to test the settings for your LDAP user registry. Enter valid credentials to ensure that you can access the LDAP database.
  9. Optional: If you want to make your LDAP user registry writable, select the User Managed checkbox in the Attribute Mapping section, and provide the mapping of your source LDAP attribute names to the target API Connect values. Click Add to add each name/value pair, specified as follows:
    • LDAP ATTRIBUTE NAME - is the name of the source LDAP attribute.
    • API CONNECT VALUE - is a string that represents the value that API Connect will populate the LDAP attribute with, by replacing the content contained in [ ] with the value that the user supplies when signing up.
    The default user profile properties that API Connect requires during user registration are username, first_name, last_name, email, and password, as shown in the following example:
    LDAP ATTRIBUTE NAME API Connect VALUE
    dn uid=[username],ou=users,dc=company,dc=com
    cn [first_name] [last_name]
    sn [last_name]
    mail [email]
    userPassword [password]
    You must ensure that you enter the correct attribute mapping values for your LDAP configuration, to enable API Connect to access the LDAP database. Note that a writable LDAP user registry cannot be used to authenticate Cloud Manager and API Manager users.
  10. Click Create.
    Your new LDAP registry is shown in the list of User Registries on the Resources page.

What to do next

If you use DataPower® API Gateway, your cloud administrator can optionally update the service and enable LDAP connection pooling to improve performance as explained in Registering a gateway service.

If you want to make the LDAP user registry available for authenticating Developer Portal users, you must enable it in the Catalog that is associated with that Developer Portal. Click the relevant Catalog, then click Settings > Onboarding. In the Catalog User Registries section, click Edit, select the user registry, and click Save. For more information, see Creating and configuring catalogs .

If you want to use the LDAP user registry to secure APIs, see the following information: