Client Initiated Backchannel Authentication
In order to understand more about CIBA flows and data about requests and responses, it's important to have a general overview of this document: https://gluu.org/docs/gluu-server/4.2/admin-guide/ciba/
Also specs are pretty helpful: https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0-ID1.html
This is the list of new properties or some others that have to be considered whenever CIBA should be deployed.
| Property | Values | Description |
|---|---|---|
| backchannelClientId | Client identificator that will be used to associate end-user device. | |
| backchannelRedirectUri | Url used to process the callback once the authentication/authorization is done | |
| backchannelAuthenticationEndpoint | CIBA Endpoint used to initiate the authentication/authorization flow using CIBA flow. | |
| backchannelDeviceRegistrationEndpoint | CIBA Endpoint used to associate a device with a people entry. This device would be used to process all authentications/authorizations steps | |
| backchannelTokenDeliveryModesSupported | poll ping push | Token delivery modes that could be supported in the authentication server. It could depend on the CIBA flow. |
| backchannelAuthenticationRequestSigningAlgValuesSupported | RS512 ES256 ES384 ES512 ES512 PS256 PS384 PS512 | Signing algorithms supported to process authentication requests. |
| backchannelUserCodeParameterSupported | true false | It defines whether authorization server will accept or not User Code parameter in the CIBA authentication/authorization flow |
| backchannelBindingMessagePattern | regex | This is a regex used to validate the content in the binding_message parameter sent by the client. |
| backchannelAuthenticationResponseExpiresIn | Default limit time used to process the authentication response. | |
| backchannelAuthenticationResponseInterval | Default interval recommended to the client to call to the /token endpoint to verify whether client has answered or not. | |
| backchannelRequestsProcessorJobIntervalSec | Time interval used for the job responsible to process all requests. | |
| backchannelRequestsProcessorJobChunkSize | Max limit of requests that every cycle in the job can process. | |
| cibaGrantLifeExtraTimeSec | Extra time added for a CIBA request in cache in order to have extra time which client could use to do the /token endpoint call. |
|
| cibaMaxExpirationTimeAllowedSec | Limit of time that client could send in the CIBA authorization request, it's only used as a validation. | |
| backchannelLoginHintClaims | inum uid mail | Determines which value is going to be shared by the client to identify his client. |
| cibaEndUserNotificationConfig | This property contains a set of other properties related to Firebase configuration. It could be gotten from the Firebase console. One of the fields notificationKey must be put encrypted, therefore it is highly recommended to use oxTrust to put this value. | |
| grantTypesSupported | There is a new grant type for this implementation and according to the specifications, this must be urn:openid:params:grant-type:ciba | |
| dynamicGrantTypeDefault | There is a new grant type for this implementation and according to the specifications, this must be urn:openid:params:grant-type:ciba |
These attributes were added to process all CIBA requests per client.
| Attribute | Description |
|---|---|
| oxAuthBackchannelAuthenticationRequestSigningAlg | Signing algorithm used to process requests received in /bc-authorize endpoint as JWT |
| oxAuthBackchannelClientNotificationEndpoint | Client endpoint that is used by ping and push modes to deliver messages depending the case. |
| oxAuthBackchannelTokenDeliveryMode | Defines the flow that will be used by the client, this value is one of the supported modes configured in the oxAuth json property backchannelTokenDeliveryModesSupported |
| oxAuthBackchannelUserCodeParameter | Defines whether this client will be able to sent a User Code or not. |
A new kind of entry was added in order to keep CIBA request data, it's mainly used to process expired requests, these entries have these attributes:
| Attribute | Description |
|---|---|
| authReqId | Authentication request identifier, it's also used to filter as a unique key. |
| clnId | Client identifier |
| usrId | User identifier |
| creationDate | Date time of the request when this is received. |
| exp | Date time when this specific request is going to be expired. |
| oxStatus | Status of the request, this could contain these values: pending, granted, denied, expired, in_process
|
CIBA is integrated with Firebase in order to send notifications to the AD(Authentication Device), therefore in the configuration is needed some parameters used by CIBA implementation to do that.
Once the whole configuration is done according to the previous documentation and with Firebase activated, you can use it to test your environment. It has been implemented a demo page just to be sure that the whole configuration is working and that the flow is completed. To test it, you can navigate to /ciba, for instance, https://test.gluu.org/oxauth/ciba, here there is a screenshot that you should see.
Also the page is going to ask you the permission to receive push notifications, you should allow it. After that press Authenticate User button, that is going to go to the common authentication flow. This is done because it is important to associate this navigator as your AD.
Once you finish the flow you will be back again to the same page, but you should have your Id Token in the screen. After some seconds below of that section, you also will see a section called Instance ID Token, this is your Firebase identificator that will be used by CIBA to send you push notifications. Here you can press Delete Token button just to update that token and create a new one. In a technical view, here the navigator called to /bc-deviceRegistration endpoint, just to associate that device with your profile.
This module allows you to test all flows that CIBA has. Here you should load the page and access it using the environment that you set up.
In order to process CIBA requests, first we need a client registered. Therefore, you should fill fields according to the flow that you want to test. These are some fields important to consider to process CIBA requests:
| Field | Description |
|---|---|
| Grant Types | For CIBA, there is a new Grant Type called urn:openid:params:grant-type:ciba |
| Backchannel Token Delivery Mode | This is the flow that this client is going to use, it could be ping, poll or push |
| Backchannel Client Notification Endpoint | For ping and push flows, the OP should call back with some information according to the flow, this field contains the URL that is going to be used. |
| Backchannel Authentication Request Signing Alg | Algorithm that is going to be used to sign the JWT requests sent to the /bc-authorize endpoint |
| Backchannel User Code Parameter | Defines whether this client will support User Code feature or not. |
Also you can use the next section below those fields to get information of an already registered client, it will be used by the RP to process all requests.
This form allows you to send CIBA requests, it will use the client data that was already done in the previous section.
| Field | Description |
|---|---|
| Backchannel Authentication Endpoint | Url used to process CIBA requests in the OP. This url should be automatically loaded when Discovery endpoint is called. |
| Scope | The scopes that you want to ask for permissions. |
| Client Notification Token | This is a string used for ping and push flows when OP calls back, this value is sent in the header and is processed by the RP. |
| ACR Values | Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the OpenID Provider is being requested to use for processing this Authentication Request, with the values appearing in order of preference. |
| Login Hint Token | A token containing information identifying the end-user for whom authentication is being requested. The particular details and security requirements for the login_hint_token as well as how the end-user is identified by its content are deployment or profile specific. |
| ID Token Hint | An ID Token previously issued to the Client by the OpenID Provider being passed back as a hint to identify the end-user for whom authentication is being requested. If the ID Token received by the Client from the OP was asymmetrically encrypted, to use it as an id_token_hint, the client MUST decrypt the encrypted ID Token to extract the signed ID Token contained in it. |
| Login Hint | A hint to the OpenID Provider regarding the end-user for whom authentication is being requested. The value may contain an email address, phone number, account number, subject identifier, username, etc., which identifies the end-user to the OP. The value may be directly collected from the user by the Client before requesting authentication at the OP, for example, but may also be obtained by other means. |
| 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. |
| User Code | A secret code, such as password or pin, known only to the user but verifiable by the OP. The code is used to authorize sending an authentication request to user's authentication device. This parameter should only be present if client registration parameter backchannel_user_code_parameter indicates support for user code. |
| Requested Expiry | A positive integer allowing the client to request the expires_in value for the auth_req_id the server will return. |
| Client ID | Identificator of the client already registered. |
| Client Secret | Secret of the client already registered. |
In this case, this oxAuth-RP module only is going to register the request and the user has to call /token endpoint many times until it returns the authentication result. Therefore, in the screen you will see only this data.
After that you can use Token Endpoint section to process all calls until OP has a result of the authentication request. Here is an example of the call.
In this case, the oxAuth-RP module is going to be pending to receive the callback from the OP and the screen will be automatically updated according to the result.
First step, CIBA request registered:
After end user allows/rejects the authentication, the oxAuth-RP will show you the result in the same section.
This flow also uses client notification endpoint to receive the authentication result from the OP, therefore in the UI you will also see the same screen than Ping flow.
First step, CIBE request registered:
After end user allows/rejects the authentication, you will see automatically the result in the same screen.
