Merge pull request #231737 from cljung/cljung-vc-post-ga-08

whats new + app access token + clarifications

Author: v-dirichards

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

@@ -24,11 +24,29 @@ The Microsoft Entra Verified ID Admin API enables you to manage all aspects of t
 
 ## Base URL
 
-The Admin API is server over HTTPS. All URLs referenced in the documentation have the following base: `https://verifiedid.did.msidentity.com`. 
+The Admin API is server over HTTPS. All URLs referenced in the documentation have the following base: `https://verifiedid.did.msidentity.com`.
 
 ## Authentication
 
-The API is protected through Azure Active Directory and uses OAuth2 bearer tokens. The app registration needs to have the API Permission for `Verifiable Credentials Service Admin` and then when acquiring the access token the app should use scope `6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access`. The access token must be for a user with the [global administrator](../../active-directory/roles/permissions-reference.md#global-administrator) or the [authentication policy administrator](../../active-directory/roles/permissions-reference.md#authentication-policy-administrator) role.
+The API is protected through Azure Active Directory and uses OAuth2 bearer tokens. The access token can be for a user or for an application.
+
+### User bearer tokens
+
+The app registration needs to have the API Permission for `Verifiable Credentials Service Admin` and then when acquiring the access token the app should use scope `6a8b4b39-c021-437c-b060-5a14a3fd65f3/full_access`. The access token must be for a user with the [global administrator](../../active-directory/roles/permissions-reference.md#global-administrator) or the [authentication policy administrator](../../active-directory/roles/permissions-reference.md#authentication-policy-administrator) role. A user with role [global reader](../../active-directory/roles/permissions-reference.md#global-reader) can perform read-only API calls.
+
+### Application bearer tokens
+
+The `Verifiable Credentials Service Admin` service supports the following application permissions.
+
+| Permission | Description |
+| ---------- | ----------- |
+| VerifiableCredential.Authority.ReadWrite | Permission to read/write authority object(s) |
+| VerifiableCredential.Contract.ReadWrite | Permission to read/write contract object(s) |
+| VerifiableCredential.Credential.Search | Permission to search for a credential to revoke |
+| VerifiableCredential.Credential.Revoke | Permission to [revoke a previously issued credential](how-to-issuer-revoke.md) |
+| VerifiableCredential.Network.Read | Permission to read entries from the [Verified ID Network](vc-network-api.md) |
+
+The app registration needs to have the API Permission for `Verifiable Credentials Service Admin` and permissions required from the above table. When acquiring the access token, via the [client credentials flow](../../active-directory/develop/v2-oauth2-client-creds-grant-flow.md), the app should use scope `6a8b4b39-c021-437c-b060-5a14a3fd65f3/.default`.
 
 ## Onboarding
 
@@ -66,7 +84,7 @@ Content-type: application/json
 }
 ```
 
-Repeatedly calling this API will result in the exact same return message.
+Repeatedly calling this API results in the exact same return message.
 
 ## Authorities
 
@@ -171,7 +189,7 @@ We support two different didModels. One is `ion` and the other supported method
 | `recoveryKeys` | string array | URL to the recovery key  |
 | `encryptionKeys` | string array | URL to the encryption key |
 | `linkedDomainUrls` | string array | Domains linked to this DID |
-| `didDocumentStatus` | string | status of the DID, `published` when it's written to ION otherwise it will be `submitted`|
+| `didDocumentStatus` | string | status of the DID, `published` when it's written to ION otherwise it is `submitted`|
 
 #### Web
 
@@ -287,7 +305,7 @@ Content-type: application/json
 
 ### Create authority
 
-This call creates a new **private key**, recovery key and update key, stores these in the specified Azure Key Vault and sets the permissions to this Key Vault for the verifiable credential service and a create new **DID** with corresponding DID Document and commits that to the ION network.
+This call creates a new **private key**, recovery key and update key, stores these keys in the specified Azure Key Vault and sets the permissions to this Key Vault for the verifiable credential service and a create new **DID** with corresponding DID Document and commits that to the ION network.
 
 #### HTTP request
 
@@ -478,7 +496,7 @@ Content-type: application/json
 Accepted
 ```
 
-The didDocumentStatus will switch to `submitted` it will take a while before the change is committed to the ION network.
+The didDocumentStatus switches to `submitted` it will take a while before the change is committed to the ION network.
 
 If you try to submit a change before the operation is completed, you'll get the following error message:
 
@@ -585,7 +603,7 @@ Content-type: application/json
 }
 ```
 
-Save this result with the file name did-configuration.json and upload this file to the correct folder and website. If you specify a domain not linked to this DID/DID Document, you'll receive an error:
+Save this result with the file name did-configuration.json and upload this file to the correct folder and website. If you specify a domain not linked to this DID/DID Document, you receive an error:
 
 ```
 HTTP/1.1 400 Bad Request
@@ -834,7 +852,7 @@ The response contains the following properties
 |`vc`| vcType array | types for this contract |
 |`customStatusEndpoint`| [customStatusEndpoint] (#customstatusendpoint-type) (optional) | status endpoint to include in the verifiable credential for this contract |
 
-If the property `customStatusEndpoint` property isn't specified then the `anonymous` status endpoint is used.
+If the property `customStatusEndpoint` property isn't specified, then the `anonymous` status endpoint is used.
 
 #### attestations type
 
@@ -1081,7 +1099,7 @@ example message:
 ### Create contract
 
 When creating a contract the name has to be unique in the tenant. In case you have created multiple authorities, the contract name has to be unique across all authorities.
-The name of the contract will be part of the contract URL which is used in the issuance requests.
+The name of the contract will be part of the contract URL, which is used in the issuance requests.
 
 #### HTTP request
 

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

@@ -26,18 +26,18 @@ To verify domain ownership to your DID, you need to have completed the following
 
 ## Verify domain ownership and distribute did-configuration.json file
 
-The domain you will verify ownership of to your DID is defined in the organizational settings.
+The domain you verify ownership of to your DID is defined in the [overview section](verifiable-credentials-configure-tenant.md#set-up-verified-id). The domain needs to be a domain under your control and it should be in the format `https://www.example.com/`. 
 
 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.
+1. Copy or download the `did-configuration.json` file.
 
    ![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. Host the `did-configuration.json` file at the location specified. Example: If you specified domain `https://www.example.com` the file need to be hosted at this URL `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.
 
@@ -50,7 +50,7 @@ There can be no additional path in the URL other than the .well-known path name.
 
 ## 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.
+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 does 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 can't be requested anonymously in a browser or via tools such as `curl`, without warnings or errors, the portal can't 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.
@@ -124,20 +124,20 @@ It is of high importance that you link your DID to a domain recognizable to the
 
 ## How do you update the linked domain on your DID?
 
-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. 
+If your trust system is Web, then updating your linked domain isn't 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?
 
-If the trust system is ION, once the domain changes are published to ION, the domain section inside the Microsoft Entra Verified ID service will display Published as the status and you should be able to make new changes to the domain. If the trust system is Web, the changes are public as soon as you replace the did-configuration.json file on your web server.
+If the trust system is ION, once the domain changes are published to ION, the domain section inside the Microsoft Entra Verified ID service displays Published as the status and you should be able to make new changes to the domain. If the trust system is Web, the changes are public as soon as you replace the did-configuration.json file on your web server.
 
 >[!IMPORTANT]
 > No changes to your domain are possible while publishing is in progress.
 
 ## 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.
+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 is, other than it contains your storage account name as part of it's hostname.
 
-Follow these steps to quickly set up a domain to use for Linked Domain:
+Follow these steps to quickly setup a domain to use for Linked Domain:
 
 1. Create an **Azure Storage account**. During storage account creation, choose StorageV2 (general-purpose v2 account) and Locally redundant storage (LRS).
 1. Go to that Storage Account and select **Static website** in the left hand menu and enable static website. If you can't see the **Static website** menu item, you didn't create a **V2** storage account.

articles/active-directory/verifiable-credentials/how-to-use-quickstart-verifiedemployee.md

@@ -67,13 +67,13 @@ When you select + Add credential in the portal, you get the option to launch two
 
 ![Quickstart start screen](media/how-to-use-quickstart-verifiedemployee/verifiable-credentials-configure-verifiedemployee-quickstart.png)
 
-In the next screen, you enter some of the Display definitions, like logo url, text and background color. Since the credential is a managed credential with directory based claims, rules definitions are predefined. You don't need to enter rule definition details. The credential type will be **VerifiedEmployee** and the claims from the user’s profile are pre-set. Select Create to create the credential.
+In the next screen, you enter some of the Display definitions, like logo url, text and background color. Since the credential is a managed credential with directory based claims, rules definitions are predefined and can't be changed. You don't need to enter rule definition details. The credential type will be **VerifiedEmployee** and the claims from the user’s profile are pre-set. Select Create to create the credential.
 
 ![Card styling](media/how-to-use-quickstart-verifiedemployee/verifiable-credentials-configure-verifiedemployee-styling.png)
 
 ## Claims schema for Verified employee credential
 
-All of the claims in the Verified employee credential come from attributes in the [user's profile](/graph/api/resources/user) in Azure AD for the issuing tenant. All claims, except photo, come from the Microsoft Graph Query [https://graph.microsoft.com/v1.0/me](/graph/api/user-get). The photo claim comes from the value returned from the Microsoft Graph Query [https://graph.microsoft.com/v1.0/me/photo/$value.](/graph/api/profilephoto-get)
+All of the claims in the Verified employee credential come from attributes in the [user's profile](/graph/api/resources/user) in Azure AD for the issuing tenant. You can't modify the set of claims. All claims, except photo, come from the Microsoft Graph Query [https://graph.microsoft.com/v1.0/me](/graph/api/user-get). The photo claim comes from the value returned from the Microsoft Graph Query [https://graph.microsoft.com/v1.0/me/photo/$value.](/graph/api/profilephoto-get)
 
 | Claim | Directory attribute | Value  |
 |---------|---------|---------|

articles/active-directory/verifiable-credentials/issuance-request-api.md

@@ -109,7 +109,7 @@ The payload contains the following properties:
 | `type` |  string |  The verifiable credential type. Should match the type as defined in the verifiable credential manifest. For example: `VerifiedCredentialExpert`. For more information, see [Create the verified credential expert card in Azure](verifiable-credentials-configure-issuer.md). |
 | `manifest` | string| The URL of the verifiable credential manifest document. For more information, see [Gather credentials and environment details to set up your sample application](verifiable-credentials-configure-issuer.md).|
 | `claims` | string| Optional. Used for the `ID token hint` flow to include a collection of assertions made about the subject in the verifiable credential. For PIN code flow, it's important that you provide the user's first name and last name. For more information, see [Verifiable credential names](verifiable-credentials-configure-issuer.md#verifiable-credential-names). |
-| `pin` | [PIN](#pin-type)| Optional. A PIN number to provide extra security during issuance. For PIN code flow, this property is required. You generate a PIN code, and present it to the user in your app. The user must provide the PIN code that you generated. |
+| `pin` | [PIN](#pin-type)| Optional. PIN code can only be used with the [ID token hint](rules-and-display-definitions-model.md#idtokenhintattestation-type) attestation flow. A PIN number to provide extra security during issuance. You generate a PIN code, and present it to the user in your app. The user must provide the PIN code that you generated. |
 
 There are currently four claims attestation types that you can send in the payload. Microsoft Entra Verified ID uses four ways to insert claims into a verifiable credential and attest to that information with the issuer's DID. The following are the four types: