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 — the OpenID Provider identifier (iss) and URLs of the documents for the privacy policy, terms of service and a guide for client app developers.
  2. Client registry settings — define the policy for registering OAuth 2.0 / OpenID Connect clients.
  3. ID token settings — ID token lifetime and cryptographic
    algorithms.
  4. Authorisation endpoint settings — for configuring the OAuth 2.0 authorisation endpoint and the login page integration web API.
  5. Token endpoint settings — the accepted methods for authenticating clients at the token endpoint.
  6. UserInfo endpoint settings — UserInfo cryptographic algorithms.

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 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 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 Provider’s policy regarding relying party use of data, in human-readable form. Leave empty if not specified.

Example URL for an OpenID Provider’s policy:

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

op.tos

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

Example URL for an OpenID Provider’s terms of service:

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

op.serviceDocs

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

Example URL for OpenID 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 for registering OAuth 2.0 / OpenID Connect clients.

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.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.requestURIQuota

The maximum allowed number of registered request URIs ("request_uris").

Defaults to 10.

op.reg.requestURIQuota = 10

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

op.reg.resourceRetriever.httpConnectTimeout {op-reg-resourceRetriever-httpConnectTimeout}

The HTTP connect timeout (in milliseconds) for retrieving client resources (JWK sets and request objects specified by URI). Zero implies no timeout.

Defaults to 250 ms.

op.reg.resourceRetriever.httpConnectTimeout = 250

op.reg.resourceRetriever.httpReadTimeout

The HTTP read timeout (in milliseconds) for retrieving client resources (JWK sets and request objects specified by URI). Zero implies no timeout.

Defaults to 250 ms.

op.reg.resourceRetriever.httpReadTimeout = 250

3. ID token

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

op.idToken.defaultLifetime

The ID default token lifetime, in seconds. Used to set the ID token expiration time (exp) after which the token must not be accepted by the client for processing. Can be overridden by individual authorisations. Must be a positive integer.

op.idToken.defaultLifetime = 900

op.idToken.jwsAlgs

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

The following JWS algorithms are supported:

  • RS256
  • RS384
  • RS512
  • PS256
  • PS384
  • PS512
  • ЕS256
  • ЕS384
  • ЕS512
  • 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, ES256, ES384, ES512, HS256, HS384, HS512

op.idToken.jweAlgs

The enabled JWE key management algorithms for applying optional additional encryption to issued ID tokens.

The following JWE algorithms are supported:

  • RSA1_5
  • RSA-OAEP
  • RSA-OAEP-256
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
  • dir
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
op.idToken.jweAlgs = RSA1_5, RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW

op.idToken.jweEncs

The enabled JWE content encryption methods for applying optional additional encryption to issued ID tokens.

The following JWE methods are supported:

  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM
op.idToken.jweEncs = A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM

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 login page (hosted separately and bound to the Connect2id server via the authorisation session API). 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 = 900

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
  • code id_token token

At a minimum code must be included.

To enable all supported response types:

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

op.authz.responseModes

List of the enabled OAuth 2.0 response_mode values.

The following standard response modes are supported:

  • query
  • fragment
  • form_post

The list may include custom (non-standard, experimental) response modes, such as based on CORS Ajax or window.postMessage provided the authorisation session handler (the login page) is able to support them.

At a minimum query and fragment must be included.

op.authz.responseModes = query, fragment, form_post

op.authz.supportClaimsParam

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

To enable support of the claims parameter:

op.authz.supportClaimsParam = true

op.authz.requestJWSAlgs

The accepted JWS algorithms for signed OpenID authentication requests passed with the optional request_uri or request parameter.

The following JWS algorithms are supported:

  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • PS256
  • PS384
  • PS512
  • ES256
  • ES384
  • ES512
  • none

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

op.authz.requestJWSAlgs = HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, none

op.authz.includeClientInfoInAuthPrompt

If true the Connect2id server will include the registered OpenID client information in the authentication prompt. The client details may then be used as an additional input to the determine the appropriate end-user authentication or session settings.

The client information is typically only required at the consent step (implies false).

op.authz.includeClientInfoInAuthPrompt = false

op.authz.includeOtherConsentedScopeAndClaimsInPrompt

If true the Connect2id server will include non-requested scope values and claim names for which previous consent exists in the consent prompt.

If false only those scope values and claim names that are explicitly requested by the client will be included in the consent prompt

op.authz.includeOtherConsentedScopeAndClaimsInPrompt = false

op.authz.alwaysPromptForConsent

If true the Connect2id server will always prompt for consent, even if previous consent for the end-user / client exists, or prompt=none has been requested by the client.

If false the Connect2id server will skip the consent step and immediately return a successful redirection URI response provided the previous consent exists (as with prompt=none).

op.authz.alwaysPromptForConsent = false

op.authz.requireIDTokenHintWithPromptNone

Specifies if a valid ID token hint is required when the OpenID authentication requests with prompt=none.

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

op.authz.promptNone.requireIDTokenHint = false

op.authz.feedSubjectSessionClaimsIntoIDToken

If true claims stored in the subject (end-user) session will be automatically fed as additional claims into the issued ID tokens (for all clients). Applies to regular as well as prompt=none OpenID authentication requests.

op.authz.feedSubjectSessionClaimsIntoIDToken = true

op.authz.advertisedScopes

List of the supported OAuth 2.0 scope values to advertise in the OpenID Provider metadata (for service discovery). The openid scope value must always be included. The standard OpenID 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 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 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, also called levels of assurance (LOA) to advertise in the OpenID Provider metadata (for service discovery). Leave empty if none.

Important: For proper step-up authentication, order the ACRs from lowest to highest (basic to high).

Example list of two supported ACRs:

op.authz.advertisedACRs = https://loa.c2id.com/lowsec, https://loa.c2id.com/highsec

op.authz.advertisedDisplayTypes

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

Standard 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 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
  • private_key_jwt
  • none

The none method enables public (unauthenticated) clients.

To enable all supported client authentication methods:

op.token.authMethods = client_secret_basic, client_secret_post, client_secret_jwt, private_key_jwt, none

op.token.authJWSAlgs

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

The following JWS algorithms are supported:

  • For client_secret_jwt authentication: HS256, HS384, HS512

  • For private_key_jwt authentication : RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512

To enable all supported JWS algorithms for client_secret_jwt and private_key_jwt client authentication:

op.token.authJWSAlgs = HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512

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
  • ES256
  • ES384
  • ES512
  • HS256
  • HS384
  • HS512

Tp enable all supported JWS algorithms:

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

op.userinfo.jweAlgs

The enabled JWE key management algorithms for applying optional additional encryption to issued UserInfo JWTs.

The following JWE algorithms are supported:

  • RSA1_5
  • RSA-OAEP
  • RSA-OAEP-256
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
  • dir
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
op.userinfo.jweAlgs = RSA1_5, RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW, dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW

op.userinfo.jweEncs

The enabled JWE content encryption methods for applying optional additional encryption to issued UserInfo JWTs.

The following JWE methods are supported:

  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM
op.userinfo.jweEncs = A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM