Authorisation store configuration
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
- 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 hashed storage is intended 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 will be disabled.
Additional access tokens, to facilitate token roll-over or for other needs,
can be configured by appending a dot (.) with a unique label to the property
name, e.g. as authzStore.apiAccessTokenSHA256.1=abc...
. Since v10.0.
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).
authzStore.code.lifetime=600
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.
authzStore.accessToken.defaultLifetime=600
authzStore.accessToken.jwsAlgorithm
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.
Supported JWS algorithms:
- RS256 (recommended)
- RS384
- RS512
- PS256
- PS384
- PS512
- ES256
- ES256K
- ES384
- ES512
- EdDSA (with Ed25519 curve key, recommended for compact high-performance signatures)
authzStore.accessToken.jwsAlgorithm=RS256
authzStore.accessToken.jweAlgorithm
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.
Supported JWE algorithms:
- dir
authzStore.accessToken.jweAlgorithm=dir
authzStore.accessToken.jweMethod
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.
Supported JWE methods:
- A128GCM (recommended)
- A192GCM
- A256GCM
- A128CBC_HS256
- A192CBC_HS384
- A256CBC_HS512
- XC20P
authzStore.accessToken.jweMethod=A128GCM
authzStore.accessToken.allowDirectInspection
If true
an access token can be inspected without presenting the master
Bearer access token to the authorisation store web
API.
authzStore.accessToken.allowDirectInspection=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.
Supported profiles:
- c2id-1.1 -- Connect2id server specific profile, available since v7.17, with the JWT "typ" (type) header set to "at+jwt". This is the default profile if not specified.
- c2id-1.0 -- Connect2id server specific profile, available since v1.0, 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 names must be specified as comma and / or space separated list. If a custom JWT codec is plugged in this setting has no effect. Since v12.13.
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 names must be specified as comma and / or space separated list. If a custom JWT codec is plugged in this setting has no effect. Since v12.13.
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).
Since v8.2.
To set the default refresh token lifetime to one week:
authzStore.refreshToken.defaultLifetime=604800
authzStore.refreshToken.alwaysUpdate
If true
causes the refresh token to be updated (rotated) on each
authorisation update and on each refresh token use. Applies to long-lived
authorisations only, the refresh tokens for short-lived (transient)
authorisations are not affected. The default value is false
(no update).
authzStore.refreshToken.alwaysUpdate=false
5. 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).
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.
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).
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