Backchannel authentication and approvals in your tenant

CIBA

Your tenant supports OpenID Connect Client-Initiated Backchannel Authentication (CIBA) in poll and ping modes. Allow the Backchannel authentication (CIBA) grant in Flow Policy and on each client that uses it. Only confidential clients can use it, because every request is authenticated. Discovery then lists backchannel_authentication_endpoint and the delivery modes. Signed authentication requests and user codes are not supported.

Asking for approval

The client authenticates as it does at the token endpoint and names the person with login_hint (their email address) or an id_token_hint this tenant issued to it:

POST /oidc/backchannel_authentication
Authorization: Basic <client ID and secret>
Content-Type: application/x-www-form-urlencoded

scope=openid&login_hint=ava%40example.com&binding_message=Order%204821

scope must include openid. A binding_message of up to 64 plain characters is shown to the person to compare with what the application shows; Flow Policy can require one. requested_expiry can shorten the wait, never lengthen it past the tenant's setting, and acr_values are matched against how the approving browser was signed in, as a preference whatever Flow Policy says for authorization requests. The answer holds the auth_req_id, how long it lasts and the polling interval, which also applies to a pinged client that polls. An unknown or locked person is unknown_user_id.

The Approvals page

The person opens Approvals in their account on any browser where they are signed in to this tenant. Each request names the application, its message and the scopes it asks for, with Approve and Deny. Only that person sees their requests, and only a full sign-in can answer them. The tokens record when and how that browser was signed in. An application that still needs an administrator's approval under your app approval policy cannot be approved here.

Polling and pings

Each client chooses its mode in its Backchannel authentication (CIBA) settings. A polling client calls the token endpoint with grant_type=urn:openid:params:grant-type:ciba and its auth_req_id, and receives authorization_pending until the person answers, slow_down when it polls faster than the interval, then its tokens with an ID token, or access_denied or expired_token. An auth_req_id is redeemed once.

A pinged client registers a notification endpoint and sends a client_notification_token with each request. When the person answers, your tenant POSTs {"auth_req_id": ...} there with that token as the bearer token, retrying as it does for logout tokens, and the client then redeems the auth_req_id. The endpoint must be https on a public host, or the CIBA endpoint of your tenant's lab receiver on the Sample API page, which records each ping and never its values. The notification token is stored sealed and never shown or recorded.

Push approvals

Turn on Let people approve a second step from another signed-in browser in the Second step card of Authentication. A person at their second step who is fully signed in on another browser of this tenant can then choose Send an approval request. The sign-in page shows a number; the other browser's Approvals page shows three, and the person chooses the one they see. A wrong number denies the request and counts as a failed second step, so approving out of habit does not work. The request lasts two minutes and is used once. It shows that someone could act in another browser already signed in to the account, over a second channel, and is recorded as mca in the session's amr. It is not a separate authenticator: anyone who could sign in to that other browser can approve. So it adds mfa only when the approving browser's own sign-in was multi-factor and the first step was not an email sign-in. Binding approval to an enrolled device key would make it a possession factor; this tenant does not offer that.

The BTL organization keeps push approvals off: Beyond the Login accounts finish their second step on the Beyond the Login site, which does not offer them yet.

Settings, Audit and limits

Flow Policy sets how long a request waits (60 to 1800 seconds), the polling interval (2 to 60 seconds) and whether a binding message is required. Each request is recorded in protocol Audit as oidc.ciba under the client and person, each answer as account.approvals with the person as actor, each ping as oidc.ciba_notification, and push approvals under the second step. A user can receive 10 CIBA requests and send 10 push requests each 15 minutes, 500 approvals can wait across the tenant, and the tenant sends up to 300 pings an hour. All appear in the tenant's usage view. A CIBA request over either limit is refused with access_denied and HTTP 403, the status CIBA gives that error, and Logs name the limit. Disconnecting an application from a person also cancels a request they approved but the application has not redeemed.