Skip to content
Connect2id

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:

  1. Web API – to set the access token for querying and managing the authorisation store over its web API.
  2. Authorisation code settings – to set the lifetime of issued authorisation codes.
  3. Access token settings – to set the default preferences of issued access tokens.
  4. LDAP server details – to set the connection details of the LDAP server where long-lived authorisations are persisted.
  5. LDAP user details – to set the LDAP server connection credentials.
  6. LDAP directory entry details – to set the LDAP directory branch location and attribute names for persisting long-lived authorisations.
  7. Custom LDAP server trust and key store – to set a custom certificate trust and / or key key for secure LDAP connections.
  8. 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.
  • [ act ] Optional authorised actor in impersonation and delegation cases.
  • [ dat ] {object} Additional authorisation data.

Recommended claims to include:

authzStore.accessToken.selfContainedClaims = iss sub exp aud cid scp clm cll uip act 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 cap the pool at 10 LDAP connections:

authzStore.ldapServer.connectionPoolSize = 10

authzStore.ldapServer.connectionPoolInitialSize

The initial LDAP connection pool size. The acceptable range is between zero and the maximum LDAP connection pool size (inclusive).

Set it to zero to enable startup of the Connect2id server without the backend LDAP directory being available.

authzStore.ldapServer.connectionPoolInitialSize = 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.act

The name of the LDAP attribute holding the optional authorised actor in impersonation and delegation cases. Must be single-valued. This setting should not be edited.

authzStore.ldapDirectory.attributes.act = authzActor

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