Edit

Frequently Asked Questions (FAQ)

  • Article

This page contains commonly asked questions about Verifiable Credentials and Decentralized Identity. Questions are organized into the following sections.

The basics

What is a DID?

Decentralized Identifiers (DIDs) are unique identifiers that can be used to secure access to resources, sign and verify credentials, and facilitate application data exchange. Unlike traditional usernames and email addresses, entities and owning and controlling the DIDs themselves (be it a person, device, or company). DIDs exist independently of any external organization or trusted intermediary. The W3C Decentralized Identifier spec explains DIDs in further detail.

Why do we need a DID?

Digital trust fundamentally requires participants to own and control their identities, and identity begins at the identifier. In an age of daily, large-scale system breaches and attacks on centralized identifier honeypots, decentralizing identity is becoming a critical security need for consumers and businesses. Individuals owning and controlling their identities are able to exchange verifiable data and proofs. A distributed credential environment allows for the automation of many business processes that are currently manual and labor intensive.

What is a Verifiable Credential?

Credentials are a part of our daily lives. Driver's licenses are used to assert that we're capable of operating a motor vehicle. University degrees can be used to assert our level of education and government-issued passports enable us to travel between countries and regions. Verifiable Credentials provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable. The W3C Verifiable Credentials spec explains verifiable credentials in further detail.

Conceptual questions

What happens when a user loses their phone? Can they recover their identity?

There are multiple ways of offering a recovery mechanism to users, each with their own tradeoffs. Microsoft currently evaluating options and designing approaches to recovery that offer convenience and security while respecting a user's privacy and self-sovereignty.

How can a user trust a request from an issuer or verifier? How do they know a DID is the real DID for an organization?

We implement the Decentralized Identity Foundation's Well Known DID Configuration spec in order to connect a DID to a highly known existing system, domain names. Each DID created using the Microsoft Entra Verified ID has the option of including a root domain name that is encoded in the DID Document. Follow the article titled Link your Domain to your Distributed Identifier to learn more.

What are the licensing requirements?

There are no special licensing requirements to issue Verifiable credentials.

How do I reset the Microsoft Entra Verified ID service?

Resetting requires that you opt-out and opt back into the Microsoft Entra Verified ID service. Your existing verifiable credentials configuration is reset and your tenant obtains a new DID to use during issuance and presentation.

  1. Follow the opt-out instructions.
  2. Go over the Microsoft Entra Verified ID deployment steps to reconfigure the service.
    1. If you're manually setting up Verified ID, choose a location for your Azure Key Vault to be in the same or closest region. This avoids performance and latency issues.
  3. Finish setting up your verifiable credentials service. You need to recreate your credentials.
    1. If your tenant needs to be configured as an issuer, it's recommended that your storage account is in the European region as your Verifiable Credentials service.
    2. You also need to issue new credentials because your tenant now holds a new DID.

How can I check my Microsoft Entra tenant's region?

  1. In the Azure portal, go to Microsoft Entra ID for the subscription you use for your Microsoft Entra Verified ID deployment.
  2. Under Manage, select Properties settings delete and opt-out
  3. See the value for Country or Region. If the value is a country or a region in Europe, your Microsoft Entra Verified ID service is set up in Europe.

Does Microsoft Entra Verified ID support ION as its DID method?

Verified ID supported the DID:ION method in preview until December 2023, after which it was discontinued.

How do I move to did:web from did:ion?

If you want to move to did:web from did:ion, you can follow these steps via the Admin API. Changing authority requires reissuance of all credentials:

Export existing did:ion credential definitions

  1. For the did:ion authority, use the portal to copy out all display and rules definition of the existing credentials.
  2. If you have more than one authority, you have to use the Admin APIs if the did:ion authority isn't the default authority. On the Verified ID tenant, connect using Admin API, list the authorities to get the authority ID for the did:ion authority. Then use the list contracts API to export them and save the result to a file so you can recreate them.

Creating new did:web authority

  1. Using the onboard API, create the new did:web authority. Alternatively, if your tenant has only one did:ion authority, you could also perform a service opt-out followed by an opt-in operation to restart with Verified ID configurations. In this case, you could choose between Quick and Manual setup.
  2. If you're setting up a did:web authority using Admin API, you need to call generate DID document to generate your did document and call generate well-known document and then upload JSON files to the respective well-known path.

Recreate credential definitions

After you have created your new did:web authority, you need to recreate your credential definitions. You can either do that via the portal if you opted-out and reonboarded, or you need to use the create contract API to recreate them.

Update existing applications

  1. Update any of your existing application (issuer/verifier apps) to use the new did:web authority. For issuance apps, update the credential manifest URL too.
  2. Test issuance and verification flows from the new did:web authority. Once the tests are successful, proceed to the next step for did:ion authority deletion.

Delete did:ion authority

If you didn't opt-out and reonboarded, you need to remove your old did:ion authority. Use the delete authority API to delete the did:ion authority.

Yes, after reconfiguring your service, your tenant has a new DID use to issue and verify verifiable credentials. You need to associate your new DID with your domain.

Is it possible to request Microsoft to retrieve "old DIDs"?

No, at this point it isn't possible to keep your tenant's DID after you have opt-out of the service.

I cannot use ngrok, what do I do?

The tutorials for deploying and running the samples describes the use of the ngrok tool as an application proxy. This tool is sometimes blocked by IT admins from being used in corporate networks. An alternative is to deploy the sample to Azure App Service and run it in the cloud. The following links help you deploy the respective sample to Azure App Service. The Free pricing tier is sufficient for hosting the sample. For each tutorial, you need to start by first creating the Azure App Service instance, then skip creating the app since you already have an app and then continue the tutorial with deploying it.

Regardless of which language of the sample you're using, the Azure AppService hostname https://something.azurewebsites.net is used as the public endpoint. You don't need to configure something extra to make it work. If you make changes to the code or configuration, you need to redeploy the sample to Azure AppServices. Troubleshooting/debugging isn't as easy as running the sample on your local machine, where traces to the console window show you errors, but you can achieve almost the same by using the Log Stream.

Next steps