Password Reset

Overview

Password Reset is an identity verification layer applied at the moment a user who cannot authenticate attempts to recover access to their account. The user arrives with no session and no credential — only a claimed identifier, typically an email address. Everything downstream has to be established rather than re-confirmed.

The workflow evaluates session risk first, then confirms the claimed identity against PII that the relying party prefills and locks, then closes with a possession or biometric step-up. Only on approve is the relying party authorized to issue a new credential. Because the requester is unauthenticated, this workflow does not have a silent "no challenge" outcome: every session that isn't denied outright at Session Risk proceeds into PII Validation. A clean device is not evidence of identity when there is no session to trust.

Unlike Sensitive Transaction, which re-verifies a user already inside the Trusted tier of the Trust Progression Model, Password Reset runs when the user has fallen out of it entirely. It re-establishes trust rather than re-confirming it.

Level of Assurance

Medium (SMS Link confirmation path) to High (Government ID and Selfie Match fallback path). There is no None/no-challenge outcome on this workflow — see note under Session Risk below.

User Friction Level

Medium for the standard path (PII confirmation + SMS Link tap). High for the fallback path (document + selfie capture). Friction is appropriate here in a way it is not at login: the user is asking for a credential to be reissued, so the standard path is deliberately not the lowest-friction option available.

End User Requirements

PII Validation: the identity attributes prefilled by the relying party (name, phone, address — see Configuration Options). SMS Link: mobile phone, ability to receive SMS, matching the prefilled/registered number. Government ID and Selfie Match fallback: same as Identity Verification.

Supported Countries

Session risk assessment: global. PII Validation: dependent on the attribute set and data sources configured. SMS Link: broad international coverage. Government ID and Selfie Match fallback: US, UK, CA (phone path); 180+ countries (document path).

Use Cases & Fraud Prevention

• Self-service password reset and forgotten-credential recovery.
• Account recovery where the user has lost access to their registered MFA factor.
• Replacing knowledge-based recovery (security questions, last-four-of-SSN) which is defeated by data available in any breach corpus.
• Reducing help-desk-mediated resets, where the verification decision rests on an agent's judgment under social-engineering pressure.
• Prevents: account takeover via the recovery path, which is typically the weakest control on an account and the one an attacker reaches for after login controls hold; SIM-swap-only recovery, where control of a phone number is treated as proof of identity; credential-stuffing follow-through, where an attacker with a valid email but no password pivots to reset.

How It Works

flowchart LR
    Start([Password reset requested]) --> SR[Session Risk<br/>Passive assessment]
    SR -->|High risk| Deny([Denied])
    SR -->|Obligation| PII[PII Validation<br/>Prefilled + locked attributes]
    PII -->|Match confirmed| FT[SMS Link<br/>Device possession check]
    PII -->|Not corroborated| Bio[Government ID and Selfie Match<br/>Document + selfie fallback]
    FT -->|Approve| Approve([Approve — reset authorized])
    FT -->|Deny| Deny
    Bio -->|Approve| Approve
    Bio -->|Deny| Deny

Session Risk: Device fingerprint, IP reputation, velocity, and behavioral signals are assessed silently for the session making the reset request. Note the divergence from Continuous Re-Authentication: there is no "trusted device + low risk → approve" outcome here. Every session that isn't denied is obligated into PII Validation. The requester is unauthenticated by definition, so a recognized device establishes nothing about who is holding it.

High risk → Deny: Sessions flagged for TOR, OFAC match, velocity violation, or flagged IP are denied immediately. No challenge is presented. Velocity is worth particular attention on this workflow — repeated reset attempts against one identifier, or one session attempting resets against many identifiers, are both signals the login-time equivalent would not see.

Obligation → PII Validation: The relying party prefills and locks the account's PII via an encrypted login hint (JWE), so PII Validation runs against the record on file rather than data the requester types. The user confirms rather than enters. This is the load-bearing property of the workflow: an attacker who knows the victim's email address is not given the opportunity to supply the rest of the identity, only to confirm or fail against what the relying party already holds.

Match confirmed → SMS Link: A one-time SMS link (FastTap) is sent to the phone number on file. Must be tapped on mobile — desktop opens or timeouts result in denial.

Not corroborated → Government ID and Selfie Match: If PII cannot be sufficiently matched, the user is stepped up to full document + selfie capture rather than denied outright.

Risk Routing Reference

Configuration Options

Template Variations

• Session Risk → PII Validation / deny (no direct-approve tier, by design — see note above)
• PII Validation → SMS Link / Government ID and Selfie Match (fallback) / deny
• Risk thresholds and PII-match sensitivity are configured per-deployment in Policy Manager

Optional Add-ons

• SIM Swap detection on the SMS Link step. More consequential here than on any other workflow: a recently swapped SIM on a reset request is the classic account-takeover sequence, and the signal is available before the possession check is trusted.
• Email Risk on the Session Risk step — the claimed identifier is an email address on most deployments, so this evaluates the thing being claimed rather than only the session claiming it.
• Reduced attribute set. Deployments can configure PII Validation against fewer attributes (for example name and phone only) where the relying party does not hold a full address record. Fewer attributes means a weaker match and more traffic into the fallback path.

Trust Device is not offered on this workflow. Password Reset authorizes a single credential-reissue event for an unauthenticated requester. Persisting device trust from that event would mean carrying trust forward from the least-trusted starting point in the model.

Integration: Gateway (OIDC)

Standard OIDC flow. See Gateway (OIDC) Integration. Your application sends one /authorize request with the account's PII carried in an encrypted login_hint (JWE, RSA-OAEP-256 / A128GCM, against the workflow's public key); the hosted UI handles all path routing and renders the prefilled, locked PII for confirmation. The token response reflects which path ran.

The claimed identifier is carried as the transaction credential inside the login hint, and surfaces as the id_token's sub. There is no credential query parameter on /authorize. Note also that a credential alone cannot drive a policy decision — ID Dataweb branches only on declared user attributes — so deployments that branch on the identifier must declare it as an attribute in addition to sending it as the credential.

Relying-party display considerations

Two properties of this workflow follow from the requester being unauthenticated, and both are the relying party's responsibility rather than the workflow's:

• Do not display the prefilled PII in your own UI. The hosted ID Dataweb page renders the locked attributes because the workflow is verifying against them, but anything your application shows before the redirect is shown to a requester who has not proven anything. Displaying the name, phone, or address on file to whoever typed the email address is an account-enumeration disclosure. Mask it, or omit it.
• Do not vary your response by whether the identifier exists. An unknown identifier and a known one should be indistinguishable from outside.

Step-by-step Setup

• Navigate to the Workflow page in the Admin Console.
• Click Add Workflow, select Password Reset, name it, and deploy.
• Enable Login Hint on the workflow and select Encrypted (not Signed) — Password Reset workflows use JWE prefill so PII arrives locked rather than user-entered. The two options are mutually exclusive; a signed hint on this workflow will not prefill.
• Register your redirect URI against the workflow's client ID.
• Configure risk thresholds in Policy Manager — which signals deny at Session Risk, and the PII-match sensitivity that routes to SMS Link vs. the Government ID and Selfie Match fallback.
• Configure asyncUIRedirect — required for the fallback path (Government ID and Selfie Match capture).

Integration: ID Dataweb API

Session Risk returns either a policyDecision (deny) or an obligation forwarding into PII Validation — there is no approve policyDecision at this step. PII Validation runs against the attributes the relying party submits (or against prefilled data carried through forwardApiKey), and its result determines whether the flow continues to SMS Link or falls back to Government ID and Selfie Match.

sequenceDiagram
    participant App as Your Application
    participant IDW as ID Dataweb API
    participant User as End User

    App->>IDW: POST /slverify (Session Risk key)
    IDW-->>App: obligation + forwardApiKey, or deny

    App->>IDW: POST /slverify (PII Validation key + locked account data)
    IDW-->>App: forwardApiKey (SMS Link or Government ID and Selfie Match)

    alt SMS Link
        App->>IDW: GET /doccapture/send-link (SMS Link key)
        IDW->>User: SMS link
        User->>IDW: Taps link on mobile
        App->>IDW: POST /slverify (SMS Link result)
        IDW-->>App: policyDecision (approve / deny)
    else Government ID and Selfie Match (fallback)
        Note over App,IDW: Continues as Identity Verification flow
    end

Step-by-step Setup

• Call Session Risk first. If deny, stop. Otherwise follow the obligation into PII Validation.
• Submit the account's locked PII to PII Validation and check forwardApiKey to determine whether the user is routed to SMS Link or the Government ID and Selfie Match fallback.
• For the fallback path, follow the same API sequence as Identity Verification from the Government ID and Selfie Match step onward.
• Issue the new credential only on a final approve. Do not treat an obligation or a completed intermediate step as authorization.
• As with every Verify API call: check the response body, never the HTTP status — a rejected call still returns 200.

See SMS Link, PII Validation, and Government ID and Selfie Match for code samples.

Testing in Preproduction

Related Resources

→ Trust Progression Model | → Sensitive Transaction | → Continuous Re-Authentication | → Identity Verification | → Identity Binding | → SMS Link | → PII Validation | → Government ID and Selfie Match | → Gateway (OIDC) Integration