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.

The emailed QR + face scan is one of SenseCrypt's three sign-in methods. Every method pairs a hardware-bound device key with a live face check — the key proves the device, the face proves the person — and SenseCrypt is built on real FIDO2/WebAuthn passkeys (ES256). On the passkey method that possession factor is a FIDO2/WebAuthn passkey, the phishing-resistant path (WebAuthn binds each assertion to its origin); your backend collects the same token set whichever method the user used.

Prerequisites

• A SenseCrypt tenant.
• A CIBA-enabled OIDC client registered in the admin console, configured for a delivery mode (poll, ping, or push — push is not available to FAPI-profile clients, which use poll or ping). 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. The two token slots must carry an id_token this tenant issued — anything else (an access token, for instance) is unknown_user_id and no email is sent.
• binding_message (optional) is shown to the user to confirm the request.
• Include client_notification_token for ping/push delivery — a bearer token (RFC 6750 b64token: no spaces or line breaks) of at most 1024 characters; SenseCrypt presents it back to your endpoint as Authorization: Bearer …. An optional binding_message is capped at 140 displayable characters of plain text (invalid_binding_message otherwise). (A user_code is not supported — SenseCrypt is passwordless, so any user_code sent is ignored.)

The response:

{
  "auth_req_id": "…",
  "expires_in": 1800,
  "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 (1800s by default, the same value whether or not the user is already enrolled). Send requested_expiry — a non-negative integer, clamped to the deployment's bounds — for a tighter window.
• 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)

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 POSTs { "auth_req_id" } to your registered notification endpoint (with Authorization: Bearer <client_notification_token>) when the request has an outcome; you then collect tokens at the token endpoint exactly as above (a refused or expired request answers access_denied / expired_token there).
• push — SenseCrypt delivers the tokens directly to your notification endpoint; a refused or expired request arrives as an error payload (access_denied / expired_token). Push clients do not poll (and get no interval). Push is not available to FAPI-profile clients.

How your endpoint answers matters: a 2xx is delivered; a 3xx or 4xx is final — never retried, a redirect never followed — and for a push client it loses the approved authorization (start a new request); a 5xx or connection failure is retried up to 5 times in total. An approval that lands in the last seconds of the request window is still delivered.

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 (your application's registered algorithm — ES256 by default, RS256 if you chose it — plus 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. For ping/push, check the client_notification_token is present, at most 1024 characters, and a plain bearer token (no spaces or line breaks). If you send a signed request object, make sure each request carries a fresh jti — the same object presented twice is refused.
• invalid_binding_message at bc-authorize. The binding_message is over 140 displayable characters or contains control / line-break / bidirectional characters. Shorten it to plain text.
• 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 1800s).
• 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.