A Well-Known DID Configuration is a W3C-standardized mechanism that cryptographically proves control of a web domain (e.g., example.com) by associating it with one or more Decentralized Identifiers (DIDs). It works by placing a specific JSON file, did-configuration.json, in the domain's /.well-known/ directory. This file contains signed Verifiable Credentials that bind the domain to a DID, allowing services to verify that the entity controlling the DID also controls the domain. This process, often called domain linkage, is foundational for establishing trust across decentralized systems without centralized authorities.
LABS
Glossary
Well-Known DID Configuration
A W3C standard for linking a domain name to a Decentralized Identifier (DID) by hosting a specific JSON file in the `.well-known` directory of the domain's web server.
Chainscore © 2026
definition
DECENTRALIZED IDENTITY STANDARD
What is Well-Known DID Configuration?
A standardized method for linking a web domain to a Decentralized Identifier (DID), enabling verifiable control and trust.
The configuration file's core component is a Domain Linkage Credential, a type of Verifiable Credential where the issuer and subject are the same DID. This credential is signed with the private key of the DID's cryptographic method (e.g., a key in its DID Document). A verifier, such as another website or an identity wallet, can fetch this file from the well-known URI, verify the credential's signature against the published DID Document, and confirm the domain-DID binding. This creates a bi-directional link, proving the DID controller can publish to the domain and that the domain can vouch for the DID.
This standard is critical for several key use cases in decentralized identity. It enables Sign-In with Ethereum (SIWE) and other blockchain-based logins by allowing a relying party to verify a user controls both a crypto wallet (via its DID) and a traditional web domain. It also underpins verifiable organizational profiles, where a company can prove it controls its official website and its associated credential-issuing DID. Furthermore, it prevents phishing and impersonation in decentralized ecosystems by providing a cryptographically verifiable link between a human-readable domain and a machine-readable DID.
Implementing a Well-Known DID Configuration involves a few precise steps. First, the domain controller generates the configuration JSON, which includes a JWT-formatted Verifiable Credential signed with their DID's key. This file is then hosted at https://example.com/.well-known/did-configuration.json. The origins field within the credential must explicitly list the domain. For verification, a client performs an HTTP GET request to this endpoint, resolves the DID listed in the credential to obtain its public key, and validates the JWT signature, thereby establishing the proof-of-control linkage.
how-it-works
DECENTRALIZED IDENTITY PROTOCOL
How Well-Known DID Configuration Works
Well-Known DID Configuration is a W3C-specified mechanism for linking a web domain to a Decentralized Identifier (DID) to establish cryptographically verifiable ownership and trust.
A Well-Known DID Configuration is a standardized method for a domain owner to prove control over a Decentralized Identifier (DID) by hosting a specific JSON file at a predictable URL: /.well-known/did-configuration.json. This file contains a signed domain linkage credential, often a Verifiable Credential (VC), that cryptographically binds the domain to the DID's public key. This process enables services to perform domain verification by fetching and validating this file, establishing that the entity controlling the DID also controls the domain's DNS records. It is a core component of the Decentralized Identity Foundation (DIF)'s Identity Hubs and the W3C DID Configuration specification.
The configuration file's primary component is the linked_dids array, which contains one or more Domain Linkage Credentials. Each credential includes the target DID, an expiration timestamp, and a JSON Web Signature (JWS) created with the private key corresponding to the DID. A verifier, such as a relying party or an identity wallet, retrieves this file via HTTPS, validates the JWS against the DID's public key in its DID Document, and confirms the credential's origin field matches the domain from which it was fetched. This creates a bidirectional trust bridge between the traditional web domain system and the decentralized identity ecosystem.
This mechanism is crucial for enabling Sign in with DID flows and verifiable website authentication. For example, a company can configure its corporate domain to link to an organizational DID, allowing users to log in using DID-based authentication with the assurance they are interacting with the legitimate domain owner. It also prevents phishing and impersonation by allowing clients to cryptographically verify a site's claimed identity. The protocol supports multiple DIDs per domain for redundancy and key rotation, and the well-known location ensures discoverability without requiring custom API endpoints or complex metadata negotiations.
key-features
DECENTRALIZED IDENTIFIER STANDARD
Key Features of Well-Known DID Configuration
The Well-Known DID Configuration is a W3C standard that allows a domain to cryptographically assert control over a Decentralized Identifier (DID), enabling secure, verifiable identity on the web.
01
Standardized Discovery Endpoint
The configuration is served from a predictable location on a web domain: /.well-known/did-configuration.json. This standardized path allows identity verifiers and relying parties to automatically discover and fetch the DID-linked credentials without prior knowledge of the specific DID in use.
02
Cryptographic Proof of Domain Control
The core mechanism proves the domain owner controls the DID. This is achieved by signing a domain linkage credential (a Verifiable Credential) with the private key of the DID. The verifier checks the signature against the DID's public key in its DID Document, creating a trusted link between the HTTPS domain and the decentralized identifier.
03
Verifiable Credentials Format
The configuration file contains one or more Domain Linkage Credentials. These are W3C Verifiable Credentials with a specific structure:
issuer: The DID claiming control.credentialSubject: Contains the domain name and a unique ID.proof: A cryptographic signature (e.g., Ed25519Signature2020, JsonWebSignature2020) proving the DID's controller authorized the linkage.
04
Decentralized Identifier (DID) Binding
It creates a bidirectional binding between a traditional web domain (e.g., example.com) and a decentralized identifier (e.g., did:key:z6Mk...). This allows services to trust that an entity presenting a credential from did:key:z6Mk... is the same entity that controls https://example.com, enabling use cases like sign-in with DID and verified organizational credentials.
05
Primary Use Case: Sign-In with DID (SIWD)
A major application is replacing centralized social logins (e.g., "Sign in with Google"). A website can implement Sign-In with DID by checking the well-known configuration of a user-provided domain. If the user's DID is linked to that domain, the site can authenticate them without relying on a third-party identity provider, enhancing privacy and user control.
06
Interoperability & Verifier Workflow
The specification ensures interoperability across different DID methods (e.g., did:web, did:key, did:ethr). A verifier's workflow is standardized:
- Extract a domain from a user's request.
- Fetch
/.well-known/did-configuration.json. - Validate the signatures in the credentials against the referenced DIDs.
- Confirm the domain in the credential matches the requested domain. This allows consistent verification across the ecosystem.
etymology-and-standard
DEFINING THE PROTOCOL
Etymology and Standardization
The term 'Well-Known DID Configuration' is a compound technical specification name that follows established web standards for discoverable metadata.
The etymology of 'Well-Known DID Configuration' is a direct combination of two distinct web concepts. The 'well-known' prefix follows the Internet Engineering Task Force (IETF) convention defined in RFC 8615, which reserves the /.well-known/ URI path segment for site-wide metadata, such as security policies (security.txt) or node information. 'DID Configuration' refers to the specific payload—a cryptographically verifiable link between a domain and a Decentralized Identifier (DID). The full term thus denotes a standardized location and format for publishing this linkage.
The standardization of this mechanism is primarily governed by the Decentralized Identity Foundation (DIF) through the DID Configuration Resource specification. This spec defines the exact JSON structure, which must contain one or more DID Configuration Resources—objects that include a DID, a proof of control (typically a Verifiable Credential), and an expiration timestamp. Standardization ensures interoperability, allowing any compliant Identity Wallet or Verifier to discover and validate the binding between a website and a decentralized identity, regardless of the underlying blockchain or DID method.
The protocol's design elegantly solves the domain ownership verification problem in a decentralized context. By placing a signed resource at a predictable location (https://example.com/.well-known/did-configuration.json), it allows a domain operator to prove control over a DID without relying on a centralized certificate authority. This is a critical building block for DID-based authentication flows, enabling use cases like 'Sign in with your Domain' or verifying organizational credentials. The standardized format prevents fragmentation and allows the ecosystem to build universal tooling for discovery and validation.
primary-use-cases
WELL-KNOWN DID CONFIGURATION
Primary Use Cases and Examples
The Well-Known DID Configuration is a W3C standard for linking a domain name to a DID document, enabling secure, verifiable identity assertions for websites and services.
01
Domain Ownership Verification
The primary use case is to cryptographically prove control of a domain. By hosting a /.well-known/did-configuration.json file, a domain owner can link their DID to their web presence. This prevents impersonation and is a foundational step for domain-based verifiable credentials.
- Mechanism: The file contains a JWT signed by the domain's DID.
- Verification: A verifier fetches this file and checks the signature against the published DID Document.
02
Sign-In with Ethereum (SIWE)
A prominent implementation where users sign in to web3 applications using their Ethereum wallet. SIWE uses the Well-Known DID Configuration to allow a service (e.g., a dApp) to verify that the user controls both the Ethereum address (their DID) and the domain hosting the service.
- Flow: The dApp's domain hosts the configuration file.
- Result: Users get a seamless, phishing-resistant login without passwords.
03
Decentralized Website Authentication
Enables websites to present verifiable authentication states without centralized identity providers. A company's official website can host a DID Configuration to prove its corporate identity, allowing partners and users to cryptographically verify they are interacting with the legitimate site.
- Example: A DAO's official forum uses this to verify membership badges issued by the DAO's DID.
04
Credential Issuer Discovery
Acts as a discovery endpoint for Verifiable Credential issuers. A university's domain (university.edu) can host a DID Configuration pointing to its official issuer DID. This allows students and third parties to automatically discover and trust credentials (like diplomas) issued by that domain's authoritative DID.
- Key Benefit: Establishes a trusted root of trust tied to a recognizable web domain.
05
Interoperability with Existing Web Infrastructure
Leverages the existing DNS and HTTPS trust model to bootstrap decentralized identity. By using the standardized /.well-known URI path, it integrates seamlessly with current web servers and security policies (CORS, HTTPS).
- Advantage: No new infrastructure is needed; it works with standard web hosting.
06
Preventing Phishing & Brand Impersonation
Provides a cryptographic defense against fake websites. A bank can publish its DID Configuration. Browser extensions or wallet software can then warn users if they are on a site that lacks the correct configuration or presents an invalid one, directly combating phishing attacks that clone web interfaces.
security-considerations
WELL-KNOWN DID CONFIGURATION
Security Considerations and Best Practices
A Well-Known DID Configuration is a standardized method for linking a domain name to a Decentralized Identifier (DID) using a /.well-known/did-configuration.json resource. This section details the critical security practices for its implementation and validation.
01
Origin Binding & TLS Validation
The primary security function is origin binding, which cryptographically links a DID to a specific web domain. This prevents phishing attacks by ensuring a user's credential issuer matches the expected website. The configuration must be served over HTTPS (TLS 1.2+) from the exact domain specified in the DID document's alsoKnownAs or service endpoint. Browsers and validators will reject configurations served over HTTP or from mismatched origins.
02
JWT Proof Integrity
The linkage is proven via a JSON Web Token (JWT) embedded in the configuration. Critical checks include:
- Signature Verification: The JWT must be signed by the private key of the DID it references.
- Claim Validation: The JWT payload must contain the correct
iss(issuer DID),domain(the serving domain), and a validexp(expiration) timestamp. - Algorithm Security: Only secure, asymmetric signing algorithms (e.g., EdDSA, ES256K, RS256) should be used. Symmetric algorithms or
noneare prohibited.
03
Cache & Expiration Management
The exp claim in the JWT proof is crucial for security. Best practices include:
- Setting a short expiration (e.g., hours or days) to limit the impact of a compromised domain or private key.
- Implementing a key rotation strategy that generates new configuration JWTs before old ones expire.
- Clients and verifiers must respect the expiration and not cache valid configurations beyond their
exptime. Stale configurations can lead to false trust assertions.
04
DID Document & Service Endpoint Consistency
The linked DID Document must be publicly resolvable and contain a service endpoint or an alsoKnownAs property that matches the domain hosting the configuration. This creates a bidirectional trust chain. Auditors should verify:
- The DID's service endpoint URL's host matches the configuration domain.
- The DID's verification method used to sign the JWT is active and not revoked.
- There is no conflict or ambiguity with multiple DIDs claiming the same domain.
05
Implementation & Deployment Hardening
Secure deployment mitigates common attack vectors:
- File Location: Strictly use the path
/.well-known/did-configuration.json. Avoid redirects. - Content-Type Header: Serve the file with the correct
application/jsonMIME type. - Access Control: Ensure the
.well-knowndirectory is accessible but not writable by unauthorized processes. - Monitoring: Log access attempts and monitor for unexpected changes to the configuration file, which could indicate a takeover attempt.
06
Verifier-Side Validation Checklist
Entities verifying a Well-Known DID Configuration must perform a comprehensive check:
- Fetch: Retrieve the file from the correct HTTPS origin.
- Parse: Validate JSON structure and JWT format.
- Resolve: Fetch the DID Document referenced by the JWT's
issclaim. - Verify Proof: Cryptographically verify the JWT signature using a verification method from the resolved DID Document.
- Validate Claims: Confirm
domainmatches the origin andexpis in the future. - Check Consistency: Ensure the DID Document references the same domain. Missing any step breaks the trust chain.
METHODOLOGY
Comparison with Other Domain-to-DID Linking Methods
A technical comparison of the Well-Known DID Configuration specification against alternative methods for establishing a secure, verifiable link between a domain name and a Decentralized Identifier (DID).
| Feature / Characteristic | Well-Known DID Configuration | DNS TXT Records | Centralized API Endpoint |
|---|---|---|---|
Standardization | W3C DID Configuration Draft Community Group Report | Ad-hoc, implementation-specific | Proprietary, service-specific |
Verification Path | Cryptographic proof via signed JWT in /.well-known/did-configuration.json | Text string match in DNS record | Trust in API provider's response and TLS |
Crawlability & Discovery | Publicly accessible via HTTP(S) GET | Requires DNS query | Requires prior knowledge of API URL |
Decentralization | |||
Client-Side Verification | |||
Supports DID Rotation | |||
Typical Setup Complexity | Medium (file generation & hosting) | Low (DNS management console) | Low (depends on provider) |
Caching & Performance | Leverages HTTP caching headers | Subject to DNS TTL (minutes/hours) | Subject to API rate limits & latency |
WELL-KNOWN DID CONFIGURATION
Frequently Asked Questions (FAQ)
A Well-Known DID Configuration is a standardized method for linking a domain name to a Decentralized Identifier (DID) and its associated DID Document, enabling verifiable control and trust. This section answers common questions about its purpose, implementation, and verification.
A Well-Known DID Configuration is a JSON file placed at a specific, predictable URL on a web domain (typically /.well-known/did-configuration.json) that cryptographically links the domain to one or more Decentralized Identifiers (DIDs). It works by containing a signed JWT (JSON Web Token) that proves the controller of the DID also controls the domain, enabling services to verify this relationship without relying on a central authority. This mechanism is defined by the W3C DID Configuration specification and is a core component of Decentralized Identity systems, allowing domains to make verifiable claims about their identity.
ENQUIRY
Get In Touch
today.
Our experts will offer a free quote and a 30min call to discuss your project.
NDA Protected
Confidentiality24h Response
Time to ValueDirectly to Engineering Team
No Sales Fluff10+
Protocols Shipped
$20M+
TVL Overall