Skip to main content

The DID Connect Workflow

A DID Connect session is a secure, decentralized authentication process that allows a user to interact with a decentralized application (DApp) using their DID Wallet. This guide breaks down the end-to-end process, from the initial QR code scan to the final handling of the user's response.

The typical workflow involves four main actors:

  1. User

    The individual interacting with the application.

  2. Browser (DApp Frontend)

    The user interface of your application running in the user's browser.

  3. DApp Backend

    Your server-side application where the @arcblock/did-connect-js library is integrated.

  4. DID Wallet

    The user's mobile or web-based wallet that manages their decentralized identity (DID) and private keys.

Visual Overview

The following diagram illustrates the high-level interaction between the DApp and the DID Wallet during a typical authentication session.

A diagram showing the DID Connect workflow between a DApp and a DID Wallet.

Step-by-Step Breakdown

Let's dive into the technical details of each step in the process. The sequence diagram below shows the complete communication flow.

The DID Connect Workflow

1. Session Initiation: Generating the QR Code

The process begins when the user wants to log in or perform a protected action.

  1. Frontend Request: The DApp's frontend makes a request to a dedicated endpoint on its backend (e.g., GET /api/did/login/token).
  2. Backend Handler: The did-connect-js handler (generateSession) on your backend creates a new, unique session. It generates:
  • A unique token to identify the session.
  • A cryptographic challenge to prevent replay attacks.
  • A full DID Connect URL (e.g., https://didconnect.io/i/?url=...) containing this information.
  1. Frontend Display: The backend returns the token and the url to the frontend. The frontend then renders the url as a QR code for the user to scan.

2. Wallet Interaction: Scanning and Approval

  1. Scan

    The user scans the QR code with their DID Wallet.

  2. Request Claims

    The wallet makes a GET request to the auth URL from the QR code. This hits the onAuthRequest handler on your backend.

  3. Backend Response

    Your backend updates the session status to scanned and sends back a signed JSON Web Token (JWT). This JWT contains the information your application is requesting from the user, known as claims (e.g., authPrincipal to request a connection, or profile to request user data).

  4. User Approval

    The wallet verifies the JWT and presents the request to the user. The user can then choose to approve or decline the request.

3. Handling the Response

  1. Wallet Submission: If the user approves, the wallet creates and signs its own JWT containing the requested information. It then POSTs this JWT back to the same auth URL.
  2. Backend Verification: This request is handled by the onAuthResponse function in your backend. The library automatically verifies the wallet's signature and the challenge. This is the most critical step for security.
  3. Execute Business Logic: If the verification is successful, the library triggers your onAuth callback. This is where you put your core business logic, such as:
  • Finding or creating a user account based on their userDid.
  • Processing the claims data (e.g., saving the user's profile).
  • Generating a web session token for the browser.
  • Using updateSession to store data that the frontend can later retrieve.
  1. Session Completion: The backend marks the session status as succeed.

4. Updating the Frontend

While the user is interacting with their wallet, your DApp's frontend polls a status endpoint (e.g., GET /api/did/login/status?_t_={token}). Once it sees the status change to succeed, it knows the process is complete. It can then fetch any necessary data (like a login token) from the session and update the UI accordingly, for example, by redirecting the user to their dashboard.

This entire flow provides a secure, passwordless authentication experience that puts the user in control of their data.

For a deeper understanding of how to manage the data received from the wallet, proceed to our guide on Handling Wallet Responses.