Connect2id server datasheet
1. OpenID certified provider
- Session management
- RP-initiated logout
- Front-channel logout
- Back-channel logout
- 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:
- Financial API — Part 1: Read Only API Security Profile
- Financial API — Part 2: Read & Write API Security Profile
Identity assurance / eKYC:
- HEART profile for OAuth 2.0
- HEART profile for OpenID Connect
- HEART profile for Fast Healthcare Interoperability Resources (FHIR) OAuth 2.0 scopes
Government / eID:
- International Government Assurance Profile (iGov) for OAuth 2.0
- International Government Assurance Profile (iGov) for OpenID Connect 1.0
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 tokens. RESTful and native interfaces enable the integration of end-user and management UIs, of custom business logic.
Standard OAuth 2.0 / OpenID Connect endpoints
Server metadata -- Publishes the URLs of the standard server endpoints, the authorisation and identity provision capabilities, the supported security 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 certificate chain, required by client applications to validate ID tokens, self-contained access tokens and other issued objects.
Client registration -- Registers client applications with the Connect2id server so they can request ID and / or access tokens. Supports the optional client read, update and delete operations.
Federation client registration -- Registers (explicitly) OpenID Connect Federation 1.0 entities that are OpenID relying parties.
PAR -- Receives Pushed Authorisation Requests (PAR) from registered clients.
Authorisation -- Receives OAuth 2.0 authorisation requests and OpenID authentication requests from registered clients.
Token -- Exchanges a valid OAuth 2.0 grant for an access, and / or ID token.
Token revocation -- Lets client applications 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 -- Facilitates 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 the associated access and refresh tokens.
Subject session store -- Enables query, access and management of end-user sessions with the Connect2id server.
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 issue event listeners -- Enables plug-in of listeners for ID and access token issue 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 metadata validator -- Enables additional validation and shaping of OAuth 2.0 client / OpenID relying party registration metadata.
PAR validator -- Enables additional validation of Pushed Authorisation Requests (PAR).
4. Supported OAuth 2.0 / OpenID Connect response types
code -- Used to obtain an ID, access and refresh token at the Token endpoint.
id_token -- Used to obtain an ID token via the front-end (with browser redirection).
token -- Used to obtain an access token via the front-end (with browser redirection).
token id_token -- Used to obtain an ID token and access token via the front-end (with browser redirection).
code id_token -- Used 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 -- Used 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.
5. Supported 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 via a form post to the redirection URI.
6. Supported OAuth 2.0 grant types
The Connect2id server supports all core OAuth 2.0 grant types:
authorization_code -- Used in the authorisation code flow.
refresh_token -- Used for long-lived authorisations.
password -- Used for highly-trusted or privileged client applications, when the other safer grant types (e.g.
authorisation_code) are not available.
client_credentials -- Used by clients acting on their own behalf (the client is also the resource owner).
The following bearer assertions are also supported:
JWT Bearer -- Using a signed JSON Web Token (JWT) as a grant.
SAML 2.0 Bearer -- Using a SAML 2.0 assertion as a grant.
Additional custom grants can be implemented via the endpoint for direct authorisation.
7. Supported OAuth client types
Confidential as well as public clients are supported:
Confidential clients -- can maintain the confidentiality of their credentials, typically implemented on a secure server
Public clients -- cannot maintain the confidentiality of their credentials, typically clients on end-user devices
8. Proof key for code exchange (PKCE)
The Proof Key for Code Exchange (PKCE) protocol (RFC 7663) is supported to protect against authorisation code interception attacks on public OAuth clients.
The following code verifier transforms are supported:
- S256 -- SHA-256 (mandatory to implement)
- plain -- for legacy clients
9. Supported subject identifier types
The Connect2id server supports the following subject identifier types:
- public -- Public subject identifier
- pairwise -- Pairwise subject identifier, implemented by encrypting the public subject identifier with deterministic AES in SIV mode.
10. 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: response_type, response_mode, client_id, scope, redirect_uri, state, code_challenge, code_challenge_method, request, request_uri
OpenID Connect: nonce, display, prompt, max_age, ui_locales, claims_locales, id_token_hint, login_hint, acr_values, claims, purpose
Custom authorisation request parameters are handled via the authorisation session API.
11. Supported client authentication methods
- 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
- self_signed_tls_client_auth -- Public key client X.509 certificate authentication
- request_object -- Request object authentication with a private key for automatic client registration in OpenID Connect Federation 1.0.
12. Supported ID token algorithms
The Connect2id server supports all standard JOSE algorithms for securing issued ID tokens by means of a digital signature, HMAC and optional additional encryption.
RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512 -- The ID token is signed with a provider's private RSA or EC key.
HS256, HS384, HS512 -- The ID token is HMAC SHA protected with a key derived from the client secret.
RSA1_5, RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW -- The ID token is additionally encrypted with a client's public RSA or EC key.
dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW -- The ID token is additionally encrypted with an AES key derived from the client secret.
none -- The ID token is unsecured.
13. Supported UserInfo algorithms
The Connect2id server supports all standard JOSE algorithms for securing JWT UserInfo responses by means of a digital signature, HMAC and optional additional encryption.
RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512 -- The
UserInfo JWT is signed with a provider's private RSA or EC key.
HS256, HS384, HS512 -- The UserInfo JWT is HMAC SHA protected with a key derived from the client secret.
RSA1_5, RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW -- The UserInfo JWT is additionally encrypted with a client's public RSA or EC key.
dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW -- The UserInfo JWT is additionally encrypted with an AES key derived from the client secret.
14. Supported request object algorithms
RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512 -- The
request object JWT is signed with a clients's private RSA or EC key.
HS256, HS384, HS512 -- The request object JWT is HMAC SHA protected with a key derived from the client secret.
RSA1_5, RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW -- The request object JWT is encrypted with a server's public RSA or EC key. Signed and encrypted JWTs are supported.
dir -- The request object JWT is encrypted with an AES key derived from the client secret. Signed and encrypted JWTs are supported.
none -- The request object JWT is unsecured.
15. Supported 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.
16. OpenID Connect session management and logout
Supported OpenID Connect session management and logout extensions:
OpenID Connect Session Management 1.0 (draft 28)
OpenID Connect Front-Channel Logout 1.0 (draft 02)
OpenID Connect Back-Channel Logout 1.0 (draft 04)
Note: Connect2id server deployments with Redis as the primary in-memory store will not deliver back-channel logout notifications for expired sessions.
17. OpenID Connect Federation 1.0
Supports OpenID Connect Federation 1.0 (draft 12):
- Configuration of one or more trust anchors (federation operators) and intermediates.
- Automatic trust anchor JWK set resolution via PKI / TLS.
- Publishes entity statement with OP metadata.
- Federation policy support:
- All standard policy operations: subset_of, one_of, superset_of, add, value, default, essential
- Configurable max path length, naming constraints and timeouts during trust chain resolution.
- Trust marks.
- Client registration:
- (Automatic on the roadmap).
18. 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.
19. Rich authorisation requests (RAR)
20. Subject (end-user) authentication
Any authentication method as well as combinations for multi-factor authentication is supported. Microsoft Active Directory / LDAP is supported out of the box, through the LdapAuth service.
Upon successful login a client application can be informed of the employed authentication strength and methods, communicated through the standard acr (Authentication Context Reference) and amr (Authentication Method Reference) ID token claims.
21. Claims 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.
22. Access tokens
22.1 Access token encoding
22.1.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 JWS algorithms for token signing:
Supported JWE algorithms for optional token encryption:
- dir -- direct encryption with shared symmetric key (AES) with
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 in development at the OAuth working group.
An SPI is provided to plug in an alternative profile.
|JWT claim||JSON type||Description|
|sub||string||Subject (end-user) ID|
|( act )||object||Actor, in impersonation and delegation scenarios|
|( 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.|
|jwt||string||Secure random JWT identifier|
|( clm )||string array||Names of consented OpenID claims|
|( 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|
|( dat )||object||Optional data|
|( cnf.x5t#S256 )||object||Confirmation of client X.509 certificate|
§ Optional JWT claims are denoted in 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 token can also be inspected by a call to the Connect2id token introspection endpoint.
22.1.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 RSA 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.
22.2 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.
22.3 Client X.509 certificate bound access tokens
When mutual TLS is used at the token endpoint the Connect2id server binds the issued access token to the client's X.509 certificate. Resource servers can validate the binding by inspecting the x5t#S256 access token claim which represents the SHA-256 thumbprint of the client certificate.
23. Refresh tokens
The Connect2id server can issue OAuth 2.0 refresh tokens subject to policy which can be based on client type, access type, or some other chosen criteria.
Refresh token lifetime (default is no expiration).
Refresh token rotation on each use and re-authorisation update (default is no rotation).
Identifier-based -- For long-lived (persisted) authorisations. The refresh token is an encrypted secure random 128-bit identifier pointing to a an authorisation record in the Connect2id server database.
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.
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.
25. Metrics and monitoring
26. 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.
- Java 11+ JVM (Java 8 for Connect2id server releases up to 7.10)
- Servlet 3.0+ compatible container: Apache Tomcat 7+
28. Backend databases
The Connect2id server supports the following backend databases:
For persisting durable data, such as client registrations and long-lived authorisations:
- Relational databases:
- MySQL 5.7.8+ (incl. compatible MariaDB editions and AWS AuroraDB DBaaS), 8.x not officially supported yet)
- PostgreSQL 9.5+ (incl. AWS AuroraDB DBaaS)
- Microsoft SQL Server 2016+
- H2 1.4+ (for testing and development only)
- LDAP v3 directory: OpenLDAP 2.4+, OpenDJ 2.6+
- AWS DynamoDB
For in-memory storage and caching outside Infinispan:
- Redis 3.2.x and 4.0.x (including AWS ElastiCache with Redis backend)
29. Hardware Security Module (HSM) support
- Signing issued ID tokens, JWT-encoded UserInfo and self-contained (JWT) access tokens.
- Decrypting request objects (JARs).
Supported key types:
- EC with P-256, P-384, and P-521 curves.
Automatic key roll-over is performed according to the validity window of the key's X.509 certificate.
Questions or comments?
Get in touch with Connect2id support.