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:
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.
- 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: - GitHub
- Slack
- 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.
- On the navigation pane, click Settings.
- Click .
- 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.
- 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
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
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
- Only set
case_sensitive
totrue
if the backend OIDC provider supports case-sensitivity. - Set
case_sensitive
tofalse
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 thestandard
provider type for any OIDC provider that is compliant with the OIDC standard.Note: If the provider type isstandard
, you must include the following additional properties in theconfiguration
section of your YAML file:
where:authorization_endpoint: 'oidc_auth_endpoint' token_endpoint: endpoint: 'oidc_token_endpoint'
- 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:
Creating your OIDC user registry
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.
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.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
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.