Skip to main content
To use Client-Initiated Backchannel Authentication (CIBA) features, you must have an Enterprise Plan or an appropriate add-on. Refer to Auth0 Pricing for details.
Client-Initiated Backchannel Authentication (CIBA) is an specification that allows a client application to initiate an authentication and/or without requiring direct user interaction on the initiating application. Rich Authorization Requests (RAR) is an OAuth 2.0 extension that allows client applications to request for more complex permissions beyond standard OAuth 2.0 scopes in an authorization request. You can use CIBA with RAR to pass data to the in a backchannel request. The authorization_details parameter contains details about the request that you can customize in a consent prompt to show the user. You can authorize users with CIBA using the following notification channels:

​
Common use cases

Use RAR with the CIBA flow for use cases that require more fine-grained control over resource access. Common use cases include:
  1. A payments app prompts the user to confirm a money transfer. The authorization_details can be customized to show the transaction details.
  2. An AI agent prompts the user with details about a rescheduled doctor’s appointment. The authorization_details can be customized to show the new time and date.

​
How it works

The User Authorization with CIBA flow is similar to the User Authentication with CIBA flow, where RAR support enables clients to pass the authorization_details to the authorization server via the /bc-authorize endpoint. The following sequence diagram explains the end-to-end User Authorization with CIBA flow:
The following sections dive step-by-step into how user authorization works with CIBA.

​
Prerequisites

To initiate a CIBA request using Auth0, you must:

​
Step 1: Client application initiates a CIBA request

Use the User Search APIs to find the authorizing user for whom you’d like to initiate a CIBA request and obtain their user ID. Once you have a user ID for the authorizing user, use the Authentication API to send a CIBA request with the authorization_details to the /bc-authorize endpoint: 
curl --location 'https://$tenant/bc-authorize' \
  --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=$client_id' \
  --data-urlencode 'client_secret=$client_secret' \
  --data-urlencode 'login_hint={ "format": "iss_sub", "iss": "https://$tenant/", "sub":"$user_id"}' \
  --data-urlencode 'audience=https://api.example.com' \
  --data-urlencode 'binding_message=Confirm payment of 2500' \
  --data-urlencode 'authorization_details=[{
      "type": "money_transfer", 
      "instructedAmount": {
        "amount": 2500, 
        "currency": "USD"
      }, 
      "sourceAccount": "xxxxxxxxxxx1234", 
      "destinationAccount": "xxxxxxxxxxx9876", 
      "beneficiary": "Hanna Herwitz", 
      "subject": "A Lannister Always Pays His Debts"
    }]'
ParametersDescription
tenantTenant name that is passed within the login_hint structure. It can also be a custom domain.

Example: login_hint={"format": "iss_sub", "iss": "https://$tenant/", "sub":"$user_id"}
client_idClient application identifier.
client_secretClient authentication method used for user authentication with CIBA, such as Client Secret, Private Key JWT, or mTLS Authentication. If you’re using Private Key JWT or mTLS, you don’t need to include the client secret.
scopeIf the client needs to identify the user (i.e., obtain an id_token), openid must be included. If the client only needs an access token for authorization, openid is optional, but commonly included.

The scope can optionally include offline_access to request a refresh token. However, for one-time authorization of a transaction with the CIBA Flow, a refresh token is not needed and does not have any meaning in this context.
user_idUser ID for the authorizing user that is passed within the login_hint structure. If iss_sub format is used, then the user ID is passed within the sub claim.

Example: login_hint={"format": "iss_sub", "iss": "https://$tenant/", "sub":"$user_id"}

The user ID for a federated connection may have a different format.
requested_expiryThe CIBA flow’s requested expiry is between 1 and 259200 (72 hours) seconds, and it defaults to 300 seconds. Include the requested_expiry parameter to set a custom expiry for the CIBA flow.

The requested_expiry parameter helps determine which notification channel CIBA uses:
  • If you set your requested_expiry to a value of 300 or lower in seconds, CIBA uses the mobile push notification channel if enabled. If you have not configured MFA for your tenant, the CIBA request fails.
  • If you set your requested_expiry to a value between 301 to 259200 seconds, CIBA uses the email notification channel if enabled.
binding_messageHuman-readable message used to bind the CIBA flow across the authentication and consumption devices. The binding message is required and up to 64 characters. Use only alphanumeric and +-_.,:# characters
audienceUnique identifier of the audience for the issued token.
authorization_detailsAn optional JSON array of objects that describes the permissions to be authorized. You should register each object’s type value on the resource server using the resource server’s authorization_details parameter. To learn more, read Configure Rich Authorization Requests.

​
Step 2: Auth0 tenant acknowledges the CIBA request

If the Auth0 tenant successfully receives the POST request, you should receive a response containing an auth-req-id that references the request: 
{
    "auth_req_id": "eyJh...",
    "expires_in": 300,
    "interval": 5
}
The auth_req_id value is passed to the /token endpoint to poll for the completion of the CIBA flow.

​
Step 3: Client application polls for a response

Use the Authentication API to call the /token endpoint using the urn:openid:params:grant-type:ciba grant type and the auth_req_id you received from the /bc-authorize endpoint:
  • cURL
  • C#
  • Go
  • Java
curl --location 'https://$tenant.auth0.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=$client_id' \
  --data-urlencode 'client_secret=$client_secret' \
  --data-urlencode 'auth_req_id=$auth_req_id' \
  --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'
Until the authorizing user approves the transaction, you should receive the following response: 
{
    "error": "authorization_pending",
    "error_description": "The end-user authorization is pending"
}
There is approximately a five-second wait interval for polling. If you poll too frequently, you will receive the following response, where the description varies depending on the backoff interval: 
{
"error": "slow_down",
"error_description": "You are polling faster than allowed. Try again in 10 seconds."
"interval": 10
}
To resolve the error, wait until the next interval (in seconds) to poll the /token endpoint.

​
Step 4: Authentication device receives the notification

Depending on the notification channel, Auth0 sends a notification to the authentication device: The authentication device retrieves the consent details i.e. the contents of the binding_message from the Auth0 Consent API:
  • Mobile push notification: The Auth0 Guardian app or a custom app integrated with the Auth0 Guardian SDK calls the Auth0 Consent API to retrieve the consent details.
  • Email notification: When the user clicks on the verification link, they are redirected to the browser, which retrieves the consent details from the Auth0 Consent API.
The Auth0 Consent API responds to the authentication device with the consent details, including the binding_message, scope, audience, and authorization_details if configured. The scopes returned to the mobile application are filtered according to your RBAC policy. To learn more, read Role-Based Access Control. The following code sample is an example response from the Auth0 Consent API: 
{
  "id": "cns_2309dsfsd098",
  "requested_details": {
    "audience": "https://api.example.com",
    "scope": ["read:profile", "write:profile"],
    "binding_message": "abc123",
    "authorization_details": [
      {
        "type": "money_transfer",
        "instructedAmount": {
          "amount": 2500,
          "currency": "USD"
        },
        "sourceAccount": "xxxxxxxxxxx1234",
        "destinationAccount": "xxxxxxxxxxx9876",
        "beneficiary": "Hanna Herwitz",
        "subject": "A Lannister Always Pays His Debts"
      }
    ]
  },
  "created_at": 1632739200,
  "expires_at": 1632739200
}
The authentication device presents the consent details with the authorization_details to the user: The user can accept or decline the authorization request at this point.

​
Step 7: Authentication device sends the user response back to Auth0

After the user accepts or declines the authorization request, the authentication device sends the user response back to Auth0:
  • Mobile push notification: The Auth0 Guardian app or a custom app integrated with the Auth0 Guardian SDK sends the user response back to Auth0.
  • Email notification: The browser sends the user response back to Auth0.

​
Step 8: Auth0 receives user response after the flow completes

The client application completes the polling upon receiving a response from the /token endpoint. A CIBA flow always requires a response, either an approval or decline, from the authorizing user, and existing grants are not checked. This means Auth0 treats every CIBA request as a fresh authorization for the authorizing user.

​
Step 9: Auth0 returns access token to client application

If the user rejects the push request, Auth0 returns an error response like the following to the client application: 
{
    "error": "access_denied",
    "error_description": "The end-user denied the authorization request or it has been expired"
}
If the user approves the push request, Auth0 returns an with the authorization_details like the following to the client application: 
{
  "id_token": "...",
  "access_token": "...",
  "expires_in": "...",
  "scope": "$granted_scopes",
  "authorization_details": [{
      "type": "money_transfer", 
      "instructedAmount": {
        "amount": 2500, 
        "currency": "USD"
      }, 
      "sourceAccount": "xxxxxxxxxxx1234", 
      "destinationAccount": "xxxxxxxxxxx9876", 
      "beneficiary": "Hanna Herwitz", 
      "subject": "A Lannister Always Pays His Debts"
    }]
}
Note: The refresh_token will only be present if the offline_access scope was included in the initial /bc-authorize request.

​
Query authorization_details

At compile time, you can query the type and objects of authorization_details from the consent details in a strongly typed manner as you would dynamically query JSON:
  • iOS
  • Android
let requestedDetails: ConsentRequestedDetails = payload.requestedDetails
let myAuthorizationDetailsTypes = requestedDetails.authorizationDetails[0].objectValue!;
let type = myAuthorizationDetailsTypes["type"]?.stringValue // Your pre-registered type value
let stringProperty = myAuthorizationDetailsTypes["string_property"]?.stringValue
let boolProperty = myAuthorizationDetailsTypes["bool_property"]?.boolValue
let numericProperty = myAuthorizationDetailsTypes["numeric_property"]?.doubleValue
let nestedObjectProperty = myAuthorizationDetailsTypes["nested_property"]?.objectValue
let nestedArrayProperty = myAuthorizationDetailsTypes["nested_array_property"]?.arrayValue
If you define a custom type to represent your object, you can use the filterAuthorizationDetailsByType() function to return all authorization_details objects that match the desired type. The following code sample queries authorization_details with the payment type:
  • iOS
  • Android
// Must implement AuthorizationDetailsType 
struct Payment : AuthorizationDetailsType { 
static let type = "payment"; 
let amount: Double; 
let currency: String; 
} 

... 

let requestedDetails: ConsentRequestedDetails = payload.requestedDetails 
let payments = requestedDetails.filterAuthorizationDetailsByType(Payment.self) 
let firstPayment = payments.first!
let type: String = firstPayment.type // "payment" 
let amount: Double = firstPayment.amount 
let currency: String = firstPayment.currency
filterAuthorizationDetailsByType() only returns objects matching the specified authorization_details type. As a result, your mobile application should present all relevant authorization_details to the user for consent, regardless of their type, to ensure a complete understanding of the request You can also query the authorization_details when the AI agent or application polls the /oauth/tokenendpoint for a response: 
POST https://$tenant/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:openid:params:grant-type:ciba&
client_id=$client_id&
client_secret=$client_secret&
auth_req_id=$auth_req_id
ParametersDescription
grant_typeSet to the CIBA grant type: urn:openid:params:grant-type:ciba
client_idSet to the application’s client ID.
client_secretSet to the application’s client secret.
auth_req_idReturned from the Auth0 tenant when it acknowledges the CIBA request. References the CIBA request.
When the authorizing user approves the request, Auth0 receives the user response, and the CIBA flow completes, returning an access token and authorization_details array: 
{ 
  "access_token": "ey...ZQ", 
  "expires_in": 86400, 
  "authorization_details": [{ 
    "type": "money_transfer", 
    "instructedAmount": {
      "amount": 2500, 
      "currency": "USD"
    }, 
    "sourceAccount": "xxxxxxxxxxx1234", 
    "destinationAccount": "xxxxxxxxxxx9876", 
    "beneficiary": "Hanna Herwitz", 
    "subject": "A Lannister Always Pays His Debts" 
  }], 
  "token_type": "Bearer" 
}

​
Limitations

Auth0 doesn’t support:
  • Modifying RAR in Actions for CIBA flows.
  • Advertising RAR types for clients to discover, which means you need to pre-register clients with the authorization_details types they can send.
  • Validating RAR objects beyond checking that they have a type property that matches allowed types for the API. Your resource server is responsible for the granular validation of the content within authorization_details. For more information, see Configure RAR.

​
Learn more