Skip to content

Trusted devices

Trusted devices

A trusted device is a phone running the Cbox ID authenticator app, enrolled against one user in one environment. Once enrolled it does two things:

  • Answers approvals. When an app or an agent starts a sign-in on the user's behalf (Approvals), the phone gets a push and the person taps approve or deny.
  • Receives security alerts. Chosen account events — a sign-in, a new session — arrive as a notification, so an unexpected one is noticed by the person it happened to rather than by whoever reads the audit log next quarter.

People without the app can still approve, on the Approvals page in the console. See Approvals without the mobile app.

The module is off by default. A deployment with no mobile app has no devices to notify, and the push decorator should not sit in the sign-in path doing nothing.

CBOX_ID_DEVICES_ENABLED=true

With that set and nothing else configured, the feature is fully usable except that pushes go nowhere: notification rows are written and immediately settled as Skipped, and the console shows the whole delivery history. That is a deliberate state to be able to sit in — you can enrol, inspect and demo without a Firebase project.

Turning it on properly

1. Provision the app's OAuth client

The authenticator is a public OAuth client, one per environment, because client_id is globally unique and one app binary has to serve every environment.

php artisan cbox-id:devices:client --environment=prod

Re-running is safe: it will not mint a second client and strand every handset that enrolled against the first.

The app finds its own configuration at an unauthenticated discovery endpoint, so a single binary can be pointed at any deployment:

GET /.well-known/cbox-authenticator

which answers with the issuer, the client_id, the scopes to request, the redirect URIs and the API base. A public client's id is not a credential, which is why this needs no authentication.

2. Give pushes somewhere to go

CBOX_ID_DEVICES_TRANSPORT=fcm
CBOX_ID_DEVICES_FCM_CREDENTIALS=/etc/cbox-id/fcm-service-account.json
CBOX_ID_DEVICES_FCM_PROJECT_ID=your-firebase-project

Firebase Cloud Messaging covers Android natively and iOS by relaying to APNs, which is why there is no separate APNs driver — one integration reaches both.

The service-account JSON can push to every device you have ever enrolled. It belongs on the server. Never bundle it into the mobile app.

If either FCM value is missing the transport silently stays on the null driver rather than failing at send time. A misconfigured push must not be able to break a login.

Do not run this with CACHE_STORE=array. FCM access tokens are cached for their lifetime; with no shared cache every worker re-exchanges the JWT on every single send, and Google's token endpoint will rate-limit you long before FCM itself complains. The module logs a warning at boot when it sees that combination.

3. Enrol a phone

A user opens My account → Trusted devices and scans the enrolment QR with the app. Nothing is required of an administrator. Sign-in → Trusted devices (Authentication → Trusted devices in an environment console) (/trusted-devices) in the console shows the fleet: who enrolled what, when it was last seen, and every notification sent to it.

Approve a browser sign-in or security confirmation

An enrolled phone can also complete the second factor after a correct password, or confirm a protected console action. Choose Approve on phone, open the existing Cbox ID Authenticator app, compare the code on both screens, and approve there. The browser continues automatically. Opening the page does not send a notification.

The request expires after five minutes. Denying it, cancelling it in the browser, or removing the phone prevents completion. Existing authenticator codes, SMS and recovery codes remain available where enrolled; passkeys remain available at sign-in. A console's password confirmation also remains available.

This uses the existing approval API and push delivery; it requires no new mobile API or authenticator application. An approval in the web console does not count as the phone factor: completion requires evidence from the enrolled device's DPoP-protected API. Approvals are bound to the initiating browser, person, environment and login or console session, and can be consumed only once. Organization and environment admin confirmation windows remain separate. Three new requests per person and environment are allowed in five minutes; repeated clicks reuse a pending request.

Mobile login approval uses hosted sign-in (the OIDC redirect supported by every stack). The embedded Frontend API retains its code-based second factors; for a person whose only enrolled factor is a phone, it returns hosted_sign_in_required instead of issuing a completed login ticket. Start the application's normal hosted OIDC flow in that case.

If push is unavailable, open the app's approvals list. A retired push token does not revoke the device key; a removed phone does. Keep an independent recovery method before relying on a single phone.

When a push cannot be delivered

This is the part worth understanding before you are debugging it at 2am.

Transient failures retry with exponential backoff — min(60, 2^attempt) minutes, up to CBOX_ID_DEVICES_MAX_ATTEMPTS (12) — after which the notification dead-letters as Exhausted.

Permanent failures do not. If FCM answers UNREGISTERED or INVALID_ARGUMENT, the device token is retired on the first attempt. A token FCM has told us is dead will not become alive again after eleven hours of retrying.

A repeatedly failing handset is taken out of rotation. Five consecutive failures open a per-device circuit breaker for five minutes, then one half-open probe decides whether to close it. The state lives on the device row rather than in the cache, so it survives a cache flush and you can see it in the console. While the breaker is open, notifications are parked without being charged an attempt — the trip is the device's fault, not the notification's, and charging it would burn a dead phone's backlog through all twelve attempts inside a single cooldown.

A notification whose queue job vanished is rescued. Anything still Pending after CBOX_ID_DEVICES_STRANDED_AFTER_SECONDS (15 minutes) is re-enqueued by the sweep. This is what makes "durable row, then enqueue" true rather than aspirational.

If you change stranded_after_seconds, know that the delivery job's unique-lock window is deliberately the same value: while the lock holds the sweep's re-enqueue is correctly suppressed as a duplicate, and the instant a row counts as stranded the lock has expired so the rescue can fire. Raising one without the other wedges the rescue shut.

When an approval arrives silently

A push can be delivered and still not show. The console then says Delivered, but the person sees nothing until they swipe down to the notification centre. The phone held the notification back, usually because a Focus mode or a notification summary was on. In that case the request waits until it expires, and the agent gets expired_token.

Cbox ID sends approval pushes at the highest priority and asks iOS to treat them as Time Sensitive. Whether a Focus lets them through depends on the app build and on the person's settings. These steps work either way.

On iPhone:

  1. Settings › Focus: open each Focus you use (Personal, Work, Sleep, Do Not Disturb). Under Allowed Notifications › Apps, add Cbox ID. In the same place, leave Time Sensitive Notifications on.
  2. Settings › Notifications › Cbox ID: turn on Allow Notifications, Lock Screen and Banners, and Time Sensitive Notifications if it is listed.
  3. Settings › Notifications › Scheduled Summary: make sure Cbox ID is not in the summary. A summarised approval arrives after it has expired.

On Android:

  1. Settings › Notifications › Do Not Disturb › Apps: add Cbox ID as an exception.
  2. Settings › Apps › Cbox ID › Notifications: allow notifications.
  3. Settings › Apps › Cbox ID › Battery: choose Unrestricted, so the system does not delay pushes to save power.

Check it works. Turn on the Focus you use most, then start a request, for example from your agent. The banner should appear on the lock screen within a few seconds.

If it still does not show, the request is on the Approvals page, https://<environment-host>/approvals, as long as it is pending. An agent should always print that link next to the binding message; see Approvals without the mobile app.

For administrators: Delivered in the console means Apple or Google accepted the push for the phone. It does not mean the phone showed it. A person who reports "no push" while the console says Delivered needs the steps above, not a server fix.

Approvals on the critical path

An approval push is racing a CIBA request's 300-second TTL, so give it a queue that is not sharing a worker pool with slow bulk work:

CBOX_ID_DEVICES_QUEUE_CONNECTION=redis
CBOX_ID_DEVICES_QUEUE=push

On QUEUE_CONNECTION=sync — the test suite, and some self-hosted installs — the FCM call runs inline inside the CIBA request, bounded by the transport's own timeouts.

By default any client holding the CIBA grant can cause a push to a user's phone. To narrow that:

CBOX_ID_DEVICES_CIBA_CLIENT_ALLOWLIST=client_abc,client_def

This is enforced as a refusal to notify, not a log line. CIBA's whole value is the human in the loop, and an attacker who can spray approval prompts at a phone is attacking exactly that — a person who has dismissed thirty prompts will approve the thirty-first. The CIBA request itself still succeeds and the client can still poll; it simply produces no push.

Security alerts

// config/id-devices.php
'alerts' => ['user.login', 'user.session_started'],

These ride the ordinary once-a-minute event relay rather than the synchronous path approvals use: "your password changed" is worth knowing about, but not worth putting on the sign-in critical path.

Only event types actually emitted to the events outbox can appear here. Audit-only actions are not reachable this way — adding one produces no alert and no error.

An alert stops being worth delivering after CBOX_ID_DEVICES_ALERT_TTL_SECONDS (24 hours). That deadline is not only about staleness: because a notification parked by an open circuit breaker is not charged an attempt, without a deadline one permanently soft-failing handset would accumulate Failed rows that — being oldest, and the sweep being oldest-first — would occupy every retry slot forever and starve every other organization's approvals. Approvals take their deadline from the CIBA request's own TTL instead.

The app's API

Enrolment and approval run over a small REST surface at /api/v1, authenticated with a DPoP-bound OAuth access token whose audience is pinned to this issuer.

Endpoint Scope What it does
POST /api/v1/devices devices.manage Enrol this handset
GET /api/v1/devices devices.manage List the user's devices
DELETE /api/v1/devices/{id} devices.manage Remove one
GET /api/v1/approvals approvals.read Pending approvals
GET /api/v1/approvals/{id} approvals.read One approval's detail
POST /api/v1/approvals/{id}/approve approvals.write Approve it
POST /api/v1/approvals/{id}/deny approvals.write Deny it

Reading and answering are separate scopes on purpose: a watch complication or a home-screen widget can show what is pending without carrying the authority to answer it.

Requests are budgeted at CBOX_ID_DEVICES_RATE_LIMIT (60) per minute, keyed on a fingerprint of the presented token — so a per-user bucket. Keying on client_id would put every mobile user in one bucket and let a single busy account throttle the fleet.

Housekeeping

Settled notification rows are kept for CBOX_ID_DEVICES_RETENTION_DAYS (30) so the console can show delivery history, then pruned by the module's own scheduled job. Only terminal rows are pruned; anything still Pending or Failed is left alone whatever its age.

This table grows with traffic, not with organizations — one row per enrolled device per alerted event — so the prune is not optional housekeeping. Make sure the scheduler is running; see Scheduled work.

Every setting

See Trusted devices in the environment-variable reference.

  • Approvals — what the person sees and decides on the phone.
  • Step-up approvals — the agent's side of a held call, and how it retries.
  • Agents and MCP — the agents whose calls end up on the phone.

App Store review access

/authenticator/review provides a repeatable test of the normal approval flow for one dedicated reviewer account. It is off unless CBOX_ID_DEVICES_ENABLED is on and all three values below are configured:

  • CBOX_ID_APP_REVIEW_ENVIRONMENT_ID: the review account's environment.
  • CBOX_ID_APP_REVIEW_SUBJECT_ID: an ordinary account with no organization memberships, administrative roles or customer data.
  • CBOX_ID_APP_REVIEW_CLIENT_ID: a dedicated confidential OAuth client with only the CIBA grant and openid scope. Do not give its secret to the reviewer.

The reviewer signs in normally, opens their Trusted devices page, connects their phone, and sends an approval from the review page. The page shows the result and allows another attempt after approval, denial or expiry. It reuses a pending request and limits new requests to three per minute. Requests expire after five minutes and can only target the signed-in review account. The page discards the polling secret, so the exercise never exchanges an approval for access tokens.

Provision the account through the identity service and verify that it has no memberships, role assignments or operator record before sharing its login with Apple. Keep the credentials in the operator's secret store and Apple's App Review fields. Removing any of these three configuration values disables the page.