The Client Initiated Backchannel Authentication flow (or CIBA for short), is an authentication flow which allows the user to have a different authentication device from his application consumption device. In other words, a user can be on his laptop and authenticate with his mobile phone.
Currently CYM-Identity only supports the Salesforce Authenticator App as an authentication channel in CIBA.
Since the CIBA flows implemented by CYM-Identity require the user must be already logged in to the application, they can only be used for identity verification or step up authentication
Before authenticating users, make sure that you have the following information :
- OpenID Provider Metadata (autodiscovery URL) : Your admin can provide you with the URL which lives in
https://${realm.url}/oauth/${realm.name}/.well-known/openid-configuration - Your client credentials : client_id & client_secret (optional)
- The client must have the grant_type
urn:openid:params:grant-type:ciba enabled
This flow is only available in version 0.4+
To initiate an authentication request, you must send a POST request to the backchannel_authentication_endpoint available in the Realm autodiscovery document
The parameters available are :
| Parameter | Required | Description |
|---|
| client_id | Yes | The client_id which was provided by your admin |
| client_secret | No | Only required if the client authenticates through client_secret_post |
| client_assertion | No | Only required if the client authenticated through client_secret_jwt or private_key_jwt |
| client_assertion_type | No | Only required if a client_assertion is used. The value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
| scope | No | A space separated list of scopes required for this authentication request. If this parameter is ommited, all scopes assigned to the client will be used. If a scope is requested and has not been assigned to the client, an error will be returned |
| requested_expiry | No | The timeout for the authentication request |
| id_token_hint | Yes | A valid id_token received by the client for the user. The id_token can be expired, the only requirement is that the signing key must still be part of the Realm JWKS |
| binding_message | No | A message to be displayed to the user to allow her to link the authentication request on her Salesforce Authenticator app with the application |
Example request :
POST /bc-authorize HTTP/1.1
client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&id_token_hint=ID_TOKEN_RECEIVED_PREVIOUSLY
&binding_message=Hello CYM-Identity
HTTP/1.1 400 Bad Request
{
"error": "AN_ERROR_CODE",
"error_description": "AN_ERROR_DESCRIPTION"
}
HTTP/1.1 200 OK
{
"auth_req_id": "AN_AUTH_REQ_ID",
"interval": 3,
"expires_in" : 120
}
Once your application successfully retrieves an auth_req_id, it can poll the token_endpoint for a status on the pending request. Make sure that your application abids to the interval returned. The request will be cancelled if the token_endpoint is polled too frequently.
| Parameter | Required | Description |
|---|
| grant_type | Yes | The value must be urn:openid:params:grant-type:ciba |
| client_id | No | Only required if the client authenticates through client_secret_post or does not authenticate (for native clients) |
| client_secret | No | Only required if the client authenticates through client_secret_post |
| client_assertion | No | Only required if the client authenticated through client_secret_jwt or private_key_jwt |
| client_assertion_type | No | Only required if a client_assertion is used. The value must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
| auth_req_id | Yes | The auth_req_id received from the CIBA Initiation request |
Example request :
POST /token HTTP/1.1
grant_type=urn:openid:params:grant-type:ciba
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&id_token_hint=ID_TOKEN_RECEIVED_PREVIOUSLY
&binding_message=Hello CYM-Identity
HTTP/1.1 400 Bad Request
{
"error": "AN_ERROR_CODE",
"error_description": "AN_ERROR_DESCRIPTION"
}
If the user has not yet approved the request on her Salesforce Authenticator App, the error returned is authorization_pending.
HTTP/1.1 200 OK
{
"access_token": "AN_ACCESS_TOKEN_VALUE",
"id_token" : "AN_ID_TOKEN",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token" : "A_REFRESH_TOKEN"
}