Enable support for did:web:path

Article
09/19/2024

In this article, we go over the steps to enable support for did:web:path to your authority.

Prerequisites

Verified ID authority is manually onboarded using did:web. Quick setup uses a domain name managed by Microsoft which can't be extended.

What is did:web:path?

Did:web:path is described in the did:web Method Specification. If you have an environment where you're required to use a high number of authorities, acquiring domain names for them becomes an administrative problem. Using one single domain and having the different authorities appear as paths under the domain may be a more favorable approach.

Enable domain for did:web:path support

By default, a tenant and an authority isn't enabled to support did:web:path. You request enablement of did:web:path for your authority via creating a new support request in the Microsoft Entra admin center.

Support ticket details:

Issue type: Technical
Service type: Microsoft Entra Verified ID
Problem type: Configuration organization and domains
Summary: Enable did:web:path request
Description: Make sure to include
- Your Microsoft Entra tenant ID
- Your did (example: did:web:verifiedid.contoso.com)
- Estimated number of sub paths
- Business justification

How can I test that my authority is enabled?

You are given confirmation on your support request, but you can also verify if a did:web domain is enabled for did:web:path by testing it in a normal browser. By adding a path that doesn't exist (:do-not-exist in the following example) you get and error message with code discovery_service.web_method_path_not_supported if your authority isn't enabled, but the code discovery_service.not_found if it's enabled.

https://discover.did.msidentity.com/v1.0/identifiers/did:web:my-domain.com:do-not-exist

How do I configure an authority using did:web:path?

Once your tenant and authority is enabled for did:web:path, you can create a new authority in the same tenant that uses did:web:path. Currently this requires using the Admin API as there's no support in the portal for it.

Get details of your existing authority
- Go to Verified ID | Overview and copy domain (example: https://verifiedid.contoso.com/)
- Go to Verified ID | Organization settings and take a note of which Key vault is being configured.
- Go to the Key vault resource and copy the resource group, the subscription ID, and the Vault URI
Call the create authority with the following JSON body (modify as required). The /my-path in the path is where you specify the path name to be used.

POST /v1.0/verifiableCredentials/authorities

{
  "name":"ExampleNameForPath",
  "linkedDomainUrl":"https://my-domain.com/my-path",
  "didMethod": "web",
  "keyVaultMetadata":
  {
    "subscriptionId":"aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroup":"verifiablecredentials",
    "resourceName":"vccontosokv",
    "resourceUrl": "https://vccontosokv.vault.azure.net/"
  }
}

Generate the did document for the new authority by calling generateDidDocument where newAuthorityIdForPath is the id attribute in the create authority response:

POST /v1.0/verifiableCredentials/authorities/:newAuthorityIdForPath/generateDidDocument

Save the did document response to a file named did.json and upload it to location on your webserver that matches the linkedDomainUrl in the API call for creating the authority. If your path is https://my-domain.com/my-path, the new did.json file must reside in that location.
Retrieve the linked domain did configuration via calling generateWellknownDidConfiguration API with the following JSON body (modify as required). The domainUrl is the domain name without the path

POST /v1.0/verifiableCredentials/authorities/:newAuthorityIdForPath/generateWellknownDidConfiguration

{
    "domainUrl":"https://my-domain.com/"
}

From the response, copy the JWT token inside the linked_dids collection.
On your webserver, open the file https://my-domain.com/.well-known/did.configuration.json in an editor and add the JWT token as a new entry inside the linked_dids collection. It should look something like this after adding it.

{
  "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld",
  "linked_dids": [
    "eyJh...old...U7cw",
    "eyJh...new...V8dx",
  ]
}

Save the file.

Creating contracts using the new did:web:path authority

Contracts need to be created using the Admin API as there's currently no user interface support for secondary authorities.

Issuing credentials based contracts in the new did:web:path authority

In order to have apps issue credentials based on contracts in the new did:web:path authority, you only need to change the authority field in the request payload to createIssuanceRequest API.

{
  "authority": "did:web:my-domain.com:my-path",
  "includeQRCode": false,
  ... the rest is the same...
}

Share via