ID Token

ID Tokens contain a standard set of claims defined by the OpenID Connect specification. Core claims include:

• sub (subject): The unique identifier for the user.
• iss (issuer): The URL of the OIDC provider.
• aud (audience): The client ID of the relying party.
• exp (expiration): The token's expiry timestamp.
• iat (issued at): The time the token was issued. These claims allow the relying party to verify the token's origin and intended recipient.

An ID Token is a specific use case of a JSON Web Token (JWT), which is a compact, URL-safe token format. A JWT consists of three Base64Url-encoded parts separated by dots:

• Header: Specifies the token type (JWT) and the signing algorithm (e.g., RS256).
• Payload: Contains the set of claims about the user.
• Signature: Created by signing the encoded header and payload, allowing the token's integrity and authenticity to be verified. This structure makes it self-contained and verifiable.

ID Tokens enable stateless authentication. The token itself contains all necessary user information, eliminating the need for the relying party (e.g., your application) to query the identity provider's database on every request. The application validates the token's signature and claims locally. This reduces latency and server load, making it ideal for distributed systems and single sign-on (SSO) architectures.

A critical security feature is the cryptographic signature, typically created using RS256 (RSA Signature with SHA-256). The relying party validates the token by:

1. Verifying the signature using the OIDC provider's public JWKS (JSON Web Key Set).
2. Checking the iss claim matches the known provider.
3. Confirming the aud claim matches its own client ID.
4. Ensuring the current time is before the exp claim. This process prevents token tampering and ensures it was issued by a trusted source.

ID Tokens have a short, predefined lifetime, usually on the order of minutes (e.g., 5-15 minutes). This is enforced by the mandatory exp (expiration) claim. The short lifespan is a security measure that limits the window of opportunity for a stolen token to be used maliciously. For persistent sessions, applications use the ID Token once to authenticate a user and then establish their own session, or use a Refresh Token to obtain new ID Tokens.

It is crucial to distinguish an ID Token from an Access Token. They serve different purposes in the OAuth 2.0 and OpenID Connect flow:

• ID Token: For authentication. It tells the client who the user is. Contains identity claims.
• Access Token: For authorization. It is used by the client to access protected resources (APIs) on behalf of the user. Contains scopes and permissions. A client should never use an ID Token to call an API; it should use the Access Token.

An ID Token is a cryptographically signed JSON Web Token (JWT). Its payload contains standardized claims about the user's authentication event. Key claims include:

• sub (subject): The unique identifier for the user.
• iss (issuer): The URL of the OIDC provider.
• aud (audience): The client ID of the application the token is intended for.
• exp (expiration): The token's expiry timestamp.
• nonce: A string value used to associate a client session with the ID Token, mitigating replay attacks.

ID Tokens are central to Sign-In with Ethereum (SIWE) and other Web3 authentication standards. The typical flow is:

1. A user connects their wallet (e.g., MetaMask) to a dApp.
2. The dApp's backend (or a service like Auth0, Clerk) requests an ID Token from an OIDC-compliant provider.
3. The user signs a SIWE message with their private key, proving control of their Ethereum address.
4. The provider validates the signature and issues an ID Token with the user's sub claim often set to their Decentralized Identifier (DID) or wallet address.
5. The dApp receives and verifies the ID Token's signature to establish a secure session.

It's critical to distinguish ID Tokens from Access Tokens, as they serve different purposes in the OAuth 2.0 and OIDC framework.

• ID Token: Purpose is authentication. It tells the client who the user is. It is intended for the client application itself.
• Access Token: Purpose is authorization. It is used by the client to access protected resources (like a user's data) on a Resource Server (e.g., an API). In Web3, an ID Token proves a user owns an address, while an Access Token might grant a dApp backend permission to read a user's on-chain data from an indexer API.

Client applications must cryptographically verify every ID Token to ensure its integrity and authenticity. This involves:

• Signature Validation: Using the OIDC provider's public keys (from its JWKS endpoint) to verify the JWT's signature.
• Claim Validation: Checking standard claims:
  • iss matches the trusted provider.
  • aud matches the client's own ID.
  • exp has not passed.
  • nonce matches the value sent in the initial request.
• Token Binding: Advanced security can involve binding the token to a specific client instance using mechanisms like DPoP (Demonstrating Proof-of-Possession).

A primary use for ID Tokens is to create and manage user sessions without constant wallet re-signing. After initial verification:

• The dApp backend extracts the user's identifier (e.g., 0x... address) from the sub claim.
• It creates a local session (e.g., via an HTTP-only cookie or a session ID) linked to this identity.
• For subsequent requests, the session is validated instead of requiring a new wallet signature, improving user experience while maintaining security rooted in the initial cryptographic proof.

ID Token functionality is defined by and interoperates with several key standards and services:

• OpenID Connect (OIDC): The core authentication layer on top of OAuth 2.0 that defines the ID Token.
• JSON Web Token (JWT): The compact, URL-safe token format (RFC 7519).
• Sign-In with Ethereum (EIP-4361): A specification for Ethereum-centric authentication that produces OIDC-compatible ID Tokens.
• Decentralized Identifiers (DIDs): The sub claim in an ID Token can be a DID, linking to a verifiable, user-controlled identity document.
• Providers: Services like Auth0, Clerk, NextAuth.js, and Web3Auth can act as OIDC providers issuing ID Tokens for dApps.

An ID Token is a bearer credential; possession grants access. The primary risks are:

• Phishing attacks that trick users into signing malicious transactions to steal tokens.
• Private key compromise on the user's device, allowing an attacker to impersonate the holder.
• Malicious dApps requesting excessive permissions (scope) beyond what is necessary for their function. Protection requires secure key management (hardware wallets) and user education to verify transaction details.

A valid ID Token presented to one verifier could be replayed to another if not properly guarded. Mitigations include:

• Using a nonce (number used once) challenge tied to a specific session or request.
• Binding the token to a specific audience (aud claim) to prevent use against unintended services.
• Implementing short token expiration times to limit the usable window for a stolen token.

The security of an ID Token is only as strong as the trust in its issuer. Considerations:

• Centralized Issuers: A compromised or malicious issuer can mint fraudulent tokens or revoke valid ones, breaking the system's decentralization promise.
• Decentralized Identifiers (DIDs): Use blockchain or distributed ledgers for verifiable, resilient issuance without a single point of failure.
• Verifiable Credentials: A W3C standard that uses cryptographic proofs, allowing verification without contacting the original issuer.

ID Tokens can inadvertently leak personal data. Secure implementations follow the Principle of Least Privilege:

• Selective Disclosure: Use zero-knowledge proofs (ZKPs) to prove a claim (e.g., age > 18) without revealing the exact birth date or full identity.
• Minimal Claims: Request and issue only the specific user attributes (name, email) absolutely required for the service.
• On-Chain Privacy: Avoid storing raw personal data or correlatable identifiers directly on a public blockchain.

A token's integrity is verified by checking its cryptographic signature. Critical checks include:

• Valid Signature: Confirming the token was signed by the trusted issuer's private key using the expected algorithm (e.g., ES256K).
• Algorithm Security: Deprecating weak algorithms (e.g., RS256 with small keys) in favor of modern, quantum-resistant options where possible.
• Key Rotation: Verifiers must have a secure mechanism to fetch the issuer's current public keys if they are rotated or revoked.

When ID Tokens are used for on-chain access (e.g., token-gated contracts), new attack vectors emerge:

• Front-running: A malicious actor sees a valid token verification transaction in the mempool and replays it for their own benefit.
• Contract Logic Flaws: Bugs in the verification logic may accept expired or malformed tokens.
• Gas Griefing: Attackers may drain user funds by forcing expensive verification logic to be run repeatedly. Audits and using established libraries like OpenZeppelin are essential.