Configuring an LDAP user registry in the Cloud Manager

You can use the Cloud Manager UI to configure an LDAP user registry as a shared resource to provide user authentication for the Cloud Manager, the API Manager, and the Developer Portal. APIs can also be secured with an LDAP user registry.

Before you begin

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

LDAP registries can be used to secure APIs, to authenticate users to the Cloud Manager and the API Manager, 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:

  • 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 a shared LDAP user registry that is available to all of the provider organizations in your API Connect environment. If you want to create an organization-specific registry, see Creating an LDAP user registry in API Manager for more information. Note also that the visibility of a user registry is set to shared by default. However, you can change the visibility setting to make the registry private, or visible only to specific provider organizations. For more information, see Setting visibility for a user registry.
Note:
  • If you configure your LDAP user registry to be writable (by selecting the User Managed check box on the registry), you can use the Developer Portal UI for onboarding and authenticating new Developer Portal users, as well as those users that already exist in the LDAP database. A writable LDAP user registry cannot be used to authenticate Cloud Manager and API Manager users.
  • You can also create and manage LDAP user registries by using the developer toolkit CLI (see Using the CLI to configure a shared LDAP user registry), and by using the API Connect REST APIs (see the API Connect REST API documentation).
  • You can map external LDAP groups to API Connect user roles to enable greater control of user access, but this configuration can be done only by using the developer toolkit CLI; see Using the CLI to configure a shared LDAP user registry for details.

You create an LDAP user registry by configuring a set of properties in the Cloud 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. After configuring the user registry, you must set it as active in Settings > User Registries. 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 shared resource in the Cloud Manager UI.

  1. In the Cloud 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 apic user-registries.
    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 an LDAP 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.
    Enable External Group Mapping Enable this property if you want user to use this user registry to map external LDAP groups to API Connect user roles to enable more control of user authorization.
    Email required Select this check box 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 check box 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 can compose the user LDAP Distinguished Name (DN) from the user name. For example, uid=<username>,ou=People,dc=company,dc=com is a DN format that can be composed from the user name. 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 cannot compose the user LDAP Distinguished Name from the user name; for example, if the base DNs of the users are different. 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 Specify the prefix to the DN. For example (uid=.
    Suffix Specify the suffix to the DN. For example ).
    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.
    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 Enter the domain part of the user principal name. For example, @acme.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 Specify the prefix to the DN. For example (uid=.
    Suffix Specify the suffix to the DN. For example ).
    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.
    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

To make the LDAP registry available for user authentication in the Cloud Manager and the API Manager, you must set it as active in the Settings > User Registries section. See Selecting user registries for Cloud Manager and API Manager for more information.

If you want to make the LDAP registry available for authenticating Developer Portal users, you must enable it in the Catalog that is associated with that Developer Portal. In the API Manager UI, click Manage followed by the relevant Catalog, and 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: