Create a Web DID

Introduction

DIDs with a method of web are a type of DID where the DID Document is hosted on a publicly accessible domain in order to make the document and contents available. For example, we’ve set up a Web DID using our own domain did:web:mattr.global this is hosted on our website at https://mattr.global/.well-known/did.json. DIDs may also be hosted at specific paths on your website.

Constraints

These DIDs rely inherently on the security of the website the DID Document is hosted on, we would generally only recommend the use of this DID on trusted known sites, like Government agencies and enterprises.

Create DID and DID Document

A DID with a DID method of web can be created as follows.

http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/dids

Request

json
Copy to clipboard.
1{
2  "method": "web",
3  "options": {
4    "url": "organization.com"
5  }
6}
  • The method is set to web in order to create a DID with a DID method of web.

  • The url is the domain that will host the DID document.

In order to resolve the DID Document the domain will be prefixed with https:// and suffixed with /.well-known/did.json. This means that the DID Document in the example above should become available on https://organization.com/.well-known/did.json.

Hosting on a specific path

It is possible to create a DID Web using a specific path rather than in the /.well-known, folder.

Note changing the URL for a DID Web will require creating a new DID that is distinct from any previously created ones.

json
Copy to clipboard.
1
2{
3  "method": "web",
4  "options": {
5    "url": "organization.com/path"
6  }
7}

The created DID will then need to be hosted on the path specified in the url option, the rest of the guide will assume you stick with the default /.well-known path configuration.

Response

json
Copy to clipboard.
1{
2
3  "did": "did:web:organization.com",
4  "registrationStatus": "PROCESSING",
5  "localMetadata": {
6    "keys": [
7      {
8        "didDocumentKeyId": "did:web:organization.com#CfZMD88eoh",
9        "kmsKeyId": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
10      },
11      {
12        "didDocumentKeyId": "did:web:organization.com#9hvq54oWSa",
13        "kmsKeyId": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
14      }
15    ],
16    "registered": 1600731355153,
17    "initialDidDocument": {
18      "@context": "https://w3.org/ns/did/v1",
19      "id": "did:web:organization.com",
20      "publicKey": [
21        {
22          "id": "did:web:organization.com#CfZMD88eoh",
23          "controller": "did:web:organization.com",
24          "type": "Ed25519VerificationKey2018",
25          "publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
26        }
27      ],
28      "authentication": [
29        "did:web:organization.com#CfZMD88eoh"
30      ],
31      "assertionMethod": [
32        "did:web:organization.com#CfZMD88eoh"
33      ],
34      "capabilityDelegation": [
35        "did:web:organization.com#CfZMD88eoh"
36      ],
37      "capabilityInvocation": [
38        "did:web:organization.com#CfZMD88eoh"
39      ],
40      "keyAgreement": [
41        {
42          "id": "did:web:organization.com#6FstRAzj71",
43          "controller": "did:web:organization.com",
44          "type": "X25519KeyAgreementKey2019",
45          "publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
46        }
47      ]
48    }
49  }
50}

The returned initial DID Document then needs to be hosted so that it is accessible from the domain provided in the options.

Hosting the DID Document on a website

Take the contents of the initialDidDocument object and save it in a text file named did.json.

Upload did.json to your domain in a folder called /.well-known.

You will need to keep this file updated if you were to change the DID on the platform.

json
Copy to clipboard.
1{
2  "@context": "https://w3.org/ns/did/v1",
3  "id": "did:web:organization.com",
4  "publicKey": [
5    {
6      "id": "did:web:organization.com#CfZMD88eoh",
7      "controller": "did:web:organization.com",
8      "type": "Ed25519VerificationKey2018",
9      "publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
10    }
11  ],
12  "authentication": [
13    "did:web:organization.com#CfZMD88eoh"
14  ],
15  "assertionMethod": [
16    "did:web:organization.com#CfZMD88eoh"
17  ],
18  "capabilityDelegation": [
19    "did:web:organization.com#CfZMD88eoh"
20  ],
21  "capabilityInvocation": [
22    "did:web:organization.com#CfZMD88eoh"
23  ],
24  "keyAgreement": [
25    {
26      "id": "did:web:organization.com#6FstRAzj71",
27      "controller": "did:web:organization.com",
28      "type": "X25519KeyAgreementKey2019",
29      "publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
30    }
31  ]
32}

Resolve DID document

Download the DID Document from https://organization.com/.well-known/did.json to ensure it is available from the domain.

The tenant will be able to prove ownership of the keys associated with the did:web DID Document through the well-known endpoint, i.e. https://tenant.vii.mattr.global/.well-known/did-configuration, while the DID Document hosted on the domain links the DID to a domain.

http
Copy to clipboard.
1GET https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/dids/did:web:organization.com

json
Copy to clipboard.
1{
2  "didDocument": {
3    "@context": "https://w3.org/ns/did/v1",
4    "id": "did:web:organization.com",
5    "publicKey": [
6    {
7      "id": "did:web:organization.com#CfZMD88eoh",
8      "controller": "did:web:organization.com",
9      "type": "Ed25519VerificationKey2018",
10      "publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
11    }
12    ],
13    "authentication": [
14    "did:web:organization.com#CfZMD88eoh"
15    ],
16    "assertionMethod": [
17    "did:web:organization.com#CfZMD88eoh"
18    ],
19    "capabilityDelegation": [
20    "did:web:organization.com#CfZMD88eoh"
21    ],
22    "capabilityInvocation": [
23    "did:web:organization.com#CfZMD88eoh"
24    ],
25    "keyAgreement": [
26    {
27      "id": "did:web:organization.com#6FstRAzj71",
28      "controller": "did:web:organization.com",
29      "type": "X25519KeyAgreementKey2019",
30      "publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
31    }
32    ]
33  },
34  "registrationStatus": "COMPLETED",
35  "localMetadata": {
36    "keys": [
37      {
38        "didDocumentKeyId": "did:web:organization.com#CfZMD88eoh",
39        "kmsKeyId": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
40      },
41      {
42        "didDocumentKeyId": "did:web:organization.com#9hvq54oWSa",
43        "kmsKeyId": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
44      }
45    ],
46    "registered": 1600731355153,
47    "initialDidDocument": {
48      "@context": "https://w3.org/ns/did/v1",
49      "id": "did:web:organization.com",
50      "publicKey": [
51        {
52          "id": "did:web:organization.com#CfZMD88eoh",
53          "controller": "did:web:organization.com",
54          "type": "Ed25519VerificationKey2018",
55          "publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
56        }
57      ],
58      "authentication": [
59        "did:web:organization.com#CfZMD88eoh"
60      ],
61      "assertionMethod": [
62        "did:web:organization.com#CfZMD88eoh"
63      ],
64      "capabilityDelegation": [
65        "did:web:organization.com#CfZMD88eoh"
66      ],
67      "capabilityInvocation": [
68        "did:web:organization.com#CfZMD88eoh"
69      ],
70      "keyAgreement": [
71        {
72          "id": "did:web:organization.com#6FstRAzj71",
73          "controller": "did:web:organization.com",
74          "type": "X25519KeyAgreementKey2019",
75          "publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
76        }
77      ]
78    }
79  }
80}

ZKP Enabled Web DID

Web DIDs can be created with a bls12381g2 key type, DIDs containing this key can then be used to create ZKP-enabled verifiable credentials.

Using the same Create DID endpoint:

http
Copy to clipboard.
1POST 
2https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/dids

Request

Include an options body with the BLS key type.

json
Copy to clipboard.
1{
2  "method": "web",
3  "options": {
4      "url": "organization.com",
5      "keyType": "bls12381g2"
6  }
7}

Response

json
Copy to clipboard.
1{
2  "did": "did:web:organization.com",
3  "registrationStatus": "PROCESSING",
4  "localMetadata": {
5    "keys": [
6      {
7        "didDocumentKeyId": "did:web:organization.com#oKhQ6nfNxg",
8        "kmsKeyId": "a4c76bad-897c-4202-8fbd-3257e165d215"
9      },
10      {
11        "didDocumentKeyId": "did:web:organization.com#2EHAKPYcG6",
12        "kmsKeyId": "6bb9bb7a-70b4-45ee-9d02-30bcecc34aa4"
13      }
14    ],
15    "registered": 1632282683786,
16    "initialDidDocument": {
17      "@context": "https://w3.org/ns/did/v1",
18      "id": "did:web:organization.com",
19      "publicKey": [
20        {
21          "id": "did:web:organization.com#oKhQ6nfNxg",
22          "controller": "did:web:organization.com",
23          "type": "Bls12381G2Key2020",
24          "publicKeyBase58": "oKhQ6nfNxgjkmMDXJpyQnpPrHZBMWjaEfBfRzxKYwL51zHA7W3QhjKkpoksD7kMkyMphMCfHFc5f7T2avs3THwiXPr6g6AiLs3i62BTgJeaK3zmkjb8Pcbper7grDgNjUCQ"
25        }
26      ],
27      "authentication": [
28        "did:web:organization.com#oKhQ6nfNxg"
29      ],
30      "assertionMethod": [
31        "did:web:organization.com#oKhQ6nfNxg"
32      ],
33      "capabilityDelegation": [
34        "did:web:organization.com#oKhQ6nfNxg"
35      ],
36      "capabilityInvocation": [
37        "did:web:organization.com#oKhQ6nfNxg"
38      ],
39      "keyAgreement": [
40        {
41          "id": "did:web:organization.com#2EHAKPYcG6",
42          "controller": "did:web:organization.com",
43          "type": "X25519KeyAgreementKey2019",
44          "publicKeyBase58": "2EHAKPYcG6wPdpMHjRtwDhg4WnSyi695V7EkfRRNxmYW"
45        }
46      ]
47    }
48  }
49}

The resulting DID can now be used to Create Credentials, either directly or via the OIDC Bridge that will result in them being ZKP-enabled.

For Web DIDs that use a bls12381g2 key type, there are limitations on other actions that can be performed with the DID.

  • Message encryption is possible by specifying the appropriate keyAgreement key

  • Message signing is not possible at this time using DIDs that contain bls12381g2 keys.