Well Known DID Configuration

Making it possible to connect existing systems and Decentralized Identifiers (DIDs) is an important undertaking that can aid in bootstrapping adoption and usefulness of DIDs. One such form of connection is the ability of a DID controller to prove they are the same entity that controls an origin.

The DID Configuration resource provides proof of a bi-directional relationship between the controller of an origin and a DID via cryptographically verifiable signatures that are linked to a DID's key material. This document describes the data format of the resource and the resource location at which origin controllers can publish their DID Configuration.

Due to the location of the DID Configuration resource, discovery of associated Decentralized Identifiers against an origin is trivial. However, the inverse (i.e given a DID discover the associated origins) is deemed out of scope.

DID Configuration is a draft specification being developed within the Decentralized Identity Foundation (DIF), and intended for registration with IANA as a Well-Known resource. This spec will be updated to reflect relevant changes, and participants are encouraged to contribute at the following repository location: https://github.com/decentralized-identity/.well-known

Terminology

DID

See the normative definition here, [[did-core]].

DID Document

See the normative definition here, [[did-core]].

Issuer

See the normative definition here, [[vc-data-model]].

Subject

See the normative definition here, [[vc-data-model]].

Controller

See the normative definition here, [[vc-data-model]].

Verifier

See the normative definition here, [[vc-data-model]].

JSON Web Token

See the normative definition here, [[vc-data-model]].

Linked Data Proof

See the normative definition here, [[vc-data-model]].

Well-Known URIs

See the normative definition here [[RFC5785]].

See the IANA registry here: Well-Known URIs.

Origins

For the standard definition of a domain-based origin in the web security context, see the WHATWG HTML Living Standard's origin definition section. For more information on origins and their composition, you may view the MDN page on Same-Origin Policy.

DID Configuration URI

A well-known URI for a DID Configuration Resource

          https://identity.foundation/.well-known/did-configuration.json

The DID Configuration resource MUST exist at the origin's root, in the IETF 8615 Well-Known Resource directory, as follows: `/.well-known/did-configuration.json`

DID Configuration Resource

A [[JSON-LD]] object that includes Domain Linkage Credentials located at a DID Configuration URI.

Given an origin, `https://example.com`, fetch the DID Configuration resource via a `GET` request over secure HTTP connection (`https`) to the well-known location: `https://example.com/.well-known/did-configuration.json`.
Provided the call returns a successful response, or has not exceeded a tolerance set by the implementer (e.g. maximum size), parse the body as JSON in accordance with IETF RFC 8259.

The DID Configuration resource MUST be a valid JSON object containing Domain Linkage Credentials, which contain cryptographically verifiable claims that prove the same entity controls both the included DIDs and the origin the resource is located under.

{
  "@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"
      ],
      "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
      "issuanceDate": "2020-12-04T14:08:28-06:00",
      "expirationDate": "2025-12-04T14:08:28-06:00",
      "type": [
        "VerifiableCredential",
        "DomainLinkageCredential"
      ],
      "credentialSubject": {
        "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
        "origin": "https://identity.foundation"
      },
      "proof": {
        "type": "Ed25519Signature2018",
        "created": "2020-12-04T20:08:28.540Z",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..D0eDhglCMEjxDV9f_SNxsuU-r3ZB9GR4vaM9TYbyV7yzs1WfdUyYO8rFZdedHbwQafYy8YOpJ1iJlkSmB4JaDQ",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM"
      }
    },
    "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa29USHNnTk5yYnk4SnpDTlExaVJMeVc1UVE2UjhYdXU2QUE4aWdHck1WUFVNI3o2TWtvVEhzZ05OcmJ5OEp6Q05RMWlSTHlXNVFRNlI4WHV1NkFBOGlnR3JNVlBVTSJ9.eyJleHAiOjE3NjQ4NzkxMzksImlzcyI6ImRpZDprZXk6ejZNa29USHNnTk5yYnk4SnpDTlExaVJMeVc1UVE2UjhYdXU2QUE4aWdHck1WUFVNIiwibmJmIjoxNjA3MTEyNzM5LCJzdWIiOiJkaWQ6a2V5Ono2TWtvVEhzZ05OcmJ5OEp6Q05RMWlSTHlXNVFRNlI4WHV1NkFBOGlnR3JNVlBVTSIsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwiaHR0cHM6Ly9pZGVudGl0eS5mb3VuZGF0aW9uLy53ZWxsLWtub3duL2RpZC1jb25maWd1cmF0aW9uL3YxIl0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmtleTp6Nk1rb1RIc2dOTnJieThKekNOUTFpUkx5VzVRUTZSOFh1dTZBQThpZ0dyTVZQVU0iLCJvcmlnaW4iOiJpZGVudGl0eS5mb3VuZGF0aW9uIn0sImV4cGlyYXRpb25EYXRlIjoiMjAyNS0xMi0wNFQxNDoxMjoxOS0wNjowMCIsImlzc3VhbmNlRGF0ZSI6IjIwMjAtMTItMDRUMTQ6MTI6MTktMDY6MDAiLCJpc3N1ZXIiOiJkaWQ6a2V5Ono2TWtvVEhzZ05OcmJ5OEp6Q05RMWlSTHlXNVFRNlI4WHV1NkFBOGlnR3JNVlBVTSIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJEb21haW5MaW5rYWdlQ3JlZGVudGlhbCJdfX0.aUFNReA4R5rcX_oYm3sPXqWtso_gjPHnWZsB6pWcGv6m3K8-4JIAvFov3ZTM8HxPOrOL17Qf4vBFdY9oK0HeCQ"
  ]
}

@context MUST be present.
linked_dids MUST be present.

The value of linked_dids MUST be an array of DomainLinkageCredential entries.

Additional members MUST NOT be present in the DID Configuration Resource.

Domain Linkage Credential

A Verifiable Credential represented as JSON-LD or JSON Web Token.

In order to eliminate ambiguity between proof-formats, the following requirements must be observed.

id MUST NOT be present.
issuanceDate MUST be present.
expirationDate MUST be present.

credentialSubject.id MUST be present, and MUST be a DID.
credentialSubject.origin MUST be present, and MUST be a domain Origin.

Linked Data Proof Format

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://identity.foundation/.well-known/did-configuration/v1"
  ],
  "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
  "issuanceDate": "2020-12-04T14:08:28-06:00",
  "expirationDate": "2025-12-04T14:08:28-06:00",
  "type": [
    "VerifiableCredential",
    "DomainLinkageCredential"
  ],
  "credentialSubject": {
    "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
    "origin": "https://identity.foundation"
  },
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2020-12-04T20:08:28.540Z",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..D0eDhglCMEjxDV9f_SNxsuU-r3ZB9GR4vaM9TYbyV7yzs1WfdUyYO8rFZdedHbwQafYy8YOpJ1iJlkSmB4JaDQ",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM"
  }
}

JSON Web Token Proof Format

          eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa29USHNnTk5yYnk4SnpDTlExaVJMeVc1UVE2UjhYdXU2QUE4aWdHck1WUFVNI3o2TWtvVEhzZ05OcmJ5OEp6Q05RMWlSTHlXNVFRNlI4WHV1NkFBOGlnR3JNVlBVTSJ9.eyJleHAiOjE3NjQ4NzkxMzksImlzcyI6ImRpZDprZXk6ejZNa29USHNnTk5yYnk4SnpDTlExaVJMeVc1UVE2UjhYdXU2QUE4aWdHck1WUFVNIiwibmJmIjoxNjA3MTEyNzM5LCJzdWIiOiJkaWQ6a2V5Ono2TWtvVEhzZ05OcmJ5OEp6Q05RMWlSTHlXNVFRNlI4WHV1NkFBOGlnR3JNVlBVTSIsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwiaHR0cHM6Ly9pZGVudGl0eS5mb3VuZGF0aW9uLy53ZWxsLWtub3duL2RpZC1jb25maWd1cmF0aW9uL3YxIl0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmtleTp6Nk1rb1RIc2dOTnJieThKekNOUTFpUkx5VzVRUTZSOFh1dTZBQThpZ0dyTVZQVU0iLCJvcmlnaW4iOiJpZGVudGl0eS5mb3VuZGF0aW9uIn0sImV4cGlyYXRpb25EYXRlIjoiMjAyNS0xMi0wNFQxNDoxMjoxOS0wNjowMCIsImlzc3VhbmNlRGF0ZSI6IjIwMjAtMTItMDRUMTQ6MTI6MTktMDY6MDAiLCJpc3N1ZXIiOiJkaWQ6a2V5Ono2TWtvVEhzZ05OcmJ5OEp6Q05RMWlSTHlXNVFRNlI4WHV1NkFBOGlnR3JNVlBVTSIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJEb21haW5MaW5rYWdlQ3JlZGVudGlhbCJdfX0.aUFNReA4R5rcX_oYm3sPXqWtso_gjPHnWZsB6pWcGv6m3K8-4JIAvFov3ZTM8HxPOrOL17Qf4vBFdY9oK0HeCQ

Example of the decoded JWT Header

          {
            "alg": "EdDSA",
            "kid": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM#z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM"
          }

typ MUST NOT be present in the JWT Header.
kid MUST be present in the JWT Header.
alg MUST be present in the JWT Header.

Additional members MUST NOT be present in the header.

          {
            "exp": 1764879139,
            "iss": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
            "nbf": 1607112739,
            "sub": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
            "vc": {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://identity.foundation/.well-known/did-configuration/v1"
              ],
              "credentialSubject": {
                "id": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
                "origin": "identity.foundation"
              },
              "expirationDate": "2025-12-04T14:12:19-06:00",
              "issuanceDate": "2020-12-04T14:12:19-06:00",
              "issuer": "did:key:z6MkoTHsgNNrby8JzCNQ1iRLyW5QQ6R8Xuu6AA8igGrMVPUM",
              "type": [
                "VerifiableCredential",
                "DomainLinkageCredential"
              ]
            }
          }

iss MUST be equal to credentialSubject.id.
sub MUST be equal to credentialSubject.id.
vc MUST be equal to the LD Proof Format without the proof property.

Additional members MUST NOT be present in the payload.

DID Configuration Resource Verification

After fetching and validating the resource via the DID Configuration Resource process. The processing entity MAY choose to validate any of Domain Linkage Credentials it contains. Domain Linkage Credentials are independent from one another, thus one being valid or invalid does not affect the state of the others. For a Domain Linkage Credential to be deemed valid, it MUST be successfully processed in accordance with the following steps:

The credentialSubject.id MUST be a DID, and the value MUST be equal to both the Subject and Issuer of the Domain Linkage Credential.
The Domain Linkage Credential must be in either a Linked Data Proof Format or JSON Web Token Proof Format
The credentialSubject.origin property MUST be present, and its value MUST match the origin the resource was requested from.
The implementer MUST perform DID resolution on the DID specified in the Issuer of the Domain Linkage Credential to obtain the associated DID document.
Using the retrieved DID document, the implementer MUST validate the signature of the Domain Linkage Credential against key material referenced in the assertionMethod section of the DID document.
If Domain Linkage Credential verification is successfull, a Verifier SHOULD consider the entity controlling the origin and the Controller of the DID to be the same entity.

If an entry fails validation during an iteration of the entries by the processing entity, there is no normative implication about the validity of other entries, and the choice to continue iteration and validation of further entries is at the election of the processing entity.

If the resource processing entity is not looking for the presence of a specific DID, or intending to validate a specific DID in the `linked_dids` array of Domain Linkage Credentials, the resource processing entity SHOULD iterate the array of Domain Linkage Credentials beginning at 0 index. This normative iteration from 0 index is intended to allow origin controllers to order their Domain Linkage Credentials in accordance with a known processing order, in cases where order may matter to the origin controller. An example of this is the case where an origin controller has a primary signing DID that is the likely target of interest for the vast majority of relying parties who seek to validate an assertion based on the DIDs associated with an origin.

Linked Domain Service Endpoint

To enable discovery of linked domains from the resolution of a DID, there must exist a DID Document mechanism for expressing origins where DID Configurations MAY be located that prove a bidirectional linkage between the DID and the origins it claims to possess control over. To that end, the following section codifies the `LinkedDomains` Service Endpoint, which allows a DID controller to specify a list of origins over which they assert control. Origins asserted within the `LinkedDomains` endpoint descriptor can then be subsequently crawled by verifying parties to locate and verify any DID Configuration resources that may exist.

{
  "@context": ["https://www.w3.org/ns/did/v1","https://identity.foundation/.well-known/did-configuration/v1"],
  "id": "did:example:123",
  "verificationMethod": [{
    "id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "type": "JsonWebKey2020",
    "controller": "did:example:123",
    "publicKeyJwk": {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ"
    }
  }],
  "service": [
    {
      "id":"did:example:123#foo",
      "type": "LinkedDomains",
      "serviceEndpoint": {
        "origins": ["https://foo.example.com", "https://identity.foundation"]
      }
    },
    {
      "id":"did:example:123#bar",
      "type": "LinkedDomains",
      "serviceEndpoint": "https://bar.example.com"
    }
  ]
}

Linked Domains

`LinkedDomains` endpoint descriptors are JSON objects composed as follows:

The object MUST contain an `id` property, and its value MUST be a valid DID URL reference.
The object MUST contain a `type` property, and its value MUST be the string `"LinkedDomains"`.
The object MUST contain a `serviceEndpoint` property, and its value MUST be either an origin string or an object that contains as `origins` property, the value of which MUST be an array of one or more origins.

This document contains examples that contain JSON and JSON-LD content. Some of these examples contain characters that are invalid, such as inline comments (//) and the use of ellipsis (...) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as valid JSON, or JSON-LD.

A DID Configuration URI is any concrete expression of the rules specified in Section DID Configuration URI and MUST comply with relevant normative statements in that section.

A DID Configuration Resource is any concrete expression of the rules specified in Section DID Configuration Resource and MUST comply with relevant normative statements in that section.

A Domain Linkage Credential is any concrete expression of the rules specified in Section Domain Linkage Credential and MUST comply with relevant normative statements in that section.

Implementations MUST comply with relevant normative statements in DID Configuration Resource Verification