Merge branch 'main' into Broken-link-fix-erd

Author: pritamso

articles/active-directory/verifiable-credentials/TOC.yml

@@ -52,31 +52,33 @@
     href: how-use-vcnetwork.md
   - name: Using the Request Service REST API
     href: get-started-request-api.md
-  - name: Link your domain to your DID
-    href: how-to-dnsbind.md
-  - name: Register your website ID
+  - name: Register decentralized ID
     href: how-to-register-didwebsite.md
+  - name: Verify domain ownership
+    href: how-to-dnsbind.md
   - name: Revoke a verifiable credential
     href: how-to-issuer-revoke.md
   - name: Opt out of Verified ID service
     href: how-to-opt-out.md
-  - name: Partner integration
+  - name: Partner gallery
     items:
-    - name: Partner gallery
-      href: partner-gallery.md
-    - name: Au10tix
-      href: howto-verifiable-credentials-partner-au10tix.md
-    - name: LexisNexis
-      href: howto-verifiable-credentials-partner-lexisnexis.md
-    - name: Vu
-      href: partner-vu.md
+    - name: IDV partners
+      items:
+      - name: IDV partner network
+        href: partner-gallery.md
+      - name: Au10tix
+        href: howto-verifiable-credentials-partner-au10tix.md
+      - name: LexisNexis
+        href: howto-verifiable-credentials-partner-lexisnexis.md
+      - name: Vu
+        href: partner-vu.md
+    - name: Services partners
+      href: services-partners.md
 - name: Samples
   expanded: true
   items:
   - name: Sample Applications
     href: https://github.com/Azure-Samples/active-directory-verifiable-credentials
-#  - name: Sample Issuer
-#   href: 
   - name: End to End Demo
     href: https://woodgroveemployee.azurewebsites.net/
 - name: Reference

articles/active-directory/verifiable-credentials/admin-api.md

@@ -408,7 +408,7 @@ This method can be used to update the display name of this specific instance of
 
 #### HTTP request
 
-`POST /v1.0/verifiableCredentials/authorities/:authorityId`
+`PATCH /v1.0/verifiableCredentials/authorities/:authorityId`
 
 Replace the value of `:authorityId` with the value of the authority ID you want to update.
 
@@ -545,7 +545,7 @@ Although it is technically possible to publish multiple domains, we currently on
 
 ### Well-known DID configuration
 
-The `generateWellknownDidConfiguration` method generates the signed did-configuration.json file. The file must be uploaded to the `.well-known` folder in the root of the website hosted for the domain in the linked domain of this verifiable credential instance. Instructions can be found [here](how-to-dnsbind.md#distribute-well-known-config).
+The `generateWellknownDidConfiguration` method generates the signed did-configuration.json file. The file must be uploaded to the `.well-known` folder in the root of the website hosted for the domain in the linked domain of this verifiable credential instance. Instructions can be found [here](how-to-dnsbind.md#verify-domain-ownership-and-distribute-did-configurationjson-file).
 
 #### HTTP request
 
@@ -829,7 +829,7 @@ The response contains the following properties
 
 | Property | Type | Description |
 | -------- | -------- | -------- |
-|`attestations`| [attestions](#attestations-type)| describing supported inputs for the rules |
+|`attestations`| [attestations](#attestations-type)| describing supported inputs for the rules |
 |`validityInterval` | number | this value shows the lifespan of the credential |
 |`vc`| vcType array | types for this contract |
 |`customStatusEndpoint`| [customStatusEndpoint] (#customstatusendpoint-type) (optional) | status endpoint to include in the verifiable credential for this contract |
@@ -840,8 +840,8 @@ If the property `customStatusEndpoint` property isn't specified then the `anonym
 
 | Property | Type | Description |
 | -------- | -------- | -------- |
-|`idTokens`| [idTokenAttestation](#idtokenattestation-type) (array) (optional) | describes id token inputs|
-|`idTokenHints`| [idTokenHintAttestation](#idtokenhintattestation-type) (array) (optional) | describes id token hint inputs |
+|`idTokens`| [idTokenAttestation](#idtokenattestation-type) (array) (optional) | describes ID token inputs|
+|`idTokenHints`| [idTokenHintAttestation](#idtokenhintattestation-type) (array) (optional) | describes ID token hint inputs |
 |`presentations`| [verifiablePresentationAttestation](#verifiablepresentationattestation-type) (array) (optional) | describes verifiable presentations inputs |
 |`selfIssued`| [selfIssuedAttestation](#selfissuedattestation-type) (array) (optional) | describes self issued inputs |
 |`accessTokens`| [accessTokenAttestation](#accesstokenattestation-type) (array) (optional) | describes access token inputs |

articles/active-directory/verifiable-credentials/get-started-request-api.md

@@ -285,7 +285,7 @@ To issue or verify a verifiable credential, follow these steps:
 
 1. Submit the request to the Request Service REST API.
 
-The Request Service API returns an HTTP Status Code `201 Created` on a successful call. If the API call returns an error, please check the [error reference documentation](error-codes.md). //TODO
+The Request Service API returns an HTTP Status Code `201 Created` on a successful call. If the API call returns an error, please check the [error reference documentation](error-codes.md).
 
 ## Issuance request example
 

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

@@ -13,32 +13,59 @@ ms.author: barclayn
 #Customer intent: Why are we doing this?
 ---
 
-# Link your domain to your Decentralized Identifier (DID)
+# Verify domain ownership to your Decentralized Identifier (DID)
 
 [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)]
 
 
 ## Prerequisites
 
-To link your DID to your domain, you need to have completed the following.
+To verify domain ownership to your DID, you need to have completed the following.
 
 - Complete the [Getting Started](get-started-verifiable-credentials.md) and subsequent [tutorial set](enable-your-tenant-verifiable-credentials.md).
 
-## Why do we need to link our DID to our domain?
+## Verify domain ownership and distribute did-configuration.json file
 
-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.
+The domain you will verify ownership of to your DID is defined in the organizational settings.
 
-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.
+1. From the Azure portal, navigate to the VerifiedID page.
+
+1. Select **Setup**, then **Verify domain ownership** and choose **Verify** for the domain
+
+1. Copy or download the `did-configuration.json` file shown in the image below.
+
+   ![Screenshot of download well-known config.](media/how-to-dnsbind/verify-download.png) 
+
+1. Host the `did-configuration.json` file at the location specified. Example: `https://www.example.com/.well-known/did-configuration.json`
+There can be no additional path in the URL other than the .well-known path name.
+
+1. When the `did-configuration.json` is publicly available at the .well-known/did-configuration.json URL, verify it by pressing the **Refresh verification status** button.
+
+   ![Screenshot of verified well-known config.](media/how-to-dnsbind/verify-download-verified.png) 
+
+1. Test out issuing or presenting with Microsoft Authenticator to validate. Make sure the setting in Authenticator 'Warn about unsafe apps' is toggled on.
+
+>[!NOTE]
+>By default, 'Warn about unsafe apps' is turned on.
+
+## How can I verify that the verification is working?
+
+The portal verifies that the `did-configuration.json` is reachable over public internet and valid when you click the **Refresh verification status** button. Microsoft Authenticator do not honor http redirects. You should also consider verifying that you can request that URL in a browser to avoid errors like not using https, a bad SSL certificate or the URL not being public. If the `did-configuration.json` file cannot be requested anonymously in a browser or via tools such as `curl`, without warnings or errors, the portal will not be able to complete the **Refresh verification status** step either.
 
-## When do you need to update the domain in your DID?
+>[!NOTE]
+> If you are experiencing problems refreshing your verification status, you can troubleshoot it via running `curl -Iv https://yourdomain.com/.well-known/did-configuration.json` on an machine with Ubuntu OS. Windows Subsystem for Linux with Ubuntu will work too. If curl fails, refreshing the verification status will not work.
 
-In the event where the domain associated with your company changes, you would also need to change the domain in your DID document. You can update the domain in your DID directly from the [Microsoft Entra Verified ID blade in the Azure portal](https://portal.azure.com/#view/Microsoft_AAD_DecentralizedIdentity/InitialMenuBlade/~/domainUpdateBlade).
+## Why do we need to verify domain ownership of our DID?
 
-## How do we link DIDs and domains?
+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.
 
-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:
+## How does VerifiedID link DIDs and domains?
 
-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.  
+VerifiedID follows 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. VerifiedID 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": [
@@ -54,7 +81,7 @@ We follow the [Well-Known DID configuration](https://identity.foundation/.well-k
     ]
     ```
 
-2. The verifiable credential service in Azure AD generates a compliant well-known configuration resource that you can host on your domain. The configuration file includes a self-issued verifiable credential of credentialType 'DomainLinkageCredential' signed with your DID that has an origin of your domain. Here's an example of the config doc that is stored at the root domain URL.
+2. The verifiable credential service in VerifiedID generates a compliant well-known configuration resource that you must host on your domain. The configuration file includes a self-issued verifiable credential of credentialType `DomainLinkageCredential`, signed with your DID, that has an origin of your domain. Here's an example of the config doc that is stored at the root domain URL.
 
 
     ```json
@@ -66,15 +93,6 @@ We follow the [Well-Known DID configuration](https://identity.foundation/.well-k
     }
     ```
 
-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.
-- 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 in the wallet
 
 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.
@@ -90,7 +108,7 @@ Before Microsoft Authenticator displays a **Verified** icon, a few things need t
 
 If all of the previously mentioned are true, then Microsoft Authenticator displays a verified page and includes the domain that was validated.
 
-![new permission request](media/how-to-dnsbind/new-permission-request.png) 
+![Screenshot of new permission request.](media/how-to-dnsbind/new-permission-request.png) 
 
 ## Unverified domain
 
@@ -102,28 +120,11 @@ If any of the above aren't true, Microsoft Authenticator displays a full page wa
 
 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)
+![Screenshot of unverified domain warning in the add credential screen.](media/how-to-dnsbind/add-credential-not-verified-authenticated.png)
 
 ## How do you update the linked domain on your DID?
 
-1. Navigate to the Verified ID in the Azure portal.  
-1. On the left side of the page, select **Registration**.
-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":::
-
-If the trust system is ION, 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. If the trust system is Web, the changes are public as soon as you replace the did-configuration.json file on your web server.
-
->[!NOTE]
->If your changes are successful you will need to [verify](#verified-domain) your newly added domain.
-
-
-:::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.  
+If your trust system is Web, then updating your linked domain is not supported. You have to opt-out and re-onboard. If your trust system is ION, you can update the linked domain via redoing the **Verify domain ownership** step. 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. 
 
 ### How do I know when the linked domain update has successfully completed?
 
@@ -132,34 +133,6 @@ If the trust system is ION, once the domain changes are published to ION, the do
 >[!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 Verified ID page. Select **Registration** and choose **Verify** for the domain
-
-2. Download the did-configuration.json file shown in the image below.
-
-   ![Download well known config](media/how-to-dnsbind/verify-download.png) 
-
-3. Copy the linked_did value (JWT), open [https://jwt.ms/](https://www.jwt.ms), paste the JWT, and validate the domain is correct.
-
-4. Copy your DID and open the [ION Network Explorer](https://identity.foundation/ion/explorer) to verify the same domain is included in the DID Document. 
-
-5. Host the well-known config resource at the location specified. Example: `https://www.example.com/.well-known/did-configuration.json`
-
-6. Test out issuing or presenting with Microsoft Authenticator to validate. Make sure the setting in Authenticator 'Warn about unsafe apps' is toggled on.
-
->[!NOTE]
->By default, 'Warn about unsafe apps' is turned on.
-
-Congratulations, you now have bootstrapped the web of trust with your DID!
-
-## How can I verify that the verification is working?
-
-The portal verifies that the `did-configuration.json` is reachable and correct when you click the **Refresh verification status** button. You should also consider verifying that you can request that URL in a browser to avoid errors like not using https, a bad SSL certificate or the URL not being public. If the `did-configuration.json` file cannot be requested anonymously in a browser or via tools such as `curl`, without warnings or errors, the portal will not be able to complete the **Refresh verification status** step either.
-
->[!NOTE]
-> If you are experiencing problems refreshing your verification status, you can troubleshoot it via running `curl -Iv https://yourdomain.com/.well-known/did-configuration.json` on an machine with Ubuntu OS. Windows Subsystem for Linux with Ubuntu will work too. If curl fails, refreshing the verification status will not work.
-
 ## Linked Domain domain made easy for developers
 
 The easiest way for a developer to get a domain to use for linked domain is to use Azure Storage's static website feature. You can't control what the domain name will be, other than it will contain your storage account name as part of it's hostname.