Integration Guide

IDToken can be integrated into any web application or service. This guide covers the integration options and how to consume IDToken identity assertions.

Integration Options

Method	Protocol	Best For
OpenID Connect	OIDC (Authorization Code Flow)	Cloud services, SaaS platforms, standard SSO
JWT (direct)	REST API + WebSocket	Custom web apps, SPAs, mobile backends
SAML 2.0	SAML assertions	Enterprise SSO, legacy systems, government portals
Verifiable Credentials	W3C VC (JWT-VC)	Digital wallets, eIDAS 2.0, offline verification
JWKS verification	Public key fetch	Any service that receives IDToken JWTs

For cloud services and standard SSO (Google Workspace, Microsoft 365, Slack, etc.), use OpenID Connect — it requires zero custom code on the client side. For custom applications that need real-time session updates (WebSocket), use the direct JWT integration below.

JWT Integration (Recommended)

1. Register Your Service

Allowed scopes — which identity data your service can request
Default scopes — scopes used when none are specified
Service name & logo — displayed to users on the mobile consent screen
Privacy policy URL — linked from the consent screen
Consent requirement — whether users must explicitly approve

You will also receive a Service VDS — a cryptographically signed credential identifying your service. Using the Service VDS for authentication provides stronger security than a plain serviceId. See Mutual Service Identity for the full benefits.

2. Initiate Authentication

When a user wants to log in, your frontend calls the IDToken auth server. You can identify your service using either a Service VDS (recommended) or a serviceId (legacy):

// Recommended: initiate auth with Service VDS
const response = await fetch('https://auth.idtoken.example.com/auth/initiate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tokenId: userTokenId,
    serviceVds: SERVICE_VDS_BASE45,  // Your Service VDS credential
    scopes: ['identity:name', 'identity:age_over_18']
  })
});

const { sessionId, autoPassword, wsToken, random } = await response.json();

// Display the OTP to the user
displayOTP(autoPassword);

3. Listen for Result

Connect to the WebSocket to receive the authentication result:

const ws = new WebSocket(
  `wss://auth.idtoken.example.com/ws/session/${sessionId}?token=${wsToken}`
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'approved') {
    // User authenticated — verify and use the JWT
    const jwt = data.jwt;
    verifyAndLogin(jwt, data.hash, data.random);
  } else if (data.type === 'rejected') {
    showError(data.reason);
  }
};

4. Verify the JWT

Fetch the server’s public key from the JWKS endpoint and verify the JWT:

// Fetch JWKS (cache this — it changes infrequently)
const jwks = await fetch('https://auth.idtoken.example.com/.well-known/jwks.json')
  .then(r => r.json());

// Verify JWT signature (ES256 / ECDSA P-256)
const payload = verifyJWT(jwt, jwks);

// Use identity claims
console.log(payload.idtoken.givenName);  // "Jean"
console.log(payload.idtoken.ageOver18);  // true

5. Verify Response Integrity (Optional)

For X.1280 anti-forgery protection, verify the response hash:

expected_hash = HMAC-SHA256(shared_secret, jwt + "|" + sessionId + "|" + random)

The random must match the value from /auth/initiate. If either check fails, the response may be forged.

JWT Claims

The JWT idtoken claim contains only the data matching the granted scopes:

{
  "iss": "https://idtoken.example.com",
  "aud": "https://services.example.com",
  "sub": "vds-token-id",
  "iat": 1705312800,
  "exp": 1705316400,
  "scope": "identity:name identity:age_over_18",
  "idtoken": {
    "tokenId": "vds-token-id",
    "givenName": "Jean",
    "familyName": "Dupont",
    "ageOver18": true,
    "trustLevel": 3
  }
}

Selective Disclosure

Services should request only the scopes they need — this is both a GDPR data minimization requirement and a better user experience.

Example Use Cases

Use Case	Scopes to Request	User Sees
Age verification (bar)	`identity:age_over_18`	”Over 18: yes/no”
Loyalty program	`identity:name`	”Name: Jean Dupont”
Age-restricted content	`identity:age_over_18`, `identity:name_initial`	”Over 18 + J. D.”
Government portal	`identity:full`	Full identity data
KYC verification	`identity:full_with_photo`	Full data + photo

Derived Scopes

These provide a yes/no answer without revealing the underlying data:

Scope	Returns	Underlying Data NOT Shared
`identity:age_over_18`	`true` / `false`	Date of birth
`identity:age_range`	Bracket (e.g., “26-35”)	Date of birth
`identity:is_eu_citizen`	`true` / `false`	Nationality code
`identity:name_initial`	”J. D.”	Full name

SAML 2.0 Integration

For enterprise environments using SAML-based SSO, IDToken acts as a SAML Identity Provider. See the SAML 2.0 IdP page for full details.

Quick setup:

Obtain the IDToken IdP metadata: GET /saml/metadata
Import the metadata into your SAML Service Provider
Register your SP with the IDToken operator (entity ID, ACS URL, signing cert)
Users authenticate via the standard X.1280 flow; the result is delivered as a SAML assertion

Revocation Handling

Services should handle token revocation gracefully:

IDToken JWTs have a configurable expiry (default: 1 hour)
For long sessions, periodically re-authenticate
The tokenId is the stable user identifier — if an enrollment is revoked and re-issued, the user gets a new tokenId
Services do not need to take action on revocation — the auth server blocks authentication for revoked tokens automatically

Go Deeper

Authentication Flow — Full protocol walkthrough with API request/response formats
Mutual Service Identity — Cryptographic service verification using Service VDS
Security Model — Threat model, cryptographic algorithms, and security guarantees
Security & Deployment — Deployment architecture and configuration reference