Domain Linkage: How DIDs Connect Business Identity to the Web

This is KChain Solutions' Decentralized Identifier on the IOTA ledger:

did:iota:0x75f27f2ba95321451a0cf443d5e91cb48cc965e903b10dbf8e0a27a38d45260f

Look at it. It is a hexadecimal string. Nothing in this identifier tells you it belongs to KChain Solutions or to any real business at all. A supply chain partner who receives a Verifiable Credential signed by this DID has no way to know who is behind it. Anyone can create a DID and claim to be any company.

Domain Linkage solves this problem. It creates a cryptographically verifiable connection between a DID and a web domain that the business already controls. If kchain.solutions and this DID are linked with bidirectional proof, a verifier can confirm: the same entity controls both.

In this article, I walk through what Domain Linkage is, how it works in practice, and two real deployment examples: KChain Solutions (hosted via Impierce's UniTrust infrastructure) and the IOTA DPP Demonstrator (self-managed). I also cover how Domain Linkage relates to other Know Your Business protocols like GLEIF's vLEI.

Quick Primer: What Is a DID?

A DID (Decentralized Identifier) is a W3C standard that defines a globally unique identifier an organization creates and controls without relying on a central registry.

What gets published on the blockchain is the DID Document: a small JSON structure containing the entity's public keys and service endpoints. These public keys are what verifiers use to check that a Verifiable Credential was actually signed by that DID.

The private keys used for signing never leave the owner's control. They can be stored on a private server, in a hardware security module, or in a dedicated Key Management System (KMS).

The separation is fundamental: the blockchain holds the public verification material, while the entity retains exclusive control of the signing keys. You can inspect KChain Solutions' DID on the IOTA explorer to see the on-chain object, or resolve it through the Universal Resolver to see the full DID Document with its two public keys (ES256 and EdDSA) and the service endpoints.

What Is Domain Linkage?

Domain Linkage is a DIF (Decentralized Identity Foundation) specification that creates a bidirectional, cryptographically verifiable association between a web domain and a DID.

The concept is straightforward. A business controls two things: a web domain (e.g., kchain.solutions) and a DID on a blockchain. Domain Linkage binds these together so anyone can verify that the same entity controls both.

The technical mechanism uses a standard web path: /.well-known/did-configuration.json. This file, hosted on the business's domain, contains one or more Domain Linkage Credentials. Each credential is a Verifiable Credential of type DomainLinkageCredential, signed by the DID's private key, that states: "This DID controls this domain."

On the other side, the DID Document on the blockchain includes a LinkedDomainService endpoint that points back to the domain. This creates the bidirectional proof: a verifier can start from the DID and check the domain, or start from the domain and verify the DID on-chain. Both directions must validate.

This bidirectional requirement is what makes it tamper-resistant. If someone creates a fake DID claiming to be KChain, they cannot produce a valid JWT hosted at kchain.solutions (they do not control the web server). If someone compromises the domain, they cannot forge the DID's on-chain signature (they do not have the private key).

graph LR
    DID["DID (On-Chain)<br/>Public Key + LinkedDomain"]
    DOMAIN["Domain (Web Server)<br/>JWT Credential signed by DID"]

    DID -- "Verify JWT signature" --> DOMAIN
    DOMAIN -- "Verify DID on-chain" --> DID

Why Does Domain Linkage Matter for Business?

Without Domain Linkage, every Verifiable Credential your organization issues is signed by an anonymous key pair. Your supply chain partners receive a credential from did:iota:0x75f27... and have no automated way to confirm it came from your company. They must rely on out-of-band verification: phone calls, emails, manual checks.

Domain Linkage eliminates this friction. Three specific business outcomes:

1. Partner onboarding becomes faster. A new supply chain partner can verify your identity in seconds by resolving your DID and checking the domain linkage. No manual due diligence on the identity layer.
2. Credential fraud risk drops. An attacker who clones your DID cannot replicate the domain linkage. The forged credential fails verification automatically.
3. Compliance audits get simpler. Regulations like the EU's ESPR (Digital Product Passports) require traceability of who issued product data. Domain Linkage provides a verifiable, auditable chain from credential to issuing organization.

How Does KChain Solutions Use Domain Linkage?

KChain Solutions has an active Domain Linkage configuration, live and verifiable right now. You can inspect it at:

https://identity.kchain.solutions/.well-known/did-configuration.json

This configuration contains four JWTs covering two DIDs and two signature algorithms:

Each JWT is a DomainLinkageCredential that binds the DID to the origin https://identity.kchain.solutions/.

The Hosted Approach (CNAME + UniTrust)

KChain's Domain Linkage is hosted through Impierce's UniTrust platform. The setup required two steps:

1. Add a CNAME record in KChain's DNS configuration, pointing identity.kchain.solutions to Impierce's infrastructure
2. Configure the DIDs and credentials through UniTrust's management interface

This approach trades some control for simplicity. KChain does not manage the DID key material directly or host the did-configuration.json file on its own servers. Impierce's infrastructure handles credential generation, key management, and hosting. The business only needs to add one DNS record.

When to use this approach:

• You want domain linkage without running identity infrastructure
• You prefer a managed service for key management and credential rotation
• Speed of deployment matters more than granular control

How Does the IOTA DPP Demonstrator Deploy Domain Linkage?

The IOTA DPP Demonstrator takes a different approach. The Domain Linkage Credential is generated directly by the application and served from the webapp itself.

You can inspect it at: https://dpp.demo.iota.org/.well-known/did-configuration.json

This configuration contains a single JWT:

The Self-Managed Approach (Code-Generated Credentials)

The DPP Demonstrator generates its own DID and Domain Linkage Credential during the application's setup phase. The backend (backend/src/lib/identity.rs) handles the full lifecycle.

If you are not a developer, you can skip the code block below. The key takeaway: the application creates a DID, links it to its domain, and publishes the result to the IOTA ledger. All of this happens programmatically, without manual steps.

// Create DID document with LinkedDomainService
let mut did_document = IotaDocument::new(identity_client.network());
did_document.generate_method(
    &keytool_storage,
    KeyType::new("secp256r1"),
    JwsAlgorithm::ES256,
    None,
    MethodScope::VerificationMethod,
).await?;

// Link the DID to the application's domain
let domain_url = Url::parse(&std::env::var("NEXT_PUBLIC_DAPP_URL")?)?;
let mut domains = OrderedSet::new();
domains.append(domain_url);

let service_url = did_document.id().clone().join("#domain-linkage")?;
let linked_domain_service = LinkedDomainService::new(
    service_url, domains, Object::new()
)?;
did_document.insert_service(linked_domain_service.into())?;

// Publish to IOTA ledger
let did_document = identity_client
    .publish_did_document(did_document)
    .build_and_execute(&identity_client)
    .await?
    .output;

The application then signs a DomainLinkageCredential as a JWT and serves it at its /.well-known/did-configuration.json endpoint. No external service involved.

When to use this approach:

• You need full control over key material and credential lifecycle
• Your application already manages its own identity infrastructure
• You want to generate, rotate, or revoke credentials programmatically
• You are building a reference implementation or developer-facing product

Hosted vs. Self-Managed: Which One to Choose?

Both approaches produce the same verifiable result. A verifier fetching /.well-known/did-configuration.json cannot tell the difference. The choice depends on whether your organization wants to manage identity infrastructure or delegate it.

How Does IOTA Identity Simplify Domain Linkage?

You do not need to implement JWT signing, credential assembly, or verification logic from scratch. IOTA Identity provides dedicated types in both TypeScript (@iota/identity-wasm) and Rust (identity_iota) that handle the full Domain Linkage lifecycle: creating the service endpoint, building the credential, assembling the did-configuration.json resource, and verifying the linkage in both directions.

The IOTA Identity repository contains working examples in both languages. The official documentation walks through the create-and-verify flow step by step. Your code handles the business logic: which domains to link, which DIDs to use, and how to serve the configuration file. IOTA Identity handles the cryptography.

What If Domain Linkage Is Not an Option?

Domain Linkage requires the business to modify its DNS configuration or host a file on its web server. In practice, not every organization will agree to this.

Consider a realistic scenario. You are a startup building a supply chain credentialing platform. You need to onboard a large institution (a bank, a government agency, a multinational manufacturer) as a trust anchor in your ecosystem. The institution's IT department is reluctant to add a CNAME record or host a did-configuration.json file on their production domain. Their security review process takes six months. Their legal team wants to understand the liability implications of linking a DID to their corporate domain.

You do not have six months. You need to launch.

IOTA Hierarchies provides an alternative path. Instead of proving identity through a domain, the institution's DID is added to a trusted federation on-chain. The federation's root authority (which does have Domain Linkage) accredits the institution's DID and assigns attributes that identify the legal entity: a business registration number, a LEI code, a tax identifier, or any other property that maps to the institution's real-world identity.

The verification flow changes. Instead of checking /.well-known/did-configuration.json on the institution's domain, a verifier queries the federation: "Is this DID accredited by the root authority? What attributes does it carry?" The root authority's own Domain Linkage anchors the trust chain. The institution inherits trust through the hierarchy without modifying its own infrastructure.

This is not a replacement for Domain Linkage. It is a pragmatic fallback for scenarios where the ideal solution is not feasible. The tradeoff: the institution depends on the federation for its trust anchor, rather than proving identity independently through its own domain.

For teams designing onboarding flows, the recommendation is to offer both paths. Domain Linkage for organizations willing to configure it. Federation membership via IOTA Hierarchies for those that are not. Both produce a verifiable identity, but through different trust models.

What About Other Know Your Business Protocols? GLEIF and vLEI

Domain Linkage connects a DID to a web domain. But a web domain is not a legal entity registration. For regulated industries, you may need a stronger link to a business's legal identity.

This is where GLEIF's vLEI (Verifiable Legal Entity Identifier) comes in. The vLEI is a cryptographically verifiable version of the LEI (Legal Entity Identifier), the 20-character code that uniquely identifies legal entities across global financial systems. vLEI adoption is growing in sectors where authority and authenticity are critical: regulatory reporting, secure communications, and digital identity verification.

The interesting part: vLEI and DID can interoperate. The pattern mirrors Domain Linkage's bidirectional approach:

• The vLEI points to the DID. The vLEI credential can include a reference to the entity's DID, establishing that the legal entity identified by LEI code 5493001KJTIIGC8Y1R12 also controls did:iota:0x75f27f...
• The DID points to the LEI. The DID Document can include a service endpoint or credential referencing the entity's LEI, enabling discovery from the DID side

This creates a chain of trust anchors: the web domain (via Domain Linkage) verifies control of the domain, the vLEI (via GLEIF's global infrastructure) verifies the legal entity registration, and the DID (on the IOTA ledger) ties both to an on-chain cryptographic identity.

For enterprises operating in regulated markets (DPP compliance, trade finance, financial services), this layered approach provides multiple independent verification paths. A supply chain partner can verify a manufacturer's identity through the domain, through the LEI registry, or through the blockchain. Each path is independent and cryptographically verifiable.

Frequently Asked Questions

What is Domain Linkage?

Domain Linkage is a DIF (Decentralized Identity Foundation) specification that creates a cryptographically verifiable, bidirectional connection between a web domain and a Decentralized Identifier (DID). It allows anyone to confirm that the entity controlling a domain (e.g., kchain.solutions) also controls a specific DID on a blockchain. The proof consists of a signed credential hosted at /.well-known/did-configuration.json on the domain, combined with a LinkedDomainService entry in the DID Document pointing back to the domain.

How does Domain Linkage work?

Domain Linkage works through bidirectional verification. The business hosts a DomainLinkageCredential (a JWT signed by the DID's private key) at the /.well-known/did-configuration.json path on its web domain. Simultaneously, the DID Document on the blockchain includes a LinkedDomainService endpoint pointing back to the domain. A verifier can start from either side: resolve the DID and check the domain, or fetch the domain's credential and verify it against the on-chain DID. Both directions must validate for the linkage to hold.

What is the difference between Domain Linkage and SSL certificates?

SSL certificates prove that a connection to a domain is encrypted and that the domain is registered with a certificate authority. Domain Linkage goes further: it proves that the entity controlling a web domain also controls a specific DID on a blockchain. SSL does not bind a domain to an on-chain identity. Domain Linkage creates a cryptographic bridge between the web (domain control) and the blockchain (DID control), enabling supply chain partners to verify that a Verifiable Credential was issued by a known business, not just by an anonymous key pair.

What to Do Next

Open your browser and navigate to https://yourdomain.com/.well-known/did-configuration.json. If you get a 404, every Verifiable Credential your organization issues is signed by an anonymous key pair. Your supply chain partners have no way to verify it comes from you.

Domain Linkage is a single file and a DNS record. The IOTA Identity repository contains working examples in Rust and TypeScript. Whether you choose a hosted service like UniTrust or generate credentials in your own application, the result is the same: a verifiable, bidirectional proof that your DID belongs to your business.

For teams building on the IOTA Trust Framework, Domain Linkage is the first layer to deploy for verifying a DID's real-world identity. Everything else (credential issuance, revocation, DPP compliance) builds on top of it.