Configuring an OIDC user registry

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.

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

Note: Refresh tokens are not supported for a user in an OIDC user registry when accessing the Cloud Manager or API Manager user interfaces.

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.

  1. In the Cloud Manager navigation pane, click Resources Resources.
  2. Click User Registries.
  3. Click Create and select OIDC User Registry.
  4. 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
    • 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 apic user-registries topic in the Command Line tool reference section of this documentation.
    Summary Provide a brief description of the new registry.
    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.
    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 4.
    Table 4. 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.
    Client Information
    Fill in the settings as described in Table 5.
    Table 5. 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.
    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 6.
    Table 6. Additional security options
    Security parameter Description
    NONCE Enable the NONCE extension to prevent compromised requests from being used again (replayed).
    Proof Key for Code Exchange (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 7.
    Table 7. Advanced features
    Feature Description
    Auto onboard Allow users to execute calls to APIs without logging in first, provided they present a valid token issued by the OIDC provider.
    Always use the userinfo endpoint Configures the OIDC user registry to always fetch user data from the userinfo endpoint, if populated.
    Return third-party access token Include the third-party OIDC access token in the response.
    Return third-party id_token Include the third-party OIDC id_token in the response.
    User Mapping
    Fill in the settings as described in Table 8.
    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 8. 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.

Enabling the OIDC user registry

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

  1. On the navigation pane, click Settings Settings.
  2. Click User Registries > Edit.
  3. Click Edit in the section that corresponds to the application for which you are enabling the new user registry.
  4. Select the new OIDC user registry.
  5. 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.

You 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, in common with a Local User Registry, cannot be used to secure APIs on the gateway.
  • Because the interaction with the third party OIDC provider is handled by the Management server, the Management server is the application from the point of view of the third party OIDC provider. Your OIDC redirection endpoint, which is used by authorization server to send the token to the Management server, must be accessible to the OIDC provider through your firewall. 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, this information is not available until you have created your OIDC user registry in API Connect. You must therefore first register your application without this information, 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
For full details of the apic login command, see Logging in to a management server.

Defining your OIDC registry configuration

You define the configuration of your OIDC user registry in a YAML file. As a minimum, the YAML file must have the following content:
title: registry_title
integration_url: oidc_integration_url
case_sensitive: case_sensitivity_setting
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, you must 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 onboarded into the registry, you cannot change this setting.
  • 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
      Use the standard provider type for any OIDC provider that is compliant with the OIDC standard.
      Note: 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. 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
  • Linkedin
    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/v1/people/~:(id,first-name,last-name,picture-url,public-profile-url,email-address)?format=json'
scope: r_basicprofile r_emailaddress
field_mapping:
  username: emailAddress
  email: emailAddress
  last_name: lastName
  first_name: firstName
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
  • Twitter:
    request_endpoint: https://api.twitter.com/oauth/request_token'
authorization_endpoint: https://api.twitter.com/oauth/authenticate'
token_endpoint: 
    endpoint: 'https://api.twitter.com/oauth/access_token'
userinfo_endpoint:
    endpoint: 'https://api.twitter.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
  • WindowsLive
    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:
  username: preferred_username
  email: email
  last_name: last_name
  first_name: first_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:
  1. Determine the URL of your OIDC user registry by using the following command:
    apic user-registries:list --server mgmt_endpoint_url --org admin
  2. 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.
  3. 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
  4. 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.
  5. Press CTRL D to terminate the input.

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

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