Create a Web DID

Introduction

DIDs with a method of web are a type of DID where the DID Document is hosted on a domain in order to link it to that domain. For example, we’ve set up a DID Web using our own domain, which can be resolved at did:web:mattr.global.

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    "domain": "organization.com"
5  }
6}

The method is set to web in order to create a DID with a DID method of web.

The domain 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.

Response

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

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

Upload to website

Upload did.json to your domain in a folder called .well-known. It should contain the content obtained when creating the DID.

json
Copy to clipboard.
1{
2
3  "@context": "https://w3.org/ns/did/v1",
4
5  "id": "did:web:organization.com",
6
7  "publicKey": [
8
9    {
10
11      "id": "did:web:organization.com#CfZMD88eoh",
12
13      "controller": "did:web:organization.com",
14
15      "type": "Ed25519VerificationKey2018",
16
17      "publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
18
19    }
20
21  ],
22
23  "authentication": [
24
25    "did:web:organization.com#CfZMD88eoh"
26
27  ],
28
29  "assertionMethod": [
30
31    "did:web:organization.com#CfZMD88eoh"
32
33  ],
34
35  "capabilityDelegation": [
36
37    "did:web:organization.com#CfZMD88eoh"
38
39  ],
40
41  "capabilityInvocation": [
42
43    "did:web:organization.com#CfZMD88eoh"
44
45  ],
46
47  "keyAgreement": [
48
49    {
50
51      "id": "did:web:organization.com#6FstRAzj71",
52
53      "controller": "did:web:organization.com",
54
55      "type": "X25519KeyAgreementKey2019",
56
57      "publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
58
59    }
60
61  ]
62
63}

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
3  "didDocument": {
4
5    "@context": "https://w3.org/ns/did/v1",
6
7    "id": "did:web:organization.com",
8
9    "publicKey": [
10
11    {
12
13      "id": "did:web:organization.com#CfZMD88eoh",
14
15      "controller": "did:web:organization.com",
16
17      "type": "Ed25519VerificationKey2018",
18
19      "publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
20
21    }
22
23    ],
24
25    "authentication": [
26
27    "did:web:organization.com#CfZMD88eoh"
28
29    ],
30
31    "assertionMethod": [
32
33    "did:web:organization.com#CfZMD88eoh"
34
35    ],
36
37    "capabilityDelegation": [
38
39    "did:web:organization.com#CfZMD88eoh"
40
41    ],
42
43    "capabilityInvocation": [
44
45    "did:web:organization.com#CfZMD88eoh"
46
47    ],
48
49    "keyAgreement": [
50
51    {
52
53      "id": "did:web:organization.com#6FstRAzj71",
54
55      "controller": "did:web:organization.com",
56
57      "type": "X25519KeyAgreementKey2019",
58
59      "publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
60
61    }
62
63    ]
64
65  },
66
67  "registrationStatus": "COMPLETED",
68
69  "localMetadata": {
70
71    "keys": [
72
73      {
74
75        "didDocumentKeyId": "did:web:organization.com#CfZMD88eoh",
76
77        "kmsKeyId": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
78
79      },
80
81      {
82
83        "didDocumentKeyId": "did:web:organization.com#9hvq54oWSa",
84
85        "kmsKeyId": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
86
87      }
88
89    ],
90
91    "registered": 1600731355153,
92
93    "initialDidDocument": {
94
95      "@context": "https://w3.org/ns/did/v1",
96
97      "id": "did:web:organization.com",
98
99      "publicKey": [
100
101        {
102
103          "id": "did:web:organization.com#CfZMD88eoh",
104
105          "controller": "did:web:organization.com",
106
107          "type": "Ed25519VerificationKey2018",
108
109          "publicKeyBase58": "CfZMD88eohsizC7XwamxwNVFuQaowN3fpNRW6rBjBEMy"
110
111        }
112
113      ],
114
115      "authentication": [
116
117        "did:web:organization.com#CfZMD88eoh"
118
119      ],
120
121      "assertionMethod": [
122
123        "did:web:organization.com#CfZMD88eoh"
124
125      ],
126
127      "capabilityDelegation": [
128
129        "did:web:organization.com#CfZMD88eoh"
130
131      ],
132
133      "capabilityInvocation": [
134
135        "did:web:organization.com#CfZMD88eoh"
136
137      ],
138
139      "keyAgreement": [
140
141        {
142
143          "id": "did:web:organization.com#6FstRAzj71",
144
145          "controller": "did:web:organization.com",
146
147          "type": "X25519KeyAgreementKey2019",
148
149          "publicKeyBase58": "6FstRAzj71Yb2BYGy62uMFA6G4vcAkvRTnqQ7sherD9x"
150
151        }
152
153      ]
154
155    }
156
157  }
158
159}