Auth Principal Claim
The authPrincipal claim is the most fundamental request in a DID Connect session. Its primary purpose is to ask the user to connect their DID Wallet and select a decentralized identity (DID) to interact with your application. This action establishes a secure session and provides the application with the user's chosen DID, which can then be used for authentication, authorization, or as a reference for subsequent requests.
This claim is often the first step in any user interaction, serving as the entry point for simple logins or more complex, multi-step workflows. For a visual overview of the entire process, see The DID Connect Workflow.
When to Use#
- User Login: Use it as a passwordless login mechanism. When the user successfully responds, you can create a session for them based on their DID.
- Session Establishment: Use it to simply establish a connection before requesting more specific information like a Profile Claim or a Verifiable Credential Claim.
- App-Specific Identities: By setting the
supervisedflag totrue, you can prompt the user to create a new, temporary identity specifically for your application, enhancing privacy and compartmentalization.
Parameters#
The authPrincipal claim can be configured with the following parameters:
Parameter | Type | Description |
|---|---|---|
|
| Required. A message displayed to the user in their wallet, explaining why they need to connect. E.g., "Connect your wallet to sign in." |
|
| Optional. A specific DID that you suggest the user select. The wallet may pre-fill this DID if it exists. Defaults to an empty string. |
|
| Optional. If |
|
| Optional. An object specifying the desired cryptographic properties for the DID, which is useful when |
Example: Simple Wallet Connection#
Here is a basic example of how to configure a DID Connect handler that only asks the user to connect their wallet. This is the simplest way to get a user's DID.
module.exports = {
action: 'connect-only',
authPrincipal: false, // Not a standard field, specific to playground setup
claims: {
authPrincipal: {
description: 'Connect your DID Wallet to continue',
// Setting supervised to true encourages the creation of a new,
// app-specific identity for enhanced privacy.
supervised: true,
},
},
onAuth: async ({ userDid }) => {
// The user's DID is available here after they approve the request.
// You can now create a session, look up the user in your database, etc.
console.log(`User ${userDid} has connected.`);
return { successMessage: `You are connected ${userDid}` };
},
};In this example, upon scanning the QR code, the user's wallet will display the message "Connect your DID Wallet to continue" and suggest creating a new supervised account for the session because supervised is set to true.
Interaction Flow#
The authPrincipal claim initiates a straightforward sequence of events between the user, your application, and their DID Wallet.
After the application verifies the wallet's response, the onAuth callback is triggered, providing the userDid for your application to use.
With the user's DID obtained, you can proceed to more specific interactions. A common next step is to request user information using the Profile Claim.