OAuth AS config (AS-centric)
17.7.1. OAuth AS configuration - AS-centric

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.
  • This is the only point in the configuration where the AS-centric implementation can be configured.
  • 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
  • Client Credentials Grant
The detail 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 consents
  • 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.
MAIN SETTINGS >> Application Settings >> OAuth 2.0 AS Access Configs (JSP Loginapp)
Every OAuth 2.0 AS Access Config protects the authorization code grant/flow exposed by this authorization server.
OAuth 2.0 AS Access Config is evaluated after user authentication and before consent is granted and tokens are issued.
Access Config configures:
  • Required roles
  • Airlock Gateway (WAF) Roles
  • Specific Access Policy
  • GDPR Consent and ToS
Loginapp >> Authentication Flows >> Target Application >> Authentication Flow (Flow and Loginapp REST UI)
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 (Loginapp REST UI)
To use the Loginapp REST 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: 17.7.1.2. AS-centric AS - 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: 12.6.4. 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 12.6.3.5. 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 13.3.2.4. AS-centric AS - 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 to 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.
Migrate Client-centric Tokens
Enable backward compatibility with an existing client-centric authorization server. See 13.3.1.9. AS-centric AS - seamless migration for more details