Design Goals

TODO: This section needs further development and refinement.

Architecture Overview

TODO: This section needs further development and refinement.

Why DID fits Agent Identity

Decentralized Identifiers (DIDs) provide a standards-based, verifiable identity primitive for agents to identify, authenticate, and authorize each other across heterogeneous ecosystems.

• Interoperability: The W3C DID Core data model and resolution interfaces enable cross-vendor, cross-platform interoperability. Any conforming DID method can be resolved into a DID Document that encodes verification methods and service endpoints in a uniform structure, allowing agents to communicate with minimal assumptions about the counterparty's stack.
• Decentralization: DIDs are created and controlled by their subjects and anchored by cryptographic keys, without relying on a single central registry. This reduces vendor lock-in, avoids single points of failure, and supports peer-to-peer trust establishment.

Why a Web-based DID method (did:wba)

• High security: Reuses the mature Web PKI and HTTPS. DID Documents are hosted under authenticated Web origins, benefiting from TLS, DNS ownership validation, and existing operational security practices — matching the security level of today’s websites.
• Simplicity of operations: The domain owner manages identifier lifecycle within its namespace (create, update, revoke). Peers fetch DID Documents directly via HTTP(S) (for example, did:wba:agent.example.com:alice resolves to https://agent.example.com/alice/did.json), enabling straightforward discovery without bespoke networks.
• Leverages existing Web infrastructure and scales: Builds on ubiquitous DNS, HTTP, CDNs, caching, and monitoring stacks, enabling horizontal scalability to billions of identifiers and low operational overhead.

Note: The did:wba method follows a Web-anchored resolution model aligned with existing enterprise and public Internet deployments.

Method reference: did:wba method design specification

Cross-Platform Identity Authentication Based on did:wba Method and HTTP Protocol

When a client makes a request to a service on different platforms, the client can use the domain name combined with TLS to authenticate the service. The service then verifies the identity of the client based on the verification methods in the client's DID document.

The client can include the DID and signature in the HTTP header during the first HTTP request. Without increasing the number of interactions, the service can quickly verify the identity of the client. After the initial verification is successful, the service can return a access token to the client. The client can then carry the access token in subsequent requests, and the service does not need to verify the client's identity each time, but only needs to verify the access token.

Initial Request

When the client first makes an HTTP request to the service, it needs to authenticate according to the following method.

Request Header Format

The client sends the following information through the Authorization header field to the service:

• DIDWba: Indicates the use of the did:wba protocol
• did: The did identifier of the client, used for identity verification.
• nonce: A randomly generated string used to prevent replay attacks. It must be unique for each request. We recommend using a 16-byte random string.
• timestamp: The time when the request is initiated, usually in UTC format using ISO 8601, accurate to seconds.
• verification_method: Identifies the verification method used in the signature, which is the DID fragment of the verification method in the DID document. For example, for the verification method did:wba:example.com%3A8800:user:alice#key-1, the verification method's DID fragment is key-1.
• signature: Sign the nonce, timestamp, service domain, and client DID. For ECDSA signatures, use the R|S format. It includes the following fields:
  • nonce
  • timestamp
  • service (the domain name of the service)
  • did (the DID of the client)

Client request example:

Authorization: DIDWba did="did:wba:example.com%3A8800:user:alice", nonce="abc123", timestamp="2024-12-05T12:34:56Z", verification_method="key-1", signature="base64url(signature_of_nonce_timestamp_service_did)"

Signature Generation Process

The client generates a string containing the following information:

{
  "nonce": "abc123",
  "timestamp": "2024-12-05T12:34:56Z",
  "service": "example.com",
  "did": "did:wba:example.com:user:alice"
}

1. Use JCS(JSON Canonicalization Scheme) to normalize the JSON string, generating a normalized string.
2. Use the SHA-256 algorithm to hash the normalized string, generating a hash value.
3. Use the client's private key to sign the hash value, generating a signature value signature, and encode it in URL-safe Base64.
4. Construct the Authorization header in the above format and send it to the service.

Service Verification

Verify Request Header

After receiving the client's request, the service performs the following verification:

• Verify Timestamp: Check if the timestamp in the request is within a reasonable time range. The recommended time range is 1 minute. If the timestamp is out of range, the request is considered expired, and the service returns 401 Unauthorized with a authentication challenge.
• Verify Nonce: Check if the nonce in the request has been used or exists. If the nonce has been used or exists, it is considered a replay attack, and the service returns 401 Unauthorized with a authentication challenge.
• Verify DID Permissions: Verify if the DID in the request has the permission to access the resources of the service. If not, the service returns 403 Forbidden.
• Verify Signature:
  1. Read the DID document based on the client's DID.
  2. Find the corresponding verification method in the DID document based on the verification_method in the request.
  3. Use the public key of the verification method to verify the signature in the request.
  Verification Result: If the signature verification is successful, the request passes verification; otherwise, the service returns 401 Unauthorized with a authentication challenge.

Signature Verification Process

1. Extract Information: Extract nonce, timestamp, service, did, and verification_method from the Authorization header.
2. Build Verification String: Construct a JSON string identical to the one constructed by the client:

{
  "nonce": "abc123",
  "timestamp": "2024-12-05T12:34:56Z",
  "service": "example.com",
  "did": "did:wba:example.com:user:alice"
}

3. Normalize String: Use JCS(JSON Canonicalization Scheme) to normalize the JSON string, generating a normalized string.
4. Generate Hash Value: Use the SHA-256 algorithm to hash the normalized string, generating a hash value.
5. Get Public Key: Obtain the corresponding public key from the DID document based on did and verification_method.
6. Verify Signature: Use the obtained public key to verify the signature, ensuring that it is generated by the corresponding private key.

Authentication Success Return Access Token

After the service successfully verifies the client's identity, it can return a access token in the response. The access token is recommended to be in JWT (JSON Web Token) format. The client can then carry the access token in subsequent requests, and the service does not need to verify the client's identity each time, but only needs to verify the access token.

The following generation process is not required by the specification, but is provided for reference. Implementers can define and implement it as needed.

JWT generation method reference RFC7519.

Generate Access Token

Assuming the service uses JWT (JSON Web Token) as the access token format, JWT typically contains the following fields:

• header: Specifies the signing algorithm
• payload: Stores user-related information
• signature: Signs the header and payload to ensure their integrity

The payload can include the following fields (other fields can be added as needed):

{
  "sub": "did:wba:example.com:user:alice",  // User DID 
  "iat": "2024-12-05T12:34:56Z",            // Issued time
  "exp": "2024-12-06T12:34:56Z",            // Expiration time
}

Implementers can add other security measures in the payload, such as using scope or binding IP addresses.

Return Access Token The generated header, payload, and signature are concatenated and URL-safe Base64 encoded to form the final access token. Then, the access token is returned through the Authorization header:

Authorization: Bearer <access_token>

Client Send Access Token The client sends the access token through the Authorization header field to the service:

Authorization: Bearer <access_token>

Service Verify Access Token After receiving the client's request, the service extracts the access token from the Authorization header and verifies it, including verifying the signature, verifying the expiration time, and verifying the fields in the payload. The verification method is based on RFC7519.

Error Handling

401 Response

When the server fails to verify the signature and requires the client to reinitiate the request, it should return a 401 response.

Additionally, if the server doesn't support recording client request Nonces, or requires clients to always use server-generated Nonces for signing, it may return a 401 response with an authentication challenge containing a Nonce for each initial client request. However, this increases the number of client requests, and implementers can choose whether to use this approach.

Error information is returned through the WWW-Authenticate header field, for example:

WWW-Authenticate: Bearer error="invalid_nonce", error_description="Nonce has already been used. Please provide a new nonce.", nonce="xyz987"

Contains the following fields:

• error: Required field, error type, containing the following string values:
  • invalid_request: Request format error, missing required fields, or contains unsupported parameters.
  • invalid_nonce: Nonce has already been used.
  • invalid_timestamp: Timestamp is out of range.
  • invalid_did: DID format error, or unable to find corresponding DID document.
  • invalid_signature: Signature verification failed.
  • invalid_verification_method: Unable to find corresponding public key based on verification method.
  • invalid_access_token: Access token verification failed.
  • forbidden_did: DID lacks permission to access server resources.
• error_description: Optional field, error description.
• nonce: Optional field, server-generated random string. If present, the client must use this Nonce to regenerate the signature and reinitiate the request.

When the client receives a 401 response, if the response contains a Nonce, the client must use the server's Nonce to regenerate the signature and reinitiate the request. If the response doesn't contain a Nonce, the client must use a client-generated Nonce to regenerate the signature and reinitiate the request.

It's important to note that both client and server implementations should limit the number of retry attempts to prevent infinite loops.

403 Response

When server authentication succeeds but the DID lacks permission to access server resources, a 403 response should be returned.