CIBA backchannel

This guide implements CIBA (Client-Initiated Backchannel Authentication): your backend starts authentication with a user hint, SenseCrypt emails the sign-in QR to the user, the user approves with an on-device face scan, and your backend collects the tokens. There is no browser and no redirect. For the model, see CIBA.

Prerequisites

• A SenseCrypt tenant.
• A CIBA-enabled OIDC client registered in the admin console, configured for a delivery mode (poll, ping, or push). CIBA requires a confidential client — SPA/public clients can't use it.

1. Start the backchannel request

Here is the whole ceremony end to end — your backend never opens a browser, and the user's biometric never leaves their phone:

Authenticate as your client and POST to the backchannel authentication endpoint (resolve backchannel_authentication_endpoint from discovery; conventionally /v1/idp/oidc/bc-authorize):

curl -X POST {backchannel_authentication_endpoint} \
  -d client_id={client_id} \
  -d client_secret={client_secret} \
  -d scope="openid profile" \
  -d login_hint="jane@acme.com" \
  -d binding_message="Approve login to Acme"

Rules:

• scope must include openid, and every scope must be one your client may use.
• Supply exactly one user hint: login_hint (email), login_hint_token, or id_token_hint.
• binding_message (optional) is shown to the user to confirm the request.
• Include client_notification_token for ping/push delivery. (A user_code is not supported — SenseCrypt is passwordless, so any user_code sent is ignored.)

The response:

{
  "auth_req_id": "…",
  "expires_in": 300,
  "interval": 5
}

• auth_req_id identifies this request at the token endpoint. It is single-use.
• expires_in is how long you have to complete it (300s by default).
• interval is the minimum seconds between polls (5s by default). For push delivery, interval is omitted (push clients don't poll).

SenseCrypt emails the sign-in QR to the resolved user. They scan it with the Authenticator app and complete the face ceremony.

2. Poll for tokens

Poll the token endpoint with the CIBA grant, waiting at least interval seconds between polls:

curl -X POST {token_endpoint} \
  -d grant_type=urn:openid:params:grant-type:ciba \
  -d auth_req_id={auth_req_id} \
  -d client_id={client_id} \
  -d client_secret={client_secret}

Handle the responses:

The pending/terminal codes arrive in the OAuth error envelope, for example:

{ "error": "authorization_pending" }

On success you receive the same token set as an interactive sign-in (an ID token and access token, plus a refresh token if offline_access was requested). A CIBA id_token carries no nonce (there was no /authorize request), so don't require one when you validate it.

Polling in code (Python)

This mirrors the demo relying party: treat authorization_pending/slow_down as "keep going", everything else terminal.

import time, httpx

PENDING = {"authorization_pending", "slow_down"}

def poll_for_tokens(token_endpoint, form, interval, deadline):
    while time.monotonic() < deadline:
        resp = httpx.post(token_endpoint, data={
            "grant_type": "urn:openid:params:grant-type:ciba",
            **form,  # auth_req_id, client_id, client_secret
        })
        if resp.status_code == 200:
            return resp.json()                     # tokens — done
        code = resp.json().get("error", "")
        if code not in PENDING:
            raise RuntimeError(f"CIBA failed: {code}")  # access_denied / expired_token / …
        time.sleep(interval + 1)                   # respect interval; back off on slow_down
    raise TimeoutError("CIBA request expired")

Ping and push delivery

• ping — SenseCrypt notifies your client_notification_token endpoint when the request is ready; you then collect tokens at the token endpoint exactly as above.
• push — SenseCrypt delivers the tokens directly to your notification endpoint. Push clients do not poll (and get no interval).

Verify it worked

1. Call bc-authorize with a test user's email and confirm you get an auth_req_id.
2. Confirm the user receives the sign-in email and can approve on their phone.
3. While pending, confirm your poll returns authorization_pending; after approval, confirm it returns 200 with an id_token.
4. Validate the id_token (ES256, iss, aud, exp) — the same as any sign-in, minus the nonce check.

Troubleshooting

• invalid_request at bc-authorize. Usually a missing/duplicate hint — send exactly one of login_hint / login_hint_token / id_token_hint, and make sure scope includes openid.
• invalid_client. Wrong credentials, or the client isn't confidential/CIBA-enabled. SPA clients cannot use CIBA.
• Stuck on authorization_pending. The user hasn't approved yet, or never got the email. Check the address resolves to an enrolled user and watch expires_in (default 300s).
• slow_down repeatedly. You're polling faster than interval. Increase the wait between polls.
• access_denied. The user declined on their phone, or their email isn't permitted for this app by the group access gate.

Related

• CIBA — the concept and delivery modes.
• Tokens & sessions — the tokens you receive.
• Python (FastAPI) — the OIDC redirect flow, for comparison.