Skip to main content

Authentication Model

Auth-svc with duo-server uses three authentication mechanisms depending on the operation:

MechanismUsed for
JWTAll standard endpoints — user registration, device registration, key listing, backup storage
Device SignatureMPC operations (keygen, sign) — proves the requesting device holds the registered private key in the TEE
JWT + face_session_id (step-up)Sensitive operations — device re-registration (when face is already enrolled), keyshare recovery, register and recover

JWT

All endpoints require a Bearer token issued by your identity provider (Auth0, Firebase, or any OIDC provider). Auth-svc extracts the user identity from the sub claim.

Authorization: Bearer <access_token>

Device Signature

For MPC operations, the device signs the request body with its ECDSA P-256 private key (held in the device's Secure Enclave / TEE). Duo-server verifies this signature before calling the auth-svc hooks.

For details on the hooks and how duo-server uses them to authorize MPC operations, see How auth-svc Works with duo-server.

Face Step-Up

After enrolling a face, sensitive operations require two credentials:

  • A valid JWT in the Authorization header
  • A face_session_id from a match scan that completed with succeeded: true

Auth-svc verifies that the match session belongs to the authenticated user and has not expired or already been spent. When the operation is accepted, auth-svc consumes the session, so each successful match authorizes exactly one operation. Sessions remain valid for FACETEC_SESSION_EXPIRY_SECONDS after the match completes—300 seconds by default.

To obtain a face_session_id, run a match scan through POST /v2/auth/face/process.

Operations requiring face step-up:

  • Device re-registration: adding a new device after a face is enrolled
  • Keyshare recovery: fetching the encrypted backup
  • Register and recover: both of the above with a single scan