Skip to content
Connect2id

Datasheet

1. OpenID certified provider

The Connect2id server has obtained certification from the OpenID foundation for the following OpenID provider profiles:

  • OpenID Connect:
    • Basic
    • Implicit
    • Hybrid
    • Configuration
    • Dynamic
    • Session management
    • RP-initiated logout
    • Front-channel logout
    • Back-channel logout
  • FAPI:
    • OP FAPI RW ID2 / private key JWT
    • OP FAPI RW ID2 / mTLS

2. Identity and security profiles

Supported domain-specific OAuth 2.0 and OpenID Connect profiles:

FAPI:

Identity assurance / eKYC:

Health care:

Government / eID:

Federations:

3. Server endpoints

The Connect2id server implements all standard OAuth 2.0 and OpenID Connect endpoints for identity provision, single sign-on (SSO) and issuing OAuth 2.0 tokens. Web and native interfaces enable the integration of end-user and management UIs, and custom logic.

Standard OAuth 2.0 / OpenID Connect endpoints

  • Server metadata – Publishes the standard server endpoints, the authorisation and identity provision capabilities, the supported cryptographic algorithms.

  • Federation metadata – Publishes the server’s OpenID Connect Federation 1.0 entity statement.

  • Server JWK set – Publishes the server’s public JSON Web Key (JWK) set and optional X.509 certificate chains, required by applications to validate ID tokens, self-contained access tokens and other issued objects. A signed JWK set is available in OpenID Connect Federation 1.0 deployments.

  • Client registration – Registers client applications with the Connect2id server so they can request ID and / or access tokens. Registered clients can be managed with read, update and delete operations. Supports software statements and signed requests via an interceptor SPI.

  • Federation client registration – Registers (explicitly) OpenID Connect Federation 1.0 entities that are OpenID relying parties.

  • PAR – Receives Pushed Authorisation Requests (PAR) from clients.

  • Authorisation – Receives OAuth 2.0 authorisation requests and OpenID authentication requests from clients.

  • Token – Exchanges an OAuth 2.0 grant for an access, and / or ID token.

  • Token introspection – Lets resource servers inspect issued access tokens. Can optionally return the introspection responses as a signed JWT.

  • Token revocation – Lets clients revoke access and refresh tokens issued to them.

  • UserInfo – Releases consented claims (attributes) about the subject (end-user) to authorised clients.

  • Check session – Handles window.postMessage polling for changes to the end-user authentication status with the OpenID Provider after the client has obtained an ID token.

  • End session – Receives end-session notifications and logout requests from clients.

Integration & plugin interfaces

  • Authorisation session – For integrating a login page (UI), end-user authentication methods and policies for setting the scope and claims of issued tokens.

  • Logout session – For integrating an optional logout page (UI), for handling end-session requests and rendering front-channel logout iframes.

  • Direct authorisation – Direct issue of ID, access and refresh tokens. Can be used to implement custom OAuth 2.0 grants, issue tokens for special needs, integrate legacy systems.

  • Authorisation store – Enables query, update and revocation of issued OAuth 2.0 / OpenID Connect authorisations and any associated access and refresh tokens.

  • Subject session store – Enables query, access and management of end-user sessions with the Connect2id server.

  • Security Token Service (STS) – Enables issue of JAR and private_key_jwt JWTs when the Connect2id server acts an OAuth 2.0 client / OpenID relying party in federated login scenarios.

  • Monitoring – Publishes over 100 server usage and performance metrics, enables execution of health checks.

  • Configuration check – Online validation of Connect2id server configurations.

  • Tenants registry – Manages Connect2id server tenants (multitenant edition only).

  • Claims source – Integrates OpenID Connect claims sources, such as LDAP directories, SQL databases and HR management systems.

  • Password grant handler – Enables plug-in of authorisation logic for handling OAuth 2.0 resource owner password credentials grants.

  • Client credentials grant handler – Enables plug-in of authorisation logic for handling client OAuth 2.0 credentials grants.

  • JWT bearer assertion grant handler – Enables plug-in of authorisation logic for handling client-issued and third-party issued (token service) JWT bearer grants.

  • SAML 2.0 bearer assertion grant handler – Enables plug-in of authorisation logic for handling client-issued and third-party issued (token service) SAML 2.0 bearer assertions grants.

  • Token exchange grant handler – Enables plug-in of logic for handling token exchange.

  • Device SSO handler – Enables plug-in of logic for handling back-channel authorisations utilising OpenID Connect native SSO.

  • Web SSO eligibility checker – Enables plugin of additional logic to check whether an OAuth 2.0 authorisation / OpenID authentication request is eligible for web SSO.

  • Token issue event listeners – Enables plug-in of listeners for ID and access token issue events.

  • Subject authentication and consent event listener – Enables plug-in of listeners for end-user authentication and authorisation events.

  • Access token encoding and introspection – Enables plug-in of alternative access token codecs, shaping of token introspection responses.

  • Custom token response – Enables customisation of token success and error responses.

  • Client registration interceptor – Enables handling of software statements and other types of signed client registration requests.

  • Client metadata validator – Enables additional validation and shaping of OAuth 2.0 client / OpenID relying party registration metadata.

  • Authorisation request validator – Enables additional validation and optional modification of received authorisation requests.

  • PAR validator – Enables additional validation and optional modification of received Pushed Authorisation Requests (PAR).

  • Private key JWT certificate verifier – Enables verification of qualified X.509 certificates for private key JWT client authentication.

  • Client authentication interceptor – Enables interception of client authentication success and error events for logging, reporting, audit and other purposes.

  • Client secret store codec – Enables hashing or encryption of client secrets before persisting them to storage. Supports import of plain, hashed or encrypted secrets.

4. OAuth 2.0 grant types

The Connect2id server supports all OAuth 2.0 core grant types:

  • authorization_code – Used in the authorisation code flow and intended for clients with a user agent (web browser)

  • implicit – Used in the implicit flow and intended for clients with a user agent (web browser). Use of this grant is no longer recommended.

  • refresh_token – For long-lived authorisations (consent).

  • password – Intended for highly-trusted or privileged client applications. Use of this grant is no longer recommended.

  • client_credentials – For clients acting on their own behalf (the client is also the resource owner).

Supported bearer assertion grants:

Other grant types:

  • OAuth 2.0 token exchange – Enables exchange of tokens of arbitrary type, encoding and issuer for a local access token, with optional refresh token and ID token. Also supports impersonation (act-as) and delegation (on-behalf-of) scenarios.

Custom grants can be implemented via the endpoint for direct authorisation.

5. OAuth 2.0 / OpenID Connect response types

The Connect2id server supports the following standard OAuth 2.0 and OpenID Connect response types:

  • code – To obtain an ID, access and refresh token at the Token endpoint.

  • id_token – To obtain an ID token via the front-end (with browser redirection).

  • token – To obtain an access token via the front-end (with browser redirection).

  • token id_token – To obtain an ID token and access token via the front-end (with browser redirection).

  • code id_token – To obtain an ID token via the front-end (with browser redirection) in addition to an ID token and access token at the Token endpoint.

  • code id_token token – To obtain an ID and access token via the front-end (with browser redirection) in addition to an ID token and access token at the Token endpoint.

6. OAuth 2.0 response modes

The Connect2id server supports all standard OAuth 2.0 response modes:

  • query – Returns the response in the redirection URI query string.

  • fragment – Returns the response in the redirection URI fragment.

  • form_post – Returns the response with a form post to the redirection URI.

  • query.jwt – Returns the response as a signed and optionally encrypted JWT (JARM) in the redirection URI query string.

  • fragment.jwt – Returns the response as a signed and optionally encrypted JWT (JARM) in the redirection URI fragment.

  • form_post.jwt – Returns the response as a signed and optionally encrypted JWT (JARM) via a form post to the redirection URI.

  • jwt – Shorthand for requesting the response as a signed and optionally encrypted JWT (JARM) appropriate for the response type.

Custom response modes, such as based on a CORS XMLHttpRequest request or on window.postMessage, can be implemented via add-on.

7. OAuth client types

Confidential as well as public clients are supported:

  • Confidential clients – can keep client authentication credentials confidential, typically clients implemented on a secure server.

  • Public clients – cannot keep client authentication credentials confidential, typically clients on end-user devices.

8. Proof key for code exchange (PKCE)

The Proof Key for Code Exchange (PKCE) protocol (RFC 7663) protects against authorisation code injection attacks on public OAuth clients and other attack vectors.

The following code verifier transforms are supported:

  • S256 – SHA-256 (mandatory to implement)
  • plain – for legacy clients

A client can be required to use PKCE by means of the code_challenge_method client metadata field. The Connect2id server can be alternatively configured to require PKCE for all clients.

9. Demonstrating Proof-of-Possession at the application layer (DPoP)

DPoP (RFC9449) is an OAuth 2.0 extension for issuing access and refresh tokens bound to a private client key. Intended primarily for public clients that are browser applications, where the alternative standard method to constrain a token, by binding it to a client X.509 certificate (RFC 8705) over mutual TLS, is unsuitable.

Supported JWS algorithms for the DPoP proof JWT:

  • RS256, RS384, RS512, PS256, PS384, PS512 – The proof JWT is signed with a client private RSA key.

  • ES256, ES256K, ES384, ES512 – The proof JWT is signed with a client private EC key.

The maximum accepted DPoP proof JWT iat age and signer clock skew when checking the age is 30 seconds.

Single use of the DPoP proof JWTs at the token and UserInfo endpoints is enforced by means of a local in-memory cache of the SHA-256 hash of the proof jti claim.

10. Subject identifier types

The Connect2id server supports the following subject identifier types in issued ID and access tokens:

  • public – Public subject identifier
  • pairwise – Pairwise subject identifier, implemented by encrypting the local subject identifier with deterministic AES in SIV mode. Supports padding for uniform pairwise identifier lengths, as additional measure against subject correlation.

Clients can be optionally registered with sector ID URNs that are managed locally by the OpenID provider. The format is urn:c2id:sector_id:<id> where <id> represents the sector ID assigned to a relying party or group of relying parties.

11. Authorisation and authentication request parameters

The Connect2id server supports all mandatory and optional OAuth 2.0 authorisation and OpenID authentication request parameters (see OpenID provider MTI):

  • OAuth 2.0 authorisation request:

    • response_type
    • response_mode
    • client_id
    • scope
    • redirect_uri
    • state
    • code_challenge
    • code_challenge_method
    • request
    • request_uri

  • OpenID Connect authentication request:

    • nonce
    • display
    • prompt
    • max_age
    • ui_locales
    • claims_locales
    • id_token_hint
    • login_hint
    • acr_values
    • claims
    • purpose

The redirect_uri parameter can be a registered URI template.

The prompt parameter is also accepted in OAuth 2.0 authorisation requests and supports all values defined in OpenID Connect Core - none, login, consent and select_account plus the create value specified in Initiating User Registration via OpenID Connect 1.0.

Custom authorisation request parameters are handled via the authorisation session API.

12. Additional authorisation response parameters

Additional OAuth 2.0 authorisation response parameters:

  • iss – Identifies the server in authorisation responses. Intended to prevent mix up attacks for OAuth 2.0 clients using more than one authorisation server (RFC 9207).

Custom authorisation response parameters are handled via the authorisation session API.

13. Client authentication methods

The Connect2id server supports all standard authentication methods for OAuth 2.0 clients, plus the new Mutual TLS Profile:

  • client_secret_basic – Basic authentication with the client secret passed in the Authorization header. The Connect2id server supports seamless secret rollover on client_secret update for uninterrupted client authentication.
  • client_secret_post – Basic authentication with the client secret passed in the request body as form parameters. The Connect2id server supports seamless secret rollover on client_secret update for uninterrupted client authentication.
  • client_secret_jwt – JWT authentication with the client secret as shared HMAC key. Replay of the JWT is prevented, unless the JWT lacks the optional JWT ID (jti) claim or the replay security feature is disabled. The Connect2id server supports seamless secret rollover on client_secret update for uninterrupted client authentication.
  • private_key_jwt – JWT authentication with public RSA or EC cryptography. The public key can be optionally passed via a qualified X.509 certificate. Replay of the JWT is prevented, unless the JWT lacks the optional JWT ID (jti) claim or the replay security feature is disabled.
  • tls_client_auth – PKI authentication with a CA-issued client X.509 certificate.
  • self_signed_tls_client_auth – Public key client X.509 certificate authentication.

Note: A Connect2id server deployment can be configured to support either tls_client_auth or self_signed_tls_client_auth, but not both, due to limitations of commonly available TLS termination software.

14. ID token

14.1 ID token claims

  • Core claims:
    • Required: iss, sub, aud, exp, iat
    • Optional and conditional: auth_time, nonce, acr, amr, sid, at_hash, c_hash, ds_hash
  • Claims switched by configuration: s_hash, jti
  • Supported end-user claim types: Normal, verified (eKYC / Identity Assurance)

14.2 ID token algorithms

Algorithms for securing issued ID tokens:

  • JWS algorithms:

    • RS256, RS384, RS512, PS256, PS384, PS512 – The ID token is signed with a Connect2id server private RSA key.

    • ES256, ES256K, ES384, ES512 – The ID token is signed with a Connect2id server private EC key.

    • EdDSA – The ID token is signed with a Connect2id server private Ed25519 key.

    • HS256, HS384, HS512 – The ID token is HMAC SHA secured with a key derived from the client secret.

  • JWE for optional encryption after signing:

    • Key encryption algorithms:

      • RSA1_5, RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 – Encryption to a client public RSA key.

      • ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW – Encryption to a client public EC key.

      • dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW – Encryption using an AES key derived from the client secret.

    • Content encryption:

      • A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 – With AES/CBC/HMAC/SHA-2.

      • A128GCM, A192GCM, A256GCM – With AES/GCM.

      • XC20P – With extended nonce nonce ChaCha20 / Poly1305.

Unsecured ID tokens with none are also supported.

14.3 ID token refresh

Support for allowing ID token refresh at the token endpoint on an individual authorisation basis. When allowed the token response will include a new ID token, provided the subject (end-user) session bound to the refresh token is still present. If the session was closed or expired an ID token will not be included in the token response.

An authorised OpenID relying party may use the ID token refresh as back-channel check for the end-user session with the OpenID provider still being present.

14.4 Explicit ID token typing

Optional configurable JWT “typ” (type) header, e.g. id_token+jwt.

15. UserInfo

The Connect2id server supports plain as well as JWT-secured UserInfo responses.

15.1 UserInfo claims

15.2 UserInfo algorithms

Algorithms for securing UserInfo responses:

  • JWS algorithms:

    • RS256, RS384, RS512, PS256, PS384, PS512 – The UserInfo is signed with a Connect2id server private RSA key.

    • ES256, ES256K, ES384, ES512 – The UserInfo is signed with a Connect2id server private EC key.

    • EdDSA – The UserInfo is signed with a Connect2id server private Ed25519 key.

    • HS256, HS384, HS512 – The UserInfo is HMAC SHA secured with a key derived from the client secret.

  • JWE for optional encryption after signing:

    • Key encryption algorithms:

      • RSA1_5, RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 – Encryption to a client public RSA key.

      • ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW – Encryption to a client public EC key.

      • dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW – Encryption using an AES key derived from the client secret.

    • Content encryption:

      • A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 – With AES/CBC/HMAC/SHA-2.

      • A128GCM, A192GCM, A256GCM – With AES/GCM.

      • XC20P – With extended nonce nonce ChaCha20 / Poly1305.

15.3 Explicit UserInfo JWT typing

Optional configurable JWT “typ” (type) header, e.g. userinfo+jwt.

16. Request objects / JWT-secured authorisation requests (JAR)

Algorithms for securing request objects (also see JWT Secured Authorization Request or JAR).

  • JWS algorithms:

    • RS256, RS384, RS512, PS256, PS384, PS512 – The request object is signed with a client private RSA key.

    • ES256, ES256K, ES384, ES512 – The request object is signed with a client private EC key.

    • HS256, HS384, HS512 – The request object is HMAC SHA secured with a key derived from the client secret.

  • JWE for optional encryption after signing:

    • Key encryption algorithms:

      • RSA1_5, RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 – Encryption to a client public RSA key.

      • ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW – Encryption to a client public EC key.

      • dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW – Encryption using an AES key derived from the client secret.

    • Content encryption:

      • A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 – With AES/CBC/HMAC/SHA-2.

      • A128GCM, A192GCM, A256GCM – With AES/GCM.

      • XC20P – With extended nonce nonce ChaCha20 / Poly1305.

Unsecured request objects with none are also supported.

17. JWT-secured authorisation responses (JARM)

Algorithms for securing authorisation responses:

  • JWS algorithms:

    • RS256, RS384, RS512, PS256, PS384, PS512 – The response is signed with a Connect2id server private RSA key.

    • ES256, ES256K, ES384, ES512 – The response is signed with a Connect2id server private EC key.

    • EdDSA – The response is signed with a Connect2id server private Ed25519 key.

    • HS256, HS384, HS512 – The response is HMAC SHA secured with a key derived from the client secret.

  • JWE for optional encryption after signing:

    • Key encryption algorithms:

      • RSA1_5, RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 – Encryption to a client public RSA key.

      • ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW – Encryption to a client public EC key.

      • dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW – Encryption using an AES key derived from the client secret.

    • Content encryption:

      • A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 – With AES/CBC/HMAC/SHA-2.

      • A128GCM, A192GCM, A256GCM – With AES/GCM.

      • XC20P – With extended nonce nonce ChaCha20 / Poly1305.

18. OpenID claim types

The Connect2id server supports all OpenID claim types:

  • normal – Claims directly asserted by the provider.

  • aggregated – Claims sourced from an external provider, made available as a signed JWT.

  • distributed – Claims which can be obtained from the endpoint of an external provider using a supplied bearer access token.

  • verified – Claims for eKYC / Identity Assurance.

19. OpenID Connect native SSO for mobile and desktop apps

Native mobile and desktop applications under the control of a single vendor can establish a device session with the Connect2id server to take advantage of the native SSO extension (draft 06).

20. OpenID Connect session management and logout

Supported OpenID Connect session management and logout extensions:

Note: Connect2id server deployments with Redis as the primary in-memory store will not deliver back-channel logout notifications for expired sessions.

21. OpenID Federation 1.0

Supports OpenID Federation 1.0 (draft 25):

  • Configuration of one or more trust anchors (federation operators) and authority hints.
  • Automatic trust anchor JWK set retrieval via web PKI / TLS.
  • Entity configuration endpoint publishing OP and general federation entity metadata.
  • Signed OP JWK set.
  • Federation policy support:
    • Policy operators and checks: value, add, default, one_of, subset_of, superset_of and essential
    • Configurable trust chain max path length, naming constraints and timeouts.
    • Trust marks.
  • Federation client registration:

22. Offline access

The Connect2id server supports authorisations bound to a subject’s session as well as offline access by means of long-lived OAuth 2.0 refresh tokens.

23. Rich authorisation requests (RAR)

Experimental support for OAuth 2.0 Rich Authorization Requests (RFC 9396) is available by devising plugins for the custom token response SPI. Built in support for RAR is planned in a next major Connect2id server release.

24. Subject (end-user) authentication

The Connect2id server supports plug in of arbitrary authentication methods as well as combinations of methods for multi-factor user authentication. Microsoft Active Directory / LDAP is supported out of the box, through the LdapAuth service.

Upon successful login the ID token issued to the client can include information about the authentication strength and the employed methods, by means of the standard acr (Authentication Context Reference) and amr (Authentication Method Reference) ID token claims.

25. Single sign-on (SSO)

26. Claims data sources

The Connect2id server supports aggregation of claims (to be fed into UserInfo responses, ID tokens and access tokens), with optional language tags, from one or more data sources.

Sourcing of end-user claims from Microsoft Active Directory / LDAP is supported out of the box. A generic interface is available for connecting other claims sources, such as relational or NoSQL database, SCIM web services and HR systems.

27. Access tokens

The Connect2id server can issue tokens for accessing its UserInfo endpoint and other external protected resources.

27.1 Access token types

Supported access token types:

  • Bearer – The default type in OAuth 2.0. Specifed in RFC 6750.

  • Bearer with client certificate binding – The token is bound to a self-signed or PKI client X.509 certificate submitted over a mutual TLS connection (HTTPS). Resource servers can validate the binding by inspecting the cnf.x5t#S256 access token claim representing the SHA-256 thumbprint of the client certificate. Specified in RFC 8705.

  • DPoP – The token is bound to a private key belonging to the client, by submitting a client signed JWT to prove the key’s possession. Resource servers can validate the binding by inspecting the cnf.jkt access token claim representing the SHA-256 thumbprint of the client key. Specified in RFC 9449.

27.2 Access token lifetime

The access token lifetime can be configured globally or per individual subject and / or client.

When the access token is issued with a refresh token, the lifetime of the access token is guaranteed to never exceed the (remaining) lifetime or the maximum idle time of the refresh token.

27.3 Access token encoding

In terms of encoding the issued access tokens can be self-contained or identifier-based (see RFC 6749, section 1.4).

27.3.1 Self-contained access tokens

The access token is encoded as a JSON Web Token (JWT). The JWT encapsulates all necessary authorisation details for relying resource servers to process requests from clients.

The JWT is signed and resource servers can obtain the public key for its validation from the Connect2id server’s public JWK set. The signed JWT can be optionally encrypted with an AES key shared with the resource server(s) for confidentiality.

Supported algorithms

JWS:

  • RSA:
  • EC:
    • ECDSA – ES256, ES256K, ES384 and ES512
  • EdDSA – with Ed25519 key

JWE for optional additional encryption after signing:

  • dir – direct encryption with shared symmetric key (AES) with
JWT profiles

Three JWT profiles for access tokens are supported out of the box:

  • c2id-1.1 – Connect2id server specific profile, available since v7.17, with the JWT “typ” (type) header set to “at+jwt”. This is the default profile.

  • c2id-1.0 – Connect2id server specific profile, available since v1.0, outputs identical JWT claims as c2id-1.1 but doesn’t set the JWT “typ” (type) header.

  • oauth-1.0 – Standard profile (RFC 9068) developed at the OAuth working group.

An SPI is available for implementing JWT codecs for other access token profiles.

JWT claim JSON type Description
c2id-1.x oauth-1.0
iss string Issuer URL
sub string Subject (end-user) ID
[ act ] object Actor, in impersonation and delegation scenarios
cid client_id string Client ID
[ aud ]† string array Audience. Can be used to explicitly denote the protected resource(s) for which the access token is intended.
scp scope string array / string Token scope
iat string Issue time (seconds since Unix epoch). The token must not be accepted as valid before that time.
exp string Expiration time (seconds since Unix epoch). The token must not be accepted as valid after that time.
jti string Secure random JWT identifier
[ ats ] string The subject ID type, set to "pairwise" if encoded in this way for the (first) token audience as sector identifier
[ clm ] string array Names of consented OpenID claims, with optional compression
[ cll ] string array Preferred claims locales, as BCP 47 language tags
[ cld ] string object Optional claims fulfillment data
[ uip ] object Preset OpenID claims for release at the UserInfo endpoint
[ sik ] object Encrypted subject session key (for internal use only). Since v14.0.
[ dat ] object Optional data
[ cnf.x5t#S256 ] object Confirmation of client X.509 certificate
[ cnf.jkt ] object Confirmation of client JWK SHA-256 thumbprint

§ Optional JWT claims are denoted in square brackets.

† The audience claim is required in the oauth-1.0 profile. If one isn’t explicitly set for the access token the default value becomes the Connect2id server issuer URL.

Self-contained access tokens can also be inspected by a call to the Connect2id token introspection endpoint.

27.3.2 Identifier-based access tokens

The access token is represented by a secure random 128 bit identifier, protected with an SHA-256 HMAC truncated to 128 bits. The authorisation details are looked up by a call to the Connect2id token introspection endpoint.

An SPI is provided for plugging an alternative identifier generator.

Identifier-based tokens are intended for clients which cannot validate digital signatures, or for applications with a security requirement for immediate revocation effect.

The Connect2id server stores the identifiers in a hashed form, to prevent token leakage if the database or a backup of the database is exposed.

27.4 Feeding additional claims into the access token

OpenID claims can be fed into the issued access tokens by prefixing their name with “access_token:” during authorisation / consent. The claims will be retrieved from the configured claims data sources and will appear on the top-level in the JWT and in introspection responses.

Two additional prefixes are supported:

  • “access_token:uip:” – Causes the OpenID claim to be merged into the top-level “uip” (optional preset UserInfo claims) JSON object claim.

  • “access_token:dat:” – Causes the OpenID claim to be merged into the top-level “dat” (optional data) JSON object claim.

28. Refresh tokens

The Connect2id server issues OAuth 2.0 refresh tokens subject to policy which can be based on client type, access type, or some other chosen criteria.

Available configurations:

  • Refresh token lifetime (default is no lifetime limit).

  • Refresh token maximum idle time (default is no maximum idle time).

  • Refresh token rotation on each use and re-authorisation (default is no rotation). Configurable reuse grace period for clients with slow or poor networking.

Encodings:

  • Identifier-based – For long-lived (persisted) authorisations. The refresh token is an encrypted secure random 128-bit identifier pointing to an authorisation record in the Connect2id server.

  • Self-contained – For transient authorisations. The refresh token is a JSON Web Encrypted (JWE) authorisation record. Enables issue of potentially unlimited number of refresh tokens for a given client and subject (end-user), which can be useful in cases where an end-user has instances of a public client on several devices, but the granted authorisations must not be shared between the client instances.

Public clients using mutual TLS (RFC 8705) or DPoP (RFC 9449) receive appropriately bound refresh tokens.

29. Impersonation

Supported impersonation use cases:

  • Issue of impersonated ID tokens to enable privileged users to log into a client under a different identity.

  • Issue of impersonated access and refresh tokens to enable privileged users to access protected resources under a different identity.

The Connect2id server provides a web API for querying, updating and revoking impersonated tokens and authorisations.

30. Issuer aliases

The Connect2id server supports issuer aliases to enable seamless online migration from one issuer URL to another, or to identify an OpenID provider / OAuth 2.0 authorisation server by multiple URLs.

Supported issuer alias modes:

  • MIGRATION – Enables seamless migration over time to a new issuer URL.
  • PERSISTED_GRANT_ISOLATION – Enforces persisted grant isolation between issuer aliases, a lightweight form of multitenancy.

31. Security Token Service (STS)

Intended for Identity Providers that act as an OAuth 2.0 client / OpenID relying party in federated login scenarios. The STS supports templates for issue of JWTs for the following purposes:

  • JAR – For issue of signed JWT-secured Authorisation Requests (JAR), also called request objects in OpenID Connect.

  • private_key_jwt – For issue of private key client authentication JWTs for use at the token and other endpoints of an OAuth 2.0 authorisation server / OpenID provider.

Supported JWS algorithms:

  • RS256, RS384, RS512, PS256, PS384, PS512 – The token is signed with a Connect2id server private RSA key.

  • ES256, ES256K, ES384, ES512 – The token is signed with a Connect2id server private EC key.

The signature of an issued JWT can be validated using the Connect2id server JWK set published at the /jwks.json endpoint.

32. Metrics and monitoring

The Connect2id server provides a RESTful endpoint for accessing over 100 metrics to monitor usage and performance. The metrics are exported in Dropwizard and Prometheus format.

The collected metrics can also be reported via JMX or Graphite.

33. Special security measures

  • User login credentials are not processed by the Connect2id server to minimise their exposed surface and ease security compliance.

  • The tokens for accessing the integration APIs are configured as SHA-256 hashes instead of plain text to prevent credential exposure in case of an accidental configuration leak.

  • The session identifiers, authorisation codes, identifier-based access tokens and PAR URIs are provisioned with a SHA-256 based message authentication code (HMAC) to differentiate between expired and invalid identifiers, to detect identifier scanning attacks and to minimise the impact to the backend database in a DoS attack.

  • The private signing keys can be stored in a Hardware Security Module to prevent their extraction.

  • Optional explicitly typed ID token and UserInfo JWTs to avoid JWT mix up in client software.

  • Support for a random component in the HTTP security header for passing the client certificate in mTLS.

  • No logging of sensitive credentials at INFO and coarser levels.

34. High-availability and scaling

The Connect2id server can be run in two modes:

  • Standalone – The Connect2id server runs in a single JVM.

  • Cluster – Two or more Connect2id server nodes are clustered for high-availability and load-balancing. Server nodes can be added or removed dynamically. Supported clustering modes:

    • Stateless mode – Ideal for large loads, allows quick up / down cluster scaling. The Connect2id server state is stored entirely in the underlying database(s).

      • Basic – Using the configured SQL or DynamoDB database to store all short and long-lived server data.

      • Redis – Improves performance and latency by using Redis as an additional in-memory database to cache frequently used server data and store sessions and other short-lived objects.

    • Replication mode – Ideal for medium, predictable loads. For improved performance sessions and other short-lived objects are stored on the JVM heap. Persisted server data that is frequently used is also cached there. The in-memory data is continuously replicated between the nodes.

35. Runtime

Required runtime:

  • Java 17
  • Connect2id server 15.x+: Jakarta Servlet 6.0+ compatible container: Apache Tomcat 10.1.x
  • Connect2id server 8.x - 14.x: Servlet 4.0.1+ compatible container: Apache Tomcat 9.0.x

36. Software Bill of Materials (SBOM)

An SBOM in CycloneDX JSON and XML formats is included in the Connect2id server WAR under /WEB-INF/sbom/.

37. Backend databases

The Connect2id server supports the following backend databases:

For persisting durable data, such as client registrations and long-lived authorisations:

  • Relational databases:
  • AWS DynamoDB
  • LDAP v3 directory: OpenLDAP 2.4+, OpenDJ 2.6+ (end of support in 2023)

For in-memory storage and caching outside Infinispan:

  • Redis 6.x, 7.x (including AWS ElastiCache with Redis backend)

38. Reverse proxy support

The Connect2id server supports all reverse proxies that are able to pass on a client certificate in an HTTP security header, in the case of mutual TLS to handle client authentication using the tls_client_auth and self_signed_tls_client_auth methods.

Popular supported reverse proxy software:

39. Hardware Security Module (HSM) support

PKCS#11 compliant Hardware Security Modules are supported for the following purposes:

Supported key types:

  • RSA 2048, 3072 or 4096 bit.
  • EC with P-256, P-384, and P-521 curves.

The Connect2id server can be optionally configured with a list of PKCS#11 key IDs (aliases) to load, to enable sharing the HSM with other applications.

Automatic roll-over of the PKCS#11 keys is performed according to the validity time window of the key’s X.509 certificate.

Questions or comments?

Get in touch with Connect2id support.