Authorisation store

The Connect2id server has a dedicated authorisation store to track or persist the following OAuth 2.0 objects:

Authorisation codes, until they get exchanged for a token, or expire.
Identifier-based access tokens, until they expire or get revoked. Self - contained (JWT-encoded) are not saved on the server.
Refresh tokens, until they get revoked or expire (unless the refresh token is permanent).
Long-lived (persisted) OAuth 2.0 authorisations, to remember previously given consent by end-users to clients, until the authorisation gets revoked.
Revocation journal entries.

The authorisation store configuration is located in the following file:

WEB-INF/authzStore.properties

The configuration properties are grouped into sections:

Web API settings
Authorisation code settings
Access token settings
Refresh token settings
Revocation settings
Miscellaneous options

Any property in the configuration file can be overridden with a Java system property, e.g. by setting the optional -D argument at JVM startup:

-DauthzStore.code.lifetime=1200

The external configuration guide has tips for setting system properties from environment variables, local files and other locations.

1. Web API

authzStore.apiAccessTokenSHA256

The access token for the authorisation store web API, represented by its SHA-256 hash (in hexadecimal format). The hash is a measure to prevent accidental leakage of the token through configuration files, logs, etc. The token is of type Bearer, non-expiring and must contain at least 32 random alphanumeric characters to make brute force guessing impractical. If not specified the web API is disabled.

Additional access tokens, for token roll-over or other needs, can be configured by appending a dot (.) with a unique label to the property name, e.g. as authzStore.apiAccessTokenSHA256.1=abc....

The hash for a token with value ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6:

authzStore.apiAccessTokenSHA256=cca68b8b82bcf0b96cb826199429e50cd95a042f8e8891d1ac56ab135d096633

authzStore.secondaryAPIAccessTokenSHA256

Optional secondary access token for the authorisation session store web API. Has the same format as sessionStore.apiAccessTokenSHA256. Must not be set if not needed.

Use authzStore.apiAccessTokenSHA256.* from v10.0 on.

authzStore.secondaryAPIAccessTokenSHA256=304b07b6d8eb155a957b965831be9ce39fb098554a2d5f2047ee0a0491022dea

2. Authorisation code

The authzStore.code.* group contains a single property which sets the lifetime of issued authorisation codes.

authzStore.code.lifetime

The authorisation code lifetime in seconds. Should be long enough to permit a client to make a token request to exchange the code for an ID / access token. Must not be shorter than 0 seconds (1 minute) or longer than 600 seconds (10 minutes). The default value is 300 seconds (5 minutes).

authzStore.code.lifetime=300

3. Access token

The authzStore.accessToken.* properties set the default preferences of issued OAuth 2.0 access tokens such as lifetime and encoding.

authzStore.accessToken.defaultLifetime

The default access token lifetime in seconds. Can be overridden by individual authorisations. Must be a positive integer. The default value is 600 seconds (10 minutes).

authzStore.accessToken.defaultLifetime=600

authzStore.accessToken.jwsAlg

The JWS algorithm for signing the self-contained (JWT-encoded) access tokens. Must be a valid and supported RSA PKCS #1, RSASSA-PSS, ECDSA, or EdDSA JWS algorithm. The default value is RS256. Since v14.0.

Supported JWS algorithms:

RS256 (default, recommended)
RS384
RS512
PS256
PS384
PS512
ES256
ES256K
ES384
ES512
EdDSA (with Ed25519 curve key, recommended for compact high-performance signatures)

authzStore.accessToken.jwsAlg=RS256

authzStore.accessToken.jweAlg

The JWE algorithm for the self-contained (JWT-encoded) access tokens which are encrypted after signing. Only direct encryption (dir) with a shared AES key is supported. The default value is dir. Since v14.0.

Supported JWE algorithms:

dir (default)

authzStore.accessToken.jweAlg=dir

authzStore.accessToken.jweEnc

The JWE method for the self-contained (JWT-encoded) access tokens which are encrypted after signing. Must be a valid and supported AES/GCM, AES/CBC/HMAC/SHA-2, or ChaCha20-Poly1305 JWE method. The default value is A128GCM. Since v14.0.

Supported JWE methods:

A128GCM (default, recommended)
A192GCM
A256GCM
A128CBC_HS256
A192CBC_HS384
A256CBC_HS512
XC20P

authzStore.accessToken.jweEnc=A128GCM

authzStore.accessToken.includeX5C

Enables / disables inclusion of the X.509 certificate chain (x5c) header parameter in issued self-contained (JWT) access tokens when the signing JWK is provisioned with a certificate. The default value is true (enabled). Since v14.0.

authzStore.accessToken.includeX5C=true

authzStore.accessToken.allowDirectInspection

If true an access token can be inspected without presenting the master Bearer access token to the authorisation store web API. The default value is false (disabled).

authzStore.accessToken.allowDirectInspection=false

authzStore.accessToken.disableSubjectSecurity

When true disables the automatic encryption of self-contained (JWT-encoded) access tokens with public (non-pairwise) subject identifiers, in cases when the access tokens are issued to clients registered for pairwise subjects in ID tokens and UserInfo responses. The default value is false. Since v14.0.

authzStore.accessToken.disableSubjectSecurity=false

authzStore.accessToken.codec.jwt.profile

The JWT profile of access tokens minted by the default self-contained access token encoder / decoder. If a custom JWT codec is plugged in this setting has no effect. The default value is c2id-1.1.

Supported profiles:

c2id-1.1 – Connect2id server specific profile, with the JWT “typ” (type) header set to “at+jwt”. This is the default profile.
c2id-1.0 – Connect2id server specific profile, outputs identical JWT claims as c2id-1.1 but doesn’t set the JWT “typ” (type) header.
oauth-1.0 – Standard profile developed in the OAuth working group.

authzStore.accessToken.codec.jwt.profile=c2id-1.1

authzStore.accessToken.codec.jwt.copyClientData

Names of members in the client registration’s “data” JSON object to copy as top-level JWT claims in access tokens minted by the default self-contained access token encoder. An “*” (asterisk) selects all members. The member names can alternatively be specified as comma and / or space separated list. If a custom JWT codec is plugged in this setting has no effect. The default value is none.

To insert the org_id client registration data member (if present) as top-level JWT claim:

authzStore.accessToken.codec.jwt.copyClientData=org_id

authzStore.accessToken.codec.jwt.moveAuthzData

Names of members in the authorisation “dat” (data) JSON object to move to top-level JWT claims in access tokens minted by the default self-contained access token encoder. An “*” (asterisk) selects all members. The member names can alternatively be specified as comma and / or space separated list. If a custom JWT codec is plugged in this setting has no effect. The default value is none.

To move all present authorisation data members to top-level JWT claims:

authzStore.accessToken.codec.jwt.moveAuthzData=*

4. Refresh token

The authzStore.refreshToken.* properties set the default preferences of issued OAuth 2.0 refresh tokens.

authzStore.refreshToken.defaultLifetime

The default refresh token lifetime in seconds. Can be overridden by individual authorisations. If zero or omitted defaults to permanent (no expiration). Must be zero or a positive integer. The default value is zero (no expiration).

To set the default refresh token lifetime to one week:

authzStore.refreshToken.defaultLifetime=604800

authzStore.refreshToken.defaultRotate

The default refresh token rotation setting. Can be overridden by individual authorisations. The default value is false (no rotation). Since v14.0.

authzStore.refreshToken.defaultRotate=false

authzStore.refreshToken.alwaysUpdate

If true causes the refresh token to be updated (rotated) on each authorisation update and on each refresh token use. The default value is false (no update). Deprecated in v14.0.

authzStore.refreshToken.alwaysUpdate=false

authzStore.refreshToken.rotatedReuseGracePeriod

Grace period in seconds during which a client may repeat a request with the same rotated refresh token without triggering the customary token revocation. Intended to enable token request retrial on slow / poor networks where the HTTP response times out after issue of the new token. Currently supported only for refresh tokens linked to short-lived (transient) authorisations. The default value is 5 seconds. Since v14.2.

authzStore.refreshToken.rotatedReuseGracePeriod=5

5. Revocation

The authzStore.revocation.* properties control the token revocation.

authzStore.revocation.checkBias

Adjusts the checking of revocation timestamps by adding a negative or positive time bias, in seconds. The default value is 0 seconds (no bias). Since v15.5.

A token is deemed active (non-revoked) if there are no recorded revocations for the token subject and / or client ID after the token issued-at time (iat). The resolution of revocations and token issued-at times is in seconds.

With no (zero) bias tokens issued at the same second when a revocation is recorded are considered active (non-revoked). This enables a subject and / or client ID to have its tokens revoked and then be immediately issued again with active tokens, within the same second.
A positive bias of 1 ensures tokens issued within the same second of a revocation are considered revoked, preventing any ambiguity in the time sequence of revocation and token issue events. A bias greater than 1 should generally not be used.
A negative bias can mitigate false revocation positives in a Connect2id server cluster where the clocks of the individual server instances are out of sync.

authzStore.refreshToken.rotatedReuseGracePeriod=0

6. Authorisation store options

The authzStore.options.* properties contains two settings.

authzStore.options.highlyAvailableMode

With an enabled highly-available mode the authorisation store will continue providing basic service even if the backend database is down or disconnected. The required data will be served from the caches if possible and database connection exceptions will not cause requests to fail (they will be logged at ERROR level however). The default value is true (enabled).

authzStore.options.highlyAvailableMode=true

authzStore.options.discardedAttributes

List of the optional authorisation attributes that are to be automatically discarded from new authorisation objects, in order to conserve cache memory and back-end storage. The default value is none.

authzStore.options.discardedAttributes=

authzStore.options.legacyPlainKeysInStorage

If true the Connect2id server will support retrieval of legacy plain keys for identifier-based access tokens from storage after upgrading to Connect2id server 8.x, false to ignore such keys which will cause the introspection of the linked access tokens to flag them as invalid. Note that enabling this configuration imposes imposes additional database reads and a performance penalty during introspection. The default value is false (no support for legacy plain access token keys). Removed in v14.0.

authzStore.options.legacyPlainKeysInStorage=false

authzStore.options.issueLegacyRefreshTokens

If true the Connect2id server will issue refresh tokens in the legacy format supported up to v7.x. Intended to facilitate seamless rolling upgrades to v8.x and later. The default value is false (no issue of legacy refresh tokens).

authzStore.options.issueLegacyRefreshTokens=false