Core Concepts
To effectively use the did-auth library, it's helpful to understand its core components and the overall architecture. This library provides the tools to integrate decentralized identity authentication into your application, interacting securely with a user's DID Wallet.
The two main pillars of the library are the WalletAuthenticator and the handlers created by createHandlers. They work together to manage the entire authentication process.
Architecture Overview#
At a high level, the authentication process involves your application server, the user's browser (the client), and the user's DID Wallet. The server generates a unique session, the client displays it as a QR code, and the wallet consumes it to start a secure, direct communication channel with your server.
Key Components#
WalletAuthenticator#
The WalletAuthenticator is the cryptographic engine of the library. Its primary job is to create and verify the JWT (JSON Web Token) messages exchanged between your application and the user's DID Wallet. You configure it with your application's identity (wallet), information (appInfo), and the blockchain it operates on (chainInfo).
Key responsibilities include:
- Signing Authentication Requests (
sign): Creates a signed JWT containing the claims you are requesting from the user. - Verifying Wallet Responses (
verify): Validates the cryptographic integrity of the data sent back from the wallet, ensuring it hasn't been tampered with and was approved by the user. - Generating the Auth URL (
uri): Constructs the deep link URL (https://abtwallet.io/i/...) that the DID Wallet understands. - Signing Final Responses (
signResponse): Creates a simple signed message to inform the wallet of the final outcome (e.g., success or error).
WalletHandlers#
The createHandlers function generates a set of middleware handlers for an Express.js-style server. These handlers manage the state and lifecycle of an authentication session.
Key handlers include:
generateSession: Initiates the authentication flow by creating a unique session token.checkSession: An endpoint for your web client to poll and check the current status of the session.onAuthRequest: Listens for the DID Wallet to connect and request the claims for a specific session.onAuthResponse: Receives the signed claims from the wallet after the user has taken action (e.g., approved or declined the request).
Session Lifecycle#
A DID Connect session proceeds through several states, tracked in your tokenStorage backend. Your client-side application polls the checkSession endpoint to get the current status and react accordingly.
Status | Description |
|---|---|
| The session has been created and is waiting for a wallet to scan the QR code. |
| A DID Wallet has scanned the QR code and is about to process the claims. |
| The user has approved all requested claims and the authentication is complete. |
| An error occurred, or the user declined the request. |
| The user's wallet is busy with another DID Connect request. |
| The DID that connected does not match the DID required by the session. |
Now that you understand the basic components and their roles, you can explore the specific stages of the authentication process in more detail.
- Authentication Flow: A step-by-step breakdown of the entire communication sequence.
- Understanding Claims: An in-depth look at the different types of information and actions you can request from a user.
- Encryption and Security: Learn how to establish a secure channel for exchanging sensitive data.
Ready to dive deeper? Start with the Authentication Flow.