People you don’t expect to operate from Area-51
Episode 02: Technical Perspective on CIBA
Jarvis never wanted to keep things in secrecy. Here goes Jarvis on area 51.
“ Oh yeah…The people who currently working in area51 are……
Yes, it is me, Vivek, his colleagues and mentors. They are in discussion about CIBA, an alien protocol maybe.”
Stop Jarvis!
Don’t intimidate them to yearn to know about that protocol. Hey you, yes you! the reader here, do you have any idea about CIBA?
If No, stop here and have a look at what this CIBA preaches.
If you have read, welcome to the area 51 of WSO2. And this is Vivek writing off about CIBA [Client Initiated Backchannel Authentication].
Why worry about a place where we cannot peek into or thing which is kept in solitary confinement. CIBA is opened to all. Learn it and strive through the IAM arena.
Jarvis keeps your heads up. You had earned some audiences and you gave my friends a very good introduction to CIBA last week.
Now as Jarvis decoded shall we start seeing CIBA with a more technical perspective?
CIBA is simply an authentication flow which decouples authentication device and consumption device. Have a look at the article written by Jarvis. Kidding !! I wrote that but Jarvis helped me. Thanks, Jarvis.
As Jarvis clinging to the word “Decouple”, Yes CIBA decouples the authentication device and consumption device.
- The user wants a service from a Consumption device [eg: A point of sales]. He invokes the transaction by providing his identity.
- Consumption device started the authentication process with an “Authentication request” to the Authorization server [step 1].
- On receiving the request, the Authorization server sends an auth_req_id to the consumption device with the response [step 2].
This auth_req_id is used for further transactions, callbacks and it is a critical element in request-response validation.
- Now the authorization server initiates communication with end-user and request credentials and then his consent to approve the consumption device to process the request[step 3].
- The server sends a notification to the consumption device once it receives consent and credentials[step 4].
- Now Client requests the ID and Access token[step 5].
- And the server sends the token [step 6].
The End Points
We need to be aware of three Endpoints. Two of them are mandatory for all flow patterns[reside on server side] and other is optional in regard to the flow and resides on the client-side.
- CIBA Endpoint
- This mandatory Endpoint accepts CIBA Authentication requests from client app of consumption device.
- And in return send a CIBA Authentication response with required parameters or an error response if the request is not valid.
2. Token Endpoint
- This mandatory Endpoint accepts the token request from the client app of the consumption device.
- And in return respond with tokens or error response if the request is not valid[ie; required parameters missing, auth_req_id expired and etc.]
3. Client Notification endpoint
- Set by the client himself.
- Will be pinged by the Authorization Server with a notification after successful communication with the end-user at the authentication device.
- It is optional and mandatory only if authentication flow follows Ping mode and Notification patterns are used.[see below]
There are three basic flow patterns after the authentication response and communication with the end-user.
- Poll Mode
The authorization server will send an authentication request to the authentication device previously registered by the Client with a unique identifier sent by Consumption device to CIBA endpoint. Once the credentials and consents are received tokens will be available to be issued. The client will continuously poll the Token Endpoint to get a response token. If the token is available tokens will be provided. Else error response will be issued.
2. Ping Mode
The authorization server will send an authentication request to the authentication device previously registered by the Client with a unique identifier sent by Consumption device to CIBA endpoint. Once the credentials and consents are received a notification is sent to Client notification endpoint about the availability of tokens. Upon receipt of the notification, the Client makes a request to the token endpoint to obtain the tokens.
3. Push Mode
The authorization server will send an authentication request to the authentication device previously registered by the Client. Once the credentials and consents are received token will be ready and Authorization server sends a notification to Consumption device, inclusive of ID and access token.
And we are aware of the Authentication device, client app operating on Consumption device and the Authorization Server. Aren’t we?
Now we will be briefly looking into the steps of the authentication flow.
1. The Authentication request
- Authentication is initiated by the client [And that’s why it is Client-Initiated Back-channel Authentication].
- Client needs to address the authorization server about for whom it is requesting the authentication.
- So it is mandatory that there should be some user identity from Consumption device for which it can request an access and ID token.
- There are three ways for a consumption device to add user identity.
- login_hint :
It is a hint to the Authorization server about the user for whom the Authentication flow is initiated. The value may be an email address, phone number, account number, username, etc., which identifies the end-user to the OP. The value may be directly collected from the user by the Client just before CIBA Authentication request or can be obtained in other ways.
{ "login_hint" : "vivek@xyz.com" }2. login_hint_token :
A token containing information identifying the end-user for whom authentication is being requested. But the details are profile specific.
{ "login_hint_token": "eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IlJTMjU2In0.eyJ
zdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6InBob25lIiwicGhvbmUiOiIrMTMzMDI
4MTgwMDQifX0.YB8_8OksJd1FwfVsIUlH-rs9cPhkIa0DUi7OVW_Da9gP6huBxf7
aSDl3qKXA20uT1zThuSiYz0bdz8J_KPRHuC6vwoFlz9yBJ9ksWOP28sHPPi19_4-
xidwnb8P12-RoXwY2eAF82_NAn2vmpvqUjluoWyNHay8vguChIutqziV0bFl-7oa
xp36i4elbvT_DYeg20a0jz4wIBKc_46K8I28ErkwbI5O35GfElPXl-4J55NHkkOs
DxuUYQtWjSM3wme19735XWq2DIT2nmLFi4HzzT27W0cnJg7L_ai9uNNBvIx_Mp5A
bcmkR83apR4jxnQuE5Xf23qyRpAhawe7IPQ" }3. id_token_hint:
An ID Token previously issued to the Client is being passed back as a hint to identify the end-user for whom authentication is being requested.
{"id_token_hint" : "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzcyNiJ9.eyJpc3MiOiJo
dHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjI0ODI4OTc2MTAwMSIs
ImF1ZCI6InM2QmhkUmtxdDMiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20i
LCJleHAiOjE1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFVJ
LjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJXNKWAg_dxVynv
MHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8iczD16A5gNjSD7yenT5fslrrW-NU
_vtmi0s1puoM4EmSaPXCR19vRJyWuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LH
fW1G74NY5DaPv-V23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1
EFWtjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7MtVb2UlCw
DQrVlg" }Exactly one of this must be used. Invalid request otherwise.
Other Authentication Request parameters:
- Scope
+ Required parameter.
+ “openID” is the mandatory value.
+ Eg: { "Scope" : "openid%20email%20example-scope" }- ACR values
+ Optional parameter.
+ Acr stands for Authentication Context class Reference.
+ Indicate whether authentication happens sucessfully or not.
+ If '0' - Did not meet the authentication requirements sucessfully.
+ Highly recommended that if request has this, let response has this too.- User-code
+ Optional parameter
+ Secret code - pin/passwword only known to end user
+ Used to authorize the Authentication request - Binding message
+ Optional parameter.
+ Human readable message displayed on both Authentication and Consumption devices to interlock.
+ Eg. { "binding_message" : "TransactionID19081995" }
- Requested expiry
+ Optional parameter
+ Positive integer value
+ This allows the client to request 'expires_in' value for auth_req_id [see below]- client_notification_token
+ Mandatory parameter if the flow is ping / push
+ A bearer token provided by client.
+ Used to authenticate the notification or token response.
+ 160 bits recommended.
+ Eg. {"client_notification_token" : "8d67dc78-7faa-4d41-aabd-67707b374255" }Sample request
POST http://localhost:8080/CIBAEndPoint HTTP/1.1
Host:http://localhost:8080
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW{
"scope" : "openid%20email%20example-scope"
"client_notification_token" : "8d67dc78-7faa-4d41-aabd-67707b374255"
"binding_message: "W4SCT"
"login_hint_token":"eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IlJTMjU2In0.eyJzdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6InBob25lIiwicGhvbmUiOiIrMTMzMDI4MTgwMDQifX0.YB8_8OksJd1FwfVsIUlHrs9cPhkIa0DUi7OVW_Da9gP6huBxf7aSDl3qKXA20uT1zThuSiYz0bdz8J_KPRHuC6vwoFlz9yBJ9ksWOP28sHPPi19_4xidwnb8P12RoXwY2eAF82_NAn2vmpvqUjluoWyNHay8vguChIutqziV0bFl7oaxp36i4elbvT_DYeg20a0jz4wIBKc_46K8I28ErkwbI5O35GfElPXl4J55NHkkOsDxuUYQtWjSM3wme19735XWq2DIT2nmLFi4HzzT27W0cnJg7L_ai9uNNBvIx_Mp5AbcmkR83apR4jxnQuE5Xf23qyRpAhawe7IPQ"
}
1.1 Signed Authentication Request
- It is recommended to use signed Authentication request.
- All request parameters are encoded as claims of the signed JWT[JSON Web Token].
- JWT must contain all authentication request parameters.
- The authentication request is signed with the private key of the client and verified with the public key of the client which was already with the authorization server [asymmetric signture].
- It is mandatory that signed JWT contains these parameters.
1. aud : Identifies the audience of the token.Here it is the Authorization Server.2. iss : Identifies the issuer of the JWT. Here it must be client_id of OAuth Client.3. exp : Identifies the validity of signed JWT.4. iat : Identifies the issued time of JWT.5. nbf : Identifies the time before which the signed authentication request is unacceptable.6. jti : This uniquley identifies the signed authentication request.
A sample JWT with claims :
{
"iss": "s6BhdRkqt3",
"aud": "https://server.example.com",
"exp": 1537820086,
"iat": 1537819486,
"nbf": 1537818886,
"jti": "4LTCqACC2ESC5BWCnN3j58EnA",
"scope": "openid email example-scope",
"client_notification_token": "8d67dc78-7faa-4d41-aabd-67707b374255",
"binding_message": "W4SCT",
"login_hint_token": "eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IlJTMjU2In0.eyJzdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6InBob25lIiwicGhvbmUiOiIrMTMzMDI4MTgwMDQifX0.YB8_8OksJd1FwfVsIUlHrs9cPhkIa0DUi7OVW_Da9gP6huBxf7aSDl3qKXA20uT1zThuSiYz0bdz8J_KPRHuC6vwoFlz9yBJ9ksWOP28sHPPi19_4xidwnb8P12RoXwY2eAF82_NAn2vmpvqUjluoWyNHay8vguChIutqziV0bFl7oaxp36i4elbvT_DYeg20a0jz4wIBKc_46K8I28ErkwbI5O35GfElPXl4J55NHkkOsDxuUYQtWjSM3wme19735XWq2DIT2nmLFi4HzzT27W0cnJg7L_ai9uNNBvIx_Mp5AbcmkR83apR4jxnQuE5Xf23qyRpAhawe7IPQ"
}Signed Authentication Request :
POST http://localhost:8080/CIBAEndPoint HTTP/1.1
Host: http://localhost:8080
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
{
"request"="eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJzNkJoZFJrcXQzIiwiYXVkIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJleHAiOjE1Mzc4MjAwODYsImlhdCI6MTUzNzgxOTQ4NiwibmJmIjoxNTM3ODE4ODg2LCJqdGkiOiI0TFRDcUFDQzJFU0M1QldDbk4zajU4RW5BIiwic2NvcGUiOiJvcGVuaWQgZW1haWwgZXhhbXBsZS1zY29wZSIsImNsaWVudF9ub3RpZmljYXRpb25fdG9rZW4iOiI4ZDY3ZGM3OC03ZmFhLTRkNDEtYWFiZC02NzcwN2IzNzQyNTUiLCJiaW5kaW5nX21lc3NhZ2UiOiJXNFNDVCIsImxvZ2luX2hpbnRfdG9rZW4iOiJleUpyYVdRaU9pSnNkR0ZqWlhOaWR5SXNJbUZzWnlJNklsSlRNalUySW4wLmV5SnpkV0pxWldOMElqcDdJbk4xWW1wbFkzUmZkSGx3WlNJNkluQm9iMjVsSWl3aWNHaHZibVVpT2lJck1UTXpNREk0TVRnd01EUWlmWDAuWUI4XzhPa3NKZDFGd2ZWc0lVbEgtcnM5Y1Boa0lhMERVaTdPVldfRGE5Z1A2aHVCeGY3YVNEbDNxS1hBMjB1VDF6VGh1U2lZejBiZHo4Sl9LUFJIdUM2dndvRmx6OXlCSjlrc1dPUDI4c0hQUGkxOV80LXhpZHduYjhQMTItUm9Yd1kyZUFGODJfTkFuMnZtcHZxVWpsdW9XeU5IYXk4dmd1Q2hJdXRxemlWMGJGbC03b2F4cDM2aTRlbGJ2VF9EWWVnMjBhMGp6NHdJQktjXzQ2SzhJMjhFcmt3Ykk1TzM1R2ZFbFBYbC00SjU1Tkhra09zRHh1VVlRdFdqU00zd21lMTk3MzVYV3EyRElUMm5tTEZpNEh6elQyN1cwY25KZzdMX2FpOXVOTkJ2SXhfTXA1QWJjbWtSODNhcFI0anhuUXVFNVhmMjNxeVJwQWhhd2U3SVBRIn0.IBuxW3F_L9tj9f6fGC7FnVsH9B9RoJYA8QyxtnxgOgMc1kcnufyGxdtd7lU1TjPCVNsbkR0vfGasCmoMYSMohPObnwAlkm8Yf0uglhxM83B0dj_I10vwlMGnVFvydaH9wnacM4Ln7EJIYOxtZa33abf1PB3fLs29GKOBmgNPn3NrxJ0iCLb0F243556Ypzdhcyj7vM8ukNzkKT3eQ0ZWJ1vVRToThgKyNHvLFpeSfJtSH5ycMYOjobqXUgKpQryUbgbpqsM1XnUV8aBD5d8VF5fQoz0PQWq63B_zpC22nstIFxNmfxztSFpnW0vgX0htNKOtL_HMwFRfwh71g"
}1.2 Request validation
- Authenticate client and validate for registered authentication method [poll, ping, push] for its client id.
- If the request is signed need to verify the signature of JWT.
- Validate the requests. If more than one hints present invalidate the request
- Validate for hint and checks if it corresponds to valid-user
2. Authentication Response
- Once the request is successfully validated, the Authorization server responds with “200 OK” indicating that the authorization request has been accepted.
- And Authorization server sends an Authorization response.
- If failed invalidation, the response message is sent with error_message and error_code. We can see them later in detail.
Parameters of the Authentication Response
- auth_req_id :
+ Required parameter.
+ Unique identifier for the Authentication request made.2. expires_in
+ Required parameter.
+ Positive long value representing seconds.
+ Marks the expiry time of auth_req_id.
+ If expired, has to respond with error response.3. Interval
+ Optional parameter [Mandatory only if ping/poll].
+ Positive long value representing seconds.
+ Denotes the polling frequency.Sample response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store{ “auth_req_id”:”702552be-f0ef-4ca0–9f66-c766e9525e63",
”interval”:2,
”expires_in”:3600
}
2.1 Response Validation
If the Client app of the consumption device received “200 OK”, then it should
- Validate for the presence of all parameters. Especially, auth_req_id which is very critical for any further interactions.
- Should clean up all expired authentication responses.
3. Communication
- Now OP(OpenId provider-Authorization server) communicates with the end-user.
- This communication step is out of the scope of the specification of CIBA.
- We need to choose a better option to implement.
- Some sample communication:
- End-user installs the client app in mobile[Authentication device]. Then he registers to the Authorization server with user identity and appid. Whence authentication is needed, appid of given user identity is classified and pushed a notification as a request for consent and credentials.
- Authorization server releases an app of its own, where a user can register with his identity and app id. For any registered client app, if a user needs a service at consumption device, client app in consumption device sends user identity [hints] to the Authorization Server and Authorization server searches for appid of the particular user identifier and push a notification to the authentication device of the particular user. Then he authenticates.
4. Notification in Push
In “Push” mode, once the consent and credentials are obtained by the Authorization server, Server creates an ID and access tokens and send a notification to client_notification_endpoint inclusive of ID and access tokens.
client_notification_token is a mandatory parameter in authentication request if the prefered [registered] flow is push or ping
POST http://payhere.com/clientnotification HTTP/1.1
Host: http://payhere.com
Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255
Content-Type: application/json{
"auth_req_id": "702552be-f0ef-4ca0–9f66-c766e9525e63",
"access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
"token_type": "Bearer",
"refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
"expires_in": "3600",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzcyNiJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjI0ODI4OTc2MTAwMSIsImF1ZCI6InM2QmhkUmtxdDMiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20iLCJleHAiOjE1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFVJLjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJXNKWAg_dxVynvMHnk3uJc46feaRIL4zfHf6Anbf_TbgMaVO8iczD16A5gNjSD7yenT5fslrrWNU_vtmi0s1puoM4EmSaPXCR19vRJyWuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LHfW1G74NY5DaPv-V23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1EFWtjGPPMj6kDVrikec47yK86HArGvsIIk1uExynJIv_tgZGE0eZI7MtVb2UlCwDQrVlg"
}
5. Notification in Ping
- Notification in “Ping” mode is a mere notification to the client.
- Once the credentials and consents are received from an authentication device, the server will be ready to issue ID and access token. So it sends a notification to the Consumption device. To be specific, send a notification to Client Notification Endpoint.
- Then Client app in Consumption device will initiate token request which is all similar to Polling.
- Parameter involved : auth_req_id [mandatory]
POST http://payhere.com/clientnotification HTTP/1.1
Host: http://payhere.com
Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255
Content-Type: application/json{
"auth_req_id": "702552be-f0ef-4ca0–9f66-c766e9525e63"
}
4. Token Request
This step is common to ping/poll flow patterns.
Parameters involved.
- grant_type
+ Mandatory parameter.
+ value should be urn:openid:params:grant-type:ciba
2. auth_req_id
+ Mandatory parameter.
+ The parameter is used to validate the request.Sample token request
POST http://localhost:8080/TokenEndPoint
Host:http://localhost:8080
Content-Type: application/json
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW{
"grant_type":"urn:openid:params:grant-type:ciba"
"auth_req_id":"702552be-f0ef-4ca0–9f66-c766e9525e63"
}
5. Token Response
Token response too, common for ping and poll
- Token Response usually adds access token, ID token and optionally a refresh token.
- It also includes expires_in parameter to mark the expiry time of the token provided.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store{
“access_token”: “G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN”,
“token_type”: “Bearer”,
“refresh_token”: “4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16”,
“expires_in”: 3600,
“id_token”: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzcyNiJ9.eyJpc3MiOiJo
dHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjI0ODI4OTc2MTAwMSIsImF1ZCI6InM2QmhkUmtxdDMiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20iLCJleHAiOjE1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFVJLjlNBX5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJXNKWAg_dxVynv
MHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8iczD16A5gNjSD7yenT5fslrrW-NU
_vtmi0s1puoM4EmSaPXCR19vRJyWuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LH
fW1G74NY5DaPv-V23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1
EFWtjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7MtVb2UlCwDQrVlg"”
}
Here I conclude for today. We have a lot to discuss dear.Error codes, security issues, implementation architecture and some more. Sooner the architecture blog might be up-here as Jarvis and I had several sessions on building up architecture to integrate CIBA feature into WSO2 Identity Server. Thanks to Ruwan Abeykoon [Architect — WSO2 ], Farasath Ahamed [Associate Tech-Lead -WSO2] and Senthalan Kanagalingam[Senior Software Engineer -WSO2] for helping me in figuring out an architecture. We will have a discussion soon buddy. Till then ready your architecture if interested and let’s discuss on that too. See you people.
Thanks, Jarvis.!!
See you.
References:
- https://www.authlete.com/news/20190213_ciba_pr/
- https://medium.com/@darutk/ciba-a-new-authentication-authorization-technology-in-2019-explained-by-an-implementer-d1e0ac1311b4
- https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.9
- https://blog.usejournal.com/lets-break-up-dear-decouple-ourselves-88159a86aba
