By default, Okta does not return the binding messages or the auth_req_id in any of the tokens generated by a Client-Initiated Backchannel Authentication (CIBA) authentication. A Token Inline Hook adds the binding message and auth_req_id to the tokens returned from Okta. Administrators require a method to include these specific values in the minted tokens during CIBA flows.

• Okta Identity Engine (OIE)
• Client-Initiated Backchannel Authentication (CIBA)
• Okta Custom Authenticator App

By default, Okta does not return the binding messages or the auth_req_id in any of the tokens generated by a CIBA authentication.

How does a Token Inline Hook include the binding message in the tokens minted by Okta?

Use a Token Inline Hook to include the binding message and auth_req_id in the token returned from Okta.

1. Initiate the CIBA challenge (/bc/authorize) and include an optional binding_message that the user receives in the push notification. The challenge returns the auth_req_id.
2. Poll the token endpoint with custom query parameters. For each token call until the push is approved, include query parameters for the binding_message / auth_req_id along with any other values desired to have added to the token.

   /oauth2/{Authorization_Server}/v1/token?binding_message=cGF5ZWUrOTku...=&auth_req_id=ftUKvnpOCriLpF89KP6rCTZ4fy0Pc3&anything=else

3.  When the Token Inline Hook service receives a request from Okta, part of the request body will contain the request object. This object will include the full URL used to invoke the token call, including query params sent with the request.

   ...
   },
   "request": {
     "id": "8e1f98e162...",
     "ipAddress": "165.x.x.x",
     "method": "POST",
     "url": {
       "value": "https://{ORG}.okta.com/oauth2/default/v1/token?binding_message=cGF5ZWUrOTku...&auth_req_id=ftUKvnpOCriLpF89KP6rCTZ4fy0Pc3B4Wz&anything=else"
     }
   },
   "session": {
   ...

4. The external hook service can extract the query parameter values and add them to the desired tokens returned by Okta. An example response from the Token hook service for the above request could be the following:

   {
     "commands": [
       {
         "type": "com.okta.identity.patch",
         "value": [
           {
             "op": "add",
             "path": "/claims/binding_message",
             "value": "cGF5ZWUrOTku..."
           },
           {
             "op": "add",
             "path": "/claims/auth_req_id",
             "value": "ftUKvnpOCriLpF89KP6rCTZ4fy0Pc3B4Wz"
           },
           {
             "op": "add",
             "path": "/claims/anything",
             "value": "else"
           }
         ]
       }
     ]
   }

Related References

• Transactional verification using CIBA
• Token Inline Hook Request / Response API Docs
• Sample Token Inline Hook Service