Your Application
Click the button below to start the ID.me verification flow
Your Application
Waiting for ID.me verification...
| Attribute | Value |
|---|---|
| uuid | Waiting for auth... |
| fname | -- |
| lname | -- |
| -- | |
| zip | -- |
Welcome to the ID.me Demo
This interactive walkthrough demonstrates how ID.me identity verification integrates into your application. You'll see the full flow from configuration to live authentication.
Authentication vs. Identity Proofing
Traditional login systems only authenticate — they confirm that a returning user knows their password. ID.me goes further with identity proofing, verifying that a person is who they claim to be using government-issued documents and biometric checks.
NIST Identity Assurance Levels (IAL)
- IAL1 — Self-asserted attributes only (email, name). No document verification.
- IAL2 — Remote identity proofing with document verification and liveness detection. Meets federal standards for most use cases.
- IAL3 — In-person identity proofing with a trained operator. Highest assurance level.
ID.me is a NIST 800-63-3 compliant credential service provider (CSP), meaning verified identities meet federal security standards.
Community Verification
Beyond individual identity proofing, ID.me verifies membership in specific communities — groups of people who share a common affiliation. This lets organizations offer targeted benefits, discounts, or access to verified community members.
Supported Communities
- Military — Active duty, veterans, military spouses, dependents, Gold Star families. Verified against DoD records (DEERS/DMDC).
- First Responders — Law enforcement, firefighters, EMTs, paramedics, 911 dispatchers. Verified via employer and credential databases.
- Students — Currently enrolled college and university students. Verified against school enrollment records.
- Teachers & Faculty — K-12 teachers, professors, and education staff. Verified via institutional email or employment records.
- Government — Federal, state, and local government employees. Verified through agency records.
- Medical Professionals — Nurses, doctors, pharmacists, and other licensed healthcare workers. Verified via license databases.
How Community Verification Works
When your application requests a community-specific policy, ID.me prompts the user to verify both their identity and their group membership. The verification method depends on the community — it may involve checking government databases, validating a .mil/.gov email, uploading credentials, or confirming enrollment records.
After verification, your app receives a group attribute confirming the user's community membership, along with standard identity attributes. Community verification status is cached, so returning users don't need to re-verify every time.
How It Works
ID.me acts as a trusted identity provider. Your application redirects users to ID.me for verification, then receives verified identity attributes back through a standard protocol.
The flow follows standard OAuth 2.0 / OpenID Connect / SAML patterns:
- User clicks "Verify with ID.me" in your app
- User is redirected to (or a popup opens for) ID.me
- User verifies their identity with ID.me
- ID.me sends an authorization code to your server
- Your server exchanges the code for user data
Why an Authorization Code?
Instead of sending tokens directly to the browser (which could be intercepted), the authorization code flow uses a two-step exchange. The browser only sees a short-lived code, and your server exchanges it for tokens using your client secret — which never leaves the server.
Security Parameters
state— A random value your app generates and verifies on callback to prevent CSRF attacks. The callback must match the state you sent.nonce(OIDC) — A random value embedded in the ID token. Your server verifies it to prevent token replay attacks.- PKCE (Proof Key for Code Exchange) — An extension where your app sends a
code_challengehash with the auth request and proves it on token exchange with the originalcode_verifier. Prevents authorization code interception.
Redirect vs. Popup
Full-page redirects are the standard approach and work everywhere. Popup windows keep your app visible but require careful handling of window.opener and postMessage. Popups may be blocked by browsers if not triggered by a direct user click.
state parameter on your callback to prevent cross-site request forgery. Never skip this check in production.
How SAML Differs from OAuth/OIDC
Unlike OAuth/OIDC which use an authorization code exchanged via back-channel, SAML uses a browser-mediated assertion. There is no token exchange step — the identity data is delivered directly in a signed XML document posted to your server.
SP-Initiated SSO Flow
- Step 1: Your app (the Service Provider) redirects the user to ID.me's
SingleSignOnServiceendpoint with parameters likeEntityIDandAuthnContext. - Step 2: The user authenticates and verifies their identity at ID.me (the Identity Provider).
- Step 3: ID.me constructs a signed SAML Response containing the assertion with verified attributes.
- Step 4: The user's browser is redirected via an auto-submitting HTML form that POSTs the base64-encoded
SAMLResponseto your Assertion Consumer Service (ACS) URL. - Step 5: Your ACS endpoint validates the signature, checks conditions, and extracts the user's attributes from the assertion.
HTTP POST Binding
The HTTP POST binding means the SAML Response travels through the user's browser as a form POST — not as a server-to-server call. ID.me returns an HTML page with a hidden form containing the SAMLResponse and optional RelayState, and JavaScript auto-submits it to your ACS URL.
Key SAML Concepts
- Assertion Consumer Service (ACS) — Your endpoint that receives and processes the SAML Response. Must be pre-registered with ID.me and match exactly.
- EntityID — A unique identifier for your Service Provider, shared with ID.me during setup.
- RelayState — An opaque value preserved through the flow. Use it to remember where to send the user after authentication (e.g. the page they were on).
- Metadata Exchange — Both SP and IdP publish XML metadata documents describing their endpoints, certificates, and capabilities. This enables automated trust configuration.
Configuration
This demo is pre-configured to use the ID.me sandbox environment, which provides a safe testing space with test credentials.
Sandbox uses api.idmelabs.com and allows testing without real identity documents. Production uses api.id.me and performs real verification.
ID.me supports three authentication protocols:
Sandbox vs. Production
The sandbox environment (api.idmelabs.com) mirrors production behavior but uses test data. No real identity documents are verified. This is where you develop and test your integration before going live.
- Sandbox — No real verification occurs, separate client credentials from production.
- Production — Real users, real document verification, real identity data. Uses
api.id.me.
Client Credential Security
Your client_secret is like a password for your application. It must never be exposed in client-side JavaScript, mobile app bundles, or public repositories. Store it in environment variables or a secrets manager.
Redirect URI Configuration
Redirect URIs must be pre-registered in the ID.me developer portal. The URI in your auth request must exactly match a registered URI — including protocol, host, port, and path. Mismatches cause invalid_grant errors.
Choose Your Protocol
Select an authentication protocol from the left panel to use for the live demo. Each protocol returns verified identity data in a different format.
Not sure which to pick? OAuth 2.0 is the most common choice for web applications. You can also just click NEXT to continue with the default.
OAuth 2.0
A delegation protocol for authorization. Your app requests specific scopes (e.g. http://idmanagement.gov/ns/assurance/ial/2) and receives an access token to retrieve user attributes from the ID.me API. Data comes back as plain JSON.
- Best for: Web and mobile apps that need verified attributes
- Token format: Opaque access token
- Data format: JSON from
/api/public/v3/attributes
OpenID Connect (OIDC)
An identity layer on top of OAuth 2.0. Adds the openid scope, which returns an ID token (a signed JWT) containing user claims. Your server can verify the JWT signature without making additional API calls.
- Best for: Apps that want cryptographically signed identity claims
- Token format: JWT (JSON Web Token) with
id_token - Data format: JWT claims or JSON from
/api/public/v3/userinfo - Discovery:
/.well-known/openid-configuration
SAML 2.0
An XML-based federation protocol commonly used in enterprise environments. The identity provider (ID.me) sends a signed XML assertion to your Assertion Consumer Service (ACS) URL via HTTP POST binding.
- Best for: Enterprise SSO, government systems, legacy integrations
- Token format: Signed XML assertion
- Data format: XML attributes in SAML assertion
- Metadata: SP and IdP metadata XML documents
Select a Policy
Policies define what level of identity verification is required and what attributes are returned. Select a policy from the left to use in the demo.
Each policy maps to a verification scope — from basic email verification to full identity proofing with document verification.
What Is a Policy?
A policy defines the scope of verification required. It controls what level of identity proofing the user must complete and what attributes your application will receive back. Policies are configured in the ID.me developer portal and map to specific scopes in your auth request.
How Policies Map to Scopes
In OAuth/OIDC, the policy handle is sent as a scope parameter (e.g. scope=http://idmanagement.gov/ns/assurance/ial/2). In SAML, it's sent as the AuthnContext parameter. Either way, it tells ID.me which verification flow to present to the user.
Common Policy Types
- IAL1 / Basic — Self-asserted identity. User provides name, email, phone. No document check. Fastest to complete.
- IAL2 / Identity Proofing — Document-verified identity. User submits a government ID and completes liveness detection. Meets NIST 800-63-3 IAL2.
- Group Affiliation — Verifies membership in a specific group (military, student, first responder, etc.) in addition to identity.
Returned Attributes
The attributes you receive depend on the policy. A basic policy may only return uuid, email, and fname/lname. An IAL2 policy returns additional fields like social, dob, address, and verification status.