Core settings

To edit the core OpenID Connect provider settings open the following properties file in the WEB-INF directory of the web application:

WEB-INF/oidcProvider.properties

The file contains configuration properties split into six sections:

1. General provider settings – specify the OpenID Connect provider identifier (iss) and the optional URLs of the documents describing the provider privacy policy, terms of service and guide for client app developers.
2. Client registry settings – policy and database details for registering OAuth 2.0 / OpenID Connect client applications.
3. ID token settings – ID token lifetime and security preferences.
4. Authorisation endpoint settings – configure the OAuth 2.0 authorisation endpoint and the login page integration web API.
5. Token endpoint settings – specify the accepted client authentication methods at the token endpoint.
6. UserInfo endpoint settings – specify the allowed UserInfo protection methods.

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:

-Dissuer=https://op.example.net

1. General

This group of properties sets the OpenID Connect provider identifier (iss) as well as URLs for the privacy policy, the terms of service and the documentation for client application developers.

op.issuer

The issuer identifier (iss) of the OpenID Connect provider. Should be set to the base public URL of the Connect2id server, and specify an https schema.

Expected format:

[base-server-URL]

Example issuer identifier:

"issuer" : "https://oidc.wonderland.net"

op.policy

URL of the OpenID Connect provider’s policy regarding relying party use of data, in human-readable form. Leave empty if not specified.

Example URL for an OpenID Connect provider’s policy:

op.policy = http://oidc.wonderland.net/policy.html

op.tos

URL of the OpenID Connect provider’s terms of service, in human-readable form. Leave empty if not specified.

Example URL for an OpenID Connect provider’s terms of service:

op.tos = http://oidc.wonderland.net/terms-of-service.html

op.serviceDocs

URL of the OpenID Connect provider’s service documentation for developers, in human-readable form. Leave empty if not specified.

Example URL for OpenID Connect provider’s service documentation:

op.serviceDocs = http://oidc.wonderland.net/service-docs.html

2. Client registry

The op.reg.* group of properties sets the policy and database details for registering OpenID Connect client applications.

op.reg.allowOpenRegistration

Enables / disables open (also called dynamic) registration of clients for the authorization_code, implicit and refresh_token grants. Open registration is intended for public Connect2id servers configured for automatic OpenID Provider discovery. See the client registration reference for more information.

Open registration is disabled by default. If in doubt whether open registration should be enabled, contact Connect2id support.

To prohibit open registration:

op.reg.allowOpenRegistration = false

op.reg.rejectNonTLSRedirectionURIs

Rejects / allows registration of non-TLS (plain HTTP and other unprotected) redirection URIs in the authorisation code flow (response_type=code).

Note that TLS (https) is always required for clients that register for the implicit flow.

To allow registration of plain http redirection URIs in the code flow:

op.reg.rejectNonTLSRedirectionURIs = false

op.reg.accessTokenByteLength

The byte length of generated registration access tokens. Must be at least 32 bytes long to make brute force guessing impractical.

To set the length of generated registration access tokens to 32 bytes:

op.reg.accessTokenByteLength = 32

op.reg.refreshAccessTokenOnUpdate

Enables / disables refreshing of the registration access token with each client registration update.

To disable refreshing of the access token with client registration updates:

op.reg.refreshAccessTokenOnUpdate = true

op.reg.clientIDByteLength

The byte length of generated client identifiers. Must be at least 8 bytes long to provide a sufficiently large identifier space.

To set the length of generated client IDs to 8 bytes:

op.reg.clientIDByteLength = 8

op.reg.clientSecretByteLength

Removed in Connect2id Server version 2.5. The server will instead use an internal lookup table to determine the minimal appropriate client secret length based on the chosen client authentication method, ID token JWS algorithm and UserInfo JWS algorithm at client registration time.

The byte length of generated client secrets. Must be at least 32 bytes long to brute force guessing impractical.

To set the length of generated client secrets to 32 bytes:

op.reg.clientSecretByteLength = 32

op.reg.clientSecretLifetime

The lifetime of issued client secrets, in hours. If zero implies no expiration. Defaults to no expiration (zero hours).

To make issued client secrets non-expiring:

op.reg.clientSecretLifetime = 0

op.reg.alwaysRefreshClientSecretOnUpdate

Enables / disables refreshing of the client secret with each client registration update. If false the client secret will be refreshed only if it has expired.

To disable refreshing of the access token with client registration updates:

op.reg.alwaysRefreshClientSecretOnUpdate = false

op.reg.preloadCache

If true the persisted client registrations will be asynchronously preloaded into the cache at server startup.

To disable cache preloading:

op.reg.preloadCache = false

op.reg.apiAccessToken

Master access token for the entire client registration web API. It is intended for use by trusted administration and monitoring applications. The token is of type Bearer and non-expiring. Must contain at least 32 random alphanumeric characters to make brute force guessing impractical. If not specified third-party access to the registration endpoint is disabled.

op.reg.apiAccessToken = ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

2.1 Client registry: LDAP server details

The op.reg.ldapServer.* properties set the connection details for the LDAP server where client registrations are persisted.

op.reg.ldapServer.url

The LDAP URL of the directory server for storing the OpenID Connect client registrations. 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 op.reg.ldapServer.selectionAlgorithm.

Example single LDAP server URL pointing to the local host:

op.reg.ldapServer.url = ldap://localhost:1389

Example list of two LDAP server URLs (for use in a failover or load-balancing configuration):

op.reg.ldapServer.url = ldap://192.168.1.10:1389 ldap://192.168.1.11:1389

op.reg.ldapServer.selectionAlgorithm

The preferred server selection algorithm in case op.reg.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:

op.reg.ldapServer.selectionAlgorithm = FAILOVER

op.reg.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:

op.reg.ldapServer.connectTimeout = 250

op.reg.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:

op.reg.ldapServer.security = StartTLS

op.reg.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:

op.reg.ldapServer.trustSelfSignedCerts = false

op.reg.ldapServer.connectionPoolSize

The maximum LDAP connection pool size. The default value is five connections.

To create a pool for 5 LDAP connections:

op.reg.ldapServer.connectionPoolSize = 5

op.reg.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:

op.reg.ldapServer.connectionPoolMaxWaitTime = 250

op.reg.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:

op.reg.ldapServer.connectionMaxAge = 0

2.2 Client registry: LDAP user details

The op.reg.ldapUser.* properties set the credentials for establishing connections to the LDAP directory server where client registrations are persisted.

op.reg.ldapUser.dn

The distinguished name (DN) of the LDAP directory user to perform the client registration operations. Must have read, add, update and delete access to the directory branch containing the client registrations. An empty value implies an anonymous user.

Example user DN:

op.reg.ldapUser.dn = cn=Directory Manager

op.reg.ldapUser.password

The directory user password. An empty value implies an anonymous user.

Example password:

op.reg.ldapUser.password = secret

2.3 Client registry: LDAP directory details

The op.reg.ldapDirectory.* properties set the LDAP directory branch location and object classes for persisting client registrations.

op.reg.ldapDirectory.baseDN

The base distinguished name (DN) of the LDAP directory branch where the client registration entries are stored (as immediate descendants).

Example base DN:

op.reg.ldapDirectory.baseDN = ou=clients,dc=wonderland,dc=net

op.reg.ldapDirectory.objectClasses

The required directory object classes for adding new client registration entries. This setting should not be edited.

op.reg.ldapDirectory.objectClasses = top oidcRelyingParty

2.4 Client registry: Custom LDAP server trust and key store

The op.reg.customTrustStore.* and op.reg.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.

op.reg.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).

op.reg.customTrustStore.enable = false

op.reg.customTrustStore.file

The location of the custom trust store file.

Example:

op.reg.customTrustStore.file = WEB-INF/truststore.jks

op.reg.customTrustStore.password

The password required to unlock the trust store file. Leave it empty if none is required.

Example:

op.reg.customTrustStore.password = secret

op.reg.customTrustStore.type

The type of the trust store file, typically JKS or PKCS12. Leave it empty to assume the system default type.

Example:

op.reg.customTrustStore.type = JKS

op.reg.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).

op.reg.customKeyStore.enable = false

op.reg.customKeyStore.file

The location of the custom key store file.

Example:

op.reg.customKeyStore.file = WEB-INF/keystore.jks

op.reg.customKeyStore.password

The password required to unlock the key store file. Leave it empty if none is required.

Example:

op.reg.customKeyStore.password = secret

op.reg.customKeyStore.type

The type of the trust store file, typically JKS or PKCS12. Leave it empty to assume the system default type.

Example:

op.reg.customKeyStore.type = JKS

3. ID token

The op.idToken.* properties set the ID token preferences.

op.idToken.lifetime

The ID token lifetime, in minutes. Used to set the ID token expiration time (exp) after which the token must not be accepted by the client for processing.

op.idToken.lifetime = 15

op.idToken.jwsAlgs

The enabled JSON Web Signature (JWS) algorithms for signing issued ID tokens.

The following standard JWS algorithms are supported:

• RS256
• RS384
• RS512
• PS256
• PS384
• PS512
• HS256
• HS384
• HS512
• none

The algorithm RS256 must always be included. The value none may be included, but must not be used unless the response type used returns no ID token from the authorisation endpoint (such as when using the authorisation code flow).

The first JWS algorithm in the list becomes the preferred algorithm for client registration.

To enable all supported JWS algorithms, save for none, and make RS256 the preferred one at client registration:

op.idToken.jwsAlgs = RS256, RS384, RS512, PS256, PS384, PS512, HS256, HS384, HS512

op.idToken.ignoreUserInfoError

Specifies if ID tokens should be returned when the Connect2id server encounters an exception retrieving requested UserInfo claims for it. The recommended policy is to ignore such exceptions and always return an ID token.

op.idToken.ignoreUserInfoError = true

4.Authorisation endpoint and login page integration

The op.authz.* properties configure the OAuth 2.0 authorisation endpoint and the web interface for integrating the login page.

op.authz.endpoint

The OAuth 2.0 authorisation endpoint of the Connect2id server. Must be set to the URL of the OpenID Connect login page (hosted separately from the Connect2id server). The URL schema should be https.

op.authz.endpoint = https://oidc.wonderland.net/login

op.authz.apiAccessToken

The access token for the authorisation session endpoint and the direct authorisation endpoint. The token is type Bearer and must contain at least 32 random alphanumeric characters to make brute force guessing impractical.

op.authz.apiAccessToken = ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

op.authz.sessionLifetime

The authorisation session lifetime, in minutes.

op.authz.sessionLifetime = 15

op.authz.responseTypes

List of the enabled OAuth 2.0 response_type values, separated by comma.

The following response types are supported:

• code
• id_token
• id_token token
• code id_token

At a minimum code should be included.

To enable all supported response types:

op.authz.responseTypes = code, id_token, id_token token, code id_token

op.authz.supportClaimsParam

Enables / disables support of the claims parameter in OpenID Connect authentication requests.

To enable support of the claims parameter:

op.authz.supportClaimsParam = true

op.authz.promptNone.requireIDTokenHint

Specifies if a valid ID token hint is required when the OpenID Connect authentication request prompt parameter is set to none.

To accept prompt=none requests without an ID token hint:

op.authz.promptNone.requireIDTokenHint = false

op.authz.promptNone.alwaysRequireLogin

If true the OpenID Connect provider will always respond with a login_required error when the authentication request prompt parameter is set to none.

op.authz.promptNone.alwaysRequireLogin = false

op.authz.promptNone.alwaysRequireConsent

If true the OpenID Connect provider will always respond with a consent_required error when the authentication request prompt parameter is set to none and consent is implied.

op.authz.promptNone.alwaysRequireConsent = false

op.authz.advertisedScopes

List of the supported OAuth 2.0 scope values to advertise in the OpenID Connect provider metadata (for service discovery). The openid scope value must always be included. The standard OpenID Connect scope values should be included if supported. Other scope values that are custom or application-specific may not be advertised.

To advertise support of all standard OpenID Connect scope values:

op.authz.advertisedScopes = openid, profile, email, address, phone, offline_access

op.authz.advertisedClaims

List of the supported claim names (UserInfo and other) to advertise in the OpenID Connect provider metadata (for service discovery). The sub (subject / user identifier) claim name must always be included. Note that for privacy or other reasons, this might not be an exhaustive list.

Example claims to advertise:

op.authz.advertisedClaims = sub, iss, auth_time, acr, name, given_name, family_name, nickname, email, email_verified

op.authz.advertisedACRs

List of the supported Authentication Context Class References to advertise in the OpenID Connect provider metadata (for service discovery). Leave empty if none.

Example list of two supported ACRs (as URNs):

op.authz.advertisedACRs = urn:c2id:lowsec, urn:c2id:highsec

op.authz.advertisedDisplayTypes

List of the the supported display parameter values to advertise in the OpenID Connect provider metadata (for service discovery).

Possible display values:

• page
• popup
• touch
• wap

To advertise support of page and popup display types:

op.authz.advertisedDisplayTypes = page, popup

op.authz.advertisedUILocales

List of the supported languages and scripts for the user interface, represented as BCP47 (RFC 5646) language tag values, to advertise in the OpenID Connect provider metadata (for service discovery).

To advertise UI support of English, Spanish and German language:

op.authz.advertisedUILocales = en, es, de

5. Token Endpoint

The op.token.* properties set the accepted client authentication methods at the token endpoint.

op.token.authMethods

List of the enabled client authentication methods at the token endpoint. It is suggested that all supported methods are enabled.

The following authentication methods are supported:

• client_secret_basic
• client_secret_post
• client_secret_jwt

To enable all supported client authentication methods:

op.token.authMethods = client_secret_basic, client_secret_post, client_secret_jwt

op.token.authJWSAlgs

List of the enabled JSON Web Signature (JWS) algorithms for client_secret_jwt client authentication at the token endpoint. It is suggested that all supported algorithms are enabled.

The following JWS algorithms are supported:

• HS256
• HS384
• HS512

To enable all supported JWS algorithms for client_secret_jwt client authentication:

op.token.authJWSAlgs = HS256, HS384, HS512

6. UserInfo Endpoint

The op.userinfo.* properties configure the UserInfo endpoint.

op.userinfo.jwsAlgs

List of the enabled JSON Web Signature (JWS) algorithms supported by the UserInfo endpoint to sign the claims in a JSON Web Token (JWT).

The following JWS algorithms are supported:

• RS256
• RS384
• RS512
• PS256
• PS384
• PS512
• HS256
• HS384
• HS512

Tp enable all supported JWS algorithms:

op.userinfo.jwsAlgs = RS256, RS384, RS512, PS256, PS384, PS512, HS256, HS384, HS512