Skip to main content
Version: 1.2

Domain Linkage

info

To use Domain Linkage in Rust you have to enable the domain-linkage feature.

Overview​

Domain Linkage can provide proof for a connection between a DID and a domain being controlled by the same entity. This linkage can transfer trust from a domain to a DID and vice versa. For instance, if an entity trusts a domain, it can also trust the linked DID and all documents signed by the verification methods included in the DID Document.

A use case could be a verifier that trusts www.example.com, and receives a verifiable presentation issued by did:foo:abc. If did:foo:abc is linked to www.example.com, the verifier can trust that the verifiable presentation is issued by the same entity controlling www.example.com. The DIF has approved a Well Known DID Configuration draft to standardize this connection by introducing the DID Configuration Resource and the Linked Domain Service Endpoint.

Identity getting started

DID Configuration Resource​

Suppose that a DID did:foo:example with the following DID Document only contains one verificationMethod, key-1:

{
    "id": "did:foo:abc",
    "verificationMethod": [
      {
        "id": "did:foo:abc#key-1",
        "controller": "did:foo:abc",
        "type": "Ed25519VerificationKey2018",
        "publicKeyMultibase": "zDShpHKXkcHKHcF8CnGAA1UqyyuEPRNz1XFEuggbWJQSq"
      }
    ]
  },

The domain https://www.example.com represents the same entity and needs to be linked to increase trust in the DID.

To establish this link, you must create a DID Configuration Resource, and make it available on the DID Configuration URL. In this case it's https://example.com/.well-known/did-configuration.json.

The DID Configuration Resource is a JSON-LD object containing verifiable credentials called Domain Linkage Credentials. Each credential represents a linkage to a single DID.

note

Note that one DID Configuration Resource can include multiple Domain Linkage Credentials, effectively linking the same domain to multiple DIDs.

In this example, the domain https://www.example.com needs to be linked to the DID did:foo:abc. This means that the DID Configuration Resource will have one Domain Linkage Credential. This credential must have the following properties:

  • Its type includes DomainLinkageCredential.
  • It includes the DID Configuration context.
  • The credentialSubject must be the DID did:foo:abc and references the domain https://www.example.com.
  • The issuer is the DID itself did:foo:abc.
  • It is signed by a key material included in the DID Document, in this case did:foo:abc#key-1.
{
  "@context": "https://identity.foundation/.well-known/did-configuration/v1",
  "linked_dids": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://identity.foundation/.well-known/did-configuration/v1"
      ],
      "type": ["VerifiableCredential", "DomainLinkageCredential"],
      "credentialSubject": {
        "id": "did:foo:abc",
        "origin": "https://www.example.com/"
      },
      "issuer": "did:foo:abc",
      "issuanceDate": "2023-02-09T22:14:15Z",
      "expirationDate": "2024-02-09T22:14:15Z",
      "proof": {
        "type": "JcsEd25519Signature2020",
        "verificationMethod": "did:foo:abc#key-1",
        "signatureValue": "4SvYqo3YoArfW7r7qKfN7RUJdZnBteb166KE4UkX8MNdbp5UW6YbykneAzvjyRmf5EVQ9bnP9cS5sbEPUn2uaAcB"
      }
    }
  ]
}

Now this DID Configuration Resource must be made available on https://example.com/.well-known/did-configuration.json, which establishes the linkage.

Linked Domain Service Endpoint​

By having a domain, one can discover what DIDs are linked to it by fetching the DID Configuration Resource and investigating the Domain Linkage Credentials.

If you want to enable discovery from the other direction, that is, if you have a DID and want to discover which domains are linked to it, you can add a Linked Domain Service Endpoint to the DID Document. The DID Document from this example will be extended as follows to enable discovery of https://www.example.com:

{
  "id": "did:foo:abc",
  "verificationMethod": [
    {
      "id": "did:foo:abc#key-1",
      "controller": "did:foo:abc",
      "type": "Ed25519VerificationKey2018",
      "publicKeyMultibase": "zDShpHKXkcHKHcF8CnGAA1UqyyuEPRNz1XFEuggbWJQSq"
    }
  ],
  "service": [
    {
      "id": "did:foo:abc#domain-linkage",
      "type": "LinkedDomains",
      "serviceEndpoint": "https://www.example.com/"
    }
  ]
}
note

Note that a DID Document can have multiple Linked Domain Services and each service can link to multiple domains.

Verifying a DID and Domain Linkage​

As mentioned above, you can discover the Domain Linkage from either direction. However, verifying the linkage in both cases involves only verifying the DID Configuration Resource. The process is as follows:

  1. Fetch DID Configuration Resource from https://www.example.com/.well-known/did-configuration.json.
  2. Resolve the DID Document of did:foo:abc.
  3. Verify the DID Configuration Resource and its Domain Linkage Credential that references did:foo:abc.
About DID Configuration Resource Verification

You can learn more about DID Configuration Resource Verification on the Identity Foundation website.

Example Code​

examples/1_advanced/6_domain_linkage.rs
loading...