Used to check for browser translation.
用于检测浏览器翻译。
ブラウザの翻訳を検出する
Core Concepts

Authentication Flow

The DID-Auth process is a stateful, multi-step interaction between a user's DID Wallet and your application server. It's orchestrated through a series of API calls, enabling secure, decentralized authentication without traditional passwords. This section breaks down the entire lifecycle of a DID-Auth session, from generating a QR code to verifying the user's identity.

The End-to-End Process#

The following diagram illustrates the complete sequence of interactions between the user's browser, your application server, and their DID Wallet.

DID WalletApplication ServerUser Browser (Client)DID WalletApplication ServerUser Browser (Client)1. Session Initiation2. Status Pollingloop[Poll for Status]3. Wallet Scans & Connects4. UI Updates on Scan5. Claims Exchangealt[More claims required][All claims fulfilled]6. Session CompletionPOST /api/did/{action}/token (Request to log in)Respond with { token, url }Display QR code from urlGET /api/did/{action}/status?_t_={token}Respond with { status: "created" }GET from QR code's url (e.g., /auth?_t_={token})Respond with first claim request (authPrincipal)Update session status to 'scanned'GET /api/did/{action}/status?_t_={token}Respond with { status: "scanned" }POST /auth (User approves & signs response)onAuthResponse verifies signatureRespond with next claim requestPOST /auth (User provides next claim)Respond with { successMessage, nextWorkflow, ... }Update session status to 'succeed'GET /api/did/{action}/status?_t_={token}Respond with { status: "succeed", did, ... }Finalize login, redirect user

Step-by-Step Breakdown#

Here is a more detailed look at each phase of the authentication flow.

1. Session Initiation: Token Generation#

The process begins when the user decides to log in. Your application's client-side (e.g., a web browser) makes a request to a designated endpoint on your server, typically /api/did/{action}/token.

  • Request: POST /api/did/login/token
  • Action: The server's generateSession function creates a new session in the tokenStorage.
  • Response: The server returns a JSON object containing:
    • token: A unique session identifier.
    • url: A deep link URL (e.g., https://abtwallet.io/i/?url=...) containing the token and the server's callback endpoint. This URL is rendered as a QR code in the browser.

The session's initial status is set to created.

2. Wallet Interaction: QR Code Scan#

The user scans the QR code with their DID Wallet.

  • Action: The wallet parses the deep link and makes a GET request to your server's /auth endpoint, presenting the token.
  • Server Response: Upon receiving the request, the server identifies the session via the token and updates its status to scanned. It then sends the first authentication challenge, known as a claim, back to the wallet. By default, this is the authPrincipal claim, which simply asks the user to prove ownership of their DID.

3. Client-Side Polling: Status Check#

While the user interacts with their wallet, your client-side application polls the /status endpoint periodically, sending the token with each request.

  • Request: GET /api/did/login/status?_t_={token}
  • Purpose: This allows your UI to react to changes in the session state. For example, after the wallet scans the code, the /status endpoint will return `status:
previous
Core Concepts
next
Understanding Claims