Airlock IAM as OIDC client with discovery configuration

The instruction-lists in this chapter apply to the Loginapp REST API only.

Procedure-related prerequisites

  • The previously described configuration steps have been carried out.
  • You need to be logged in to the Airlock IAM Adminapp and be able to access the Config Editor.
  • The credentials for the connection to the remote authorization server must be available.

Basic Settings

  1. Go to and if necessary create:
         Loginapp ► OAuth 2.0/OIDC Clients ► OIDC Discovery Flow Client
  2. Provider identifier must hold the identifier of the remote authorization server
  3. Client ID holds the identifier which Airlock IAM uses as a client at the remote authorization server
  4. Client Secret is a string generated by the remote authorization server during registration of Airlock IAM as a client. This string is used like a password.
  5. Airlock IAM can successfully connect to the OIDC REST endpoints of the remote authorization server

To retain existing account links when migrating from JSP-Loginapp to Login REST UI, it is possible to configure the OAuth 2.0 or OIDC client settings with the identical Provider Identifier.

It is important that the configuration of the OAuth 2.0 or OIDC client settings for both providers are configured identically to ensure that all account links connect to the same remote authorization server for authentication.

Communication and Discovery

  1. HTTP Client Config must hold a HTTP Client Config plugin that configures the http connection to the remote authorization server.
  2. Discovery Endpoint URL configures the URL of the remote authorization server to retrieve the openid-configuration metadata.
  3. Cache Refresh Time configures the interval at which the openid-configuration metadata is refreshed..
  4. Airlock IAM can configure itself from the remote authorization server's openid-configuration metadata.

Authorization Request

  1. Claims to Request configure a list of claims that the remote authorization server should be able to supply. The remote authorization server may omit claims that are not marked essential. If the external authorization server cannot supply all essential claims, the authorization code flow will fail.
  2. ACR Values Claim configures an Authentication Context Class Reference (ACR) to be requested from the external authorization server and configure validators to ensure the requested ACR has been met.
  3. Include Nonce configure if OIDC replay attack mitigation is enabled. It is recommended to enable this option.
  4. Include Language Parameter configure if the client should request the language parameter from the browser and propagate it to the remote authorization server.
  5. Max Authentication Age configure the maximum age of the authenticated session at the remote authorization server.
  6. Send Prompt Parameter configure if user interaction at the remote authorization server is mandatory, optional or prohibited.
  7. Scope To Request contains a list of all scopes the remote authorization server should supply.
  8. Client Redirect URI is used by the remote authorization server after successful authentication of the user to deliver the authorization code. Choose a plugin from the following table:

    9. Plugin

    Redirect URI properties

    OAuth 2.0 REST UI Client Redirect URI

    This is the default setting.

    It contains the external base URL of IAM as it must be used by the remote authorization server.

    IAM will complete the base URL with the correct path for the client.

    OAuth 2.0 Custom Client Endpoint Redirect URI

    Use this setting to hardcode an absolute URL to be used by the remote authorization server.

    OAuth 2.0 Legacy Client Endpoint Redirect URI

    Use this setting for backward compatibility, if the remote authorization server configuration cannot be changed.

    It contains the external base URL of IAM as it must be used by the remote authorization server.

    IAM will complete the base URL with the correct legacy path for the client.

    This plugin requires that the Legacy Client Endpoint Setting in the OAuth 2.0/OIDC Client plugin is configured.

    OAuth 2.0 No Redirect URI

    Use this plugin, if the remote authorization server should default to the already registered redirect URI.

  9. Airlock IAM can successfully start the authorize call and receive an authorization code.

Access Token Request

  1. Token Endpoint Authentication contains the method, how IAM as a client will authenticate to the remote authorization server. The following methods are supported:

    2. Plugin

    Authentication Method

    OAuth 2.0 Basic Auth Client Secret

    Basic Auth ist used to supply credentials.

    OAuth 2.0 Header Client Secret

    Use this method, if the remote authorization server requires a special header or format to be used.

    OAuth 2.0 No Client Secret Authentication

    This will omit authentication with the remote authorization server.

    OAuth 2.0 Parameter Client Secret

    Use this method, if the remote authorization server requires the credentials to be supplied as parameters in the request URL.

  2. Access Token Request Method defines how the request for access and refresh tokens is to be sent to the remote authorization server.
  3. Airlock IAM can request access and refresh token from the remote authorization server.

ID Token

  1. Signature Validator configure a plugin to validate the signature
  2. Custom Issuer Claim configure this option, if the external authorization server does not follow the standard for issuer claims.
  3. Audience Claim Validation Method configure how the audience claim is to be validated.
  4. Custom Audience Claim configures whether ACR values in the ID token are validated against the requested ACR values.
  5. Validate ACR Claim configures whether ACR values in the ID token are validated against the requested ACR values.
  6. Additional Claim Validators optionally configure additional validators for claims.
  7. Airlock IAM can successfully validate the claims contained in the id token.

Resource Mappings

  1. ID Token Resources defines how attributes, retrieved from the remote authorization server, are mapped locally.

    2. Plugin

    Resource mapping

    OAuth 2.0 Remote Username Resource

    Must be defined exactly once.

    Defines which attribute of the remote authorization server is used to identify the local user.

    OAuth 2.0 Remote Context Data Resource

    May be defined zero or more times.

    Matches an attribute from the remote authorization server to the configured local context data item.

    Optionally allows for the string to be transformed.

    OAuth 2.0 Remote User Role Resource

    May be defined zero or more times.

    Matches an attribute from the remote authorization server to the local roles.

    If multiple plugins are configured all the retrieved attributes are merged in to the local roles.

  2. Resource Requests is optional. It defines how additional resource endpoint (.e.g. Userinfo Endpoint) should be queried to retrieve additional claims.
  3. If Resource Requests are required, go to:
         OAuth 2.0 SSO Resource Request plugin
  4. Resource URL defines a URL of a remote server where the resource request is to be sent. This is often the remote authorization server.
  5. Contained Resources defines how attributes, retrieved from the remote server, should be interpreted:

    6. Plugin

    Resource mapping

    OAuth 2.0 Remote Username Resource

    May be defined at most once. Make sure there is no double configuration with the username from the id token.

    Matches an attribute from the remote authorization server to the username.

    OAuth 2.0 Remote Context Data Resource

    May be defined zero or more times.

    Matches an attribute from the remote authorization server to the configured local context data item.

    Optionally allows for the string to be transformed.

    OAuth 2.0 Remote User Role Resource

    May be defined zero or more times.

    Matches an attribute from the remote authorization server to the local roles.

    If multiple plugins are configured all the retrieved attributes are merged in to the local roles.

  6. Request Method defines if a GET or POST method is to be used.
  7. Access Token Config defines it the access token is sent as header or as parameter to the remote authorization server.
  8. Airlock IAM can successfully map all attributes retrieved from the id token or from the remote authorization server to the local user, roles and context data items.

Logout

  1. Call End Session Endpoint configures if the remote authorization server is to be notified of an RP initated logout.
  2. Post Logout Redirect URL URL provided to the external authorization server to redirect the user session after the logout has been performed. Choose the appropriate option:

    3. Plugin

    Resource mapping

    OAuth 2.0 Post Logiout Redirect Base URL

    Define a post logout URL.

    OpenID No Post Logout Redirect URL

    Use this plugin, if the remote authorization server handles the user agent redirect.

  3. Airlock IAM can handle logout interactions with the remote authorization server.