Configuring LDAP group mappings on Cloud Manager user roles

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

Before you begin

You must have an LDAP user registry resource in the Cloud Manager that has the external_group_mapping_enabled configuration set to true. See Using the CLI to configure a shared LDAP user registry for information.

One of the following roles is required to edit roles:

Administrator
Owner
Topology Administrator
Custom role with the Settings: manage permissions

Note: The Admin organization roles apply only to Cloud Manager users. If you want to apply LDAP group mapping to API Manager users, see Configuring LDAP group mapping on API 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 log in to API Connect.
If a user is removed from the external LDAP user registry, then to ensure quick removal from API Connect you must also delete the user membership in API Connect.

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 Cloud Manager UI to configure LDAP group mappings.

Procedure

Login to the Cloud Manager UI 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 Cloud 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 Cloud 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 the cloud administration organization. Use the following command:
```
apic login --server mgmt_endpoint_url --username user_id --password password --realm admin/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 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.

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

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

where:

ldap_user_registry is the name or ID of your LDAP user registry resource.
--org admin means that the registry details are retrieved from the admin 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 2.
- 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 admin --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 scope that you want the update to apply to. For this task, the value must be org.
- --org admin means that the user role is updated on the admin organization.
- mgmt_endpoint_url is the platform API endpoint URL.
- mapping_properties_file is the name of your mapping properties file from Step 3, 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 Cloud Manager, and automatically be assigned the correct access permissions for their role.