Multiple OIDC providers

Configuring multiple OIDC providers

The identity/oidc configuration can be provided with the configuration for multiple providers.

identity:
  oidc:
    - name:               primary
      discovery_endpoint: https://primary.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration
      client_id:          819a7fb3-9853-4969-b9cc-e29ee73fa06f
      client_secret:      "@primary-client-secret"
    - name:               secondary
      discovery_endpoint: https://secondary.verify.ibm.com/oidc/endpoint/default/.well-known/openid-configuration
      client_id:          f6e4387b-9056-468f-ab78-610b27281df6
      client_secret:      "@secondary-client-secret"

The key field to note is the name field. The name field is used by IAG to determine which identity provider is used when the OIDC start URL is requested. If the name field is not provided, the name default is used.

The order of the provider definitions is important. The first provider that is given in the configuration is the provider IAG sends clients to when they are challenged for authentication.

Starting the authentication

The OIDC authentication flow is started in IAG by directing clients to the OIDC start URL /pkmsoidc?iss=<name>. When multiple OIDC identity providers are configured, IAG challenges the client to authenticate by using the first provided OIDC provider.

To start an OIDC authentication flow that uses a different OIDC provider, clients must be directed to the OIDC start URL that specifies the name given to the OIDC provider in the configuration. For example, clients who must authenticate by using the provider that is named secondary must be directed to the URL /pkmsoidc?iss=secondary to begin the authentication flow.

Where are you from (WAYF) examples

When IAG is configured to use multiple OIDC identity providers, many strategies can be used to determine which provider clients must be sent to for authentication. However, determining which identity provider clients use is not a function of IAG itself, IAG provides many mechanisms that can be used to help build a WAYF experience.

Browser-based or client-side WAYF

The simplest WAYF is to allow users to select which OIDC identity provider they use for authentication. For example, an implementation serves a static HTML page that provides links to the OIDC start URLs for each provider.

See the WAYF client-side (browser) example page.

Lua-based or server-side WAYF

Another strategy for determining which OIDC provider clients are redirected to is to use Lua transformation rules. Using this approach, the decision of where to redirect an OIDC provider can be made server-side.

See the WAYF server-side (lua) example page.

Selecting an OIDC provider by using a server-side decision is not an enforcement mechanism. Clients are still able to start OIDC authentication with any configured provider by accessing to /pkmsoidc?iss=<name> directly.