Creating an organization-specific custom user registry
You can configure an organization-specific custom user registry to provide user authentication for the Developer Portal.
Before you begin
Custom user registries can be used for authenticating users to the Developer Portal, but cannot be used to secure APIs.
To configure a custom user registry as a resource in API Manager, the external user directory must be created and available to use with your API Connect ecosystem.
Also, a custom user registry definition for your external user registry must already have been created on the Cloud Manager, as you will need the information from this definition to set up the custom user registry. See Configuring a shared custom user registry for information.
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 user registry can be used for authenticating Developer Portal users in a specific provider organization. While a shared user registry can be used for authenticating Cloud Manager, API Manager, and Developer Portal users.
This topic describes how to configure an organization-specific custom user registry. If you want to create a shared registry, see Configuring a shared custom user registry for more information.- You can also create and manage 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.
Creating a custom user registry by using the API Manager UI
You configure a custom user registry by creating a new custom user registry resource, which references the custom user registry type that is defined in the Cloud Manager. To make the custom user registry available to the Developer Portal for user authentication, you must enable the registry in the associated Catalog. 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 resource
- 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. For example, my-custom-user-registry-type. Use the drop-down arrow to select different custom user registry types. The custom user registry type is defined in the Cloud Manager. 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 checkboxfalse
- 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 Developer Portal login
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 . In the Catalog User Registries section, click Edit, select the custom user registry, and click Save. For more information, see Creating and configuring Catalogs.Creating a custom user registry by using the developer toolkit CLI
You configure an organization-specific custom user registry by creating a new custom user registry resource that references the integration document that exists on the Cloud Manager. You use developer toolkit CLI commands to create the custom user registry, and to make the registry available to the Developer Portal, you must enable the registry in the associated Catalog. 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
apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider
--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 Local 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.
For more information about how to use the CLI, see Installing the toolkit, and Overview of the command-line tool.
Defining your custom user registry
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
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 is 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:
|
case_sensitive |
Determines whether your user registry is case-sensitive. Valid values are:
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:
|
email_required |
Determines whether an email address is required as part of the user onboarding process.
Valid values are:
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:
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:
|
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
apic user-registries:create --server mgmt_endpoint_url --org organization_name custom_config_file.yaml
where:mgmt_endpoint_url
is the platform API endpoint URL.--org organization_name
means that the registry will be created in your provider organization.custom_config_file
is the name of the YAML file that defines the configuration of your custom user registry.
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 organization-specific user registry is now created; see the following section for instructions on how to make the registry available to users.