Published in


Architecture for Implementing Client Initiated Back-channel Authentication

Episode 03: Proxy Architecture for CIBA

Everyone loves to build and destroy. Though it is easy to destroy things in a second, it is difficult to build something. It takes time. It requires patience. It needs hard work and reflection. It yearns for guidance. Building something is always a beautiful feeling.

I myself love my heartbeat to resonate with nature’s sound. Always wanted to build a mansion by the sea, where I could always listen to the sound of rolling waves and not even a pin-drop mechanical noise. Or I would like to build a villa, by the mountain and river where the mist could always be felt at my feet. I always wanted ‘she’, be dwelling among the untrodden ways. So the inhabitants, I can stay in peace and bliss.

A Case Study — Minister & WEIRD City people

Fig.1. Case Study — Minister & WEIRD city people

Recently I was blessed with a chance of designing an architecture along with some senior people.

  • We need to build a service hut for a minister as he had the office built among the mountains [He got my point]; A no man's land and such a quiet place. Though he wants to continue serving the people, he never wanted the traffic getting closer to him as he is sick of the noise by a load of service stations polling for services, especially annoyed by the “WEIRD” city service stations. The people are nasty in “WEIRD” city and wanted the service at once. So service stations keep polling!
  • We build a service-hut; a micro house situates in between the office and “WEIRD” city.
  • Though other city service stations can directly get service from minister, we should never allow “WEIRD” city service stations to go directly to the minister to get a service.
  • Service hut gets the service requests from service stations established in “WEIRD” city.
  • People of busy towns [who keep polling for services] reach out service stations and service stations initiate the service request for them.
  • Service hut receives service requests and sort the requests out, verify and process everything in the best possible way and then send it to minister[office] only for approvals.
  • Incase if the signature of “WEIRD” city people needed, will send them directly through the post to “Authentication stations” and get it verified.
  • Further proceedings will be taken care with minimal effort and send a response[confirmation] to service stations through service hut, once the service request is confirmed.

“She dwelt among the untrodden ways”.Yes, the office of a minister is. Except for the service hut, the path to the minister’s office is unknown for any people from “WEIRD” city whereas people from other villages know it well.

The Approach of Architecture — V1.0

The above was the case study which we can relate us to CIBA. Since we are going to implement CIBA feature and hence we need to figure out a good architecture. And We thought of implementing it on WSO2 Identity Server as an extension to it [& Since I work on this project as an intern].

Please Do read what CIBA is all about and its basics from these blogs. And can find the code from below repo [Don’t worry about the code section if there is any in the blog. We will see them in a separate blog later]

1. “CIBA” — Let’s Break-up dear !!! [Episode 01: Basic Understanding of CIBA]

2. People you don’t expect to operate from Area-51 [Episode 02: Technical Perspective on CIBA]

3. GitHub Repo :

Important Factors to consider about CIBA :

  1. CIBA stands for Client-Initiated Authentication request
  • That is even without user interaction client initiating the authentication request for the user of its own interest.
  • But CIBA never lets down a user. The client app can obtain a user identity from the user and can initiate the request for him.

2. CIBA ensures decouples authentication

  • Since CIBA is originally designed for Clients[consumption devices] initiating the authentication request for users, hence both consumption devices and authentication devies[devices which user uses to authenticates himself] should be physically separated, CIBA preaches decoupled authentication.
  • Solution: But WSO2 Identity Server lacks decoupled authentication for now, but since BioMetric Authenticator is on the cards, we can ensure the decoupled authentication.

3. CIBA introduces Polling

  • This had been our main concern as polling introduces load into WSO2 Identity Server.
  • Solution: We thought of the Proxy approach which we understood through the case study above[read the case study again]


  1. The Minister's office — This will be WSO2 Identity server and it continues to provide the service to any other service providers
  2. Service Hut — This will be the CIBA Proxy Server and this is only meant for the service providers subscribed to CIBA feature
  3. Weird” city service stations — The Consumption devices who use CIBA feature
  4. Weird” city Authentication stations — The Authentication devices
  5. other cities — Other service providers and client apps
  6. People — end users

And for the moment we consider one proxy for each client [client app with client id obtained after registering in IS].

Basic Layout Architecture

Fig.2. CIBA Architecture Layout + Sequence

Why this Approach??

We choose Proxy Approach because

  1. CIBA is so specific than any other implemented persisting features in wso2 IS, that it requires polling. Polling will always create load on WSO2 identity server. So to reduce the load on Identity server we chose this approach.
  2. If it is to scale the Identity server to distribute the load, it would cost much even if we require an extra core. But if we are to scale up because of polling it is less costly to scale CIBA proxy.
  3. Since the world is heading towards microservice architecture thought of taking CIBA & Device FLOW[similar feature under development] as a new microservice.
  4. In my personal opinion, this architecture will motivate the community around WSO2 IS to try out new extensions and set an example how a dev can exploit this architecture to retain from the dependency curve when developing the component inside of WSO2 IS

The Sequence Flow of Proxy Approach

  1. Consumption device obtains a valid identifier for the user they want to authenticate. [Consider it to be user_name]
"user_name" : "vivek"

2. Consumption device initiates an interaction flow to authenticate their users [CIBA Authentication Request]

POST http://localhost:8080/CIBAEndPoint HTTP/1.1
Host: http://localhost:8080
Content-Type: application/x-www-form-urlencoded
"request" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzNkJoZFJrcXQzIiwiYXVkIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJleHAiOjE1NjkzMTY4ODYsImlhdCI6MTUzNzgxOTQ4NiwibmJmIjoxNTM3ODE4ODg2LCJqdGkiOiI0TFRDcUFDQzJFU0M1QldDbk4zajU4RW5BIiwic2NvcGUiOiJvcGVuaWQgZW1haWwgZXhhbXBsZS1zY29wZSIsImNsaWVudF9ub3RpZmljYXRpb25fdG9rZW4iOiI4ZDY3ZGM3OC03ZmFhLTRkNDEtYWFiZC02NzcwN2IzNzQyNTUiLCJiaW5kaW5nX21lc3NhZ2UiOiJXNFNDVCIsImxvZ2luX2hpbnQiOiJ2aXZlayJ9.jgc2rCK9yPhDlmJLhvarUiFlH-NurSDV967CCXxTc3g"

3. Proxy Server Validates the Consumption Device[Business Case-optional implementation]


4–5.a. Proxy Server Validates the Authentication Request and issues an Authentication Response.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{ “auth_req_id”:”702552be-f0ef-4ca0–9f66-c766e9525e63",

5.b. Proxy Server initiates authorization request to Authorization endpoint of WSO2 IS [ Proxy’s internal HTTP call]

https://localhost:9443/oauth2/authorize?scope=openid&response_type=code&state=" + auth_req_id + "&redirect_uri="+CIBAParameters.getInstance().
getCallBackURL()+"&client_id="+ ConfigurationFile.getInstance().getCLIENT_ID()+"&user=vivek

* 6–10

The Authorization Request is handled by the WSO2 IS and authentication framework. The physical prospect of the Sequence flow will give a detail about the interaction among framework, authenticators and endpoints.

11. Proxy Server Receives Authorize_code [ with user identifier sent with authorization request ] if successful. Else error code.

Authorization Code is received at:

12. If Authorize-code send authorize_code to token Endpoint


MultiValueMap<String, String> map =
new LinkedMultiValueMap<String, String>();
map.add("grant_type", "authorization_code");
map.add("code", code);
map.add("redirect_uri", CIBAParameters.getInstance().getCallBackURL());
map.add("state", idenitifier);

HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<MultiValueMap<String, String>>(map, headers);

String token = restTemplate.postForObject("https://localhost:9443/oauth2/token", request, String.class);

13.Receive token and persists

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

The flow after 5.b varies according to modes Poll,Ping,Push.

We can check for token availbility and can send Token Response accordingly. Tokens if tokens found.Else, will send Error Response.

If the CIBA proxy has a physical structure!


This proxy approach required us t do some compromises and bargain.

  1. It is required to store token outside of WSO2 IS.

This is a big issue where we allow access and dID tokens to be stored outside of the Identity Server. This is totally unacceptable and Architecture — V1.1 will address this issue.

2. Used existing authorize code flow

Though the specification says it's mandatory to have new grant_type, CIBA Proxy also excepts the new grant_type,

"grant_type" : "urn:openid:params:grant-type:ciba"

But when Proxy initiates the token request, it follows authorization_code as the

grant_type = authorization_code

This approach is also alleged. So we will be addressing this issue in Architecture — V1.1 as well.


  • We consider Polling Only. Push is obsolete as Finacial Grade API has not recommended it. Ping has similar flow except for Proxy push notification about ‘Authorization Response’.And then only Consumption device will have a Token Request.
  • Don't Get upset over code snippets over there and I could read your thoughts on how it would actually work. Our next episode will be mainly in this demonstration.

My Sincere thanks to Ruwan Abeykoon [architect], Farasath Ahamed[Associate TechLead] and Senthalan Kanagalingam[SSE], Janak Amarasena in helping me out to come up with this architecture. And hope, the next will be on how to set up and run CIBA Proxy, using our POC.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store