Introduction

This document is the Developer Guide for Ubisecure SSO OpenID Connect Client-Initiated Backchannel Authentication (later CIBA) flow based integrations. The CIBA authentication method can be used to integrate custom backchannel authentication methods to Ubisecure SSO. These types of authentication transactions are not driven by the browser but happen as backend requests from the Ubisecure SSO to the CIBA implementation.

Ubisecure SSO supports CIBA Core 1.0 specification with certain limitations. These limitations are described in this document.

For more details on how to configure a CIBA method, please refer to

OpenID Connect CIBA authentication method - SSO

Abbreviations

Abbreviation	Description
CIBA	Client-Initiated Backchannel Authentication
OP	OpenID Provider. In this article, the CIBA implementation

Reference implementation

Swedish BankID Mobile - SSO authentication adapter acts as Ubisecure's reference implementation of the CIBA authentication method. The adapter publishes its OpenID Connect CIBA compliant API using Swagger which can be browsed for more details.

How CIBA works

CIBA has two primary endpoints that are required to be implemented

Backchannel Authentication Endpoint
Token Request Endpoint (not used in push mode)

In addition to this an implementation of CIBA is recommended to expose the following endpoints to ease up configuring a new CIBA method to Ubisecure SSO:

OAuth2 Authorization Server metadata with CIBA Provider metadata extensions

When end-user authentication is performed by Ubisecure SSO it initiates an external authentication request using the Backchannel Authentication Endpoint. As a response Ubisecure SSO expects an authentication request identifier which it will use for subsequent token endpoint requests. When the authentication has been initiated, the CIBA implementation performs end-user authentication using a desired method. This can be for example sending a notification to end-user's mobile device and ask for confirmation, or asking the user to use an external fingerprint reader. The possibilities are unlimited. The ability to perform any out-of-bounds authentication is the flexibility CIBA introduces for Ubisecure SSO.

When the authentication has been completed by the CIBA implementation, Ubisecure SSO receives a token response via a request to the Token Endpoint. The following sequence diagram describes the flow:

Figure 1: Basic CIBA flow using poll mode

When the CIBA OP implementation receives a Backchannel Authentication Request in step 2 it typically does the following actions

Perform client authentication according to the used client authentication method
Validate the request parameters
Start the authentication process according to the request parameters (e.g. send a notification to the authentication device)

The end user is further authenticated via an out-of-bound method as mentioned before. Ubisecure SSO will continue polling the token endpoint until the request expires or the CIBA OP returns a successful token response. The step 8 typically involves the following actions

Perform client authentication according to the used client authentication method
Validate the request parameters
If the user is authenticated
- then create a token response with a signed ID token
else if the authentication is not yet completed
- then return an error with code authorization_pending

For successful token response Ubisecure SSO will use the associated ID token to obtain relevant information about the authenticated user.

Supported features

Ubisecure SSO supports the following CIBA features.

Backchannel Authentication request parameters

In addition to the mandatory Backchannel Authentication request parameters, the following optional parameters are used and supported by Ubisecure SSO

Parameter Description

login_hint

A hint to the OP regarding the end-user for whom authentication is being requested.

Ubisecure SSO uses this parameter to denote the user being authenticated. For unregistered CIBA method, this is the value that the user enters in the login screen whereas for the registered CIBA method the value can be obtained from a directory user attribute. See OpenID Connect CIBA Authentication method configuration chapter for more details.

binding_message

A human-readable identifier or message intended to be displayed on both the consumption device and the authentication device to interlock them together for the transaction by way of a visual cue for the end-user.

Ubisecure SSO supports delivering binding message as denoted by UBAA_TEXT message property. This defaults to

UBAA_TEXT = {0} is your Event ID

which will generate a random number as the event ID used in the binding message.

user_code

A secret code, such as a password or pin, that is known only to the user but verifiable by the OP.

Ubisecure SSO supports user code if it is supported by the CIBA integration. This is denoted by the CIBA Provider metadata extension property backchannel_user_code_parameter_supported. If the value of this metadata attribute is true, and the CIBA integration returns error code missing_user_code for the backchannel authentication request, Ubisecure SSO will ask the user to enter the secret code.

If the backchannel_user_code_parameter_supported is set to false Ubisecure SSO will not use the user_code request parameter in any circumstances.

Authentication result delivery modes

Ubisecure SSO supports the following Authentication result delivery modes

Poll

Poll mode

The poll mode is described in Figure 1: Basic CIBA flow using poll mode. In this delivery mode, Ubisecure SSO initiates an authentication request as follows

POST /oidc/bc-authorize HTTP/1.1
Host: localhost
accept: application/json
Content-Type: application/x-www-form-urlencoded

binding_message=1234%20is%20your%20Event%20ID&client_assertion=eyJ..&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_id=ubisecure-sso&login_hint=johndoe&scope=openid

As a response Ubisecure SSO should get something similar to

HTTP/1.1 200 OK
Content-Type: application/json 

{
  "expires_in": 600,
  "interval": 5,
  "auth_req_id": "465382f0-2375-452c-807e-f326d329ecfe"
}

Now as Ubisecure SSO received a valid authentication request id, it will start polling the service with a token request similar to

POST /oidc/token HTTP/1.1
Host: localhost
accept: application/json
Content-Type: application/x-www-form-urlencoded

auth_req_id=465382f0-2375-452c-807e-f326d329ecfe&client_assertion=eyJ...&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_id=ubisecure-sso&grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba

Polling interval

If the polling interval is available in the authentication response Ubisecure SSO will respect that. Otherwise either system defaults or method configuration is used for polling and slowing down in case of slow_down error code from the Token Endpoint request.

When the user is successfully authenticated via an authentication device, Ubisecure SSO should receive

HTTP/1.1 200 OK
Content-Type: application/json 

{
  "access_token": "eyJ..",
  "expires_in": 3600,
  "token_type": "Bearer",
  "id_token": "eyJ.."
}

Ubisecure SSO then further obtains the ID token from the response and performs a normal authentication and authorization process for the identity denoted by the received ID token.

Client authentication

Ubisecure SSO can perform client authentication towards a CIBA implementation using the following methods:

Authentication method	Related request parameters	Description
client_secret_post	client_id, client_secret	Client authentication performed using client ID and secret in the request body.
client_secret_basic		Client authentication performed using client ID and secret by using the HTTP Basic Authentication scheme.
client_secret_jwt	client_assertion, client_assertion_type	Client authentication performed using a signed JWT using a pre-shared client secret.
private_key_jwt	client_assertion, client_assertion_type	Client authentication performed using a signed JWT using a private key.

For more information related to these client authentication methods, please refer to OpenID Connect Core 1.0 - Client Authentication.

Security considerations

In addition to CIBA Core 1.0 - Security considerations this chapter discusses some security considerations that should be taken into account when implementing a CIBA OP.

Use HTTPS

The CIBA OP should always enforce HTTPS.

Token response best practices

The CIBA OP should at least sign ID tokens it grants. In addition ID tokens should have short expiration time. Consider the lifetime in minutes or hours rather than days.

Client authentication

Client authentication should be used always. Shared secrets can be used but are not recommended. Using asymmetric keys is the recommended approach for client authentication.

Prevent unsolicited authentication request with user code

The user_code backchannel authentication request parameter can be used to prevent unsolicited authentication requests from appearing to end-users.

Error handling

This chapter describes how errors from a CIBA OP implementation are mapped by Ubisecure SSO. Some error can be localized. Please refer to Internationalization - SSO for more details.

Backchannel Authentication Endpoint

Errors reported by the Backchannel authentication endpoint are processed as follows

Error code	Behaviour
`invalid_request`	As this error is caused by an invalid request it is considered as system error. Verify that your CIBA implementation processes requests according to the CIBA Core 1.0 specification. This error should not occur in a production environment.
`invalid_scope`	As this error is caused by an invalid scope it is considered as system error. Verify that you implementation accepts valid scopes. This error should not occur in a production environment.
`expired_login_hint_token`	As `login_hint_token` is not supported by Ubisecure SSO this error is considered a system error. This error should not occur in a production environment.
`unknown_user_id`	Ubisecure SSO considers that the user was not found. An error is shown in the login screen which can be localized using message property `USER_NOT_FOUND`.
`unauthorized_client`	As this error indicates that Ubisecure SSO was not authorized to access the CIBA OP it is considered as system error. Verify that the client authentication is performed as expected by the CIBA OP implementation. This error should not occur in a production environment.
`missing_user_code`	If the CIBA OP metadata field `backchannel_user_code_parameter_supported` indicates that user codes are supported Ubisecure SSO will request the user to enter a secret code which is sent to the CIBA OP using the `user_code` parameter. If this error occurs when `backchannel_user_code_parameter_supported` is set to `false`, the error is considered as system error which should not occur in a production environment.
`invalid_user_code`	If user codes are supported and Ubisecure SSO has sent the secret code to the CIBA OP this error will be prompted to the user as localizable error indicating that the given secret or password was incorrect. This error can be localized using message property INVALID_CREDENTIALS.
`invalid_binding_message`	This error code indicates that the binding message is invalid or unaccepted to use with this CIBA OP. Consider altering the text according to the CIBA OP implementation. This is considered as system error. This error should not occur in a production environment.
`invalid_client`	Client authentication failed. This is a configuration error and is considered as system error. Verify that the client authentication is performed as expected by the CIBA OP implementation. This error should not occur in a production environment.
`access_denied`	Access was denied before any user interaction. An error is shown in the login screen which can be localized using message property `LOGIN_CANCEL`.

Token Endpoint

Errors reported by the Token endpoint are processed as follows

Error code	Behaviour
`authorization_pending`	The authorization is still pending. Ubisecure SSO will continue to poll the token endpoint.
`slow_down`	Ubisecure SSO will slow down the polling frequency accordingly. CIBA method configuration property `polling.interval.increase` can be used to control how much the polling frequency is slowed down.
`expired_token`	The authentication request has expired. An error is shown in the login screen which can be localized using message property `LOGIN_EXPIRED`.
`access_denied`	Access was denied by the user. An error is shown in the login screen which can be localized using message property `LOGIN_CANCEL`.
`invalid_grant`	This error can occur if the authentication request would belong to a different client than Ubisecure SSO. Although in theory this is possible, it is unlikely to occur. Ubisecure SSO handles this similarly to `access_denied` error. An error is shown in the login screen which can be localized using message property `LOGIN_CANCEL`.
`invalid_request`	As this error is caused by an invalid request it is considered as system error. This error should not occur in a production environment.
`unauthorized_client`	As this error indicates that Ubisecure SSO was not authorized to access the CIBA OP it is considered as system error. Verify that the client authentication is performed as expected by the CIBA OP implementation. This error should not occur in production environment.

Browser not supported