Password Reset

Overview

Password Reset is an identity verification check applied when a user who cannot authenticate tries 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.

Unlike Login Authentication and Sensitive Transaction, there is no trusted-device approve. A recognized device establishes nothing about who is holding it when there is no session to trust, so every session that isn't denied goes through PII Validation. The logic:

• High risk → deny.
• Low risk → PII Validation against the account's prefilled, locked PII.
• PII match → SMS Link to confirm possession of the phone on file.
• PII no match → Government ID and Selfie Match.

Only on a final approve is the relying party authorized to issue a new credential. Where Sensitive Transaction 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) to High (Government ID and Selfie Match). There is no no-challenge outcome on this workflow.

User Friction Level

Medium for the standard path — PII confirmation plus an SMS Link tap. High for the fallback — document and selfie capture. The friction is deliberate: the user is asking for a credential to be reissued.

End User Requirements

PII Validation: the identity attributes on file, prefilled by the relying party. SMS Link: a mobile phone able to receive SMS, matching the number on file. Government ID and Selfie Match: a government-issued photo ID and a device with a camera.

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: 180+ countries.

Use Cases & Fraud Prevention

• Self-service password reset and forgotten-credential recovery.
• Account recovery when 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 decision rests on an agent's judgment under social-engineering pressure.
• Prevents: account takeover via the recovery path — typically the weakest control on an account; phone-number-only recovery, where control of a number is treated as proof of identity; and 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]
    SR -->|High risk| Deny([Denied])
    SR -->|Low risk| PII[PII Validation<br/>Prefilled + locked attributes]
    PII -->|Match| SMS[SMS Link<br/>Confirm phone possession]
    PII -->|No match| Bio[Government ID<br/>and Selfie Match]
    SMS -->|Confirmed on mobile| Approve([Approve — reset authorized])
    SMS -->|Not confirmed| Deny
    Bio -->|Pass| Approve
    Bio -->|Fail| Deny

Session Risk. Device fingerprint, IP reputation, velocity, and behavioral signals are assessed silently. The step has two outcomes:

• High risk → Deny. Sessions flagged for TOR, a blocklisted IP, or a velocity violation are denied immediately. Velocity matters most on this workflow — repeated reset attempts against one identifier, or one session attempting resets against many identifiers.
• Low risk → PII Validation. There is no trusted-device bypass.

PII Validation. The relying party prefills and locks the account's PII through an encrypted login hint, so PII Validation runs against the record on file rather than data the requester types. The user confirms rather than enters. This is what makes the workflow hold: an attacker who knows the victim's email is never given the chance to supply the rest of the identity. A match continues to SMS Link. No match steps up to Government ID and Selfie Match rather than denying outright.

SMS Link. A one-time link is sent by SMS to the phone number on file. Tapping it on the mobile device confirms possession. Confirmed → approve. Desktop opens and timeouts → deny. Device trust is not set on this workflow — trust is not carried forward from an unauthenticated starting point.

Government ID and Selfie Match. The user captures a government ID and a selfie. The document is authenticated and the selfie is compared biometrically to the portrait. Pass → approve. Fail → deny.

Risk Routing Reference

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 routing and renders the prefilled, locked PII for confirmation.

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.

Relying-party display considerations

Because the requester is unauthenticated, two things are the relying party's responsibility:

• Do not display the prefilled PII in your own UI. Showing 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 look the same 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). A signed hint 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.
• Configure asyncUIRedirect — required for Government ID and Selfie Match.

Integration: ID Dataweb API

Your app calls the Verify API directly rather than redirecting. Session Risk returns deny or an obligation into PII Validation — there is no approve at this step. PII Validation's result names the next step: SMS Link or 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: policyDecision (deny / obligation)

    App->>IDW: POST /slverify (PII Validation key + account PII)
    IDW-->>App: obligation (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
        App->>IDW: POST /async-ui/send-link (Government ID and Selfie Match key)
        User->>IDW: Captures ID + selfie
        App->>IDW: POST /slverify (Government ID and Selfie Match result)
        IDW-->>App: policyDecision (approve / deny)
    end

Step-by-step Setup

• Call Session Risk. If deny, stop. Otherwise follow the obligation into PII Validation.
• Submit the account's PII to PII Validation, then call the step the obligation names and re-submit the result to /slverify.
• Issue the new credential only on a final approve. An obligation or a completed intermediate step is not authorization.
• As always: 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 | → Login Authentication | → Sensitive Transaction | → SMS Link | → PII Validation | → Government ID and Selfie Match | → Gateway (OIDC) Integration