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 for a particular end-user to a client, until the authorisation gets revoked.
The authorisation store is based on a combination of a Infinispan data grid (provides in-memory storage of codes and access tokens, caches authorisations) and an LDAP directory server (persists the long-lived authorisations).
To edit the authorisation store configuration open the following properties
file in the WEB-INF
directory of the web application:
WEB-INF/authzStore.properties
The configuration properties are split into eight sections:
- Web API – to set the access token for querying and managing the authorisation store over its web API.
- Authorisation code settings – to set the lifetime of issued authorisation codes.
- Access token settings – to set the default preferences of issued access tokens.
- LDAP server details – to set the connection details of the LDAP server where long-lived authorisations are persisted.
- LDAP user details – to set the LDAP server connection credentials.
- LDAP directory entry details – to set the LDAP directory branch location and attribute names for persisting long-lived authorisations.
- Custom LDAP server trust and key store – to set a custom certificate trust and / or key key for secure LDAP connections.
- Authorisation store options – to set various authorisation store options.
Any configuration file property can be overridden by setting a system-wide
property with a matching key, e.g. by using the optional -D
argument at JVM
startup:
-DauthzStore.code.lifetime=1200
1. Web API
authzStore.apiAccessToken
The access token for the web API of the authorisation store. It is of type Bearer and non-expiring. Must contain at least 32 random alphanumeric characters to make brute force guessing impractical. If blank (unspecified) the web API will be disabled.
authzStore.apiAccessToken = ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
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 60 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 JSON Web Signature (JWS) algorithm for signing the self-contained (JWT-encoded) access tokens. Must be a valid and supported RSA-SSA JWS algorithm:
- RS256 (recommended)
- RS384
- RS512
- PS256
- PS384
- PS512
authzStore.accessToken.jwsAlgorithm = RS256
authzStore.accessToken.jweAlgorithm
The JSON Web Encryption (JWE) algorithm for the self-contained (JWT-encoded) access tokens which are encrypted after signing. Only direct encryption (dir) with a shared key is supported.
- dir
authzStore.accessToken.jweAlgorithm = dir
authzStore.accessToken.jweMethod
The JSON Web Encryption method for the self-contained (JWT-encoded) access tokens which are encrypted after signing. Must be a valid and supported JWE method.
- A128GCM (recommended)
- A192GCM
- A256GCM
- A128CBC_HS256
- A192CBC_HS384
- A256CBC_HS512
authzStore.accessToken.jweMethod = A128GCM
authzStore.accessToken.selfContainedClaims
The authorisation attributes (or JWT claims) to include in the self-contained access tokens. After the JWT is successfully verified the resource server may utilise these attributes in order to fulfil the client request.
All attributes are optional (denoted in square brackets), however some are commonly required by resource servers.
The protected UserInfo endpoint requires the following attributes:
sub exp scp clm cll uip
Supported attributes:
-
[ iss ] {string} The authorisation issuer, i.e. the OpenID Provider
(OP) identifier, for example
https://oidc.mycompany.com
. - [ sub ] {string} The subject (end-user) identifier. Required by the UserInfo endpoint, or any resource server that needs the subject to be asserted by the access token. May be omitted in case the privacy policy forbids sharing the user identity with resource servers.
- [ iat ] {integer} The access token issue time, as a Unix timestamp. The token should not be accepted as valid by protected resources before that time.
- [ exp ] {integer} The access token expiration time, as a Unix timestamp. The token should not be accepted as valid by protected resources after that time.
- [ aud ] {string array} The audience list. Can be used to explicitly denote the protected resources for which the access token is intended.
- [ jti ] {string} Secure random JWT identifier for the access token.
- [ cid ] {string} The client identifier.
- [ scp ] {string array} The authorised scope values.
- [ clm ] {string array} The authorised claims for release at the UserInfo endpoint.
- [ cll ] {string array} The preferred locales for the authorised claims for release at the UserInfo endpoint.
- [ uip ] {object} The preset claims for release at the UserInfo endpoint.
- [ dat ] {object} Additional authorisation data.
Recommended claims to include:
authzStore.accessToken.selfContainedClaims = iss sub exp aud cid scp clm cll uip dat
authzStore.accessToken.jtiByteLength
The JSON Web Token (JWT) ID byte length. Must be at least 8 bytes long.
authzStore.accessToken.jtiByteLength = 8
authzStore.accessToken.allowDirectInspection
If true
clients can inspect an access token without presenting the master
Bearer access token to the authorisation store web
API.
authzStore.accessToken.allowDirectInspection = true
4. LDAP server details
The authzStore.ldapServer.*
properties set the connection details for the
LDAP server where long-lived OAuth 2.0 / OpenID Connect authorisations are
persisted.
authzStore.ldapServer.url
The LDAP URL of the directory server for storing the subject / client
authorisations. The schema must be ldap
or ldaps
, it must specify a valid
host name or IP address as well as the port number if a non-default is used.
If the directory is replicated across several LDAP servers for the purpose of failover or load-balancing, the value is a space-separated list of the corresponding LDAP URLs. Server selection is handled according to authzStore.ldapServer.selectionAlgorithm.
Example single LDAP server URL pointing to the local host:
authzStore.ldapServer.url = ldap://localhost:1389
Example list of two LDAP server URLs (for use in a failover or load-balancing configuration):
authzStore.ldapServer.url = ldap://192.168.1.10:1389 ldap://192.168.1.11:1389
authzStore.ldapServer.selectionAlgorithm
The preferred server selection algorithm in case authzStore.ldapServer.url is an LDAP server set:
-
FAILOVER
– Establish connections to the LDAP servers in the order they are provided. If the first server is unavailable, then it will attempt to connect to the second, then to the third and so on. -
ROUND_ROBIN
– Use a round-robin algorithm to select the LDAP server to which the connection should be established. Any number of servers may be included in the set and each request will attempt to retrieve a connection to the next server in the list, circling back to the beginning of the list as necessary. If a server is unavailable when an attempt is made to establish a connection to it, then the connection will be established to the next available server in the list.
To specify failover server selection:
authzStore.ldapServer.selectionAlgorithm = FAILOVER
authzStore.ldapServer.connectTimeout
The timeout in milliseconds for LDAP connect requests. If zero the underlying LDAP client library will handle this value.
To specify a connect timeout of 250 ms:
authzStore.ldapServer.connectTimeout = 250
authzStore.ldapServer.responseTimeout
The timeout in milliseconds for LDAP server responses. If zero the underlying LDAP client library will handle this value.
To specify a connect timeout of 1 second:
authzStore.ldapServer.responseTimeout = 1000
authzStore.ldapServer.security
The LDAP connection security:
-
NONE
– Establish a plain insecure connection. -
SSL
– Establish a secure connection over SSL. -
StartTLS
– Establish a secure connection using the StartTLS protocol (recommended method).
To use StartTLS for LDAP connections:
authzStore.ldapServer.security = StartTLS
authzStore.ldapServer.trustSelfSignedCerts
Determines whether to accept self-signed certificates presented by the LDAP server (for secure SSL or StartTLS connections). Self-signed certificates are not trusted by default.
To reject self-signed certificates:
authzStore.ldapServer.trustSelfSignedCerts = false
authzStore.ldapServer.connectionPoolSize
The maximum LDAP connection pool size. The default value is five connections.
To create a pool for 5 LDAP connections:
authzStore.ldapServer.connectionPoolSize = 5
authzStore.ldapServer.connectionPoolMaxWaitTime
The maximum length of time in milliseconds to wait for a connection to become available when trying to obtain an LDAP connection from the pool. A value of zero should be used to indicate that the pool should not block at all if no connections are available and that it should either create a new connection or throw an exception.
To set the max LDAP connection pool wait time to 250ms:
authzStore.ldapServer.connectionPoolMaxWaitTime = 250
authzStore.ldapServer.connectionMaxAge
The maximum time in milliseconds that an LDAP connection in the pool may be established before it should be closed and replaced with another connection. A value of zero indicates that no maximum age should be enforced. Defaults to no maximum age (zero).
To disable LDAP connection expiration:
authzStore.ldapServer.connectionMaxAge = 0
5. LDAP user details
The authzStore.ldapUser.*
properties set the credentials for establishing
connections to the LDAP directory server.
authzStore.ldapUser.dn
The distinguished name (DN) of the LDAP directory user to perform the authorisation record operations. Must have read, add, update and delete access to the directory branch containing the authorisation records. An empty value implies an anonymous user.
Example user DN:
authzStore.ldapUser.dn = cn=Directory Manager
authzStore.ldapUser.password
The directory user password. An empty value implies an anonymous user.
Example password:
authzStore.ldapUser.password = secret
6. LDAP directory entry details
The authzStore.ldapDirectory.*
properties set the LDAP directory branch
location and attribute names for persisting long-lived OAuth 2.0 / OpenID
Connect authorisations.
authzStore.ldapDirectory.baseDN
The base distinguished name (DN) of the LDAP directory branch where the authorisation entries are stored (as immediate descendants).
authzStore.ldapDirectory.baseDN = ou=authorizations, dc=wonderland, dc=net
authzStore.ldapDirectory.pageSize
The page size to use when retrieving multiple authorisation object entries from the LDAP directory. See LDAP Control Extension for Simple Paged Results Manipulation (RFC 2696).
authzStore.ldapDirectory.pageSize = 500
authzStore.ldapDirectory.preferAsyncRequests
If true
selected LDAP directory requests will be made asynchronously to
increase throughput under load.
authzStore.ldapDirectory.preferAsyncRequests = false
authzStore.ldapDirectory.objectClasses
The directory object classes of the authorisation object entries. This setting should not be edited.
authzStore.ldapDirectory.objectClasses = top oauth2Authz oidcAuthz
authzStore.ldapDirectory.attributes.sub
The name of the LDAP attribute holding the authorisation subject. Must be single-valued. This setting should not be edited.
authzStore.ldapDirectory.attributes.sub = authzSubject
authzStore.ldapDirectory.attributes.cid
The name of the LDAP attribute holding the identifier of the authorised client identifier. Must be single-valued. This setting should not be edited.
authzStore.ldapDirectory.attributes.cid = authzClientID
authzStore.ldapDirectory.attributes.scp
The name of the LDAP attribute holding the authorisation scope values. Must be multi-valued. This setting should not be edited.
authzStore.ldapDirectory.attributes.scp = authzScopeValue
authzStore.ldapDirectory.attributes.scs
The name of the LDAP attribute holding the saved scope values from previous authorisations. Must be multi-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.scs = authzSavedScopeValue
authzStore.ldapDirectory.attributes.irt
The name of the LDAP attribute holding the preference for issuing refresh tokens. Must be single-valued. This setting should not be edited.
authzStore.ldapDirectory.attributes.irt = authzIssueRefreshToken
authzStore.ldapDirectory.attributes.rts
The name of the LDAP attribute holding the refresh token secret, with optional alias(es). Must be single-valued. This setting should not be edited.
authzStore.ldapDirectory.attributes.rts = authzRefreshTokenSecret authzRefreshTokenSalt
authzStore.ldapDirectory.attributes.rtl
The name of the LDAP attribute holding the refresh token lifetime, in seconds. Must be single-valued. This setting should not be edited.
authzStore.ldapDirectory.attributes.rtl = authzRefreshTokenLifetime
authzStore.ldapDirectory.attributes.rti
The name of the LDAP attribute holding the refresh token issue date. Must be single-valued. This setting should not be edited.
authzStore.ldapDirectory.attributes.rti = authzRefreshTokenIssueDate
authzStore.ldapDirectory.attributes.atl
The name of the LDAP attribute holding the access token lifetime, in seconds. Must be single-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.atl = authzAccessTokenLifetime
authzStore.ldapDirectory.attributes.ate
The name of the LDAP attribute holding the access token encoding. Must be single-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.ate = authzAccessTokenEncoding
authzStore.ldapDirectory.attributes.atc
The name of the LDAP attribute holding the access token encrypt setting. Must be single-valued boolean. This setting should not be edited.
authzStore.ldapDirectory.attributes.atc = authzAccessTokenEncrypt
authzStore.ldapDirectory.attributes.iss
The name of the LDAP attribute holding the authorisation subject. Must be single-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.iss = authzIssuer
authzStore.ldapDirectory.attributes.iat
The name of the LDAP attribute holding the authorisation issue date. Must be single-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.iat = authzIssueDate
authzStore.ldapDirectory.attributes.uat
The name of the LDAP attribute holding the last authorisation update date. Must be single-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.uat = authzUpdateDate
authzStore.ldapDirectory.attributes.aud
The name of the LDAP attribute holding the authorisation audience. Must be multi-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.aud = authzAudience
authzStore.ldapDirectory.attributes.clm
The name of the LDAP attribute holding the consented OpenID Connect claim names, with optional language tags. Must be multi-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.clm = oidcClaimName
authzStore.ldapDirectory.attributes.cls
The name of the LDAP attribute holding the saved consented OpenID Connect claim names from previous authorisations, with optional language tags. Must be multi-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.cls = oidcSavedClaimName
authzStore.ldapDirectory.attributes.cll
The name of the LDAP attribute holding the preferred OpenID Connect claims locales. Must be single-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.cll = oidcClaimsLocales
authzStore.ldapDirectory.attributes.uip
The name of the LDAP attribute holding the preset OpenID Connect UserInfo claims. Must be single-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.uip = oidcPresetUserInfoClaims
authzStore.ldapDirectory.attributes.sid
The name of the LDAP attribute holding the associated subject session identifier (SID). If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.sid = oidcSessionID
authzStore.ldapDirectory.attributes.dat
The name of the LDAP attribute holding the auxiliary data, as a JSON object. Must be single-valued. If empty LDAP storage of the attribute will be disabled.
authzStore.ldapDirectory.attributes.dat = authzData
7. Custom LDAP server trust and key store
The authzStore.customTrustStore.*
and authzStore.customKeyStore.*
properties specify custom trust and key stores (apart from those provided by
the underlying JVM) to establish the security context of TLS/SSL connections to
the LDAP servers.
authzStore.customTrustStore.enable
Set to true
to use your custom trust store file for determining the
acceptable security certificates presented by the remote LDAP server.
Set to false
to use the default trust store of the web server / host system
(if one has been provided and correctly configured).
If you set this to true
you must also specify a trust store file, type and
password (see the corresponding parameters below).
authzStore.customTrustStore.enable = false
authzStore.customTrustStore.file
The location of the custom trust store file.
Example:
authzStore.customTrustStore.file = WEB-INF/truststore.jks
authzStore.customTrustStore.password
The password required to unlock the trust store file. Leave it empty if none is required.
Example:
authzStore.customTrustStore.password = secret
authzStore.customTrustStore.type
The type of the trust store file, typically JKS or PKCS12. Leave it empty to assume the system default type.
Example:
authzStore.customTrustStore.type = JKS
authzStore.customKeyStore.enable
Set to true
to use your custom key store file for client security
certificates to be presented to the remote LDAP server requiring such
authentication.
Set to false
to use the default key store of the web server / host system (if
one has been provided and correctly configured).
If you set this to true
you must also specify a key store file, type and
password (see the corresponding parameters below).
authzStore.customKeyStore.enable = false
The location of the custom key store file.
Example:
authzStore.customKeyStore.file = WEB-INF/keystore.jks
authzStore.customKeyStore.password
The password required to unlock the key store file. Leave it empty if none is required.
Example:
authzStore.customKeyStore.password =
authzStore.customKeyStore.type
The type of the trust store file, typically JKS
or PKCS12
. Leave it empty
to assume the system default type.
Example:
authzStore.customKeyStore.type = JKS
8. Authorisation store options
The authzStore.options.*
properties contains a single setting which enables
or disables the highly-available operation of the authorisation store.
authzStore.options.highlyAvailableMode
With an enabled highly-available mode the authorisation store will continue providing basic service when the LDAP server is down or disconnected. The required data will be served from the caches if possible and LDAP connection exceptions will not cause requests to fail (they will be logged at ERROR level however).
authzStore.options.highlyAvailableMode = true
authzStore.options.preloadCache
If true
all long-lived (persisted) authorisations will be asynchronously
preloaded into the cache at server startup. Intended to increase performance
and high-availability, provided cache size and free memory are sufficient.
authzStore.options.preloadCache = false