Using the CLI to configure a shared LDAP user registry

You can use the developer toolkit CLI to configure an LDAP user registry 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 resource in the Cloud 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 authenticating users to the Cloud Manager, the API Manager, and the Developer Portal.

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 onboarding and authenticating Developer Portal users, 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 a shared LDAP user registry. If you want to create an organization-specific registry, see Using the CLI to create an organization-specific LDAP user registry 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 the LDAP user registry is configured as writable (by enabling the user-managed property 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 LDAP user registries by using the Cloud Manager UI (see Configuring an LDAP user registry in the Cloud Manager), and 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 configure 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. Finally, to make the registry available for user authentication, you need to configure the registry in the management server, or in the appropriate Catalog, or both, depending on your requirements. 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 the cloud administration organization. Use the following command:
apic login --server mgmt_endpoint_url --username user_id --password password --realm admin/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 admin --server mgmt_endpoint_url --fields title,realm
For example:
apic identity-providers:list --scope admin --server myserver.com --fields title,realm
total_results: 2
results:
  - title: Cloud Manager User Registry
    realm: admin/default-idp-1
  - title: Corporate LDAP user registry
    realm: admin/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 Cloud Manager Local User Registry for login as a member of the cloud administration organization is default-idp-1.

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.
name: registry_name
title: "display_title"
integration_url: LDAP_integration_url
user_managed: true_or_false
user_registry_managed: false
external_group_mapping_enabled: true_or_false
case_sensitive: 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.
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.
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
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 shared LDAP user registry, run the following CLI command:
apic user-registries:create --server mgmt_endpoint_url --org admin ldap_config_file.yaml
where:
  • mgmt_endpoint_url is the platform API endpoint URL.
  • --org admin means that the registry will be created in the admin organization, which is required for a user registry to be shared.
  • 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 shared LDAP user registry is now created; see the following sections for instructions on how to make the registry available to users.

Configuring your LDAP registry for Cloud Manager or API Manager login

If you want to make your LDAP registry available for authenticating Cloud Manager and API Manager users, you must configure it on the management server.
  1. 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 admin
  2. Determine what the current user registries are, because you will need to confirm these as well as add your new LDAP registry:
    apic user-registry-settings:get --server mgmt_endpoint_url --output -
    This command outputs a list of all the current user registries in your environment, similar to the following example:
    type: user_registry_setting
    api_version: 2.0.0
    name: user-registry-setting
    admin_user_registry_default_url: >-
      https://server.com/api/user-registries/xxxxx/xxxxx-1234
    admin_user_registry_urls:
      - >-
        https://server.com/api/user-registries/xxxxx/xxxxx-1234
    provider_user_registry_default_url: >-
      https://https://server.com/api/user-registries/xxxxx/xxxxx-5678
    provider_user_registry_urls:
      - >-
        https://https://server.com/api/user-registries/xxxxx/xxxxx-5678
    created_at: '2019-09-30T12:22:19.467Z'
    updated_at: '2019-10-17T10:05:37.867Z'
    url: 'https://server.com/api/cloud/settings/user-registries'
  3. Enter the following command to update your user registries (the terminating hyphen character means that the command takes input from the command line):
    apic user-registry-settings:update --server mgmt_endpoint_url -
    The following message is output:
    Reading USER_REGISTRY_SETTING_FILE arg from stdin
  4. If you want to make your LDAP registry available for authenticating Cloud Manager users, enter the following data, followed by a new line:
    admin_user_registry_urls:
      - >-
        current_admin_user_registry_urls
      - new_ldap_user_registry_url
    where:
    • current_admin_user_registry_urls are the current admin user registry URLs, as listed in Step 2 in the admin_user_registry_urls section. Note that you must include all of the user registry URLs that you want to remain, listing each URL on a new line.
    • new_ldap_user_registry_url is the URL of your new LDAP user registry, as determined in Step 1.
  5. If you want to make your LDAP registry available for authenticating API Manager users, enter the following data, followed by a new line:
    provider_user_registry_urls:
      - >-
        current_provider_user_registry_urls
      - new_ldap_user_registry_url
    where:
    • current_provider_user_registry_urls are the current provider organization user registry URLs, as listed in Step 2 in the provider_user_registry_urls section. Note that you must include all of the user registry URLs that you want to remain, listing each URL on a new line.
    • new_ldap_user_registry_url is the URL of your new LDAP user registry, as determined in Step 1.
  6. Press CTRL D to terminate the input. A confirmation message is output, for example:
    user-registry-setting   https://server.com/api/cloud/settings/user-registries
    where server.com is your management server endpoint.

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:
  1. 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 admin
  2. Log in to the management server as a member of a provider organization by entering the following command:
    apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider
    For full details of the apic login command, see Logging in to a management server.
  3. 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
  4. 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.
  5. 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.
  1. 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 admin
    The command returns a list of all the user registries on that server, 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.
  2. 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 admin 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
  3. 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.
  4. 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:

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
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]"