Skip to content
Connect2id

Core settings

The core OpenID Connect provider / OAuth 2.0 authorisation server configuration settings are located in this properties file:

WEB-INF/oidcProvider.properties

The configuration properties are split into six sections:

  1. General provider – the token issuer (iss) URL that identifies the OpenID provider / OAuth 2.0 authorisation server on the internet as well as URLs for the privacy policy, the terms of service and the developer documentation.
  2. Client registry – policies for registering OpenID relying parties and OAuth 2.0 clients.
  3. ID token – ID token lifetime and cryptographic algorithms.
  4. Authorisation endpoint – for configuring the OAuth 2.0 authorisation endpoint and the login page web API.
  5. Token endpoint – the accepted methods for authenticating clients at the token endpoint.
  6. Token introspection endpoint – proprietary extension settings.
  7. UserInfo endpoint – UserInfo cryptographic algorithms.
  8. Check session – Check session iframe settings.
  9. Logout endpoint – Logout (end-session) endpoint settings.
  10. Mutual TLS – Mutual TLS client authentication settings.

Any configuration file property can be overridden with a Java system property, e.g. by setting the optional -D argument at JVM startup:

-Dop.issuer=https://op.example.net

The external configuration guide has tips for setting system properties from environment variables, local files and other locations.

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:

op.issuer = https://oidc.wonderland.net

op.policy

URL of the OpenID Provider’s policy regarding relying party use of data, in human-readable form. The URL can be also be specified relative to the OpenID provider issuer URL. Leave blank 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. The URL can be also be specified relative to the OpenID provider issuer URL. Leave blank 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. The URL can be also be specified relative to the OpenID provider issuer URL. Leave blank 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.requireInitialAccessTokenAudience

If true the initial registration access token must include an audience value that is the OpenID Provider / Authorisation Server issuer URI or the client registration endpoint URI, else the access token won’t be accepted. Defaults to true. Since v6.19.

op.reg.requireInitialAccessTokenAudience = true

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

Enables / disables inclusion of a state hash claim (s_hash) in issued ID tokens. Disabled by default. Since v6.13.

op.idToken.includeStateHash = false

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. The URL can be also be specified relative to the OpenID provider issuer URL. Leave blank if not specified.

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 can then be used as an additional input to the determine the appropriate end-user authentication or session settings.

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

op.authz.includeClientInfoInAuthPrompt = false

op.authz.includeClientInfoInFinalResponse

If true the Connect2id server will include the registered OAuth 2.0 / OpenID Connect client information in the final response of an authorisation session.

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

op.authz.includeClientInfoInFinalResponse = false

op.authz.includeSubjectSessionInFinalResponse

If true the Connect2id server will include the subject (end-user) session with its ID and other parameters in the final response of an authorisation session.

The subject session is required typically only when a UI is presented, during authentication and consent (implies false). Since v6.14.

op.authz.includeSubjectSessionInFinalResponse = 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.alwaysPromptForAuth

The Connect2id server is normally configured (false) to always skip the authentication step, provided the end-user has a valid session (established by a cookie) and the authentication strength requirement (ACCR) of the client are met.

If true the Connect2id server will always prompt for authentication, even if the end-user is currently authenticated (has a valid session). This can be used to ensure some custom logic or script is always executed during the authentication step. OpenID prompt=none authentication requests will be handled according to op.authz.alwaysPromptMode.

op.authz.alwaysPromptForAuth = false

op.authz.alwaysPromptForConsent

The Connect2id server is normally configured (false) to always skip the consent step, provided such is already recorded for the given end-user and client.

If true the Connect2id server will always prompt for consent, even if previous consent for the end-user and client exists. This can be used to ensure some custom logic or script is always executed during the consent step. OpenID prompt=none authentication requests will be handled according to op.authz.alwaysPromptMode.

op.authz.alwaysPromptForConsent = false

op.authz.alwaysPromptMode

Controls processing of OpenID prompt=none authentication requests when op.authz.alwaysPromptForAuth or op.authz.alwaysPromptForConsent is enabled. Since v6.7.

Supported modes:

  • LIMITED – No authentication or consent prompt will be returned on a OpenID prompt=none authentication request. The Connect2id server will proceed straight to returning the final response (success or login_required / consent_required error).
  • PROMPT_NONE – An authentication or consent prompt will be returned on a OpenID prompt=none authentication request provided an existing session or consent is found and the request can be fulfilled with no end-user interaction. This is the default mode for legacy reasons.
  • PROMPT_NONE_WITH_INTERACTION_ERRORS – An authentication or consent prompt will be returned on a OpenID prompt=none authentication request even if the request cannot be fulfilled due to required end-user interaction; in that case the login page must handle the login_required and consent_required errors by itself.
op.authz.alwaysPromptMode = PROMPT_NONE

op.authz.requireIDTokenHintWithPromptNone

Specifies if a valid ID token hint (id_token_hint) is required with OpenID prompt=none authentication requests.

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 – Basic authentication with the client_secret passed in the Authorization header.
  • client_secret_post – Basic authentication with the client_secret passed in the request body as form parameters.
  • client_secret_jwt – JWT authentication using the client_secret as shared HMAC key
  • private_key_jwt – JWT authentication using public RSA or EC cryptography; the client must register its public key (s) with the Connect2id server
  • self_signed_tls_client_auth – Self-signed client X.509 certificate authentication; the client must register its public key(s) for the certificate with the Connect2id server
  • none – no client authentication

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, self_signed_tls_client_auth, 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. Token Introspection Endpoint

The op.token.introspection.* properties configure the token introspection endpoint.

op.token.introspection.alwaysRespondWithJWT

If true causes the token introspection responses to be always returned as a JWT signed with the same JWS algorithm and key as self-contained (JWT) access tokens. The default value is false.

Since v6.18.

op.token.introspection.alwaysRespondWithJWT = false

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

8. Check Session Iframe

The op.checkSession.* properties configure the OpenID check session iframe.

op.checkSession.iframe

The OpenID Connect check session iframe URL. The URL schema should be https. The URL can be also be specified relative to the OpenID provider issuer URL.

Browser JavaScript code running in the iframe must be able to access the cookie used to store the subject (end-user) session ID. This requires the iframe to have the same web origin (domain) as the login page which set the session cookie. The cookie must also be set with a path visible by the iframe and without the HttpOnly flag.

If blank check session support will be disabled and the iframe will not be advertised in the OpenID provider metadata.

The Connect2id server provides a default check session iframe at /check-session.html relative to the OpenID provider issuer URL.

Since v6.9.

op.checkSession.iframe = /check-session.html

op.checkSession.cookieName

The name of the cookie which is used by the login page to store the subject (end-user) session ID. The cookie must be accessible from browser JavaScript running in the check session iframe, i.e. it must be set with a common path and without the HttpOnly flag.

Since v6.9.

op.checkSession.cookieName = sid

9. Logout (End-Session) Endpoint

The op.logout.* properties configure the OpenID logout (end-session) endpoint and the web interface for integrating the logout page.

op.logout.endpoint

The OpenID Connect Logout (end-session) endpoint of the Connect2id server. Must be set to the URL of the OpenID provider logout page (hosted separately from the Connect2id server). The URL schema should be https. The URL can be also be specified relative to the OpenID provider issuer URL. Leave blank if not specified.

If not specified the endpoint will be disabled and not advertised in the OpenID provider metadata.

Since v6.8.

op.logout.endpoint = https://c2id.com/logout

op.logout.apiAccessToken

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

Since v6.8.

op.logout.apiAccessToken = ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

op.logout.sessionLifetime

The logout session lifetime, in minutes.

Since v6.8.

op.logout.sessionLifetime = 5

10. Mutual TLS

Settings for client authentication using mutual TLS with client X.509 certificates.

op.tls.clientX509CertHeader

The name of the HTTP header to receive validated self-signed client X.509 certificates (PEM-encoded) from a TLS termination proxy. Intended for use in public key TLS client authentication (pub_key_tls_client_auth) only. The header name must be kept confidential between the TLS termination proxy and the Connect2id server and must include at least 32 random alphanumeric characters to make brute force guessing impractical.

If not specified or commented out use of a TLS termination proxy for public key TLS client authentication is disabled.

Since v6.12.

op.tls.clientX509CertHeader = X-Client-X509-Cert-alaeLuL8geiqu3OhOg1Mafa4Ecu9ahsh