Overview
The did-auth library provides a complete solution for integrating decentralized identity (DID) authentication into your applications. It enables secure, passwordless login flows where users prove their identity by using a DID Wallet, eliminating the risks associated with traditional password-based systems.
This library is built around two core components that work together to manage the authentication process: WalletAuthenticator and WalletHandlers.
Core Components#
- WalletAuthenticator: This class is the cryptographic engine of the library. It is responsible for creating, signing, and verifying the messages exchanged between your application and the user's DID Wallet. It handles the construction of authentication requests (claims) and the validation of the wallet's responses.
- WalletHandlers: This class provides a set of handlers designed to be attached to an Express.js application. It manages the entire authentication lifecycle, including generating unique session tokens, providing endpoints for the wallet to fetch authentication challenges, and handling the final response from the user's wallet.
How it Works#
A typical DID authentication flow involves the user's browser, your application backend, and the user's DID Wallet. The process enables the user to securely log in by simply scanning a QR code and approving the request in their wallet.
Key Features#
- Passwordless Login: Replace vulnerable passwords with secure, public-key cryptography.
- Standardized Claims: Request specific information from users, such as a profile, a signature for a transaction, or a verifiable credential, using a standardized schema.
- Express.js Integration: Quickly add DID authentication to your Node.js application with pre-built Express.js middleware.
- Secure Communication Channel: Establish an encrypted channel between the application and the wallet to protect sensitive data.
Example: Basic Setup#
Here is a minimal example of how to initialize WalletAuthenticator and WalletHandlers in your application.
const { WalletAuthenticator, WalletHandlers } = require('@did-connect/auth');
const { fromRandom } = require('@ocap/wallet');
// 1. Configure the application's wallet (authenticator)
const wallet = fromRandom().toJSON();
const authenticator = new WalletAuthenticator({
wallet,
appInfo: {
name: 'My Awesome App',
description: 'This is a demo app for DID Auth',
icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
link: 'http://localhost:3000',
},
});
// 2. Configure handlers to manage the authentication flow
const handlers = new WalletHandlers({
authenticator,
tokenStorage: new Map(), // Use a simple Map for token storage in this example
});
// Now you can attach these handlers to your Express app routes.
// app.use('/api/did', handlers.attach(...));This setup provides the foundation for building robust, decentralized authentication. To see how to put it all together, proceed to the next section.
Next, let's walk through a complete, step-by-step setup in the Getting Started guide.