Configuration of IAM as OAuth Authorization Server / OpenID Provider

Authorization Server configuration

The flexibility of the OAuth 2.0 and OIDC implementation in Airlock IAM results in a rather large and complex configuration. The information presented here should help navigate this complexity:

Menu Entry

Purpose

Loginapp >> OAuth 2.0/OIDC Authorization Servers

Configuration of OAuth 2.0 and OIDC. It resides directly under the Loginapp root menu.

  • On this level, it is possible to configure multiple authorization servers

Authorization Server

Configuration of the individual authorization servers:

  • Name and issuer of the authorization server
  • Grants or flows
  • Endpoints
    • shared endpoints between OAuth 2.0 and OIDC
    • OIDC specific endpoints
  • Clients both static and dynamic

OAuth 2.0 Grants/OpenID Connect Flows

Configuration of the grants and flow this authorization server supports.

  • OAuth 2.0 Authorization Code Grant
  • OIDC Authorization Code Flow
  • OIDC Hybrid Flow
  • Client Credentials Grant
  • Token Exchange Grant

The detailed configuration covers:

  • Tokens that are used with this grant or flow:
    • Toke lifetimes
    • ID token claims
    • Token format of access tokens (custom JWT or opaque)
  • Local and remote consent.
  • ACR and scopes.
  • Login hint.
  • Target application.

The current implementation does not support using OAuth 2.0 grants and OIDC flows in the same authorization server.

Loginapp >> Applications and Authentication >> Target Application >> Authentication Flow

The target application defines the authentication flow to be used for user authentication.

The target application must contain an OAuth 2.0/OIDC ID Propagator.

The authentication flow must contain an OAuth 2.0 Consent Step.

Loginapp >> UI Settings >> Authentication UIs

To use the Loginapp UI with the authentication flow and the AS an Authentication & Authorization UI must be configured.

Basic Settings

Identifier

The Identifier uniquely identifies the authorization server.

It is used in all URL paths of all endpoints exposed by this authorization server.

Issuer ID

The Issuer ID is an URL that identifies the authorization server.

It is used as a prefix to all endpoints. Append

  • /.well-known/openid-configuration for the OIDC discovery endpoint
  • /.well-known/oauth-authorization-server for the OAuth 2.0 metadata endpoint

Clients

The authorization server does support both statically configured clients and clients registered through dynamic client registration.

Static Clients

Configure a client with a minimal set of attributes.

Persisted Clients

Configure the data persister, where dynamically registered clients are stored.

To configure dynamic client registration see: Dynamic client registration configuration

OAuth 2.0/OIDC persisted clients are handled like regular tech-clients. The main difference is that they use the OAuth 2.0/OIDC specific client-id/client-secret credentials for authentication of the client.

For more information on tech-clients and their management see: Technical client in IAM and tech-clients REST API.

Endpoints and OpenID Connect Endpoints

In these two sections, all the REST endpoints are configured. All the endpoints share the following properties:

  • Most Endpoints are optional. If an endpoint is not configured, the authorization server will work without the functionality of this endpoint.
  • The JWKS endpoint is always present. It will provide public keys to verify the signatures of ID tokens and JWT access tokens. If neither ID tokens nor JWT access tokens use private key signatures (e.g. using MACs) the JWKS endpoint will return an empty key set.

Endpoints

The following table describes the configuration of each endpoint and in particular the authentication options available to use the endpoint:

Endpoint

Configuration Options

Special properties

Authentication Options

Metadata Endpoint

Configure the issuer validation mode. Verifies that the URL data provided as metadata matches the URL that was used to request this metadata.

Default is Fail, to ensure that clients receive correct URL information.

no authentication

Token Endpoint

  • client authentication is configurable:
    • client_id/client_secret
    • mTLS authentication
    • no authentication
  • Scopes to remove on refresh
    • Use this option, if you need to differentiate between tokens issued during the initial grant or flow and tokens issued during a token refresh.

client_id/client_secret
as HTTP Basic Auth or POST parameter

mTLS authentication is supported for PSD2. See TPP Authentication using client certificates and OAuth 2.0 for STET for more information

no authentication

Token Introspection Endpoint

  • configure username/password

The configured username and password are used as a shared secret for resources that access the introspection endpoint.

The return values are predefined as

  • sub: username of the user
  • scope: list of scopes
  • active: true|false
  • exp: expiration time of the token
  • iat: issuing time of the token
  • client_id: identifier of the client that the token was issued to

Token introspection is only possible with tokens obtained from an authorization code grant/flow.

Token introspection will fail for tokens obtained with a client credentials grant.

HTTP Basic Auth

Token Revocation Endpoint

Configure revocation strategies for access and refresh tokens:

  • single token only revokes the token supplied. The default for access token revocation.
  • revokes all tokens that were derived from an authorization code grant/flow. The default value for refresh token revocation.

no authentication or client_id/client_secret
as HTTP Basic Auth or POST parameter

access or refresh token must be provided as a parameter

Resource Endpoint

Multiple resources may be configured

  • list of resources

Each resource is identified with a resource-id and aggregates multiple data elements:

  • username
  • user roles
  • string context data items
  • date and local date context data items
  • SSO tickets
  • Static strings

The resource-id must be used by a client accessing this resource to identify it.

To learn more about the purpose and use of SSO tickets in OAuth 2.0 / OIDC see Forced user re-authenticate

access token
in Authorization header

Session Management Endpoint

Configure an optional list of custom attributes that will be available in every session.

Authorized clients may read and optionally write certain custom attributes.

access token
in Authorization header

Dynamic Client Registration

The configuration of dynamic clients requires three parts:

  • generator for client_id and client_secret
  • supported grants
  • processors for claims provided by the client

OpenID Connect Endpoints

Endpoint

Configuration Options

Special properties

Authentication Options

Discovery Endpoint

Configure the issuer validation mode. Verifies that the URL data provided as metadata matches the URL that was used to request this metadata.

Default is Fail, to ensure that clients receive correct URL information.

no authentication

Userinfo Endpoint

Standard claims use specialized plugins to add the claim information to the Userinfo response.

Custom claims can be configured to include any context data item in the Userinfo response.

The Userinfo endpoint will only return those claims that have a value. Empty claims are omitted from the response.

Claims provided by the Userinfo Endpoint are configured independently of Claims configured for the ID token.

The standard claim phone number refers to the context data item mtan_number and not the device token for mTAN.

access token
in Authorization header

Persistency

In this section the database storage is configured:

Storage

Comment

User Data Source

In most cases, you may re-use the “Database User Persister” that is already configured.

Token Data Provider

In most cases, you may re-use the “Default Token Data Provider” that is already configured.

Session Repository

The session repository is an independent storage area that is only used for OAuth 2.0 and OIDC session management.

Advanced Settings

Setting

Purpose

Username Transformation

Use this setting if the internal username should not be exposed in the OAuth 2.0/OIDC endpoints and tokens

Role Transformation

Use this setting if roles need to be added, deleted, kept, or transformed.

Token Generator Settings

Tokens are stored in the database as hashes and never in plaintext. This setting configures the parameters for the hash function.

If you configure a very complex hash function (e.g. scrypt) this may degrade the overall system performance when many requests with access tokens are being made.

Logging Settings

Use this setting to generate more log output and to optionally include all tokens values in the log output.

These options should only be used to integrate a system. Since tokens in the log may be used to compromise user credential security.

Delete Tokens On Logout

Enable this option to delete all tokens and sessions on user logout.

Delete Tokens On Password Change

A security feature that ensures that all tokens are invalidated when a user changes the password.

Delete Tokens On User Locked

A security feature that ensures that all tokens are invalidated when a user account is locked.

Persist Claims

Enabling this option will persist all claims at the end of the user authentication so they are available during token refresh.

Cache-Control Response Header

The Cache-Control header is used to specify browser caching policies. With the Cache-Control Response Header setting, you can configure a Cache-Control response header, for the following endpoints:

  • /auth-login/rest/oauth2/authorization-servers/{authorizationServerId}/jwks/
  • /auth-login/rest/oauth2/authorization-servers/{authorizationServerId}/.well-known/openid-configuration/
  • /auth-login/rest/oauth2/authorization-servers/{authorizationServerId}/.well-known/oauth-authorization-server/

Multiple, comma-separated values are allowed. For example: public, max-age=3600. Here, public means that reponses can be cached in a non-private, shared cache. max-age=3600 defines the maximum amount of time in seconds that fetched responses are allowed to be used again.

If the setting is left empty (default), the Cache-Control response header is set to no-store, no-cache, must-revalidate. This means that returned responses

  • should either not be stored (no-store),
  • or can be stored, but should be validated with the origin server before each reuse (no-cache),
  • or can be reused for subsequent requests to the same endpoint if fresh, but should be validated with the origin server if stale (must-revalidate).

 
Info

It is good practice to reset all OAuth sessions after security-critical end-user actions such as setting a new password. Changing the password, for example, maybe the result of the existing password having been stolen or revealed to non-legitimate persons.

To do so, use the OAuth 2.0 Session Reset Step in the corresponding self-service flows.

Chapter content