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 defintion 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.

  1. 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`.
  2. 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/contexts/did-configuration-v0.0.jsonld",
  "linked_dids": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld"
      ],
      "issuer": "did:web:identity.foundation",
      "issuanceDate": "2020-04-13T16:44:52-05:00",
      "expirationDate": "2020-05-13T16:44:52-05:00",
      "type": ["VerifiableCredential", "DomainLinkageCredential"],
      "credentialSubject": {
        "id": "did:web:identity.foundation",
        "origin": "https://identity.foundation"
      },
      "proof": {
        "type": "JsonWebSignature2020",
        "created": "2020-04-13T21:49:40Z",
        "verificationMethod": "did:web:identity.foundation#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
        "proofPurpose": "assertionMethod",
        "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..KyuVW9YdrShA3kDMufSWKtKHXtIKTzRpbxPgx1n50S2pl3GwrqtJWtZAexUD6beaTqu4W4njCoAv3_qaCQmuBA"
      }
    },
    "eyJraWQiOiJkaWQ6d2ViOmlkZW50aXR5LmZvdW5kYXRpb24jX1FxMFVMMkZxNjUxUTBGamQ2VHZuWUUtZmFIaU9wUmxQVlFjWV8tdEE0QSIsImFsZyI6IkVkRFNBIn0.eyJzdWIiOiJkaWQ6d2ViOmlkZW50aXR5LmZvdW5kYXRpb24iLCJpc3MiOiJkaWQ6d2ViOmlkZW50aXR5LmZvdW5kYXRpb24iLCJuYmYiOjE1ODY4MTQyOTIsImV4cCI6MTU4OTQwNjI5MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL2lkZW50aXR5LmZvdW5kYXRpb24vLndlbGwta25vd24vY29udGV4dHMvZGlkLWNvbmZpZ3VyYXRpb24tdjAuMC5qc29ubGQiXSwiaXNzdWVyIjoiZGlkOndlYjppZGVudGl0eS5mb3VuZGF0aW9uIiwiaXNzdWFuY2VEYXRlIjoiMjAyMC0wNC0xM1QxNjo0NDo1Mi0wNTowMCIsImV4cGlyYXRpb25EYXRlIjoiMjAyMC0wNS0xM1QxNjo0NDo1Mi0wNTowMCIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJEb21haW5MaW5rYWdlQ3JlZGVudGlhbCJdLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDp3ZWI6aWRlbnRpdHkuZm91bmRhdGlvbiIsImRvbWFpbiI6ImlkZW50aXR5LmZvdW5kYXRpb24ifX19.qEV-lat1Wc8qKU_OLbTd07fx7tkW12QhkyiB912OsHi4FmkTWr_qMAFyW8IZxaQAsXg1E4yCRe8VsfGYaePfCg"
  ]
}                 
        

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 represenrted as JSON-LD or JSON Web Token.

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

Linked Data Proof Format

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld"
  ],
  "issuer": "did:web:identity.foundation",
  "issuanceDate": "2020-04-13T16:44:52-05:00",
  "expirationDate": "2020-05-13T16:44:52-05:00",
  "type": ["VerifiableCredential", "DomainLinkageCredential"],
  "credentialSubject": {
    "id": "did:web:identity.foundation",
    "origin": "https://identity.foundation"
  },
  "proof": {
    "type": "JsonWebSignature2020",
    "created": "2020-04-13T21:49:40Z",
    "verificationMethod": "did:web:identity.foundation#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
    "proofPurpose": "assertionMethod",
    "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..KyuVW9YdrShA3kDMufSWKtKHXtIKTzRpbxPgx1n50S2pl3GwrqtJWtZAexUD6beaTqu4W4njCoAv3_qaCQmuBA"
  }
}
        

JSON Web Token Proof Format

          eyJraWQiOiJkaWQ6d2ViOmlkZW50aXR5LmZvdW5kYXRpb24jX1FxMFVMMkZxNjUxUTBGamQ2VHZuWUUtZmFIaU9wUmxQVlFjWV8tdEE0QSIsImFsZyI6IkVkRFNBIn0.eyJzdWIiOiJkaWQ6d2ViOmlkZW50aXR5LmZvdW5kYXRpb24iLCJpc3MiOiJkaWQ6d2ViOmlkZW50aXR5LmZvdW5kYXRpb24iLCJuYmYiOjE1ODY4MTQyOTIsImV4cCI6MTU4OTQwNjI5MiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL2lkZW50aXR5LmZvdW5kYXRpb24vLndlbGwta25vd24vY29udGV4dHMvZGlkLWNvbmZpZ3VyYXRpb24tdjAuMC5qc29ubGQiXSwiaXNzdWVyIjoiZGlkOndlYjppZGVudGl0eS5mb3VuZGF0aW9uIiwiaXNzdWFuY2VEYXRlIjoiMjAyMC0wNC0xM1QxNjo0NDo1Mi0wNTowMCIsImV4cGlyYXRpb25EYXRlIjoiMjAyMC0wNS0xM1QxNjo0NDo1Mi0wNTowMCIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJEb21haW5MaW5rYWdlQ3JlZGVudGlhbCJdLCJjcmVkZW50aWFsU3ViamVjdCI6eyJpZCI6ImRpZDp3ZWI6aWRlbnRpdHkuZm91bmRhdGlvbiIsImRvbWFpbiI6ImlkZW50aXR5LmZvdW5kYXRpb24ifX19.qEV-lat1Wc8qKU_OLbTd07fx7tkW12QhkyiB912OsHi4FmkTWr_qMAFyW8IZxaQAsXg1E4yCRe8VsfGYaePfCg 
        

Example of the decoded JWT Header

          {
            "kid": "did:web:identity.foundation#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
            "alg": "EdDSA"
          }
        

Additional members MUST NOT be present in the header.

          {
            "sub": "did:web:identity.foundation",
            "iss": "did:web:identity.foundation",
            "nbf": 1586814292,
            "exp": 1589406292,
            "vc": {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld"
              ],
              "issuer": "did:web:identity.foundation",
              "issuanceDate": "2020-04-13T16:44:52-05:00",
              "expirationDate": "2020-05-13T16:44:52-05:00",
              "type": [
                "VerifiableCredential",
                "DomainLinkageCredential"
              ],
              "credentialSubject": {
                "id": "did:web:identity.foundation",
                "origin": "identity.foundation"
              }
            }
          }
        

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:

  1. The credentialSubject.id MUST be a DID, and the value MUST be equal to both the Subject and Issuer of the Domain Linkage Credential.
  2. The Domain Linkage Credential must be in either a Linked Data Proof Format or JSON Web Token Proof Format
  3. The credentialSubject.origin property MUST be present, and its value MUST match the origin the resource was requested from.
  4. The implementer MUST perform DID resolution on the DID specified in the Issuer of the Domain Linkage Credential to obtain the associated DID document.
  5. 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.
  6. If Domain Linkage Credential verification is successfull, a Verifier SHOULD consider the entitry controlling the originand 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",
  "id": "did:example:123456789abcdefghi",
  "authentication": [{
    
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],
  "service": [
    {
      "id":"did:example:123456789abcdefghi#vcs",
      "type": "LinkedDomains",
      "serviceEndpoint": {
        "origins": ["https://foo.example.com", "https://identity.foundation"]
      }
    },
    {
      "id":"did:example:123456789abcdefghi#vcs",
      "type": "LinkedDomains",
      "serviceEndpoint": "https://bar.example.com"
      }
    }
  ]
}                 
      

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

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