Skip to content
IDToken

Architecture

The IDToken Auth Server is the central orchestrator of the X.1280 passwordless authentication protocol. It connects browsers, mobile apps, and relying parties through a trust chain anchored in government-issued documents.

End-to-End Overview

Section titled “End-to-End Overview”
IssuanceAuthenticationTrust InfrastructureOfficial DocumentDoc ReaderMRZ + NFC ICAOFace SDKLiveness + 1:1 matchBioSeal IssuanceService (id3)IDToken QR CodeVDS + photoStored in appWeb Browser1. Enter ID2. OTP displayedWebSocketAuth ServerWSPushBrowserMobile3. Receive pushIDToken Mobile App4. Compare OTP5. Face match6. ECDSA sign7. POST /verifyJWT to browserVDSIC GovernanceOtentik SchemeOperator (IAC: VDS)Trust Service ListCertificate AuthorityVDS Signing CertECDSA P-256 + UsageList

Issuance (left) happens once: a government document is read, the holder’s face is verified, and a cryptographically signed VDS credential is stored on their mobile device. Authentication (center) happens on every login: the browser displays a server-generated OTP, the Auth Server pushes it to the mobile app, and the user confirms by matching the code and completing a biometric check. The app then signs the response and POST /verify returns a JWT. Trust Infrastructure (right) underpins both: the Auth Server walks the PKI chain — from the VDSIC Governance List down to the signing certificate — to verify every VDS credential it encounters.

Network Topology

Section titled “Network Topology”
Public Internet (TLS)Web BrowserAuth ServerMobile AppPush ServiceHTTPS / WSSHTTPSPush NotificationInternal NetworkAuth Server(internal)Databaseenrollmentssessions · audit logSession Storeactive sessions · cachereal-time events

System Components

Section titled “System Components”
ComponentRole
IDToken Auth ServiceCentral orchestrator — implements the X.1280 passwordless protocol. Manages enrollment, OTP generation, push delivery, session state, VDS verification, and JWT issuance. Exposes REST + WebSocket APIs and can act as a SAML 2.0 IdP.
IDToken Mobile AppReceives push notifications, displays the OTP for user comparison, performs face-match liveness verification, signs the auth response with the device ECDSA key, and stores the user’s VDS credential.
Web BrowserInitiates the auth session, displays the server-generated OTP, and receives real-time status updates (approved/rejected) over WebSocket.
BioSeal Issuance ServiceReads official documents (MRZ + NFC), performs face liveness and 1:1 match, and produces the cryptographically signed VDS credential stored on the mobile device.
Push Service (FCM)Delivers push notifications from the Auth Service to the mobile app over an out-of-band channel.
PostgreSQLStores enrollments, registered services, and the immutable audit log.
RedisManages active sessions, caching, and pub/sub for real-time WebSocket event delivery across multiple server instances.
Trust InfrastructureThe PKI chain (VDSIC Governance List → Scheme Operator → TSL → CA → Signing Certificate) that the Auth Service walks to verify every VDS credential.

Trust Chain

Section titled “Trust Chain”
VDS PKI Trust ChainISO 22385 ESEDS · ISO 22376 VDSVDSIC Governance BoardRoot List of Trusted Lists (LoTL)XAdES-T signedXML documentlistsOtentik Scheme OperatorIAC: “VDS” · Scheme List (LoTL)Otentik TSOISO 22385 roledefinesIDToken ManifestID: 0A0001 · payload schema + AuthorizedUsage OIDgn, fn, dob, nat,doc, tid, exp,photo, facereferencesTrust Service List (TSL)Catalog of CAs + credential issuers under schemeXAdES-T signed+ VRL endpointsauthorizesCertificate AuthorityCIN: “EU” · issues signing certs + CRL/OCSPX.509 v3 issuerC40-encoded refissuesVDS Signing CertificateECDSA P-256 · UsageList OID 1.3.6.1.4.1.51528.1.1raw r|s 64 bytesUsageList UUIDmust match manifestverifiesVDS Signature VerificationSHA-256( header || SHA-256(payload) ) · ECDSA verifyL1L2L3L4L5L6L7

The Auth Server walks this chain top-down for every VDS credential it encounters. Starting from the VDSIC Governance Board — the global root of trust — each level is cryptographically linked to the next: the Governance List references recognized Scheme Operators, Otentik’s Scheme List defines the IDToken Manifest and its authorized Trust Service Lists, each TSL catalogs the Certificate Authorities under that scheme, and the CA issues the signing certificate whose UsageList OID must match the manifest. At the bottom, the actual ECDSA signature is verified against the certificate’s public key using a double SHA-256 hash of the VDS header and payload. All trust artifacts are cached in Redis with a configurable TTL for offline verification.

See Trust Architecture for the full verification process.

Design Principles

Section titled “Design Principles”
PrincipleDescription
No user databaseEnrollments link a VDS token identifier to a mobile device public key. Identity comes from the VDS itself — the server stores no personal data.
Server-generated OTPThe one-time password is derived from a server-side master secret and session context, not a shared TOTP/HOTP seed.
Out-of-band deliveryThe OTP reaches the mobile app via push notification (a separate channel from the browser), preventing man-in-the-middle interception.
Real-time browser updatesWebSocket connections deliver session state changes (OTP ready, approved, rejected) instantly to the browser, backed by pub/sub for multi-instance deployments.
Immutable audit trailAll security-relevant events are logged to an append-only store. Updates and deletions are blocked at the database level.

Go Deeper

Section titled “Go Deeper”