User Authorization with CIBA

Client-Initiated Backchannel Authentication (CIBA) is an OAuth 2.0 specification that allows a client application to initiate an authentication and/or authorization flow 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 fine-grained authorization data specific to the request the user needs to authorize. The authorization_details parameter contains details about the request that you can customize in a consent prompt to show the user.

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. An AI agent 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 except that when the initiating user, in this case, the AI agent, initiates a CIBA request, it passes the authorization_details parameter 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=urn:my-api' \ --data-urlencode 'binding_message=1234ABCD \ --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"}]'

Was this helpful?

/

After the mobile application receives the push notification via the Guardian SDK, it can fetch the consent details, which includes the authorization_details, from the Auth0 Consent API:

let device: AuthenticationDevice = // the object you obtained when enrolling
if let consentId = notification.transactionLinkingId {
    Guardian
        .consent(forDomain: {yourTenantDomain}, device: device)
        .fetch(consentId: consentId, notificationToken: notification.transactionToken)
        .start{result in
            switch result {
            case .success(let payload):
                let authorizationDetails = payload.requestedDetails.authorizationDetails
            case .failure(let cause):
                // something went wrong
        }
    }
}

Was this helpful?

/

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:

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

Was this helpful?

/

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:

struct Payment : AuthorizationDetailsType, Decodable { // Must implement AuthorizationDetailsType and Decodable
    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

Was this helpful?

/

Because filterAuthorizationDetailsByType() ignores values that do not match the desired type, make sure you’re providing all the required authorization_details to the user for consent.

You can also query the authorization_details when the AI agent or application polls the /oauth/token endpoint for a response:

Parameters Description
grant_type Set to the CIBA grant type: urn:openid:params:grant-type:ciba&client_id
client_id Set to the application’s client ID.
client_secret Set to the application’s client secret.
auth_req_id Returned from the Auth0 tenant when it acknowledges the CIBA request. References the CIBA request.
audience Specifies the access token's intended consumer, typically the resource server (API) the client wants to access. 

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]&audience=[MY_AUDIENCE]

Was this helpful?

/

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" }

Was this helpful?

/

Limitations

Auth0 doesn’t support:

  • Accessing or modifying RAR in Actions for CIBA flows.

  • Advertising RAR types for clients to discover.

  • Validating RAR objects beyond checking that they have a type property that matches allowed types for the API. For more information, see Configure RAR.

Learn more