How It Works

IDToken replaces passwords with a cryptographic credential derived from your passport and a mobile app that confirms your identity through face verification.

The service has its own user database. The user enters their user ID — the service maps it to a tokenId and initiates the IDToken authentication.

Confirm on your device

Match this code on your IDToken app

Waiting for approval...

Identity Verified

Welcome back, authenticated via VDS

9:41

Thursday, March 19

IDToken Login request from portal.gov.eu

now

IDToken

Confirm this code matches

847293

portal.gov.eu

2:47 remaining

Verifying identity...

Authenticated

Identity verified via VDS credential

The User Journey

Step 1: Get Your IDToken (One-Time Enrollment)

A user creates their BioSeal — either at an issuance station (a kiosk or operator desk) or directly on their own smartphone — using their passport or national ID card:

The passport or ID card is read via MRZ + NFC (ICAO 9303 chip)
The id3 Face SDK performs liveness detection and matches the user’s face against the document chip photo
The BioSeal Issuance Service generates a VDS (Visible Digital Seal) — a cryptographically signed credential containing the user’s identity data and biometric photo
The VDS is encoded as a QR code displayed on screen (issuance station) or stored directly in the app (smartphone)

If issued at a station, the user opens the IDToken mobile app and scans the QR code. If issued on the smartphone, the VDS is already in the app. In both cases, the app:

Verifies the VDS signature locally
Performs a face verification (live capture vs. VDS face template) — this ensures the person holding the phone is the rightful owner of the credential, which is essential when the VDS was obtained from an external QR code
Generates an ECDSA P-256 key pair in the device’s secure element
Registers the public key with the auth server (POST /enroll)

The private key never leaves the device. The server only stores the public key + tokenId binding.

Step 2: Register with a Service (One-Time per Service)

Before logging in, the user must trust the service. The website displays a Service VDS QR code — a cryptographically signed credential that identifies the service and declares what identity data it can request.

The service website fetches a Service VDS from the auth server — a signed credential containing the service’s name, URL, logo, and authorized scopes
The website displays the Service VDS as a QR code with a “Scan to register” prompt
The user scans the QR code with the IDToken app
The app verifies the Service VDS signature using the auth server’s public key (from JWKS) and shows a registration screen with the service details and the maximum scopes it can request
The user taps “Trust this service”
The app stores the service locally and registers the binding with the auth server

This is done once per service. The user can review and remove trusted services from the app at any time. At each subsequent login, the user still controls exactly which scopes to share (per-authentication consent).

Step 3: Log In (Every Authentication)

When a user wants to log into a trusted service:

The user enters their tokenId on the service website
The auth server generates a 6-digit OTP and stores the session (60-second TTL)
The OTP is pushed to the mobile app via FCM push notification
The OTP is also sent to the browser via WebSocket for display
The user compares the OTP on screen with the one on their phone — this verifies the service is legitimate (mutual authentication)
The user confirms with face verification on their phone (id3 Face SDK, liveness detection + 1:1 match against VDS face template)
The app signs the session with the device’s ECDSA private key and sends it to the server
The server verifies the signature and OTP
The server issues a JWT with the identity claims matching the granted scopes
The JWT is delivered to the browser via WebSocket — the user is logged in

Step 4: The Service Gets Identity Claims

The JWT contains only the identity data the service is allowed to see. The user controls what is shared:

The user can toggle individual scopes on or off before approving. The granted scopes are cryptographically bound to the ECDSA signature — the server cannot inflate them after the user’s biometric approval.

Why It’s Secure

Property	How
No passwords to steal	Identity is based on a signed credential + device-bound key, not a memorized secret
Mutual authentication	The user verifies the service (OTP match), the service verifies the user (ECDSA signature). With Service VDS, both sides present cryptographic credentials.
Phishing-resistant	A fake service cannot generate a valid OTP without the server’s HKDF master secret
Replay-proof	Sessions are single-use, deleted after verification, with a 60-second TTL
Biometric gating	Face verification must pass before the device key can sign — a stolen phone is useless
Privacy-preserving	Selective disclosure: services only see what they need, and users approve each disclosure

Phone Loss Recovery

If a user loses their phone:

An operator revokes the old enrollment (POST /revoke)
The user presents their passport or ID card (at an issuance station or on a new smartphone)
A new VDS is issued, the user re-enrolls with the new phone
No per-service action needed — all services verify the tokenId on each login, so revocation propagates automatically

What’s Different from Passwords, FIDO, and Passkeys?

Feature	Passwords	FIDO/Passkeys	IDToken
User database required	Yes	Yes (public keys)	No (key binding only)
Phishing resistance	None	Strong	Strong (mutual OOB)
Identity source	Self-declared	Self-declared	Government document
Biometric verification	No	Device-local	1:1 against passport photo
Works across devices	Yes (portable)	Per-device	Any device (OOB via phone)
Recovery on device loss	Password reset	Account recovery	Present document, re-enroll
Selective disclosure	No	No	Yes (scope-based)
Trust level	None	None	PKI-backed (eIDAS levels)

Combining with Access Management

IDToken is an Identity Provider — it proves who the user is with government-backed credentials and biometric verification. It does not manage roles, permissions, or access policies. This separation is intentional: organizations already have access management infrastructure, and IDToken is designed to plug into it, not replace it.

The signed JWT issued after authentication is the integration point. It carries verified identity claims (sub, given_name, age_over_18, etc.) that any standard authorization layer can consume:

API gateways (Kong, Envoy, AWS API Gateway) verify the JWT and enforce access policies before requests reach your backend
RBAC / ABAC systems map the tokenId to local roles and use JWT claims as policy attributes
Enterprise SSO — IDToken speaks OIDC and SAML 2.0, so it plugs directly into existing IAM platforms (Microsoft Entra ID, Okta, etc.)
Zero Trust architectures (Cloudflare Access, Zscaler) use IDToken as an external OIDC identity source

The user’s scope-based consent acts as a cryptographic ceiling for all authorization decisions — even if your policies grant full access, the JWT only contains the claims the user chose to share.

Learn more: Access Management Integration

Go Deeper

The VDS Credential — How the Visible Digital Seal works: structure, signature, manifests, and revocation
Quick Start — Integrate IDToken into your application with code examples
Authentication Flow — Protocol-level detail of each phase, with API request/response formats
Security Model — Threat model, cryptographic algorithms, and OTP derivation
Trust Architecture — The full PKI governance chain from VDSIC to signing certificate