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.
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.
-
In the API
Manager, click
Resources.
-
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.
-
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.
|
-
Click Next and enter the authentication information, which will vary
depending on the selected Authentication Method. The choices are:
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.
-
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. |
-
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. |
-
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. |
- 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.
- 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.
-
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
. 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: