Configuring an OIDC user registry in Cloud Manager

Configure a shared OIDC user registry for user onboarding and authentication when multi-factor authentication (MFA) is required.

You can create an OIDC user registry that is specific to a provider organization, or that is shared and available to all the provider organizations in your API Connect environment. An organization-specific OIDC user registry is used for onboarding and authenticating Developer Portal users, while a shared OIDC user registry can be used for onboarding and authenticating Cloud Manager, API Manager, and Developer Portal users.

This topic describes how to create a shared registry. For information on how to create an organization-specific registry, see Creating an OIDC user registry in API Manager.

Important: If you are using X (formerly known as Twitter) as your OIDC provider, API Connect supports only the OAuth 1.0a method, so your X application must be configured to use OAuth 1.0a. Other OIDC providers support OAuth 2.0.

API Connect provides two methods for creating an OIDC user registry in Cloud Manager, as described in the following sections:

Using the UI to configure an OIDC user registry
Using the CLI to configure an OIDC user registry

Using the UI to configure an OIDC user registry

Use the Cloud Manager application's user interface to configure a shared OIDC user registry when multi-factor authentication (MFA) is required.

In the Cloud Manager navigation pane, click Resources.
Click User Registries.
Click Create and select OIDC User Registry.
Important: Do not share user registries between the API Manager and the Developer Portal, or between Developer Portal sites when self-service onboarding is enabled or account deletions in any of the sites are expected. You should create separate user registries for them, even if the separate registries point to the same backend authentication provider (for example, an LDAP server). This separation enables the Developer Portal to maintain unique email addresses across the catalog, without API Manager needing the same requirement. It also avoids problems with users deleting their accounts from the Developer Portal that then affects their API Manager access.

On the Create OIDC User Registry page, use the fields in each of the following sections to configure the registry settings, and then click Create.

Many of the registry settings are preconfigured to simplify the configuration steps.

Provider Type

Use the settings in Table 1 to define the provider type.

Table 1. Provider Type settings
Field	Description
Provider Type	OIDC provider. Select one of the following supported OIDC providers: Facebook GitHub Google LinkedIn Slack X (formerly known as Twitter) Windows Live Standard OIDC (default value allows you to specify another provider)
Title	Provide a descriptive name for display purposes.
Name	Automatically generated. This name is used in CLI commands to reference the registry. For details of the CLI commands for managing user registries, see the toolkit CLI reference documentation.
Summary	Provide a brief description of the new registry.
Email required	Select this option 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 option 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.

Provider Endpoint

Automatically generated for most supported providers. In the Authorization Endpoint field, type the URL of the provider's authorization endpoint.

Token Endpoint

Fill in the settings as described in Table 2.

Table 2. Token Endpoint settings
Field	Description
URL	Preconfigured for most of the supported OIDC providers. Type the URL of the provider's token endpoint.
TLS	Select the TLS Client Profile for the token endpoint (OIDC must be configured to use TLS). Default is Default TLS Client Profile.

UserInfo Endpoint

Fill in the settings as described in Table 3.

Table 3. UserInfo Endpoint settings
Field	Description
URL	Preconfigured for most of the supported OIDC providers. Type the URL of the provider's userinfo endpoint. For LinkedIn, the endpoint changed and now uses the following value: `https://api.linkedin.com/v2/me` If you previously configure the OIDC registry using the legacy LinkedIn OIDC protocol, you do not need to specify this endpoint.
TLS	Select the TLS Client Profile for the userinfo endpoint (OIDC must be configured to use TLS). Default is Default TLS Client Profile.

Email Endpoint

Required for the legacy LinkedIn OIDC protocol.

Due to changes in LinkedIn, the configuration settings for the OIDC registry in API Connect also changed. If you are configuring a new OIDC registry for LinkedIn, you can leave the Email Endpoint field blank.

If you previously configured an OIDC registry for use with the legacy LinkedIn OIDC protocol, update your configuration by providing the Email endpoint settings as described in Table 4. The new setting is required for the legacy LinkedIn OIDC protocol.

Table 4. Email Endpoint settings
Field	Description
URL	For the legacy LinkedIn OIDC protocol, this field defaults to the following value: `https://api.linkedin.com/v2/emailAddress?q=members&projection=(elements*(handle~))` You can override the setting by typing in a new value.
TLS	Select the TLS Client Profile for the userinfo endpoint (OIDC must be configured to use TLS). Default is Default TLS Client Profile.

JWKS Endpoint

Fill in the settings as described in Table 5.

Table 5. JWKS Endpoint settings
Field	Description
URL	Type the URL of the read-only endpoint that contains the public keys' information in JWKS format.
TLS	Select the TLS Client Profile for the userinfo endpoint (OIDC must be configured to use TLS). Default is Default TLS Client Profile.

Logout

You can configure either of the following types of logout support, but not both:

Logout redirect:
Allows you to specify what the user sees after logging out of API Connect; for example, you might want to "redirect" the user to the OIDC provider's logout endpoint, or to another address. When the user logs out of API Connect, the browser is redirected to the specified URL for further processing by the specified URL.
RP-initiated logout:
Provides a more secure form according to the OpenID Connect RP-Initiated Logout 1.0 Profile. When the user logs out of API Connect, API Connect issues a POST request to the specified endpoint URL to clear the user's session. With this option, you can optionally provide an RP logout redirect endpoint URL as well.

Fill in the settings as described in Table 6.

Table 6. Logout options
Field	Description
Logout redirect URL	Optional. Provide a URL to redirect the browser when the user logs out of API Connect. If you use this option, do not enable the OIDC RP logout.
Enable OIDC RP logout	Select this option to use the RP-initiated logout instead of the conventional logout redirect. If you use this option, do not provide a Logout redirect URL. With the RP-initiated logout, you can optionally specify an RP-logout redirect URL.
URL endpoint that the RP will issue a POST request	Provide the URL to the endpoint where the POST request will be executed; for example, the authorization endpoint of the OpenID provider.
TLS	Select the TLS profile to use when sending the POST request to the OpenID provider endpoint.
RP logout redirect endpoint URL	Optional. Provide a URL where the OIDC provider can redirect after the logout operation. The URL functions as the `post_logout_redirect_uri`, as described in the OpenID Connect RP-Initiated Logout 1.0 Profile.
Include refresh_token in logout	Optional. Allow the refresh_token to be included, in addition to the id_token_hint, per the OpenID Connect RP-Initiated Logout 1.0 Profile.

Client Information

Fill in the settings as described in Table 7.

Table 7. Client Information settings
Field	Description
Client ID	Provide the client ID of the application that is registered with the selected OIDC provider.
Client Secret	Provide the client secret of the application that is registered with the selected OIDC provider. This field is optional when you create an OIDC directory of type Standard and set the Client Authentication Method to Data encoded form body. If you are not using the Client Secret, ensure that mutual TLS is configured with the OIDC provider. To enable mutual TLS, create a TLS profile and include it in the OIDC user registry setup.
Response Type	Preconfigured for most of the supported OIDC providers. Specify the data type of the response that will be received from the OIDC provider.
Scopes	Preconfigured for most of the supported OIDC providers. Specify the access scope for the OIDC provider.
Client Authentication Method	Preconfigured for most of the supported OIDC providers. Select the authentication method to be used with the OIDC provider. Options are: HTTP Basic authentication schema Data encoded form body

Additional Support

Optional. Select the additional security parameters described in Table 8.

Table 8. Additional security options
Security parameter	Setting name for CLI	Description
NONCE	`nonce`	Enable the NONCE extension to prevent compromised requests from being used again (replayed).
Proof Key for Code Exchange (PKCE)	`pkce`	Enable the PKCE extension to allow public clients to mitigate the threat of having the authorization code intercepted.

Advanced Features

Optional. Select the advanced features described in Table 9.

Table 9. Advanced features
Feature / UI Label	Setting name for CLI	Description
Auto onboard	`auto_onboard`	Allow users to executes calls to APIs without logging in first, provided they present a valid token issued by the OIDC provider. Note: Does not apply to consumer organizations.
Always use the userinfo endpoint	`userinfo`	Configures the OIDC user registry to always fetch user data from the userinfo endpoint, if populated.
Use Portal as Endpoint for external OIDC provider traffic	`proxy_redirect`	When authenticating users, redirect the external OIDC provider to communicate with the Developer Portal instead of API Manager.
Return third-party access token	`proxy_access_token`	Include the third-party OIDC access token in the response. Note: Enable this setting for debugging purposes only. This setting is not recommended for use in a production environment. When this setting is enabled, the token size will increase when a request is made to API Connect using the token. The larger token size might exceed the HTTP protocol limit, resulting in an ERR_HTTP2_PROTOCOL_ERROR or ERR_CONNECTION_CLOSED error. You can avoid the size issue by additionally enabling Return third-party access_token and id_token as separate claims so that the third-party tokens are not added to the access_token that is issued API Connect.
Return third-party id_token	`proxy_id_token`	Include the third-party OIDC id_token in the response. Note: Enable this setting for debugging purposes only. This setting is not recommended for use in a production environment. When this setting is enabled, the token size will increase when a request is made to API Connect using the token. The larger token size might exceed the HTTP protocol limit, resulting in an ERR_HTTP2_PROTOCOL_ERROR or ERR_CONNECTION_CLOSED error. You can avoid the size issue by additionally enabling Return third-party access_token and id_token as separate claims so that the third-party tokens are not added to the access_token that is issued API Connect.
Return third-party access_token and id_token as separate claims	`proxied_token_as_separate_claim`	Include the third-party OIDC tokens (the `proxy_access_token` and `proxy_id_token`) in the response as separate claims instead of adding them to the access_token issued by API Connect. To use this feature, you must enable at least one of the Return third-party access token and Return third-party id_token options. Separating the third-party tokens prevents them from affecting the size of the access_token issued by API Connect.
Token Relay	`token_relay`	Allow `access_token/refresh_token` to send in 302 redirect for logout
Userinfo POST	`post_userinfo`	If supported by your OIDC provider, by using HTTP POST method when contacting userinfo endpoint. Note: Not all OIDC providers support POST. Ensure that your OIDC provider supports this before you enable the feature.
Use IBM APIC token expiration setting from cloud	`override_provider_ttl`	Override the OIDC provider's token expiration setting with the access token and refresh token expiration settings that are configured in API Connect. For information on configuring the access token and refresh token expiration settings in API Connect, see Configuring timeouts for access tokens and refresh tokens.
Disable hash verification (CLI only)	`disable_hash_verification`	Disable `at_hash`, `c_hash`

User Mapping

Fill in the settings as described in Table 10.

Note: The User Mapping fields are preconfigured for most of the supported OIDC providers to minimize potential errors; use care when changing the settings. For the Standard OIDC option, contact your OIDC provider to obtain the details of the fields.

Table 10. User mapping settings
Field	Description
Username	The name of the field in the response token that contains the user's user name. Note: The Username field must be unique for this OIDC registry, because it identifies the user in the system and cannot be changed.
Email	The name of the field in the response token that contains the user's email address.
First name	The name of the field in the response token that contains the user's given name.
Last name	The name of the field in the response token that contains the user's surname.

Redirect URI: The Redirect URI section lists the endpoints to which the OIDC authorization server will redirect the authorization code. There is one endpoint for each API Connect organization type: Cloud administration, Provider organization, and Consumer organization. The redirect endpoint is required when a user registers their application with the OIDC provider. For example, if this OIDC user registry is used by a provider organization, the user must register the provider organization's redirect endpoint with the OIDC provider. These read-only fields are provided for you to copy the endpoint values as required.

Enabling the OIDC user registry

Complete the following steps to enable the new user registry for Cloud Manager, API Designer, or both.

On the navigation pane, click Settings.
Click User Registries > Edit.
Click Edit in the section that corresponds to the application for which you are enabling the new user registry.
Select the new OIDC user registry.
When you have finished enabling the registry, click Save.

Using the CLI to configure an OIDC user registry

Use the developer toolkit CLI to configure a shared OIDC user registry when multi-factor authentication (MFA) is required.

Configure an OIDC user registry by first defining the registry details in a configuration file. You then use a CLI command to create the registry, passing the configuration file as parameter. To make the registry available to the Developer Portal, you must enable the registry in the associated catalog.

Note:

An OIDC registry cannot be used to secure APIs on the gateway.
If you are using an OIDC user registry for login, The Management server handles the interaction with the third-party OIDC provider. The management server is considered the application from the perspective of the third-party OIDC provider. Therefore, your OIDC redirect endpoint on the management server, which the third-party authorization server uses to send the token, must be accessible to the OIDC provider. To ensure login functions, you must allow access if your API Connect environment is secured behind a firewall. This is true for user login on both API Manager and Cloud Manager.
If OIDC user registry is used for consumer login at the Developer Portal and Developer Portal is in the DMZ, you can use the proxy_redirect property. This allows the Developer Portal to act as the endpoint for proxying communication between the OIDC provider and API Connect.
When you register your application with the third-party OIDC provider, you are required to supply the associated OIDC redirect URI, https://consumer.mycompany.com/consumer-api/oauth2/redirect for example. However, you cannot access this information until you create your OIDC user registry in API Connect. First, register your application without this information and then update it later, as detailed in the instructions on this page.

Logging in to the Management server

Before you can create an OIDC user registry, you must log in to your management server from the CLI. 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 apic login command, see Logging in to a management server.

Defining your OIDC registry configuration

Define the configuration of your OIDC user registry in a YAML file. At a minimum, the YAML file must include the settings from the following list. For additional settings, see the tables provided with the UI version of the procedure in this topic.

title: registry_title
integration_url: oidc_integration_url
case_sensitive: case_sensitivity_setting
email_required: true_or_false
email_unique_if_exist: true_or_false
configuration:
  client_id: 'app_client_id'
  client_secret: 'my-client-secret'
  provider_type: oidc_provider_type

where:

registry_title is your chosen descriptive title for the user registry.
oidc_integration_url is the OIDC integration URL in your API Connect configuration. You can determine the OIDC integration URL by using the following CLI command:
```
apic integrations:list --server mgmt_endpoint_url --subcollection user-registry
```
case_sensitivity_setting determines whether your user registry is case-sensitive. Valid values are:
- true
- false
To ensure proper handling of user name capitalization, ensure that your case-sensitivity setting here matches the setting on the backend OIDC provider:
- Only set case_sensitive to true if the backend OIDC provider supports case-sensitivity.
- Set case_sensitive to false if the backend OIDC provider does not support case-sensitivity.
Note: After at least one user has been added to the registry, you cannot change this setting.
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.
app_client_id is the client ID of the application that is registered with the OIDC server, and must be in string format.
my-client-secret is the client secret of the application that is registered with the OIDC server, and must be in string format.
oidc_provider_type is the type of OIDC provider; specify one of the following values:
- facebook
- github
- google
- linkedin
- slack
- twitter
- windows_live
- standard
  Note:
  - Use the twitter provider type if your OIDC provider is X (formerly known as Twitter).
  - Use the standard provider type for any OIDC provider that is compliant with the OIDC standard.
    If the provider type is standard, you must include the following additional properties in the configuration section of your YAML file:
    authorization_endpoint: 'oidc_auth_endpoint' token_endpoint: endpoint: 'oidc_token_endpoint'
    where:
    
    oidc_auth_endpoint is the authorization endpoint on the OIDC server, and must be in string format.
    
    oidc_token_endpoint is the token endpoint on the OIDC server, and must be in string format.

Default OIDC configurations

For each OIDC provider type, API Connect assumes a default configuration, but you can override the default configuration properties in your YAML file.

Note: Endpoints are subject to change; when you create a registry you must verify the default endpoint provided by API Connect.

API Connect makes the best effort to update endpoints for the known OIDC user registry types. However the OIDC provider can change the endpoint at any time. It is the customer's responsibility to confirm that the endpoints provided by API Connect are supported by the OIDC provider and to update the OIDC configuration as needed.

The default configurations are as follows:

Facebook

authorization_endpoint: 'https://www.facebook.com/v3.1/dialog/oauth'
token_endpoint:
  endpoint: 'https://graph.facebook.com/v3.1/oauth/access_token'
userinfo_endpoint:
  endpoint: 'https://graph.facebook.com/me'
scope: email public_profile
field_mapping:
  username: email
  email: email
  last_name: last_name
  first_name: first_name

GitHub

authorization_endpoint: 'https://github.com/login/oauth/authorize'
token_endpoint:
  endpoint: 'https://github.com/login/oauth/access_token'
userinfo_endpoint:
  endpoint: 'https://api.github.com/user'
scope: 'read:user user:email'
field_mapping:
  username: login
  email: email
  last_name: name
  first_name: name

Google

authorization_endpoint: 'https://accounts.google.com/o/oauth2/v2/auth'
token_endpoint:
  endpoint: 'https://www.googleapis.com/oauth2/v4/token'
scope: openid profile email
field_mapping:
  username: email
  email: email
  last_name: family_name
  first_name: given_name

Some settings differ between the legacy configuration and the newer configuration. Be sure to use the correct settings for the LinkedIn protocol that you are using.

New OIDC protocol:

authorization_endpoint: 'https://www.linkedin.com/oauth/v2/authorization'
  credential_location: form_body
  field_mapping:
    email: email
    username: name
    first_name: given_name
    last_name: family_name
  scope: openid profile email
  token_endpoint:
    endpoint: 'https://www.linkedin.com/oauth/v2/accessToken'
  userinfo_endpoint:
    endpoint: 'https://api.linkedin.com/v2/me'

Legacy OIDC protocol:

authorization_endpoint: 'https://www.linkedin.com/oauth/v2/authorization'
token_endpoint:
  endpoint: 'https://www.linkedin.com/oauth/v2/accessToken'
userinfo_endpoint:
  endpoint: 'https://api.linkedin.com/v2/me'
email_endpoint:
  endpoint: 'https://api.linkedin.com/v2/emailAddress?q=members&projection=(elements*(handle~))'
scope: r_liteprofile r_emailaddress
field_mapping:
  username: emailAddress
  email: emailAddress
  last_name: localoizedLastName
  first_name: localizedFirstName
credential_location: form_body

Slack

authorization_endpoint: 'https://slack.com/oauth/authorize'
token_endpoint:
  endpoint: 'https://slack.com/api/oauth.access'
userinfo_endpoint:
  endpoint: 'https://slack.com/api/users.identity'
scope: identity.basic identity.email
field_mapping:
  username: user.email
  email: user.email
  last_name: user.name
  first_name: user.name

X (formerly known as Twitter)

request_endpoint: https://api.x.com/oauth/request_token'
authorization_endpoint: https://api.x.com/oauth/authenticate'
token_endpoint: 
    endpoint: 'https://api.x.com/oauth/access_token'
userinfo_endpoint:
    endpoint: 'https://api.x.com/1.1/account/verify_credentials.json'
oauth_signature_method: 'HMAC-SHA1'
field_mapping: 
    email: email
    first_name: name
    last_name: name
    username: screen_name

Windows Live

authorization_endpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize'
token_endpoint:
  endpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token'
scope: openid offline_access profile email
field_mapping:
  email: email
  username: preferred_username
  first_name: name
  last_name: name

Standard
```
response_type: code
scope: openid
field_mapping:
  username: sub
  email: email
  last_name: family_name
  first_name: given_name
credential_location: auth_header
```
Although this is the default configuration for the standard provider type, you should contact your OIDC provider to obtain the details of the fields that you need to define.

Creating your OIDC user registry

To create your OIDC user registry, use the following CLI command:

apic user-registries:create --server mgmt_endpoint_url --org admin oidc_config_file

where:

mgmt_endpoint_url is the platform API endpoint URL.
organization_name is the value of the name property of your provider organization.
oidc_config_file is the name of the YAML file that defines the configuration of your OIDC user registry.

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

registry_name registry_url

By default, the registry_name is derived from the title property in the configuration YAML file but you can override this by including a name property in the file. The registry_url is an internal URL that API Connect assigns to the registry.

After you have created your OIDC user registry, you must update your application registration with the third party OIDC provider to include the OIDC redirect URI; you can obtain this information by using the following command, which displays the details of the registry in the command window:

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

The required oidc_redirect_uri value is in the consumer: section; for example:

consumer:
  oidc_redirect_uri: https://consumer.mycompany.com/consumer-api/oauth2/redirect

Enabling your OIDC registry in a Catalog

If you want to make your OIDC registry available for onboarding and 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 OIDC user registry by using the following command:
```
apic user-registries:list --server mgmt_endpoint_url --org admin
```
Log in to the Management server as a member of a provider organization; enter 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: oidc_registry_url
```
where oidc_registry_url is the URL of your OIDC registry, obtained in step 1.
Press CTRL D to terminate the input.

For details of all the apic user-registries and apic configured-catalog-user-registries commands, see the toolkit CLI reference documentation.

You can also complete the operations described in this topic by using the API Connect REST APIs; see the API Connect REST API documentation.