Third Party Providers

IBM Application Gateway (IAG) can be used as an OpenID Connect (OIDC) relying party with many third-party identity-as-a-service (IDaaS) providers. This scenario documentation walks through the process of how to configure IAG for various third-party providers. This documentation covers three providers specifically, the strategies that are illustrated can be applied to virtually any other third-party provider.

Architecture

IAG operates as a reverse proxy placed in front of heritage web applications that do not have support for federated single sign-on protocols such as OIDC or SAML. IAG does not authenticate users directly but instead acts as an OIDC relying party to a third-party identity provider (OIDC provider). IAG receives user attributes in the OIDC id_token as part of the single sign-on protocol.

An authenticated user session is established between a browser and IAG. Any of the users attributes received from the OIDC provider can be propagated to the heritage application by using various different identity-propagation, integration patterns. Examples include HTTP headers, LTPAv2 tokens, Kerberos or even JWTs.

IAG provides URL-level authorization based on values of any of the available user session attributes.

Common IAG Configuration

For illustrative purposes these steps, which are focused on SSO configuration, do not protect any application, but instead configures the built-in credential viewer local application. This application allows introspection of the credential attributes received in the id_token from the third-party OIDC provider.

See Credential Viewer application for more details.

The credential viewer local application can be configured with the following YAML:

server:
  local_applications:
    cred_viewer:
      path_segment: "ivcreds"
      enable_html:  true

The hostname www.mysp.ibm.com is used to access IAG in these examples. For demonstration purposes, the IAG server was run on the default port of 8443.

In the example scenario:

IAG is accessible at: https://www.mysp.ibm.com:8443/
The credential viewer application is accessed at https://www.mysp.ibm.com:8443/ivcreds.

IAG acts as an OIDC relying party, which requires a few key pieces of configuration information from the third-party identity provider. These values vary between providers. The OIDC standards-based integration helps ensure that the name and purpose of these parameters are the same.

This YAML contains the common properties of OIDC providers that need to be configured. Use this YAML as a template and provide the values from the third-party OIDC provider.

identity:
  oidc:
    discovery_endpoint: "https://OIDC_PROVIDER_HOST_PATH/.well-known/openid-configuration"
    client_id:          "CLIENT_ID_PROVIDED_BY_OIDC_PROVIDER"
    client_secret:      "CLIENT_SECRET_PROVIDED_BY_OIDC_PROVIDER"
    # Common scope values used for ODIC login - may vary between providers
    scopes:
      - "profile"
      - "email"

IAG provides extra configurable parameters when it is acting as an OIDC relying party. For most cases, it is not necessary to explicitly define these extra parameters and the default values can be used. In some scenarios, such as configuring against PingOne, extra parameters are required.

Redirect URI

When an OIDC relying party is configured at the partner OIDC provider, a required parameter is the redirect_uri. The redirect_uri is the location that a browser is redirected to with the authorization_code as part of the OIDC SSO flow. For IAG, this URL is a static URL https://<iag>/pkmsoidc.

In the example scenario guides, the redirect_uri used is https://www.mysp.ibm.com:8443/pkmsoidc.

Default IAG OIDC Relying-Party Behaviors

It is also beneficial to understand some of IAG's default OIDC relying party behaviors. Understanding these behaviors helps guide the choices that are required to configure with third-party OIDC providers.

OIDC Property	Default IAG behavior
Client authentication method	client_id and client_secret with basic-authentication (not post-body parameters)
response_type	The code response type is requested. The code response type is all that is needed for a standard OIDC login.

This scenario guide now continues for three different third-party identity providers. Each guide provides examples of configuring with the third-party services and extra provider-specific configuration capabilities.