Using the CLI to create an organization-specific LDAP user registry

You can use the developer toolkit CLI to configure an organization-specific LDAP user registry to provide user authentication 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 available to 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.

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

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 onboarding and authenticating Developer Portal users in a specific provider organization. While a shared LDAP user registry can be used for authenticating Cloud Manager, API Manager, and Developer Portal users.

This topic describes how to configure an organization-specific LDAP user registry. If you want to create a shared registry, see Using the CLI to configure a shared LDAP user registry for more information.

Note:

You can also create organization-specific LDAP user registries by using the API Manager UI; for more information see Creating an LDAP user registry in API Manager.
In addition, you can create and manage LDAP user registries by using the API Connect REST APIs; see the API Connect REST API documentation.
If you are using the DataPower® API Gateway, LDAP group authentication is not supported.
You can map external LDAP groups to API Connect user roles to enable more control of user authorization by using the developer toolkit CLI. The following instructions explain how to set the external_group_mapping_enabled configuration on your LDAP user registry resource. For information about how to set external role mapping on your API Connect user roles, see Configuring LDAP group mapping on Cloud Manager user roles.

You create an LDAP user registry by first defining the registry details in a configuration file. You then use a developer toolkit CLI command to create the registry, passing the configuration file as a parameter. To make the registry available to the Developer Portal, you must enable the registry in the associated Catalog. To secure APIs with an LDAP registry, you must configure security definitions. You can use the following instructions to create a writable or a read-only LDAP user registry.

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

Logging in to the management server CLI

Before you can define the LDAP user registry configuration, you must log in to your management server from the developer toolkit CLI as a member of a provider organization. Use the following command:

apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider

You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):

apic identity-providers:list --scope provider --server mgmt_endpoint_url --fields title,realm

For example,

apic identity-providers:list --scope provider --server myserver.com --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap

The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.

For full details of the login command, see Logging in to a management server.

For more information about how to use the CLI, see Installing the toolkit, and Overview of the command-line tool.

Defining your LDAP configuration

You define the configuration of your LDAP user registry in an ldap_config_file.yaml file, as shown in the following example. Note that the actual contents of your YAML file will vary depending on the authentication method of your LDAP server, and this is explained in the following tables.

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.

name: registry_name
title: "display_title"
integration_url: LDAP_integration_url
user_managed: true_or_false
user_registry_managed: false
directory_type: ad
external_group_mapping_enabled: true_or_false
case_sensitive: true_or_false
email_required: true_or_false
email_unique_if_exist: true_or_false
identity_providers:
 - name: provider_name
   title: provider_title
endpoint:
  endpoint: "ldap_server_url_and_port"
configuration:
  authentication_method: authentication_method
  authenticated_bind: "true_or_false"
  admin_dn: "admin_dn"
  admin_password: admin_password
  search_dn_base: "search_dn_base"
  search_dn_scope: search_dn_scope  
  search_dn_filter_prefix: prefix
  search_dn_filter_suffix: suffix
  attribute_mapping:
    dn: "distinguished_name"
    cn: "common_name"
    sn: "last_name"
    mail: "email_address"
    userPassword: "password"

The registry properties that are common to each authentication method are described in the following table:

Property	Description
`name`	The name of the registry. This name is used in CLI commands.
`title`	A descriptive name to display in a graphical user interface.
`integration_url`	The LDAP integration URL in your API Connect configuration. You can determine the LDAP integration URL by using the following CLI command: `apic integrations:list --server mgmt_endpoint_url --subcollection user-registry`
`user_managed`	Determines whether your user registry is writable or not. Must be set to `true` for writable LDAP. You can change this setting to `false` if you don't want the registry to be writable; see the Switching your LDAP registry between writable and read-only section at the end of this topic for details. Note that a writable LDAP user registry cannot be used to authenticate Cloud Manager and API Manager users.
`user_registry_managed`	Must be set to `false` for LDAP. Determines whether API Connect manages your user registry. Only LUR registries are managed by API Connect.
`directory`	Specify one of the of following values for the directory type: `ad` - Indicates that the LDAP is Microsoft Active Directory `standard` - (Default value) Indicates any other LDAP
`external_group_mapping_enabled`	Determines whether your user registry supports LDAP group mapping. Valid values are: `true` `false` The default value is `false`.
`case_sensitive`	Determines whether your user registry is case-sensitive. Valid values are: `true` `false` 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 set `case_sensitive` to `true` if your backend LDAP server supports case-sensitivity. Set `case_sensitive` to `false` if your backend LDAP server does not support case-sensitivity. Note: After at least one user has been onboarded into the registry, you cannot change this setting.
`email_required`	Determines whether an email address is required as part of the user onboarding process. Valid values are: `true` `false` If set to `true`, 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.
`email_unique_if_exist`	Determines whether email addresses must be unique within the user registry. Valid values are: `true` `false` 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.
`identity_providers`	An array containing the details of your LDAP server, where: `name` - is the name of the LDAP server and is the name that is used in CLI commands `title` - is the display name of the LDAP server
`endpoint`	The endpoint of your LDAP server, made up of the url and port, for example: `"ldap://server.com:389"`
`tls_profile`	Optionally set the TLS Client Profile that the LDAP server requires.
`protocol_version`	Optionally set the version number for the LDAP protocol that you are using. Valid values are: `2` `3` Defaults to `3` if not explicitly set.

The properties in the configuration section will vary depending on the selected authentication method. The three authentication methods are:

compose_dn - Set 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 - Set 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.

For authentication method compose_dn, set the following configuration properties:

Properties	Description
`authentication_method`	`compose_dn`
`authenticated_bind`	The bind method. Valid values are: `"true"` - authenticated bind `"false"` - anonymous bind If specific permissions are not needed to search the registry, select `"false"`. If specific permissions are necessary, select `"true"`.
`admin_dn`	If `authenticated_bind` is set to `"true"`, enter the Distinguished Name (DN) of a user authorized to perform searches in the LDAP directory. For example: `"cn=admin,dc=company,dc=com"`
`admin_password`	If `authenticated_bind` is set to `"true"`, enter the user password for the `admin_dn`.
`search_dn_base`	Optionally set a base DN, for example: `"dc=company,dc=com"`
`bind_prefix`	Set the prefix to the DN, for example: `(uid=`
`bind_suffix`	Set the suffix to the DN, for example: `)`
`attribute_mapping`	If `user_managed` is set to `true`, provide the mapping of your source LDAP attribute names to the target API Connect values. This mapping is configured as a name/value pair, specified as follows: `ldap_registry_attribute_name: "apic_ldap_attribute_value"` Where: `ldap_registry_attribute_name` - is the name of the source LDAP attribute `apic_ldap_attribute_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 user profile properties that API Connect requires during user registration are `username`, `first_name`, `last_name`, `email`, and `password`. The following extract shows an example of an attribute mapping: `attribute_mapping: dn: "uid=[username],ou=users,dc=company,dc=com" cn: "[first_name] [last_name]" sn: "[last_name]" mail: "[email]" userPassword: "[password]"`

For authentication method compose_upn, set the following configuration properties:

Properties	Description
`authentication_method`	`compose_upn`
`authenticated_bind`	The bind method. Valid values are: `"true"` - authenticated bind `"false"` - anonymous bind If specific permissions are not needed to search the registry, select `"false"`. If specific permissions are necessary, select `"true"`.
`admin_dn`	If `authenticated_bind` is set to `"true"`, enter the Distinguished Name (DN) of a user authorized to perform searches in the LDAP directory. For example: `"cn=admin,dc=company,dc=com"`
`admin_password`	If `authenticated_bind` is set to `"true"`, enter the user password for the `admin_dn`.
`bind_suffix`	Enter the domain part of the user principal name. For example: `@acme.com`
`attribute_mapping`	If `user_managed` is set to `true`, provide the mapping of your source LDAP attribute names to the target API Connect values. This mapping is configured as a name/value pair, specified as follows: `ldap_registry_attribute_name: "apic_ldap_attribute_value"` Where: `ldap_registry_attribute_name` - is the name of the source LDAP attribute `apic_ldap_attribute_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 user profile properties that API Connect requires during user registration are `username`, `first_name`, `last_name`, `email`, and `password`. The following extract shows an example of an attribute mapping: `attribute_mapping: dn: "uid=[username],ou=users,dc=company,dc=com" cn: "[first_name] [last_name]" sn: "[last_name]" mail: "[email]" userPassword: "[password]"`

For authentication method search_dn, set the following configuration properties:

Property	Description
`authentication_method`	`search_dn`
`authenticated_bind`	The bind method. Valid values are: `"true"` - authenticated bind `"false"` - anonymous bind If specific permissions are not needed to search the registry, select `"false"`. If specific permissions are necessary, select `"true"`.
`admin_dn`	If `authenticated_bind` is set to `"true"`, enter the Distinguished Name (DN) of a user authorized to perform searches in the LDAP directory. For example: `"cn=admin,dc=company,dc=com"`
`admin_password`	If `authenticated_bind` is set to `"true"`, enter the user password for the `admin_dn`.
`search_dn_base`	Optionally set a base DN, for example: `"dc=company,dc=com"`
`search_dn_scope`	Optionally set the search DN scope. The scope determines which part of the directory information tree is examined. Possible values are: `base` `one` `sub` (default value)
`search_dn_filter_prefix`	Set the prefix to the DN, for example: `(uid=`
`search_dn_filter_suffix`	Set the suffix to the DN, for example: `)`
`attribute_mapping`	If `user_managed` is set to `true`, provide the mapping of your source LDAP attribute names to the target API Connect values. This mapping is configured as a name/value pair, specified as follows: `ldap_registry_attribute_name: "apic_ldap_attribute_value"` Where: `ldap_registry_attribute_name` - is the name of the source LDAP attribute `apic_ldap_attribute_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 user profile properties that API Connect requires during user registration are `username`, `first_name`, `last_name`, `email`, and `password`. The following extract shows an example of an attribute mapping: `attribute_mapping: dn: "uid=[username],ou=users,dc=company,dc=com" cn: "[first_name] [last_name]" sn: "[last_name]" mail: "[email]" userPassword: "[password]"`

Save your ldap_config_file.yaml so it can be accessed by the user-registries:create command in the following section. See the Example section for an example configuration file.

Creating your LDAP user registry

To create your organization-specific LDAP user registry, run the following CLI command:

apic user-registries:create --server mgmt_endpoint_url --org organization_name ldap_config_file.yaml

where:

mgmt_endpoint_url is the platform API endpoint URL.
organization_name is the value of the name property of your provider organization.
ldap_config_file is the name of the YAML file that defines the configuration of your LDAP user registry.

On completion of the registry creation, the command displays the following summary details:

registry_name registry_url

The registry_name is derived from the name property in the configuration YAML file. The registry_url is the URL with which the registry resource can be accessed.

Your LDAP user registry is now created; see the following section for instructions on how to make the registry available in the Developer Portal.

Configuring your LDAP registry in a Catalog

If you want to make your LDAP registry available for authenticating Developer Portal users, you must enable it in the Catalog that is associated with that Developer Portal. Complete the following steps:

Determine the URL of your LDAP user registry by using the following command (or you can copy and paste from the summary of the registry creation):
```
apic user-registries:list --server mgmt_endpoint_url --org organization_name
```
Log in to the management server as a member of a provider organization; enter the following command:
```
apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider
```
You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
```
apic identity-providers:list --scope provider --server mgmt_endpoint_url --fields title,realm
```
For example,
```
apic identity-providers:list --scope provider --server myserver.com --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
```
The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.
For full details of the apic login command, see Logging in to a management server.
Enter the following command (the terminating hyphen character means that the command takes input from the command line):
```
apic configured-catalog-user-registries:create --server mgmt_endpoint_url --org organization_name --catalog catalog_name -
```
where catalog_name is the value of the name property of the required Catalog. The command returns
```
Reading CONFIGURED_CATALOG_USER_REGISTRY_FILE arg from stdin
```
Enter the following data, followed by a new line:
```
user_registry_url: ldap_registry_url
```
where ldap_registry_url is the URL of your LDAP registry, obtained in step 1.
Press CTRL D to terminate the input.

Switching your LDAP registry between writable and read-only

After an LDAP user registry has been created, it can be switched between writable and read-only by updating the user_managed property in the registry configuration. Complete the following steps.

Determine the name or ID of the LDAP user registry that you want to update, by running the following command (or you can use the summary from the registry creation):
```
apic user-registries:list --server mgmt_endpoint_url --org organization_name
```
The command returns a list of all the user registries for that organization, shown by name followed by their registry URL. The registry ID is located at the end of the URL, for example https://company.com/api/user-registries/x-x-x-x-x/registry_id.
Enter the following command (the terminating hyphen character means that the command takes input from the command line):
```
apic user-registries:update --server mgmt_endpoint_url --org organization_name registry_name_or_id -
```
where registry_name_or_id is the name or ID of the LDAP user registry that you want to update (as determined in the previous step). The command returns:
```
Reading USER_REGISTRY_FILE arg from stdin
```
Enter the following data, followed by a new line:
```
user_managed: true_or_false
```
where true makes the registry writable, and false makes the registry read-only.
Press CTRL D to terminate the input.

Note that if you are changing your registry from read-only to writable, you must also set the attribute_mapping configuration, as described in the previous registry property tables.

Using an LDAP user registry to secure APIs

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

To use for basic authentication in the security definition for an API, see Creating a basic authentication security definition.
To use for authentication in the User Security configuration for a native OAuth provider, see Configuring user security for a native OAuth provider.

For details of all the apic user-registries and apic configured-catalog-user-registries commands, see apic user-registries and apic configured-catalog-user-registries.

Example

The following example shows a configuration file that uses the Search DN authentication method for setting up writable LDAP:

name: sdn-ldap
title: "SDN LDAP User Registry"
integration_url: https://mycompany.com/api/cloud/integrations/user-registry/xxx-xxx-xxx
user_managed: true
user_registry_managed: false
directory_type: standard
case_sensitive: false
identity_providers:
  - name: ldap
    title: "SDN LDAP Identity Provider"
endpoint:
  endpoint: "ldap://mycompany.com:389"
configuration:
  authentication_method: search_dn
  authenticated_bind: "true"
  admin_dn: "cn=admin,dc=company,dc=com"
  admin_password: xxxx
  search_dn_base: "dc=company,dc=com"
  search_dn_scope: sub
  search_dn_filter_prefix: (uid=
  search_dn_filter_suffix: )
  attribute_mapping:
    dn: "uid=[username],ou=users,dc=company,dc=com"
    cn: "[first_name] [last_name]"
    sn: "[last_name]"
    mail: "[email]"
    userPassword: "[password]"