Muokkaa

Jaa

Frequently Asked Questions (FAQ)

  • Artikkeli

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 used to secure access to resources, sign and verify credentials, and facilitate data exchange between applications. 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 about linked domains.

What are the size limitations for a Verifiable Credential in Verified ID?

  • For issuance request - 1 MB
  • Photo in the Verifiable credential - 1 MB
  • Callback result 10 MB without receipt

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. Choosing same region avoids performance and latency issues.
  3. Finish setting up your verifiable credentials service. You need to recreate your credentials.
    1. 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.

    Screenshot of 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

When 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 opted out of the service.

I can't 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.

Network hardening for callback events

The Request Service API makes use of callbacks to a URL provided by the relying party application. This URL needs to be reachable from the Verified ID system for the callbacks to be received. Callbacks are coming from Azure infrastructure in the same region as your Microsoft Entra tenant. If you need to harden your network, you have two options.

  • Use Azure firewall service tags AzureCloud.
  • Use the published CIDR range to configure your firewall. You need to use AzureCloud.regions that matches where your Microsoft Entra tenant is deployed to config your firewall to let callback traffic from Request Service API through. For instance, if your tenant is in EU, you should pick all CIDR ranges from AzureCloud.northeurope, .westeurope, etc., to your firewalls config.

Scanning the QR code

In the documentation, the instruction scan the QR code refers to scanning it with the Microsoft Authenticator mobile app, unless otherwise stated. It is possible to scan the QR code with the mobile's camera app, which then launches the Microsoft Authenticator. For this to work, the protocol handler for openid-vc:// must be registered for Microsoft Authenticator. If another mobile app have been registered for it, the Authenticator will not open.

On Android mobile phones, known problems of scanning the QR code are:

  • On Android 9 and older versions, scanning the QR code with the camera app doesn't work, and there is no other workaround than using the Microsoft Authenticator app to scan it.
  • On Android phones with both work and personal profiles, each profile has its own instance of the Microsoft Authenticator app. If you have a credential in the work profile's Authenticator app and try to scan a QR code using the camera app from the personal profile, the personal Authenticator app will open. This causes an error because the credential is in the work profile, not the personal one. The error message will say, "You'll have to add this Verified ID and try again."

Next steps