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

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

UBAA_TEXT = {0} is your Event ID

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

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:

client_secret_post

client_id, client_secret

client_secret_basic

client_secret_jwt

client_assertion, client_assertion_type

private_key_jwt

client_assertion, client_assertion_type

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

Token Endpoint

Errors reported by the Token endpoint are processed as follows