Creating and configuring an LDAP for user login
This blog is the third part of the series Securing your API Connect Cloud with LDAP. The series aims to provide a brief introduction to LDAP, how its used for user authentication and how you can secure your API Connect cloud with LDAP to meet your enterprise security needs. You can find the complete list of entries for this series from the main page here.
If you want users from your organization to authenticate with their existing accounts in your enterprise LDAP directory to log into API Connect, you can create and configure an LDAP resource in API Connect. This post will show how you can create and configure an LDAP resource in API Connect for user login.
LDAP configuration properties in API Connect:
To create an LDAP resource in API Connect, you would need one or more of the properties listed in the table below.
Example login configurations:
API Connect supports three different types of login configurations for LDAP authentication: search_dn, compose_dn or compose_upn. This is specified through the authentication_method property. If you do not know which type of login configuration to choose, refer to the post here.
The figure below shows a user entry in an Active Directory setup for user Sprout Ponoma. We will be looking at examples for all three login configurations for same setup shown below.
- search_dn configuration:
Assume you want to use the sAMAccountName attribute for user login. The sample configuration would look like:
{authenticated_bind: 'true',
admin_dn: 'CN=Administrator,CN=Users,DC=apim,DC=ca,DC=com',
admin_password: 'secret',
authentication_method: 'search_dn',
search_dn_base: 'CN=Users,DC=apim,DC=ca,DC=com',
search_dn_filter_prefix: '(sAMAccountName=',
search_dn_filter_suffix: ')'}
- compose_dn configuration:
If the login configuration is compose_dn, the login attribute should be part of the DN itself and in this case that would be the cn attribute. The sample configuration would look like:
{authenticated_bind: 'true',
admin_dn: 'CN=Administrator,CN=Users,DC=apim,DC=ca,DC=com',
admin_password: 'secret',
authentication_method: 'compose_dn',
search_dn_base: 'CN=Users,DC=apim,DC=ca,DC=com',
bind_prefix: 'CN=',
bind_suffix: ',CN=Users,DC=apim,DC=ca,DC=com'}
- compose_upn configuration:
Since this is Active Directory, we can also use the compose_upn and allow users to sign in with their userPrincipalName attribute. The sample configuration would look like:
{authenticated_bind: 'true',
admin_dn: 'CN=Administrator,CN=Users,DC=apim,DC=ca,DC=com',
admin_password: 'secret',
authentication_method: 'compose_upn',
bind_suffix: '@apim.ca.com'}
Toolkit samples — Creating and configuring an LDAP for user login:
For the purposes of this post, we will be using the product toolkit. You could also use the UI or platform REST APIs documented here:
1. Creating an LDAP resource:
- Login: You can create an LDAP resource in the admin organization(Cloud Manager) or a provider organization (API Manager). Depending on where you want to create it, perform a user login. We will be using the admin org here.
apic login --server <mgmt_endpoint> --username <username> --password <password> --realm admin/<identity_provider>- Get LDAP integration: To create a user registry, you will need to get the integration_url for that registry type. Use the following command and from the response, pick the URL listed against ldap:
apic integrations:list --server <mgmt_endpoint> --subcollection user-registry- Create registry:
apic user-registries:create --server <mgmt_endpoint> --org admin ldap_config_file.yamlAssuming an API Connect instance is running on apimserver.example.com, and we want to use the search_dn configuration from the example above, a sample input ldap_config_file.yaml would look like:
name: corporate-ldap
title: Corporate LDAP User Registry
endpoint:
endpoint: ldaps://my-ldap-server:636
configuration:
authentication_method: search_dn
authenticated_bind: 'true'
admin_dn: CN=Administrator,CN=Users,DC=apim,DC=ca,DC=com
admin_password: secret
search_dn_base: CN=Users,DC=apim,DC=ca,DC=com
search_dn_filter_prefix: "(sAMAccountName="
search_dn_filter_suffix: ")"
integration_url: https://apimserver.example.com/api/cloud/integrations/user-registry/ldap- You can verify that the new resource has been created by listing the registries in the org.
apic user-registries:list --server <mgmt_endpoint> --org admin2. Configuring the LDAP registry for Cloud/API Manager login:
If you want to use the LDAP resource for Cloud or API Manager login, you will need to update the user-registry-settings at the cloud.
- Get user registry settings:
apic user-registry-settings:get --server <mgmt_endpoint>- Update user registry settings:
For Cloud manager login, add the URL of the LDAP resource to the admin_user_registry_urls array.
For API Manager login, update the provider_user_registry_urls array.
apic user-registry-settings:update --server <mgmt_endpoint> user-registry-setting.yamlAssuming the URL of the LDAP resource is
https://apimserver.example.com/api/user-registries/0ec054a0-ceb8-457f-8d78-ae6b13fc6d3e/e634f0e3-42f9-4951-aa89-e7cb57363a1ba sample user-registry-setting.yaml input file to use this LDAP for both API Manager and Cloud Manager login would look like:
name: user-registry-setting
admin_user_registry_urls:
- 'https://apimserver.example.com/api/user-registries/0ec054a0-ceb8-457f-8d78-ae6b13fc6d3e/9e81c171-9e72-4326-8c52-5999153faed1'
- 'https://apimserver.example.com/api/user-registries/0ec054a0-ceb8-457f-8d78-ae6b13fc6d3e/e634f0e3-42f9-4951-aa89-e7cb57363a1b'
provider_user_registry_urls:
- 'https://apimserver.example.com/api/user-registries/0ec054a0-ceb8-457f-8d78-ae6b13fc6d3e/74456a8c-b28a-4699-ab8b-fa326e97eea1'
- 'https://apimserver.example.com/api/user-registries/0ec054a0-ceb8-457f-8d78-ae6b13fc6d3e/e634f0e3-42f9-4951-aa89-e7cb57363a1b'3. Configuring the LDAP registry for Developer Portal login:
If you want to use your LDAP resource for Developer Portal login, you will need to configure it at the catalog of the Developer Portal in question. By configuring, you create a configured-catalog-user-registry resource.
Since this is performed by an API Manager user, you will need to login as one to do this:
apic login --server <mgmt-endpoint> --username <username> --password <password> --realm provider/<identity_provider>apic user-registries:list --server <mgmt_endpoint> --org <provider-org>apic configured-catalog-user-registries:create --server <mgmt-endpoint> --org <provider-org> --catalog <catalog> configured-registry.yaml
Sample configured-registry.yaml (requiring only the URL of the LDAP registry):
user_registry_url: 'https://apimserver.example.com/api/user-registries/e59b9393-fce9-41b9-89c4-167af67e645d/e634f0e3-42f9-4951-aa89-e7cb57363a1b'Note that the toolkit samples shown here are applicable to all other user registry types too. The only difference would be the registry specific properties (integration type and configuration).
