Use this practical OAuth and OpenID Connect claims checklist to design identity verification tokens, validate provider responses, limit sensitive data exposure, and avoid common audience, scope, and assurance mistakes.
Overview
Identity verification applications often connect several systems: an identity provider, an onboarding service, a customer-facing application, a compliance workflow, and downstream APIs. OAuth and OpenID Connect (OIDC) provide the authorization and authentication layers for those connections, but they do not automatically define how every verification result should be represented.
The first design decision is to separate authentication claims from identity verification claims. Authentication claims describe how a subject authenticated and which client or service received the token. Verification claims describe the outcome and context of an identity proofing or document-checking process. These are related, but they answer different questions:
- Authentication: Who is the subject, and how did the subject authenticate?
- Authorization: What may this client or service do?
- Verification: What checks were completed, when, and with what level of confidence or assurance?
OIDC standard claims such as iss, sub, aud, exp, iat, nonce, acr, and amr support authentication and token validation. A provider may also issue profile claims such as name, email, or birthdate when the relevant scope, consent, and implementation support them. A verification status field, however, is often application-specific or defined by another profile. Do not assume that a claim name has the same meaning across identity providers.
For broader context, review the difference between identity verification, authentication, and authorization before finalizing your token model.
Checklist by scenario
1. Issuing an ID token to a relying party
An ID token is intended for the OIDC client that requested authentication. Before issuing one, confirm:
iss: Use a stable issuer identifier and require exact issuer matching during validation.sub: Use a stable subject identifier appropriate for the relying party. Avoid using an email address as the primary identifier because it can change and may not be unique across providers.aud: Include the intended client identifier and ensure the client validates it.expandiat: Give the token a bounded lifetime and validate its time claims with an explicitly documented clock-skew policy.nonce: Include and validate it when the OIDC flow requires replay protection for the authentication response.auth_time,acr, andamr: Include these only when your implementation can accurately describe the authentication event and the relying party needs that context.
Keep the ID token focused on the client. Do not use it as a general-purpose identity record or pass it to unrelated APIs. If a downstream service needs information, give that service an access token for its own audience and let it obtain only the data it needs.
2. Returning verification results through UserInfo
UserInfo can be useful for returning claims associated with the authenticated subject, but it should not become an unrestricted document repository. Define each verification claim with a clear meaning, owner, source, and retention expectation.
A useful verification response might distinguish between:
- Process state: whether verification is pending, completed, rejected, or requires review.
- Check type: the category of check performed, such as document, liveness, age, or business-identity review.
- Completion time: when the result was established, represented in a consistent time format.
- Assurance context: the level or method used, where your system has a documented definition.
- Review reference: a non-sensitive case identifier that allows authorized systems to retrieve audit details without placing those details in the token.
Names such as verification_status or document_verified should be treated as custom claims unless a specification or provider contract gives them a defined meaning. Namespace custom claims to reduce collisions, document their types, and version changes deliberately. A value of true alone is rarely enough: consumers may also need to know which check was completed, when it happened, and whether the result is still valid for the current action.
3. Authorizing a protected API
For an API, validate the access token rather than trusting an ID token copied from the client. Check the signature using the provider's trusted key-discovery process, then validate at least the issuer, audience, expiry, and required authorization context. The exact checks depend on the token format and deployment, so record them in the API security design rather than relying on library defaults.
Use narrow scopes and enforce them at the API boundary. For example, a service that only needs to confirm an onboarding state should receive permission to read that state, not permission to access a complete customer profile. If the API needs a verification result, define whether it trusts a signed claim, queries a verification service, or receives a server-to-server decision. The choice affects revocation, freshness, auditability, and failure handling.
4. Supporting high-risk or regulated actions
Do not treat a successful login as proof that every high-risk action is safe. For account recovery, a sensitive profile change, a payout, or another elevated operation, consider whether the application needs recent authentication, a stronger authentication method, a fresh verification result, or an independent risk decision.
Document the relationship between claims and decisions. A claim such as amr describes an authentication method; it does not by itself prove that a document belongs to the person using the account. Likewise, a verification result does not replace authorization or transaction-risk controls. This separation supports layered account takeover prevention.
What to double-check
| Area | Questions to answer | Design preference |
|---|---|---|
| Token purpose | Is this an ID token, access token, or a response from UserInfo? | Use each artifact only for its intended audience and function. |
| Audience | Which exact client or API is expected to consume it? | Use distinct audiences and reject unexpected ones. |
| Scopes | What data and operation does each scope authorize? | Prefer small, purpose-specific scopes with documented consent. |
| Verification status | What does the status mean, and who is responsible for updating it? | Define states, timestamps, expiry or refresh rules, and review paths. |
| Privacy | Does the consumer need the raw value, or only a decision? | Return the minimum data needed; keep documents and biometric material out of tokens. |
| Freshness | Can the result change after the token is issued? | Use short-lived decisions or an authoritative lookup for time-sensitive actions. |
| Audit | Can an authorized reviewer explain how the claim was produced? | Store a protected case reference and maintain an auditable server-side record. |
Also test the negative paths. A secure integration should handle missing claims, duplicate claims, unexpected data types, expired tokens, invalid signatures, wrong audiences, insufficient scopes, and a verification result that has moved from approved to review. Use contract tests to ensure that a provider or SDK update does not silently change claim names, types, or null-handling behavior.
When integrating an identity verification API, pair this claims review with the identity verification API integration checklist and confirm that webhook events cannot overwrite a result without signature validation, replay protection, and idempotent processing.
Common mistakes
- Putting every user attribute in the ID token: Large tokens increase exposure and create unnecessary dependencies between clients and identity data.
- Accepting a token because its signature is valid: Signature validation does not replace issuer, audience, expiry, nonce, or scope checks.
- Confusing authentication with identity proofing: A strong login event and a completed document verification are different signals.
- Using a boolean as a permanent decision: Verification can have a time boundary, a review state, or a purpose-specific result.
- Trusting client-supplied verification claims: Sensitive decisions should be based on claims from a trusted issuer or an authoritative backend service.
- Exposing raw evidence downstream: Documents, extracted identity numbers, face images, and detailed fraud signals should not travel through every service by default.
- Changing claim meanings without versioning: A field that changes from “document accepted” to “person fully verified” can create serious authorization errors even if its name stays the same.
When to revisit
Revisit this claims design before adding a relying party, introducing a new identity provider, changing token audiences, expanding scopes, or connecting a new downstream service. It should also be reviewed when verification workflows change, when a new document or biometric check is introduced, or when a high-risk action begins relying on a verification result.
As a practical maintenance routine, schedule a review before seasonal planning cycles and after significant OAuth, OIDC, identity-provider, or SDK changes. Confirm the applicable specifications, provider documentation, library validation defaults, consent behavior, key-rotation handling, and privacy requirements at that time rather than assuming an older integration remains correct.
Use this final release checklist:
- List every token and response type in the workflow.
- Map each claim to its issuer, consumer, purpose, sensitivity, and retention rule.
- Separate authentication, authorization, and verification decisions.
- Write explicit validation rules for issuer, audience, signature, time, nonce, scope, and required claims.
- Minimize personal data and keep raw verification evidence behind an authorized service boundary.
- Test success, failure, stale-result, missing-claim, and wrong-audience cases.
- Record the claim contract and set a review trigger for the next workflow or tool change.
That discipline makes an identity verification integration easier to review, safer to extend, and less likely to turn an authentication token into an uncontrolled store of personal information.