Configuring a shared custom user registry

You can configure a custom user registry to provide user authentication for the Cloud Manager, the API Manager, and the Developer Portal.

Before you begin

To configure a custom user registry as a resource in the Cloud Manager, the external user directory must be created and available to use with your API Connect ecosystem.

Custom user registries can be used for authenticating users to the Cloud Manager, the API Manager, and the Developer Portal, but cannot be used to secure APIs.

One of the following roles is required to configure a custom user registry:

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

About this task

You can create a custom 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 custom user registry can be used for authenticating Developer Portal users, while a shared custom user registry can be used for authenticating Cloud Manager, API Manager, and Developer Portal users.

This topic describes how to configure a shared custom user registry. If you want to create an organization-specific registry, see Creating an organization-specific custom 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:

You can also create custom user registries by using the API Connect REST APIs (see the API Connect REST API documentation).

You can use the following instructions to create a writable or a read-only custom user registry.

API Connect provides two methods for creating a shared custom user registry in the Cloud Manager, as described in the following sections:

Creating a shared custom user registry by using the Cloud Manager UI
Creating a shared custom user registry by using the developer toolkit CLI

Creating a shared custom user registry by using the Cloud Manager UI

You configure a custom user registry by first creating a custom user registry type that defines your external user registry, and then creating a new custom user registry resource that references the custom user registry type that you just created. To make the registry available for user authentication, you need to add the registry to the Cloud Manager, or to the API Manager, or both, depending on your requirements. When the custom user registry is used for authentication, API Connect makes a REST call to the endpoint of your external registry, as defined in the custom user registry type.

Creating a custom user registry type

Use the following instructions to create a custom user registry type that defines your external user registry.

In the Cloud Manager, click Resources.
Click Create in the User registry type section.

Enter the following information:

Property	Description
Title	A descriptive name of the custom user registry type to display in the UI. For example, `My custom user registry type`.
Name	The name of the user registry type. This name is auto-generated, and is used in CLI commands.
Version	The version number of the custom user registry type.
Summary	A brief description of the custom user registry type.
Properties	Enter the properties of your external user registry. Must include the property: `remote: true` This property must be set to `true` to indicate that this is an external user registry.
Secured Endpoint	Denotes the external registry secured endpoint section of the custom user registry type.
URL	The secure endpoint of your external user registry interface, where your platform REST API is located. It is made up of the URL and port, for example: `https://custom.ms.com:8888` API Connect will make REST calls to this endpoint for the user registry actions.
TLS Client Profile	Optionally set the TLS Client Profile URL that the custom server requires.
Headers	Optionally complete the user-defined header section to your external registry specification.
Configuration schema	Optionally complete the user-defined configuration schema section to your external registry specification.

Click Create. A new user registry with a Type of Custom is displayed in the User registry type list.

Creating a custom user registry resource

Use the following instructions to create a new custom user registry resource that references the custom user registry type that you just created.

Click Create in the User Registries section of Resources.
Click the Custom user registry tile.

Enter the following information:

Property	Description
Custom type	The name of the custom user registry type that you just created. For example, `my-custom-user-registry-type`. Use the drop-down arrow to select different custom user registry types.
Title	A descriptive name to display in the UI.
Name	The name of the custom user registry. This name is auto-generated, and is used in CLI commands.
Summary	A brief description of the custom user registry.
Endpoint	Optional endpoint information.
Case sensitive	To ensure proper handling of user name capitalization, you must ensure that your case-sensitivity setting here matches the setting on your backend server: Only select Case sensitive if your backend server supports case-sensitivity. Do not select Case sensitive if your backend server does not support case-sensitivity. Note: The Developer Portal does not support case sensitive usernames. After at least one user has been onboarded into the registry, you cannot change this setting.
User registry managed	Determines whether API Connect manages your user registry. Valid values are: `true` - select the checkbox `false` - clear the checkbox
User managed	Determines whether your user registry is writable or not. Select the checkbox to set to `true` for writable. Clear the checkbox for the non-writable option.
Email required	Select this checkbox if an email address is required as part of the user onboarding process. If selected, 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.
Unique email address	Select this checkbox if email addresses must be unique within the user registry. 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.

Click Create. The new user registry is displayed in the User registries list.

Adding your custom user registry to the Cloud Manager or API Manager login

To make the custom user registry available for user authentication in the Cloud Manager or the API Manager, you must set it as active in the Settings > User Registries section of the Cloud Manager UI. See Selecting user registries for Cloud Manager and API Manager for more information.

If you want to make the custom user registry available for authenticating Developer Portal users, you must enable it in the Catalog that is associated with that Developer Portal. In the API Manager UI, click Manage followed by the relevant Catalog, and then click Catalog settings > Onboarding. In the Catalog User Registries section, click Edit, select the user registry, and click Save. For more information, see Creating and configuring Catalogs.

Creating a shared custom user registry by using the developer toolkit CLI

You configure a custom user registry by first configuring an integration document that defines your external user registry, and then creating a new custom user registry resource that references the integration document that you just created. You use developer toolkit CLI commands to create the integration document, and then the custom user registry. 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. When the custom user registry is used for authentication, API Connect makes a REST call to the endpoint of your external registry, as defined in the integration document.

Logging in to the management server CLI

Before you can define the custom user registry, 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 integration document

You define the configuration of your external user registry in an integration_file.yaml document, as shown in the following example.

integration: '1.0.0'
integration_type: 'user_registry'
info:
  name: 'custom_user_registry'
  version: '1.0.0'
  title: 'Custom External User Registry'
  summary: 'Configure External User Registry'
properties:
  remote: true 
secured_endpoint:
  endpoint:  'https://custom.ms.com:8888'
  tls_client_profile_url: {$tslClientProfileUrl}
headers:
  key1: value1
  key2: value2
configuration_schema:
  option_config1:
     type: string
  option_config2:
     type: boolean

The integration document properties are described in the following table:

Property	Description
`integration_type`	The type of integration, which in this case is `user_registry`.
`info`	Denotes the information section for the integration document.
`name`	The name of the user registry type, for example `custom_user_registry`. This name is used in the user registry file to denote the registry type.
`version`	The version number of the integration document.
`title`	A descriptive name to display in a graphical user interface.
`summary`	A brief description of the integration document.
`properties`	Denotes the property section of the integration document.
`remote`	Indicates that this is an external user registry. Must be set to `true`.
`secured_endpoint`	Denotes the external registry endpoint section of the integration document.
`endpoint`	The secure endpoint of your external user registry interface, where your platform REST API is located. It is made up of the url and port, for example: `https://custom.ms.com:8888` API Connect will make REST calls to this endpoint for the user registry actions.
`tls_client_profile_url`	Optionally set the TLS Client Profile URL that the custom server requires.
`headers`	Complete the user-defined header section to your external registry specification.
`configuration_schema`	Complete the user-defined configuration schema section to your external registry specification.

Save your integration_file.yaml so it can be accessed by the integrations:create command in the following section.

Creating your custom integration

To create your custom user registry integration, run the following CLI command:

apic integrations:create --server mgmt_endpoint_url --subcollection user-registry integration_file.yaml

where:

mgmt_endpoint_url is the management platform API endpoint URL.
integration_file is the name of the YAML file that defines the configuration of your external user registry.

At this point API Connect makes a REST request call to the endpoint that is configured in the integration document, and the external platform REST API will need to return the requested information.

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

integration_name custom_integration_url

The integration_name is derived from the name property in the configuration YAML file. The custom_integration_url is the URL with which the integration can be accessed. Both properties are needed when defining your custom user registry in the next section.

After your custom integration has completed successfully, you can continue to create the custom user registry.

Defining your custom user registry

You define the configuration of your custom user registry in a custom_config_file.yaml file, as shown in the following example.

name: 'custom_registry_name'
title: 'display_title'
registry_type: 'custom_user_registry'
integration_url: custom_integration_url
case_sensitive: true_or_false
user_managed: true_or_false
user_registry_managed: true_or_false 
email_required: true_or_false
email_unique_if_exist: true_or_false
identity_providers:
 - name: provider_name
   title: 'provider_title'
configuration:
  custom_config1: 'value1'
  customize: true

The registry properties are described in the following table:

Property	Description
`name`	The name of the custom user registry. This name is used in the CLI commands.
`title`	A descriptive name to display in a graphical user interface.
`registry_type`	The registry type that you configured in the `name` property in the integration document, for example `custom_user_registry`.
`integration_url`	The custom integration URL in your API Connect configuration. You can determine the custom integration URL by using the following CLI command: `apic integrations:list --server mgmt_endpoint_url --subcollection user-registry` Or you can copy and paste from the summary of the integration creation.
`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.
`user_managed`	Determines whether your user registry is writable or not. Must be set to `true` for writable. Set to `false` if you don't want the registry to be writable.
`user_registry_managed`	Determines whether API Connect manages your user registry. Valid values are: `true` `false`
`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 custom server, where: `name` - is the name of the custom server and is the name that is used in CLI commands `title` - is the display name of the custom server
`configuration`	The user-defined configuration based on the `configuration_schema` that is defined in the integration document.

Save your custom_config_file.yaml so it can be accessed by the user-registries:create command in the following section.

Creating your custom user registry

To create your shared custom user registry, run the following CLI command:

apic user-registries:create --server mgmt_endpoint_url --org admin custom_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.
custom_config_file is the name of the YAML file that defines the configuration of your custom 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 custom user registry YAML file. The registry_url is the URL with which the custom registry resource can be accessed.

Your shared custom user registry is now created; see the following sections for instructions on how to make the registry available to users.

Configuring your custom registry for Cloud Manager or API Manager login

If you want to make your custom registry available for authenticating Cloud Manager and API Manager users, you must configure it on the management server.

Determine the URL of your custom 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
```

Determine what the current user registries are, because you will need to confirm these as well as add your new custom 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'

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
```
If you want to make your custom 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_custom_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_custom_user_registry_url is the URL of your new custom user registry, as determined in Step 1.
If you want to make your custom 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_custom_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_custom_user_registry_url is the URL of your new custom user registry, as determined in Step 1.
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 custom registry in a Catalog

If you want to make your custom 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 custom 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
```
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.
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: custom_registry_url
```
where custom_registry_url is the URL of your custom registry, obtained in step 1.
Press CTRL D to terminate the input.