Connect2id server 19.0

The cross-device OAuth flow (CIBA) to authenticate users and request tokens typically invokes a native IdP app. This allows for a user experience that is both convenient and relatively secure, utilising the user’s mobile device and a familiar biometric authentication. When Connect2id introduced support for CIBA, the server included a flexible plugin interface (SPI) for deployments to integrate an IdP app, by means of a push notification service or another method.

In line with the CIBA roadmap, this release ships a built-in plugin, which, when enabled, allows an IdP app instance to poll the Connect2id server directly for pending back-channel requests. The app polls the server by POSTing a session identifier for the logged-in user. The simplicity of this method means it can be implemented on any device, OS and framework.

POST /ciba-sessions/rest/v1/queue/poll HTTP/1.1
Host: c2id.com
Authorization: SID WYqFXK7Q4HFnJv0hiT3Fgw.-oVkvSXgalUuMQDfEsh1lw

The release is marked as major (19.0) as it introduces a new data structure (a bounded, or circular, queue) to store the pending CIBA requests. On startup the Connect2id server will automatically create the necessary table (SQL or DynamoDB), or Redis database, to store these requests.

How does a CIBA flow looks like when using the plugin:

1. A CIBA client makes a back-channel authorisation request to the Connect2id server.

2. The server authenticates the client and performs initial processing of the request. An important part is this is to take the received user identity hint (login_hint_token, id_token_hint or login_hint) and resolve it to an ID for an actual user at the IdP. If the hint is an email address or telephone number, this is done by calling by calling the login hint resolver.

3. A CIBA request that passed the initial processing is handed over by the Connect2id server to the plugin, which places it in a queue. The number of pending requests that a user can have in the queue at any one time is limited to two. If this limit is reached, the plugin will reject the CIBA request with an access_denied error. Pending requests that aren’t claimed expire according to their expires_in value, typically 5 to 10 minutes.

4. An IdP app polls the Connect2id server for pending CIBA requests at the /ciba-sessions/rest/v1/queue/poll resource. To access the queue the app includes an Authorization header with the session ID of the logged-in user.

5. If a CIBA request is pending, the IdP app prompts the user to authorise it.

6. If the CIBA request is authorised, the IdP app POSTs that fact to the Connect2id server at the /ciba-sessions/rest/v1/authorize resource. This POST requires a callback token that the Connect2id server attached in the pending CIBA request.

   If the CIBA request was not authorised, or the user didn’t act upon it, the IdP app simply lets it expire.

7. In the meantime the client is polling the token endpoint, which will return the requested tokens as soon as the IdP app has POSTed the authorisation, as explained above.

To sum up, this plugin provides a simple poll-based method for a native IdP app to retrieve pending CIBA requests from the Connect2id server. The API utilises HTTP and is not tied to a particular OS or framework.

More information about Connect2id server 19.0 can be found in the release notes below.

Download 19.0

For the signature validation: Public GPG key

Standard Connect2id server edition

Apache Tomcat package with Connect2id server 19.0: Connect2id-server.zip

GPG signature: Connect2id-server.zip.asc

SHA-256: f1ec3d234d0e64a77cae1900d745dfc1327eb0c5875b85249bfd56b51f10562f

Connect2id server 19.0 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: 02237cef02513e06012306840062fd39f7701d544eae1f34b9ca6e8b4d6676ba

Multi-tenant edition

Apache Tomcat package with Connect2id server 19.0: Connect2id-server-mt.zip

GPG signature: Connect2id-server-mt.zip.asc

SHA-256: bfb2dd24dd8951e2566ec05305e362f028ec08673f94281b0fd4494c30722335

Connect2id server 19.0 WAR package: c2id-mt.war

GPG signature: c2id-mt.war.asc

SHA-256: cddcfc1f6e59fd75fe01cad35d040875a6d069177e05bbb1c2e6ae2f6c8dff2b

Questions?

For technical questions about this new release contact Connect2id support. To purchase a production license for the Connect2id server, renew or upgrade your support and updates subscription, email our sales.

Release notes

19.0 (2025-05-28)

Summary

• Includes a built-in plugin for the CIBARequestHandler SPI that puts all CIBA requests that the Connect2id server successfully pre-preprocessed into
  a queue, which native IdP apps or an IdP backend service can poll at
  /ciba-sessions/rest/v1/queue/poll. A CIBA request that isn’t claimed from the queue expires automatically, according to its expires_in value.

  An IdP app instance that has established a session for the user with the Connect2id server can retrieve pending CIBA requests for the user by presenting its session ID. Alternatively, a bearer token can be presented; this method is intended when the polling is performed by a trusted backend service. The callback_token attached to the pending CIBA request is required to submit the consented scope and other parameters at the /ciba-sessions/rest/v1/authorize resource, in the case when the user was successfully authenticated and the request authorised.

  The queue imposes a limit of two pending CIBA requests per user. CIBA requests that overflow are rejected with a CIBA access_denied error response.

Configuration

• /WEB-INF/cibaRequestQueue.properties – New configuration for the CIBA request queue plugin (implementing the CIBARequestHandler SPI).

  • op.ciba.requestQueue.enable – Enables / disables the CIBA request queue plugin. Disabled (false) by default.

  • op.ciba.requestQueue.apiAccessTokenSHA256 – Optional access token to poll the CIBA request queue at the CIBA sessions web API (/ciba-sessions/rest/v1/queue/poll), represented by its SHA-256 hash (in hexadecimal format). The hash is a measure to prevent accidental leakage of the token through configuration files, logs, etc. The token is of type Bearer, non-expiring and must contain at least 32 random alphanumeric characters to make brute force guessing impractical.

    Additional access tokens, for token roll-over or other needs, can be configured by appending a dot (.) with a unique label to the property name, e.g. as op.cibaRequestQueue.apiAccessTokenSHA256.1=abc...

  • op.ciba.requestQueue.requestParams – CIBA request parameters to include in the queued messages, as comma and / or space separated list of. The default are: scope, claims, purpose, authorization_details, binding_message, user_code, request_context.

• /WEB-INF/infinispan-*.xml

  • Adds a new ciba_request_queue table. In existing Connect2id server deployments with an SQL RDBMS or DynamoDB the server will automatically create the table on startup. For SQL databases the automatic table creation is enabled by default and can be turned off by setting the dataSource.createTableIfMissing Java system property to false.

Web API

• /ciba-sessions/rest/v1

  • New queue/poll resource, made available when the CIBA request queue plugin is enabled. When enabled native IdP app instances can poll the resource to retrieve pending CIBA requests that the Connect2id server has received and validated for the logged-in IdP app user.

    To poll the resource the HTTP POST request must include an Authorization header with the IdP app session ID (SID). Alternatively, the resource may be accessed with a bearer token (op.cibaRequestQueue.apiAccessTokenSHA256) in the Authorization header, in which case the request must specify the subject (user).

    If a CIBA request is pending the resource returns an HTTP 200 OK response with the subject (user) identifier, the type of CIBA login hint used, selected CIBA request parameters (`op.cibaRequestQueue.requestParams) and other information that may be necessary for the consent prompt. If no CIBA request is pending the resource returns an HTTP 204 No Content response.

SPI

• Upgrades the Connect2id server SDK to com.nimbusds:c2id-server-sdk:5.13

  • The CIBARequestHandler SPI is updated to enable plugins to throw a GeneralException when the request is rejected, for example due to the request queue for the resolved subject being full. The GeneralException should include an appropriate HTTP status and error code.

Resolved issues

• The CIBA handler callback tokens receive an explicit JWT type “ciba-authz-token+jwt” (issue server/1087).

• Adds missing login_hint_tokens SQL create table statement for Connect2id server 18.x to WEB-INF/sql/create-table-statements-*.sql and WEB-INF/sql-mt/create-table-statements-*.sql (issue server/1088).

• The published OpenID provider / OAuth 2.0 authorisation server grant_types metadata must indicate when CIBA support is enabled (issue server/1089).

Dependency changes

• Upgrades to com.nimbusds:c2id-server-sdk:5.13

• Upgrades to com.nimbusds:oauth2-oidc-sdk:11.25