Merge pull request #188570 from barclayn/linked-domain

adding link domain update sections

Author: laurabren

articles/active-directory/verifiable-credentials/how-to-dnsbind.md

@@ -7,7 +7,7 @@ manager: karenhoran
 ms.service: active-directory
 ms.topic: how-to
 ms.subservice: verifiable-credentials
-ms.date: 04/01/2021
+ms.date: 02/22/2022
 ms.author: barclayn
 
 #Customer intent: Why are we doing this?
@@ -17,15 +17,9 @@ ms.author: barclayn
 
 > [!IMPORTANT]
 > Azure Active Directory Verifiable Credentials is currently in public preview.
-> This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. 
+> This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.
 > For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
 
-In this article:
-> [!div class="checklist"]
-> * Why do we need to link our DID to our domain?
-> * How do we link DIDs and domains?
-> * How does the domain linking process work?
-> * How does the verify/unverified domain logic work?
 
 ## Prerequisites
 
@@ -35,16 +29,20 @@ To link your DID to your domain, you need to have completed the following.
 
 ## Why do we need to link our DID to our domain?
 
-A DID starts out as an identifier that is not anchored to existing systems. A DID is useful because a user or organization can own it and control it. If an entity interacting with the organization does not know 'who' the DID belongs to, then the DID is not as useful.
+A DID starts out as an identifier that isn't anchored to existing systems. A DID is useful because a user or organization can own it and control it. If an entity interacting with the organization doesn't know 'who' the DID belongs to, then the DID isn't as useful.
 
 Linking a DID to a domain solves the initial trust problem by allowing any entity to cryptographically verify the relationship between a DID and a Domain.
 
+## When do you need to update the domain in your DID?
+
+In the event where the domain associated with your company changes, you would also need to change the domain in your DID document that is also published in the ION network. You can update the domain in your DID directly from the Azure AD Verifiable Credential portal.
+
 ## How do we link DIDs and domains?
 
-We make a link between a domain and a DID by implementing an open standard written by the Decentralized Identity Foundation called [Well-Known DID configuration](https://identity.foundation/.well-known/resources/did-configuration/). The verifiable credentials service in Azure Active Directory (Azure AD) helps your organization make the link between the DID and domain by including the domain information that you provided in your DID, and generating the well-known config file:
+We follow the [Well-Known DID configuration](https://identity.foundation/.well-known/resources/did-configuration/) specification when creating the link. The verifiable credentials service links your DID and domain. The service includes the domain information that you provided in your DID, and generates the well-known config file:
 
 1. Azure AD uses the domain information you provide during organization setup to write a Service Endpoint within the DID Document. All parties who interact with your DID can see the domain your DID proclaims to be associated with.  
-
+  
     ```json
     "service": [
       {
@@ -71,25 +69,25 @@ We make a link between a domain and a DID by implementing an open standard writt
     }
     ```
 
-After you have the well-known configuration file, you need to make the file available using the domain name you specified when enabling your AAD for verifiable credentials.
+After you have the well-known configuration file, you need to make the file available using the domain name you specified when you enabled your Azure AD for verifiable credentials.
 
-* Host the well-known DID configuration file at the root of the domain.
-* Do not use redirects.
-* Use https to distribute the configuration file.
+- Host the well-known DID configuration file at the root of the domain.
+- Don't use redirects.
+- Use https to distribute the configuration file.
 
 >[!IMPORTANT]
 >Microsoft Authenticator does not honor redirects, the URL specified must be the final destination URL.
 
-## User experience 
+## User experience in the wallet
 
-When a user is going through an issuance flow or presenting a verifiable credential, they should know something about organization and its DID. If the domain our verifiable credential wallet, Microsoft Authenticator, validates a DID's relationship with the domain in the DID document and presents users with two different experiences depending on the outcome.
+When a user is going through an issuance flow or presenting a verifiable credential, they should know something about the organization and its DID. Microsoft Authenticator, validates a DID's relationship with the domain in the DID document and presents users with two different experiences depending on the outcome.
 
 ## Verified domain
 
 Before Microsoft Authenticator displays a **Verified** icon, a few things need to be true:
 
 * The DID signing the self-issued open ID (SIOP) request must have a Service endpoint for Linked Domain.
-* The root domain does not use a redirect and uses https.
+* The root domain doesn't use a redirect and uses https.
 * The domain listed in the DID Document has a resolvable well-known resource.
 * The well-known resource's verifiable credential is signed with the same DID that was used to sign the SIOP that Microsoft Authenticator used to kick start the flow.
 
@@ -99,19 +97,47 @@ If all of the previously mentioned are true, then Microsoft Authenticator displa
 
 ## Unverified domain
 
-If any of the above are not true, the Microsoft Authenticator will display a full page warning to the user that the domain is unverified, the user is in the middle of a risky transaction and they should proceed with caution. We have chosen to take this route because:
+If any of the above aren't true, Microsoft Authenticator displays a full page warning to the user indicating that the domain is unverified. The user is warned that they are in the middle of a potential risky transaction and they should proceed with caution. We have chosen to take this route because:
 
 * The DID is either not anchored to a domain.
-* The configuration was not set up properly.
-* The DID the user is interacting with is malicious and actually can't prove they own a domain (since they actually don't). Due to this last point, it is imperative that you link your DID to the domain the user is familiar with, to avoid propagating the warning message.
+* The configuration wasn't set up properly.
+* The DID that the user is interacting with could be malicious and actually can't prove that they own the domain linked. 
+
+It is of high importance that you link your DID to a domain recognizable to the user.
 
 ![unverified domain warning in the add credential screen](media/how-to-dnsbind/add-credential-not-verified-authenticated.png)
 
-## Distribute well-known config
+## How do you update the linked domain on your DID?
+
+1. Navigate to the Verifiable Credentials | Getting Started page.  
+1. On the left side of the page select **Domain**.
+1. In the Domain box, enter your new domain name.
+1. Select **Publish**.
+
+:::image type="content" source="media/how-to-dnsbind/publish-update-domain.png" alt-text="Choose the publish button so your changes become":::
+
+It might take up to two hours for your DID document to be updated in the [ION network](https://identity.foundation/ion) with the new domain information. No other changes to the domain are possible before the changes are published.
+
+>[!NOTE]
+>If your changes are successful you will need to [verify](#verified-domain) your newly added domain.
 
-1. Navigate to the Settings page in Verifiable Credentials and choose **Verify this domain**
 
-   ![Verify this domain in settings](media/how-to-dnsbind/settings-verify.png) 
+:::image type="content" source="media/how-to-dnsbind/verification.png" alt-text="You need to verify your domain once that the publishing process completes":::
+
+### Do I need to wait for my DID Doc to be updated to verify my newly added domains?
+
+Yes. You need to wait until the config.json file gets updated before you publish it using your domain's hosting location.  
+
+### How do I know when the linked domain update has successfully completed?
+
+Once the domain changes are publised to ION, the domain section inside the Azure AD Verifiable Credentials service will display `Published` as the status and you should be able to make new changes to the domain. 
+
+>[!IMPORTANT]
+> No changes to your domain are possible while publishing is in progress.
+
+## Distribute well-known config
+
+1. From the Azure portal, navigate to the Verifiable Credentials page. Select **Domain** and choose **Verify this domain**
 
 2. Download the did-configuration.json file shown in the image below.
 
@@ -132,4 +158,4 @@ Congratulations, you now have bootstrapped the web of trust with your DID!
 
 ## Next steps
 
-If during onboarding you enter the wrong domain information or if you decide to change it, you will need to [opt out](how-to-opt-out.md). At this time, we don't support updating your DID document. Opting out and opting back in will create a brand new DID.
+- [How to customize your Azure Active Directory Verifiable Credentials](credential-design.md)

articles/active-directory/verifiable-credentials/media/how-to-dnsbind/publish-update-domain.png

@@ -6,7 +6,7 @@ manager: karenhoran
 ms.service: active-directory
 ms.subservice: verifiable-credentials
 ms.topic: reference
-ms.date: 02/11/2022
+ms.date: 02/22/2022
 ms.custom: references_regions
 ms.author: barclayn
 
@@ -18,13 +18,16 @@ ms.author: barclayn
 
 This article lists the latest features, improvements, and changes in the Azure Active Directory (Azure AD) Verifiable Credentials service.
 
+## March 2022
+- Azure AD Verifiable Credentials customers can now change the [domain linked](how-to-dnsbind.md) to their DID easily from the Azure Portal.
+
 ## February 2022
 
-We are rolling out some important updates to our service that are breaking changes and require Azure AD Verifiable Credentials service reconfiguration and re-issuance of verifiable credentials for end-users.
+We are rolling out some breaking changes to our service. These updates require Azure AD Verifiable Credentials service reconfiguration. End-users need to have their verifiable credentials reissued.
 
 - The Azure AD Verifiable Credentials service can now store and handle data processing in the Azure European region. [More information](whats-new.md?#azure-ad-verifiable-credentials-available-in-europe)
-- Azure AD Verifiable Credentials customers can take advantage of enhancements to credential revocation that add a higher degree of privacy through the implementation of the [W3C Status List 2021](https://w3c-ccg.github.io/vc-status-list-2021/) standard. [More information](whats-new.md?#credential-revocation-with-enhanced-privacy)
-- We made protocol updates in Microsoft Authenticator in the interaction between the Issuer of a verifiable credential and the user preenting the verifiable credential. This update will force all Verifiable Crecentials to be re-issued in Microsoft Authenticator for Android. [More information](whats-new.md?#microsoft-authenticator-android-did-generation-update)
+- Azure AD Verifiable Credentials customers can take advantage of enhancements to credential revocation. These changes add a higher degree of privacy through the implementation of the [W3C Status List 2021](https://w3c-ccg.github.io/vc-status-list-2021/) standard. [More information](whats-new.md?#credential-revocation-with-enhanced-privacy)
+- We made updates to Microsoft Authenticator that change the interaction between the Issuer of a verifiable credential and the user presenting the verifiable credential. This update forces all Verifiable Credentials to be reissued in Microsoft Authenticator for Android. [More information](whats-new.md?#microsoft-authenticator-android-did-generation-update)
 
 >[!IMPORTANT]
 > All Azure AD Verifiable Credential customers receiving a banner notice in the Azure portal need to go through a service reconfiguration before March 31st 2022. On March 31st 2022 tenants that have not been reconfigured will lose access to any previous configuration. Administrators will have to set up a new instance of the Azure AD Verifiable Credential service. Learn more about how to [reconfigure your tenant](verifiable-credentials-faq.md?#how-do-i-reconfigure-the-azure-ad-verifiable-credentials-service).
@@ -34,7 +37,7 @@ We are rolling out some important updates to our service that are breaking chang
 Since the beginning of the Azure AD Verifiable Credentials service public preview, the service has only been available in our Azure North America region. Now, the service is also available in our Azure Europe region.
 
 - New customers with Azure AD European tenants now have their Verifiable Credentials data located and processed in our Azure Europe region.
-- Customers with Azure AD tenants setup in Europe who start using the Azure AD Verifiable Credentials service after February 15, 2022, have their data automatically processed in Europe and don't need to take any further actions.
+- Customers with Azure AD tenants setup in Europe who start using the Azure AD Verifiable Credentials service after February 15, 2022, have their data automatically processed in Europe. There's no need to take any further actions.
 - Customers with Azure AD tenants setup in Europe that started using the Azure AD Verifiable Credentials service before February 15, 2022, are required to reconfigure the service on their tenants before March 31, 2022.
 
 Take the following steps to configure the Verifiable Credentials service in Europe:
@@ -92,20 +95,20 @@ Sample contract file:
   } 
   ```
 
-3. You have to issue new verifiable credentials using your new configuration. All verifiable credentials previously issued will continue to exist as your previous DID will remain resolvable however, they use the previous status endpoint implementation.
+3. You have to issue new verifiable credentials using your new configuration. All verifiable credentials previously issued continue to exist. Your previous DID remains resolvable however, they use the previous status endpoint implementation.
 
 >[!IMPORTANT]
 > You have to reconfigure your Azure AD Verifiable Credential service instance to create your new Identity hub endpoint. You have until March 31st 2022, to schedule and manage the reconfiguration of your deployment. On March 31st, 2022 deployments that have not been reconfigured will lose access to any previous Azure AD Verifiable Credentials service configuration. Administrators will need to set up a new service instance.
 
 ### Microsoft Authenticator Android DID Generation Update
 
-We are making protocol updates in Microsoft Authenticator to support Single Long Form DID, thus deprecating the use of pairwise. With this update your DID in Microsoft Authenticator will be used of every issuer and relaying party exchange. Holders of verifiable crendentials in Microsoft Authenticator for Android must get their verifiable credentials re-issued as any previous credentials are not going to continue working. 
+We are making protocol updates in Microsoft Authenticator to support Single Long Form DID, thus deprecating the use of pairwise. With this update, your DID in Microsoft Authenticator will be used of every issuer and relaying party exchange. Holders of verifiable credentials using Microsoft Authenticator for Android must get their verifiable credentials reissued as any previous credentials aren't going to continue working.
 
 ## December 2021
 
 - We added [Postman collections](https://github.com/Azure-Samples/active-directory-verifiable-credentials/tree/main/Postman) to our samples as a quick start to start using the Request Service REST API.
 - New sample added that demonstrates the integration of [Azure AD Verifiable Credentials with Azure AD B2C](https://github.com/Azure-Samples/active-directory-verifiable-credentials/tree/main/B2C).
-- Fastrack setup sample for setting up the Azure AD Verifiable Credentials services using [PowerShell and an ARM template](https://github.com/Azure-Samples/active-directory-verifiable-credentials/tree/main/ARM).
+- Sample for setting up the Azure AD Verifiable Credentials services using [PowerShell and an ARM template](https://github.com/Azure-Samples/active-directory-verifiable-credentials/tree/main/ARM).
 - Sample Verifiable Credential configuration files to show sample cards for [IDToken](https://github.com/Azure-Samples/active-directory-verifiable-credentials/tree/main/CredentialFiles/IDToken), [IDTokenHit](https://github.com/Azure-Samples/active-directory-verifiable-credentials/tree/main/CredentialFiles/IDTokenHint) and [Self-attested](https://github.com/Azure-Samples/active-directory-verifiable-credentials/tree/main/CredentialFiles/IDTokenHint) claims.
 
 ## November 2021
@@ -116,10 +119,10 @@ Callback types enforcing rules so that URL endpoints for callbacks are reachable
 
 ## October 2021
 
-You can now use [Request Service REST API](get-started-request-api.md) to build applications that can issue and verify credentials from any programming language you're using. This new REST API provides an improved abstraction layer and integration to the Azure AD Verifiable Credentials Service.
+You can now use [Request Service REST API](get-started-request-api.md) to build applications that can issue and verify credentials from any programming language. This new REST API provides an improved abstraction layer and integration to the Azure AD Verifiable Credentials Service.
 
 It's a good idea to start using the API soon, because the NodeJS SDK will be deprecated in the following months. Documentation and samples now use the Request Service REST API. For more information, see [Request Service REST API (preview)](get-started-request-api.md).
 
 ## April 2021
 
-You can now issue [verifiable credentials](decentralized-identifier-overview.md) in Azure AD. This service is useful when you need to represent proof of employment, education, or any other claim, so that the holder of such a credential can decide when, and with whom, to share their credentials. Each credential is signed by using cryptographic keys associated with the decentralized identity that the user owns and controls.
+You can now issue [verifiable credentials](decentralized-identifier-overview.md) in Azure AD. This service is useful when you need to present proof of employment, education, or any other claim. The holder of such a credential can decide when, and with whom, to share their credentials. Each credential is signed by using cryptographic keys associated with the decentralized identity that the user owns and controls.