Connect2id server datasheet

1. Server endpoints

The Connect2id server supports all standard OAuth 2.0 / OpenID Connect endpoints for single sign-on (SSO), authorisation and identity provision. It also provides a number of powerful RESTful and native interfaces for integration of end-user, monitoring and administration interfaces / tools.

Standard OAuth 2.0 / OpenID Connect endpoints

  • Provider metadata — Advertises the standard OAuth 2.0 / OpenID Connect endpoint URLs, identity provider capabilities and supported security (JOSE + JWT) algorithms.

  • Provider JWK set — Publishes the provider’s public JSON Web Key (JWK) set and certificate chain, required by client applications to verify ID tokens and other issued objects.

  • Client registration — Registers client applications with the Connect2id server, so they can login end-users and request ID and / or access tokens. The endpoint can be operated in a public (open registration) or private mode. Supports the optional client read, update and delete operations.

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

  • Token — Exchanges a valid OAuth 2.0 grant for an access, refresh and / or ID token. Supported grant types: authorisation codes, refresh token, resource owner password, client credentials, JWT bearer assertion and SAML 2.0 bearer assertion.

  • Token introspection — Allows resource servers to inspect issued access tokens.

  • Token revocation — Allows client applications to revoke issued access and refresh tokens.

  • UserInfo — Releases consented claims (name, contact and other details) about the subject (end-user) to authorised clients.

Integration & plugin interfaces

  • Authorisation session — Provides login page (UI) integration, plug-in of arbitrary end-user authentication methods and custom business / authorisation logic for setting the claims and scopes of the issued ID and access tokens.

  • Direct authorisation — Facilitates direct issue of ID, access and refresh tokens, without going through the standard OAuth grant mechanisms. Can be used to proxy and federate external identity providers, including 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 — Enables query, access and management of the end-users’ SSO sessions with the Connect2id server.

  • Monitoring — Provides access to over 100 server usage and performance metrics and execution of health-checks.

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

2. Supported OAuth 2.0 / OpenID Connect response types

The Connect2id server supports all standard OpenID Connect response types. The server can be configured to accept only a subset of these, either for the entire provider or on a per client basis. The token response is generally not supported as it falls outside the scope of OpenID Connect; OAuth 2.0 clients should use token id_token instead.

  • code — Used to request an ID token and access token at the Token endpoint.

  • id_token — Used to request an ID token (implicit grant).

  • token id_token — Used to request an ID token and access token (implicit grant).

  • code id_token — Used to request an ID token with the authorisation response as well as an ID token and access token at the Token endpoint.

  • code id_token token — Used to request an ID and access token with the authorisation response and at the Token endpoint.

3. Supported OAuth 2.0 response modes

The Connect2id server supports all standardised 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.

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

4. Supported OAuth 2.0 grant types

The Connect2id server supports all core OAuth 2.0 grant types. The server can be configured to accept only a subset of these, either for the entire provider or on a per client basis.

  • authorization_code — Used in the authorisation code flow.

  • implicit — Used in the implicit 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 universal endpoint for direct authorisation.

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

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

7. Supported subject identifier types

The Connect2id server supports the following subject identifier types:

  • public — Public subject identifier
  • pairwise — Pairwise subject identifier (using SIV AES deterministic encryption)

8. OpenID Connect authentication request parameters

The Connect2id server supports all mandatory and optional OpenID authentication request parameters:

  • Supported OAuth 2.0 parameters: response_type, response_mode, client_id, scope, redirect_uri, state, code_challenge, code_challenge_method

  • Supported OpenID Connect parameters: nonce, display, prompt, max_age, ui_locales, claims_locales, id_token_hint, login_hint, acr_values, claims, request, request_uri

9. Supported client authentication methods

The Connect2id server supports all standard authentication methods for OAuth 2.0 clients.

  • client_secret_basic — Basic HTTP authentication with client secret
  • client_secret_post — Basic HTTP authentication with client secret
  • client_secret_jwt — JWT assertion authentication with client secret
  • private_key_jwt — JWT assertion authentication with a private RSA or EC key that belongs to the client

10. Supported ID token algorithms

The Connect2id server supports all standard JSON Web 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 the provider’s RSA or EC JWK.

  • HS256, HS384, HS512 — The ID token is HMAC SHA protected with 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 JWK.

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

11. Supported UserInfo algorithms

The Connect2id server supports all standard JSON Web Algorithms for securing UserInfo JWT 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 the provider’s RSA or EC JWK.

  • HS256, HS384, HS512 — The UserInfo JWT is HMAC SHA protected with 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 JWK.

  • dir, A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW — The UserInfo JWT is additionally encrypted with an AES key derived from the client secret.

12. Supported claim types

The Connect2id server issues normal claims. Aggregated and distributes claims, asserted by a claims provider other than the OpenID provider, will be supported in a future release.

  • normal Claims directly asserted by the provider.

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

14. Subject (end-user) authentication

Password-based authentication of end-users as well as stronger multi-factor methods are supported.

Upon successful login a client application may be informed of the employed authentication strength and methods, communicated through the standard acr and amr ID token claims.

The Connect2id server supports integration of arbitrary authentication methods. Microsoft Active Directory / LDAP is supported out of the box, through an LdapAuth service.

15. Claims data sources

The Connect2id server supports aggregation of claims (standard UserInfo and others), 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.

16. Access tokens

The Connect2id server can issue self-contained as well as identifier-based access tokens (see RFC 6749, section 1.4):

  • Self-contained: The access token is encoded as a secure JSON Web Token (JWT) containing all necessary authorisation details for the resource server. The JWT has an RSA signature, which the resource server can verify with the Connect2id server’s public key. The standard RS256, RS384, RS512, PS256, PS384 and PS512 JWS signature algorithm are supported. The JWT may also optionally be encrypted with AES for confidentiality. The following claims (fields) can be included in the JWT:

    • sub — subject (end-user ID)
    • cid — client ID
    • iss — issuer
    • aud — audience
    • scp — scope
    • iat — token issue time
    • exp — token expiration time
    • clm — consented OpenID claims
    • dat — optional custom data.

    The self-contained token can also be inspected by a web call to the Connect2id token introspection endpoints.

  • Identifier-based: The access token is represented by a secure 256 bit random identifier, protected with additional SHA-256 HMAC. The corresponding authorisation is looked up by a web call to the Connect2id token introspection endpoint. Identifier-based tokens are intended for minimal clients that cannot verify JWT signatures, or for applications which security requires revocation to have an immediate effect.

17. Impersonation

Impersonation use cases are supported:

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

18. Metrics and monitoring

The Connect2id server proves a RESTful endpoint for accessing over 100 different metrics to monitor usage and performance.

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

19. High-availability and scaling

The Connect2id server can be run in two modes.

  • Single server — The Connect2id server runs in a single server instance.

  • Cluster — The Connect2id server runs in a cluster configuration for high-availability and load-balancing. Server nodes can be added or removed dynamically. Supported clustering modes:
    • Replication — sessions and other in-memory data is replicated between the Connect2id server nodes
    • Distribution — in-memory data is distributed across the nodes with some specified redundancy; intended for high loads and more than 10 million users
    • Invalidation — intended for setups with a secondary in-memory / cache store, such as Redis or AWS Redis ElastiCache.

20. Runtime

Required runtime:

  • Java 8+ JVM
  • Servlet 3.0+ compatible container: Apache Tomcat 7+

21. Data backends

The Connect2id supports the following backends for persisting its own data, such as client registrations and long-lived authorisations:

  • LDAP v3 directory: OpenLDAP 2.4+, OpenDJ 2.6+
  • Relational database: MySQL 5.7.8+, PostgreSQL 9.5+, H2 1.4+
  • Redis, AWS ElastiCache in Redis mode

Questions or comments?

Get in touch with Connect2id support.