Configuring LDAP group mappings on API Manager user roles

As an API Manager administrator, you can configure LDAP group mapping on API Connect roles in a provider organization by using the developer toolkit CLI.

Before you begin

You must have an LDAP user registry resource in the API Manager that has the external_group_mapping_enabled configuration set to true. See Using the CLI to create an organization-specific LDAP user registry for information.

One of the following roles is required to edit roles:

Administrator
Owner
Custom role with the Settings: manage permissions

Note: The provider organization roles apply only to API Manager users. If you want to apply LDAP group mapping to Cloud Manager users, see Configuring LDAP group mapping on Cloud Manager user roles. LDAP group mapping cannot be applied to Developer Portal users.

About this task

You can map external LDAP groups to the API Connect preconfigured user roles (except for the Owner and Member roles), as well as to any custom user roles, to reflect your business needs.

Notes:

After LDAP group mapping is enabled on a role, user onboarding always honors the group mappings.
Once on-boarded, user membership in API Connect is valid throughout the login period (access_token_ttl), irrespective of any changes in the external LDAP registry. Membership is updated only on the next login, when the LDAP information is fetched and refreshed.
One or more API Connect roles can be mapped to one or more LDAP groups, and one or more LDAP groups can be mapped to a role.
When multiple LDAP groups are mapped to a single role, it means that a user from any one of the LDAP groups can logon to API Connect.
If a user is removed from the external LDAP user registry, to ensure quick removal from API Connect you must also delete the user membership in API Connect.
In API Manager you can map roles at the provider organization, Catalog and, if appropriate, Space level. However, you can only map roles at the child level of Catalog, and then the Catalog's child level of Space, if the parent level also has group mapping defined. Mapping at a child level overrides the mapping for the same role at the parent level. For example:
If the Administrator Role at the provider organization level is mapped to the LDAP group of cn=APIC-Administrators,ou=ibmgroups,o=ibm.com, and the Administrator Role at a Catalog level is mapped to the LDAP group of cn=APIC-Developers,ou=ibmgroups,o=ibm.com, then any user that is added as a Catalog member must belong to the cn=APIC-Developers,ou=ibmgroups,o=ibm.com group. Note that provider organization level members that belong to the cn=APIC-Administrators,ou=ibmgroups,o=ibm.com group can still access the Catalog due to inheritance.

You can configure LDAP group mappings using one of the following methods:

Using the UI to configure LDAP group mappings
Using the CLI to configure LDAP group mappings

Using the UI to configure LDAP group mappings

Use the API Manager UI to configure LDAP group mappings.

Procedure

Login to the API Manager as a user with the appropriate permissions.
Click Settings > Roles > Add a new Role or edit existing role .
Select the following settings:
- Enable external group mapping - select to enable external group mapping for this role.
- LDAP user Registry - LDAP user registry list which has external group mapping enabled. User must select one of the LDAP user registry from this list.
- LDAP group names - add one or more LDAP group names that you want to map to the user role.
- User group prefix - add the prefix for the LDAP user group.
- User group suffix - add the suffix for the LDAP user group.
Save your changes.

Results

The role is updated with the LDAP group mapping information. Users can now log on to the API Manager, and automatically be assigned the correct access permissions for their role.

Using the CLI to configure LDAP group mappings

Use the toolkit CLI to configure LDAP group mappings.

About this task

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

Procedure

Perform the following steps to map external LDAP groups to API Manager user roles.

Log in to the management server CLI.
Before you can update the role 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
```
where mgmt_endpoint_url is the platform API endpoint URL.
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.

Run the following command to get the URL of the LDAP user registry resource in the API Manager that you want to map the user roles to:

apic user-registries:get  ldap_user_registry --org organization_name --server mgmt_endpoint_url --output -

where:

ldap_user_registry is the name or ID of your LDAP user registry resource.
organization_name is the value of the name property of your provider organization.
mgmt_endpoint_url is the platform API endpoint URL.

This command outputs the configuration details of your LDAP user registry, and the url: is shown at the end of the list, for example:

type: user_registry
api_version: 2.0.0
id: 35e75bad-1d89-4a65-a70f-xxxxxx
name: ldap
title: LDAP
integration_url: >-
  https://server.com/api/cloud/integrations/user-registry/147b5fb1-e88e-41e3-90e9-xxxxxx
registry_type: ldap
user_managed: false
user_registry_managed: false
external_group_mapping_enabled: true
...
url: >-
  https://server.com/api/user-registries/3d58ce7e-16a8-493b-9684-xxxxxx/35e75bad-1d89-4a65-a70f-xxxxxx

Create a role yaml file that contains the following LDAP group mapping configuration properties:
```
external_group_mapping:
  user_registry_url: https://server.com/api/user-registries/3d58ce7e-16a8-493b-9684-xxxxxx/35e75bad-1d89-4a65-a70f-xxxxxx
  ldap_groups:
    - 'cn=apic-administrators,ou=ibmgroups,o=ibm.com'
    - 'cn=apic-developers,ou=ibmgroups,o=ibm.com'
  user_group_filter_prefix: (&(uniquemember=
  user_group_filter_suffix: )(objectClass=groupOfUniqueNames))
```
Where:
- user_registry_url is the URL of your LDAP user registry resource from Step #task_apim_role_mapping__ldap_url.
- ldap_groups is a list of the LDAP group names that you want to map to the user role.
- user_group_filter_prefix is the prefix for the LDAP user group.
- user_group_filter_suffix is the suffix for the LDAP user group.
Run the following command to update the user role with the external_group_mapping configuration properties:
```
apic roles:update role_name --scope org --org organization_name --server mgmt_endpoint_url mapping_properties_file
```
Where:
- role_name is the name of the user role that you want to add the LDAP group mapping to.
- --scope is the organization level that you want the update to apply to. Valid values are:
  - org to apply the mapping at the provider organization level.
  - catalog to apply the mapping at the Catalog level.
  - space to apply the mapping at the Space level.
- organization_name is the value of the name property of your provider organization.
- mgmt_endpoint_url is the platform API endpoint URL.
- mapping_properties_file is the name of your mapping properties file from Step #task_apim_role_mapping__role_file, for example role_mapping_file.yaml.
If you prefer to enter the configuration properties interactively on the command line, you can substitute the mapping_properties_file for a terminating hyphen character -, and enter the information manually, followed by pressing CTRL D to terminate the input.
If you want to create a custom role that includes LDAP group mapping, you can include the external_group_mapping configuration section in the role_file, and then create the new role by using the apic roles:create command.

For more information about the apic roles commands, see the toolkit CLI reference documentation.

Results

The role is updated with the LDAP group mapping information. Users can now log on to the API Manager, and automatically be assigned the correct access permissions for their role.