Integration interfaces
The Connect2id server provides a set of interfaces for linking external data sources, designing customised user journeys, and integrating application-specific authorisation logic. These interfaces fall into two categories:
- Web interfaces – REST and JSON-based APIs for front-end integration and straightforward connectivity to web services.
- Java Service Provider Interfaces (SPI) – Native Java plugins for maximum efficiency and performance. These plugins can also implement web hooks to external services.
To run an OpenID provider / OAuth authorisation 2.0 server, it’s sufficient to link a user authentication source and a user interface (UI) via the authorisation session web API. All other integration points are optional.
| Interface | Type | Requirement | Purpose |
|---|---|---|---|
| Authorisation session | web | required | Integrate a login page (UI), subject (end-user) authentication methods, and business / authorisation logic for front-channel flows. |
| Logout session | web | optional | Integrate a logout page (UI) for end-session requests from client applications and the IdP. |
| Direct authorisation | web | optional | Obtain ID, access and / or refresh tokens directly, without user-user interaction. Allows the implementation of custom OAuth 2.0 grants and flows. |
| Authorisation store | web | optional | Query, update, and revoke OAuth 2.0 / OpenID Connect authorisations and tokens. |
| Subject session store | web | optional | Query, and manage subject (end-user) sessions with the Connect2id server. |
| Key store | web | optional | Inspect, generate, rotate, and revoke Connect2id server keys. |
| Security Token Service (STS) | web | optional | Request issuance of JAR and `private_key_jwt` JWTs for upstream federated login, and issuance of `login_hint_token`s for CIBA. |
| Web session bootstrap | web | optional | Allow native clients to open WebViews with a pre-established session for an authenticated subject (end-user) at the IdP, providing a seamless login experience for web applications. |
| Monitoring | web | optional | Obtain server usage and performance metrics and run health checks. |
| Configuration check | web | optional | Validate a Connect2id server configuration before applying it. |
| Tenants registry | web | optional | Manage Connect2id server tenants (multitenant edition only). |
| Claims source | SPI | required | Integrate OpenID Connect claims sources, such as LDAP directories, SQL databases, and HR management systems. |
| Password grant handler | SPI | optional | Plug in logic to handle OAuth 2.0 resource owner password credentials grants. |
| Client credentials grant handler | SPI | optional | Plug in logic to handle OAuth 2.0 client credentials grants. |
| JWT bearer assertion grant handler | SPI | optional | Plug in logic to handle client-issued and third-party issued (token service) JWT bearer assertion grants. |
| SAML 2.0 bearer assertion grant handler | SPI | optional | Plug in logic to handle client-issued and third-party issued (token service) SAML 2.0 bearer assertion grants. |
| Token exchange grant handler | SPI | optional | Plug in logic to handle token exchange, including impersonation (act-as) and delegation (on-behalf-of) scenarios. |
| CIBA handler | SPI | optional | Plug in logic to handle CIBA requests. |
| Web SSO eligibility checker | SPI | optional | Plug in additional checks whether an OAuth 2.0 authorisation / OpenID authentication request is eligible for web SSO. |
| Device SSO handler | SPI | optional | Plug in logic to handle device SSO authorisations by native clients. |
| Token issue events | SPI | optional | Record or send access and ID token issuance events. |
| Authentication and consent events | SPI | optional | Record or send end-user authentication and authorisation events. |
| Custom access token encoding and introspection | SPI | optional | Customise access token encoding and token introspection responses. |
| Custom token response | SPI | optional | Customise token success and error responses. |
| Client registration interceptor | SPI | optional | Intercept requests at the client registration endpoint to handle software statements and other signed requests. |
| Client metadata validator | SPI | optional | Carry out additional validation or shaping of OAuth 2.0 client / OpenID relying party registration metadata after the Connect2id server has completed the standard validations. |
| Authorisation request validator | SPI | optional | Carry out additional validation and optional modification of received authorisation requests. |
| PAR validator | SPI | optional | Carry out additional validation and optional modification of received Pushed Authorisation Requests (PAR). |
| Private key JWT certificate verifier | SPI | optional | Verify qualified X.509 certificates for private key JWT client authentication. |
| Client authentication interceptor | SPI | optional | Intercept client authentication success and error events for logging, reporting, audit, and other purposes. |
| Client secret store codec | SPI | optional | Hash or encrypt client secrets before persisting them to storage. Supports importing encoded secrets. |