diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index f809019fa50da..148916f914a1b 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -813,8 +813,8 @@ "branch_mapping": {} }, { - "path_to_root": "azure-spring-cloud-reference-architecture", - "url": "https://github.com/Azure/azure-spring-cloud-reference-architecture", + "path_to_root": "azure-spring-apps-reference-architecture", + "url": "https://github.com/Azure/azure-spring-apps-reference-architecture", "branch": "main", "branch_mapping": {} }, @@ -1016,9 +1016,11 @@ "articles/mysql/.openpublishing.redirection.mysql.json", "articles/container-apps/.openpublishing.redirection.container-apps.json", "articles/spring-cloud/.openpublishing.redirection.spring-cloud.json", + "articles/spring-apps/.openpublishing.redirection.spring-apps.json", "articles/load-testing/.openpublishing.redirection.azure-load-testing.json", "articles/azure-video-indexer/.openpublishing.redirection.azure-video-indexer.json", "articles/machine-learning/.openpublishing.redirection.machine-learning.json", - "articles/static-web-apps/.openpublishing.redirection.static-web-apps.json" + "articles/static-web-apps/.openpublishing.redirection.static-web-apps.json", + ".openpublishing.redirection.virtual-desktop.json" ] } diff --git a/.openpublishing.redirection.active-directory.json b/.openpublishing.redirection.active-directory.json index 8558013e3b889..fcb05a93f1d8a 100644 --- a/.openpublishing.redirection.active-directory.json +++ b/.openpublishing.redirection.active-directory.json @@ -10830,7 +10830,13 @@ "source_path": "articles/active-directory/manage-apps/howto-enforce-signed-saml-authentication.md", "redirect_url": "/azure/active-directory/manage-apps/howto-saml-token-encryption", "redirect_document_id": true + }, + { + "source_path_from_root": "/articles/active-directory/manage-apps/recover-deleted-apps-faq.md", + "redirect_url": "/azure/active-directory/manage-apps/delete-recover-faq", + "redirect_document_id": false } + ] } diff --git a/.openpublishing.redirection.azure-monitor.json b/.openpublishing.redirection.azure-monitor.json index 43d85e6072615..2e749f838d83c 100644 --- a/.openpublishing.redirection.azure-monitor.json +++ b/.openpublishing.redirection.azure-monitor.json @@ -430,6 +430,11 @@ "source_path_from_root": "/articles/azure-monitor/insights/key-vault-insights-overview.md" , "redirect_url": "/azure/key-vault/key-vault-insights-overview", "redirect_document_id": false + }, + { + "source_path_from_root": "/articles/azure-monitor/app/cloudservices.md" , + "redirect_url": "/azure/azure-monitor/app/azure-web-apps-net-core", + "redirect_document_id": false } ] } diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index a94da9b063b7e..3695575ec0d1c 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -24728,11 +24728,6 @@ "redirect_url": "/azure/traffic-manager/traffic-manager-manage-profiles", "redirect_document_id": false }, - { - "source_path_from_root": "/articles/virtual-desktop/connect-windows-7-and-10.md", - "redirect_url": "/azure/virtual-desktop/connect-windows-7-10", - "redirect_document_id": true - }, { "source_path_from_root": "/articles/troubleshoot-client-connection.md", "redirect_url": "/azure/virtual-desktop/troubleshoot-client", diff --git a/.openpublishing.redirection.virtual-desktop.json b/.openpublishing.redirection.virtual-desktop.json new file mode 100644 index 0000000000000..c33009d5b196e --- /dev/null +++ b/.openpublishing.redirection.virtual-desktop.json @@ -0,0 +1,9 @@ +{ + "redirections": [ + { + "source_path_from_root": "/articles/virtual-desktop/connect-windows-7-and-10.md", + "redirect_url": "/azure/virtual-desktop/connect-windows-7-10", + "redirect_document_id": true + } + ] +} diff --git a/articles/active-directory-b2c/authorization-code-flow.md b/articles/active-directory-b2c/authorization-code-flow.md index a0afe04f8f87e..b6d77bbb7f88f 100644 --- a/articles/active-directory-b2c/authorization-code-flow.md +++ b/articles/active-directory-b2c/authorization-code-flow.md @@ -8,7 +8,7 @@ manager: CelesteDG ms.service: active-directory ms.workload: identity ms.topic: conceptual -ms.date: 04/12/2022 +ms.date: 07/29/2022 ms.author: kengaderdus ms.subservice: B2C ms.custom: fasttrack-edit @@ -60,7 +60,7 @@ client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 |{tenant}| Required | Name of your Azure AD B2C tenant| | {policy} | Required | The user flow to be run. Specify the name of a user flow you've created in your Azure AD B2C tenant. For example: `b2c_1_sign_in`, `b2c_1_sign_up`, or `b2c_1_edit_profile`. | | client_id |Required |The application ID assigned to your app in the [Azure portal](https://portal.azure.com). | -| response_type |Required |The response type, which must include `code` for the authorization code flow. | +| response_type |Required |The response type, which must include `code` for the authorization code flow. You can receive an ID token if you include it in the response type, such as `code+id_token`, and in this case, the scope needs to include `openid`.| | redirect_uri |Required |The redirect URI of your app, where authentication responses are sent and received by your app. It must exactly match one of the redirect URIs that you registered in the portal, except that it must be URL-encoded. | | scope |Required |A space-separated list of scopes. The `openid` scope indicates a permission to sign in the user and get data about the user in the form of ID tokens. The `offline_access` scope is optional for web applications. It indicates that your application will need a *refresh token* for extended access to resources.The client-id indicates the token issued are intended for use by Azure AD B2C registered client. The `https://{tenant-name}/{app-id-uri}/{scope}` indicates a permission to protected resources, such as a web API. For more information, see [Request an access token](access-tokens.md#scopes). | | response_mode |Recommended |The method that you use to send the resulting authorization code back to your app. It can be `query`, `form_post`, or `fragment`. | diff --git a/articles/active-directory-b2c/azure-ad-external-identities-videos.md b/articles/active-directory-b2c/azure-ad-external-identities-videos.md index d0291bb3d5d1e..4c7a0c14bfc05 100644 --- a/articles/active-directory-b2c/azure-ad-external-identities-videos.md +++ b/articles/active-directory-b2c/azure-ad-external-identities-videos.md @@ -29,7 +29,7 @@ Get a deeper view into the features and technical aspects of the Azure AD B2C se |[Azure AD B2C sign-up sign-in](https://www.youtube.com/watch?v=c8rN1ZaR7wk&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=6&t=2s) 10:25 | [:::image type="icon" source="./media/external-identities-videos/customer-sign-up-sign-in.png" border="false":::](https://www.youtube.com/watch?v=c8rN1ZaR7wk&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=6) | [Azure AD B2C single sign on and self service password reset](https://www.youtube.com/watch?v=kRV-7PSLK38&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=7) 8:40 | [:::image type="icon" source="./media/external-identities-videos/single-sign-on.png" border="false":::](https://www.youtube.com/watch?v=kRV-7PSLK38&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=7) | | [Application and identity migration to Azure AD B2C](https://www.youtube.com/watch?v=Xw_YwSJmhIQ&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=9) 10:34 | [:::image type="icon" source="./media/external-identities-videos/identity-migration-aad-b2c.png" border="false":::](https://www.youtube.com/watch?v=Xw_YwSJmhIQ&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=9) | [Build resilient and scalable flows using Azure AD B2C](https://www.youtube.com/watch?v=8f_Ozpw9yTs&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=12) 16:47 | [:::image type="icon" source="./media/external-identities-videos/b2c-scalable-flows.png" border="false":::](https://www.youtube.com/watch?v=8f_Ozpw9yTs&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=12) | | [Building a custom CIAM solution with Azure AD B2C and ISV alliances](https://www.youtube.com/watch?v=UZjiGDD0wa8&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=8) 10:01 | [:::image type="icon" source="./media/external-identities-videos/build-custom-b2c-solution.png" border="false":::](https://www.youtube.com/watch?v=UZjiGDD0wa8&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=8) | [Protecting Web APIs with Azure AD B2C](https://www.youtube.com/watch?v=wuUu71RcsIo&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=10) 19:03 | [:::image type="icon" source="./media/external-identities-videos/protecting-web-apis.png" border="false":::](https://www.youtube.com/watch?v=wuUu71RcsIo&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=10) | -| [Integration of SAML with Azure AD B2C](https://www.youtube.com/watch?v=r2TIVBCm7v4&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=11) 9:09 | [:::image type="icon" source="./media/external-identities-videos/saml-integration.png" border="false":::](https://www.youtube.com/watch?v=r2TIVBCm7v4&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=11) | +| [Integration of SAML with Azure AD B2C](https://www.youtube.com/watch?v=r2TIVBCm7v4&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=11) 9:09 | [:::image type="icon" source="./media/external-identities-videos/saml-integration.png" border="false":::](https://www.youtube.com/watch?v=r2TIVBCm7v4&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=11) | [Azure AD B2C Identity Protection and Conditional Access](https://www.youtube.com/watch?v=frn5jVqbmUo&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=15) 14:44 | [:::image type="icon" source="./media/external-identities-videos/identity-protection-and-conditional-access.png" border="false":::](https://www.youtube.com/watch?v=frn5jVqbmUo&list=PL3ZTgFEc7LyuJ8YRSGXBUVItCPnQz3YX0&index=15) ## Azure Active Directory B2C how to series diff --git a/articles/active-directory-b2c/media/external-identities-videos/identity-protection-and-conditional-access.png b/articles/active-directory-b2c/media/external-identities-videos/identity-protection-and-conditional-access.png new file mode 100644 index 0000000000000..997a11d5c7404 Binary files /dev/null and b/articles/active-directory-b2c/media/external-identities-videos/identity-protection-and-conditional-access.png differ diff --git a/articles/active-directory-b2c/technicalprofiles.md b/articles/active-directory-b2c/technicalprofiles.md index aa7b6e11cbe9c..0bcc4aba0d306 100644 --- a/articles/active-directory-b2c/technicalprofiles.md +++ b/articles/active-directory-b2c/technicalprofiles.md @@ -249,6 +249,7 @@ The **InputClaim** element contains the following attributes: | --------- | -------- | ----------- | | ClaimTypeReferenceId | Yes | The identifier of a claim type. The claim is already defined in the claims schema section in the policy file or parent policy file. | | DefaultValue | No | A default value to use to create a claim if the claim indicated by ClaimTypeReferenceId doesn't exist so that the resulting claim can be used as an InputClaim element by the technical profile. | +|AlwaysUseDefaultValue |No |Forces the use of the default value. | | PartnerClaimType | No | The identifier of the claim type of the external partner that the specified policy claim type maps to. If the PartnerClaimType attribute isn't specified, the specified policy claim type is mapped to the partner claim type of the same name. Use this property when your claim type name is different from the other party. An example is if the first claim name is *givenName*, while the partner uses a claim named *first_name*. | ## Display claims diff --git a/articles/active-directory/app-provisioning/on-premises-scim-provisioning.md b/articles/active-directory/app-provisioning/on-premises-scim-provisioning.md index 43912ba21b335..25f1f2555cb0a 100644 --- a/articles/active-directory/app-provisioning/on-premises-scim-provisioning.md +++ b/articles/active-directory/app-provisioning/on-premises-scim-provisioning.md @@ -23,27 +23,31 @@ The Azure Active Directory (Azure AD) provisioning service supports a [SCIM 2.0] - Administrator role for installing the agent. This task is a one-time effort and should be an Azure account that's either a hybrid administrator or a global administrator. - Administrator role for configuring the application in the cloud (application administrator, cloud application administrator, global administrator, or a custom role with permissions). -## On-premises app provisioning to SCIM-enabled apps -To provision users to SCIM-enabled apps: - - 1. [Download](https://aka.ms/OnPremProvisioningAgent) the provisioning agent and copy it onto the virtual machine or server that your SCIM endpoint is hosted on. - 1. Open the provisioning agent installer, agree to the terms of service, and select **Install**. - 1. Open the provisioning agent wizard, and select **On-premises provisioning** when prompted for the extension you want to enable. - 1. Provide credentials for an Azure AD administrator when you're prompted to authorize. Hybrid administrator or global administrator is required. - 1. Select **Confirm** to confirm the installation was successful. - 1. Navigate to the Azure Portal and add the **On-premises SCIM app** from the [gallery](../../active-directory/manage-apps/add-application-portal.md). - 1. Select **On-Premises Connectivity**, and download the provisioning agent. 1. Go back to your application, and select **On-Premises Connectivity**. - 1. Select the agent that you installed from the dropdown list, and select **Assign Agent(s)**. - 1. Wait 20 minutes prior to completing the next step, to provide time for the agent assignment to complete. - 1. Provide the URL for your SCIM endpoint in the **Tenant URL** box. An example is https://localhost:8585/scim. - ![Screenshot that shows assigning an agent.](./media/on-premises-scim-provisioning/scim-2.png) - 1. Select **Test Connection**, and save the credentials. Use the steps [here](on-premises-ecma-troubleshoot.md#troubleshoot-test-connection-issues) if you run into connectivity issues. - 1. Configure any [attribute mappings](customize-application-attributes.md) or [scoping](define-conditional-rules-for-provisioning-user-accounts.md) rules required for your application. - 1. Add users to scope by [assigning users and groups](../../active-directory/manage-apps/add-application-portal-assign-users.md) to the application. - 1. Test provisioning a few users [on demand](provision-on-demand.md). - 1. Add more users into scope by assigning them to your application. - 1. Go to the **Provisioning** pane, and select **Start provisioning**. - 1. Monitor using the [provisioning logs](../../active-directory/reports-monitoring/concept-provisioning-logs.md). +## Deploying Azure AD provisioning agent +The Azure AD Provisioning agent can be deployed on the same server hosting a SCIM enabled application, or a seperate server, providing it has line of sight to the application's SCIM endpoint. A single agent also supports provision to multiple applications hosted locally on the same server or seperate hosts, again as long as each SCIM endpoint is reachable by the agent. + + 1. [Download](https://aka.ms/OnPremProvisioningAgent) the provisioning agent and copy it onto the virtual machine or server that your SCIM application endpoint is hosted on. + 2. Run the provisioning agent installer, agree to the terms of service, and select **Install**. + 3. Once installed, locate and launch the **AAD Connect Provisioning Agent wizard**, and when prompted for an extensions select **On-premises provisioning** + 4. For the agent to register itself with your tenant, provide credentials for an Azure AD admin with Hybrid administrator or global administrator permissions. + 5. Select **Confirm** to confirm the installation was successful. + +## Provisioning to SCIM-enabled application +Once the agent is installed, no further configuration is necesary on-prem, and all provisioning configurations are then managed from the portal. Repeat the below steps for every on-premises application being provisioned via SCIM. + + 1. In the Azure portal navigate to the Enterprise applications and add the **On-premises SCIM app** from the [gallery](../../active-directory/manage-apps/add-application-portal.md). + 2. From the left hand menu navigate to the **Provisioning** option and select **Get started**. + 3. Select **Automatic** from the dropdown list and expand the **On-Premises Connectivity** option. + 4. Select the agent that you installed from the dropdown list and select **Assign Agent(s)**. + 5. Now either wait 10 minutes or restart the **Microsoft Azure AD Connect Provisioning Agent** before proceeding to the next step & testing the connection. + 6. In the **Tenant URL** field, provide the SCIM endpoint URL for your application. The URL is typically unique to each target application and must be resolveable by DNS. An example for a scenario where the agent is installed on the same host as the application is https://localhost:8585/scim ![Screenshot that shows assigning an agent.](./media/on-premises-scim-provisioning/scim-2.png) + 7. Select **Test Connection**, and save the credentials. The application SCIM endpoint must be actively listening for inbound provisioning requests, otherwise the test will fail. Use the steps [here](on-premises-ecma-troubleshoot.md#troubleshoot-test-connection-issues) if you run into connectivity issues. + 8. Configure any [attribute mappings](customize-application-attributes.md) or [scoping](define-conditional-rules-for-provisioning-user-accounts.md) rules required for your application. + 9. Add users to scope by [assigning users and groups](../../active-directory/manage-apps/add-application-portal-assign-users.md) to the application. + 10. Test provisioning a few users [on demand](provision-on-demand.md). + 11. Add more users into scope by assigning them to your application. + 12. Go to the **Provisioning** pane, and select **Start provisioning**. + 13. Monitor using the [provisioning logs](../../active-directory/reports-monitoring/concept-provisioning-logs.md). ## Additional requirements * Ensure your [SCIM](https://techcommunity.microsoft.com/t5/identity-standards-blog/provisioning-with-scim-getting-started/ba-p/880010) implementation meets the [Azure AD SCIM requirements](use-scim-to-provision-users-and-groups.md). diff --git a/articles/active-directory/develop/howto-remove-app.md b/articles/active-directory/develop/howto-remove-app.md index c2f5dfe9bdc35..4a2399e086ce8 100644 --- a/articles/active-directory/develop/howto-remove-app.md +++ b/articles/active-directory/develop/howto-remove-app.md @@ -9,7 +9,7 @@ ms.service: active-directory ms.subservice: develop ms.topic: how-to ms.workload: identity -ms.date: 11/15/2020 +ms.date: 07/28/2022 ms.author: ryanwi ms.custom: aaddev ms.reviewer: marsma, aragra, lenalepa, sureshja @@ -48,9 +48,9 @@ To delete an application, be listed as an owner of the application or have admin ## Remove an application authored by another organization -If you are viewing **App registrations** in the context of a tenant, a subset of the applications that appear under the **All apps** tab are from another tenant and were registered into your tenant during the consent process. More specifically, they are represented by only a service principal object in your tenant, with no corresponding application object. For more information on the differences between application and service principal objects, see [Application and service principal objects in Azure AD](./app-objects-and-service-principals.md). +If you're viewing **App registrations** in the context of a tenant, a subset of the applications that appear under the **All apps** tab are from another tenant and were registered into your tenant during the consent process. More specifically, they're represented by only a service principal object in your tenant, with no corresponding application object. For more information on the differences between application and service principal objects, see [Application and service principal objects in Azure AD](./app-objects-and-service-principals.md). -In order to remove an application’s access to your directory (after having granted consent), the company administrator must remove its service principal. The administrator must have Global Administrator access, and can remove the application through the Azure portal or use the [Azure AD PowerShell Cmdlets](/previous-versions/azure/jj151815(v=azure.100)) to remove access. +In order to remove an application’s access to your directory (after having granted consent), the company administrator must remove its service principal. The administrator must have Global Administrator access. To learn how to delete a service principal, see [Delete an enterprise application](../manage-apps/delete-application-portal.md). ## Next steps diff --git a/articles/active-directory/develop/howto-restore-app.md b/articles/active-directory/develop/howto-restore-app.md index a970ab0ac2d7b..39c97420e97dd 100644 --- a/articles/active-directory/develop/howto-restore-app.md +++ b/articles/active-directory/develop/howto-restore-app.md @@ -9,21 +9,19 @@ ms.service: active-directory ms.subservice: develop ms.topic: how-to ms.workload: identity -ms.date: 3/22/2021 +ms.date: 07/28/2022 ms.author: arcrowe ms.custom: aaddev #Customer intent: As an application developer, I want to know how to restore or permanently delete my recently deleted application from the Microsoft identity platform. --- # Restore or remove a recently deleted application with the Microsoft identity platform -After you delete an app registration, the app remains in a suspended state for 30 days. During that 30-day window, the app registration can be restored, along with all its properties. After that 30-day window passes, app registrations cannot be restored and the permanent deletion process may be automatically started. This functionality only applies to applications associated to a directory. It is not available for applications from a personal Microsoft account, which cannot be restored. -You can view your deleted applications, restore a deleted application, or permanently delete an application using the App registrations experience under Azure Active Directory (Azure AD) in the Azure portal. +After you delete an app registration, the app remains in a suspended state for 30 days. During that 30-day window, the app registration can be restored, along with all its properties. After that 30-day window passes, app registrations can't be restored, and the permanent deletion process may be automatically started. This functionality only applies to applications associated to a directory. It isn't available for applications from a personal Microsoft account, which can't be restored. -Note that neither you nor Microsoft customer support can restore a permanently deleted application or an application deleted more than 30 days ago. +You can view your deleted applications, restore a deleted application, or permanently delete an application using the **App registrations** experience under Azure Active Directory (Azure AD) in the Azure portal. -> [!IMPORTANT] -> The deleted applications portal UI feature [!INCLUDE [PREVIEW BOILERPLATE](../../../includes/active-directory-develop-preview.md)] +Neither you nor Microsoft customer support can restore a permanently deleted application or an application deleted more than 30 days ago. ## Required permissions You must have one of the following roles to permanently delete applications. @@ -50,9 +48,9 @@ Review the list of applications. Only applications that have been deleted in the ## Restore a recently deleted application -When an app registration is deleted from the organization, the app is in a suspended state and its configurations are preserved. When you restore an app registration, its configurations are also restored. However, if there were any organization-specific settings in **Enterprise applications** for the application's home tenant, those will not be restored. +When an app registration is deleted from the organization, the app is in a suspended state, and its configurations are preserved. When you restore an app registration, its configurations are also restored. However, if there were any organization-specific settings in **Enterprise applications** for the application's home tenant, those won't be restored. -This is because organization-specific settings are stored on a separate object, called the service principal. Settings held on the service principal include permission consents and user and group assignments for a certain organization; these configurations will not be restored when the app is restored. For more information, see [Application and service principal objects](app-objects-and-service-principals.md). +This is because organization-specific settings are stored on a separate object, called the service principal. Settings held on the service principal include permission consents and user and group assignments for a certain organization; these configurations won't be restored when the app is restored. To learn how to restore the service principal with its previous configurations, see [Restore a recently deleted enterprise application](../manage-apps/restore-application.md). ### To restore an application diff --git a/articles/active-directory/develop/id-tokens.md b/articles/active-directory/develop/id-tokens.md index f1e0fb677f0a2..b41926acec6d1 100644 --- a/articles/active-directory/develop/id-tokens.md +++ b/articles/active-directory/develop/id-tokens.md @@ -84,7 +84,7 @@ The table below shows the claims that are in most ID tokens by default (except w |`roles`| Array of strings | The set of roles that were assigned to the user who is logging in. | |`rh` | Opaque String |An internal claim used by Azure to revalidate tokens. Should be ignored. | |`sub` | String | The principal about which the token asserts information, such as the user of an app. This value is immutable and cannot be reassigned or reused. The subject is a pairwise identifier - it is unique to a particular application ID. If a single user signs into two different apps using two different client IDs, those apps will receive two different values for the subject claim. This may or may not be wanted depending on your architecture and privacy requirements. | -|`tid` | String, a GUID | Represents the tenant that the user is signing in to. For work and school accounts, the GUID is the immutable tenant ID of the organization that the user is signing in to. For sign-ins to the personal Microsoft account tenant (services like Xbox, Teams for Life, or Outlook), the value is `9188040d-6c67-4c5b-b112-36a304b66dad`. To receive this claim, your app must request the `profile` scope. | +|`tid` | String, a GUID | Represents the tenant that the user is signing in to. For work and school accounts, the GUID is the immutable tenant ID of the organization that the user is signing in to. For sign-ins to the personal Microsoft account tenant (services like Xbox, Teams for Life, or Outlook), the value is `9188040d-6c67-4c5b-b112-36a304b66dad`.| | `unique_name` | String | Only present in v1.0 tokens. Provides a human readable value that identifies the subject of the token. This value is not guaranteed to be unique within a tenant and should be used only for display purposes. | | `uti` | String | Token identifier claim, equivalent to `jti` in the JWT specification. Unique, per-token identifier that is case-sensitive.| |`ver` | String, either 1.0 or 2.0 | Indicates the version of the id_token. | diff --git a/articles/active-directory/enterprise-users/groups-write-back-portal.md b/articles/active-directory/enterprise-users/groups-write-back-portal.md index 772c02796153c..2eb3057022f26 100644 --- a/articles/active-directory/enterprise-users/groups-write-back-portal.md +++ b/articles/active-directory/enterprise-users/groups-write-back-portal.md @@ -20,7 +20,7 @@ ms.collection: M365-identity-device-management # Group writeback in the Azure Active Directory admin center (preview) -Group writeback is a valuable tool for administrators of Azure Active Directory (Azure AD) tenants being synced with on-premises Active Directory groups. Microsoft is now previewing new capabilities for group writeback. In this preview, you can specify in the Azure AD admin center which groups you want to write back and what you’d like each group to write back as. You can write Microsoft 365 groups back to on-premises Active Directory as Distribution, Mail-enabled Security, or Security groups, and write Security groups back as Security groups. Groups are written back with a scope of universal​. +Group writeback is a valuable tool for administrators of Azure Active Directory (Azure AD) tenants being synced with on-premises Active Directory groups. Microsoft is now previewing new capabilities for group writeback for tenants with an Azure AD Premium license and Azure AD Connect version 2021 December release or later. In this preview, once you have [enabled Azure AD Connect group writeback](..//hybrid/how-to-connect-group-writeback-v2.md), you can specify in the Azure AD admin center which groups you want to write back and what you’d like each group to write back as. You can write Microsoft 365 groups back to on-premises Active Directory as Distribution, Mail-enabled Security, or Security groups, and write Security groups back as Security groups. Groups are written back with a scope of universal​. >[!NOTE] > If you were previously writing Microsoft 365 groups back to on-premises Active Directory as universal distribution groups, they will appear in the Azure portal as not enabled for writeback in both the **Groups** page and in the properties page for a group. These pages display a new property introduced for the preview, “writeback enabled”. This property is not set by the current version of group writeback to ensure backward compatibility with the legacy version of group writeback and to avoid breaking existing customer setups. diff --git a/articles/active-directory/fundamentals/scenario-azure-first-sap-identity-integration.md b/articles/active-directory/fundamentals/scenario-azure-first-sap-identity-integration.md index b5677bb7728de..4ce22bab1dcd5 100644 --- a/articles/active-directory/fundamentals/scenario-azure-first-sap-identity-integration.md +++ b/articles/active-directory/fundamentals/scenario-azure-first-sap-identity-integration.md @@ -29,7 +29,7 @@ This document provides advice on the technical design and configuration of SAP p | [IPS](https://help.sap.com/viewer/f48e822d6d484fa5ade7dda78b64d9f5/Cloud/en-US/2d2685d469a54a56b886105a06ccdae6.html) | SAP Cloud Identity Services - Identity Provisioning Service. IPS helps to synchronize identities between different stores / target systems. | | [XSUAA](https://blogs.sap.com/2019/01/07/uaa-xsuaa-platform-uaa-cfuaa-what-is-it-all-about/) | Extended Services for Cloud Foundry User Account and Authentication. XSUAA is a multi-tenant OAuth authorization server within the SAP BTP. | | [CF](https://www.cloudfoundry.org/) | Cloud Foundry. Cloud Foundry is the environment on which SAP built their multi-cloud offering for BTP (AWS, Azure, GCP, Alibaba). | -| [Fiori](https://www.sap.com/products/fiori/develop.html) | The web-based user experience of SAP (as opposed to the desktop-based experience). | +| [Fiori](https://www.sap.com/products/fiori.html) | The web-based user experience of SAP (as opposed to the desktop-based experience). | ## Overview @@ -272,4 +272,4 @@ Azure AD B2C doesn't natively support the use of groups to create collections of Fortunately, Azure AD B2C is highly customizable, so you can configure the SAML tokens it sends to IAS to include any custom information. For various options on supporting authorization claims, see the documentation accompanying the [Azure AD B2C App Roles sample](https://github.com/azure-ad-b2c/api-connector-samples/tree/main/Authorization-AppRoles), but in summary: through its [API Connector](../../active-directory-b2c/api-connectors-overview.md) extensibility mechanism you can optionally still use groups, app roles, or even a custom database to determine what the user is allowed to access. -Regardless of where the authorization information comes from, it can then be emitted as the `Groups` attribute inside the SAML token by configuring that attribute name as the [default partner claim type on the claims schema](../../active-directory-b2c/claimsschema.md#defaultpartnerclaimtypes) or by overriding the [partner claim type on the output claims](../../active-directory-b2c/relyingparty.md#outputclaims). Note however that BTP allows you to [map Role Collections to User Attributes](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/b3fbb1a9232d4cf99967a0b29dd85d4c.html), which means that *any* attribute name can be used for authorization decisions, even if you don't use the `Groups` attribute name. \ No newline at end of file +Regardless of where the authorization information comes from, it can then be emitted as the `Groups` attribute inside the SAML token by configuring that attribute name as the [default partner claim type on the claims schema](../../active-directory-b2c/claimsschema.md#defaultpartnerclaimtypes) or by overriding the [partner claim type on the output claims](../../active-directory-b2c/relyingparty.md#outputclaims). Note however that BTP allows you to [map Role Collections to User Attributes](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/b3fbb1a9232d4cf99967a0b29dd85d4c.html), which means that *any* attribute name can be used for authorization decisions, even if you don't use the `Groups` attribute name. diff --git a/articles/active-directory/governance/identity-governance-overview.md b/articles/active-directory/governance/identity-governance-overview.md index eded0ab4608e3..d1fd972a79f77 100644 --- a/articles/active-directory/governance/identity-governance-overview.md +++ b/articles/active-directory/governance/identity-governance-overview.md @@ -19,7 +19,7 @@ ms.collection: M365-identity-device-management # What is Azure AD Identity Governance? -Azure Active Directory (Azure AD) Identity Governance allows you to balance your organization's need for security and employee productivity with the right processes and visibility. It provides you with capabilities to ensure that the right people have the right access to the right resources. These and related Azure AD and Enterprise Mobility + Security features allows you to mitigate access risk by protecting, monitoring, and auditing access to critical assets -- while ensuring employee and business partner productivity. +Azure Active Directory (Azure AD) Identity Governance allows you to balance your organization's need for security and employee productivity with the right processes and visibility. It provides you with capabilities to ensure that the right people have the right access to the right resources. These and related Azure AD and Enterprise Mobility + Security features allows you to mitigate access risk by protecting, monitoring, and auditing access to critical assets while ensuring employee and business partner productivity. Identity Governance gives organizations the ability to do the following tasks across employees, business partners and vendors, and across services and applications both on-premises and in clouds: @@ -58,7 +58,7 @@ When a user attempts to access applications, Azure AD enforces [Conditional Acce ## Privileged access lifecycle -Historically, privileged access has been described by other vendors as a separate capability from Identity Governance. However, at Microsoft, we think governing privileged access is a key part of Identity Governance -- especially given the potential for misuse associated with those administrator rights can cause to an organization. The employees, vendors, and contractors that take on administrative rights need to be governed. +Historically, privileged access has been described by other vendors as a separate capability from Identity Governance. However, at Microsoft, we think governing privileged access is a key part of Identity Governance especially given the potential for misuse associated with those administrator rights can cause to an organization. The employees, vendors, and contractors that take on administrative rights need to be governed. ![Privileged access lifecycle](./media/identity-governance-overview/privileged-access-lifecycle.png) diff --git a/articles/active-directory/hybrid/how-to-connect-group-writeback-v2.md b/articles/active-directory/hybrid/how-to-connect-group-writeback-v2.md index bd8a0b936db0f..bc463727fd7b1 100644 --- a/articles/active-directory/hybrid/how-to-connect-group-writeback-v2.md +++ b/articles/active-directory/hybrid/how-to-connect-group-writeback-v2.md @@ -119,7 +119,7 @@ To enable group writeback via PowerShell: Set-ADSyncScheduler -SyncCycleEnabled $true ``` -You've now enabled the group writeback feature. +You've now enabled the group writeback feature, and can [select the groups for writeback](../enterprise-users/groups-write-back-portal.md). ### Optional Configuration @@ -194,4 +194,5 @@ Limitations and known issues specific to Group Writeback: ## Next steps -Learn more about [Integrating your on-premises identities with Azure Active Directory](whatis-hybrid-identity.md). \ No newline at end of file +- Configure [group writeback in the Azure Active Directory Admin Center](../enterprise-users/groups-write-back-portal.md) +- Learn more about [Integrating your on-premises identities with Azure Active Directory](whatis-hybrid-identity.md). diff --git a/articles/active-directory/manage-apps/create-service-principal-cross-tenant.md b/articles/active-directory/manage-apps/create-service-principal-cross-tenant.md new file mode 100644 index 0000000000000..696dce455a1a8 --- /dev/null +++ b/articles/active-directory/manage-apps/create-service-principal-cross-tenant.md @@ -0,0 +1,108 @@ +--- +title: 'Create an enterprise application from a multi-tenant application' +description: Create an enterprise application using the client ID for a multi-tenant application. +services: active-directory +author: omondiatieno +manager: CelesteDG +ms.service: active-directory +ms.subservice: app-mgmt +ms.topic: how-to +ms.workload: identity +ms.date: 07/26/2022 +ms.author: jomondi +ms.reviewer: karavar +ms.custom: mode-other +zone_pivot_groups: enterprise-apps-cli + + +#Customer intent: As an administrator of an Azure AD tenant, I want to create an enterprise application using client ID for a multi-tenant application provided by a service provider or independent software vendor. +--- + +# Create an enterprise application from a multi-tenant application in Azure Active Directory + +In this article, you'll learn how to create an enterprise application in your tenant using the client ID for a multi-tenant application. An enterprise application refers to a service principal within a tenant. The service principal discussed in this article is the local representation, or application instance, of a global application object in a single tenant or directory. + +Before you proceed to add the application using any of these options, check whether the enterprise application is already in your tenant by attempting to sign in to the application. If the sign-in is successful, the enterprise application already exists in your tenant. + +If you have verified that the application isn't in your tenant, proceed with any of the following ways to add the enterprise application to your tenant using the appId + +## Prerequisites + +To add an enterprise application to your Azure AD tenant, you need: + +- An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). +- One of the following roles: Global Administrator, Cloud Application Administrator, or Application Administrator. +- The client ID of the multi-tenant application. + + +## Create an enterprise application + +:::zone pivot="admin-consent-url" + +If you've been provided with the admin consent URL, navigate to the URL through a web browser to [grant tenant-wide admin consent](grant-admin-consent.md) to the application. Granting tenant-wide admin consent to the application will add it to your tenant. The tenant-wide admin consent URL has the following format: + +```http +https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id=248e869f-0e5c-484d-b5ea1fba9563df41&redirect_uri=https://www.your-app-url.com +``` +where: + +- `{client-id}` is the application's client ID (also known as appId). + +:::zone-end + +:::zone pivot="msgraph-powershell" + +1. Run `connect-MgGraph -Scopes "Application.ReadWrite.All"` and sign in with a Global Admin user account. +1. Run the following command to create the enterprise application: + + ```powershell + New-MgServicePrincipal -AppId fc876dd1-6bcb-4304-b9b6-18ddf1526b62 + ``` +1. To delete the enterprise application you created, run the command: + + ```powershell + Remove-MgServicePrincipal + -ServicePrincipalId + ``` +:::zone-end +:::zone pivot="ms-graph" + +From the Microsoft Graph explorer window: + +1. To create the enterprise application, insert the following query: + + ```http + POST /servicePrincipals. + ``` +1. Supply the following request in the **Request body**. + + { + "appId": "fc876dd1-6bcb-4304-b9b6-18ddf1526b62" + } +1. Grant the Application.ReadWrite.All permission under the **Modify permissions** tab and select **Run query**. + +1. To delete the enterprise application you created, run the query: + + ```http + DELETE /servicePrincipals/{objectID} + ``` +:::zone-end +:::zone pivot="azure-cli" +1. To create the enterprise application, run the following command: + + ```azurecli + az ad sp create --id fc876dd1-6bcb-4304-b9b6-18ddf1526b62 + ``` + +1. To delete the enterprise application you created, run the command: + + ```azurecli + az ad sp delete --id + ``` + +:::zone-end + +## Next steps + +- [Add RBAC role to the enterprise application](/azure/role-based-access-control/role-assignments-portal) +- [Assign users to your application](add-application-portal-assign-users.md) \ No newline at end of file diff --git a/articles/active-directory/manage-apps/delete-application-portal.md b/articles/active-directory/manage-apps/delete-application-portal.md index cca73033b9952..040f4a3875f87 100644 --- a/articles/active-directory/manage-apps/delete-application-portal.md +++ b/articles/active-directory/manage-apps/delete-application-portal.md @@ -1,25 +1,27 @@ --- -title: 'Quickstart: Delete an enterprise application' +title: 'Delete an enterprise application' description: Delete an enterprise application in Azure Active Directory. services: active-directory author: omondiatieno manager: CelesteDG ms.service: active-directory ms.subservice: app-mgmt -ms.topic: quickstart +ms.topic: how-to ms.workload: identity -ms.date: 03/24/2022 +ms.date: 07/28/2022 ms.author: jomondi ms.reviewer: sureshja -ms.custom: mode-other +zone_pivot_groups: enterprise-apps-all + #Customer intent: As an administrator of an Azure AD tenant, I want to delete an enterprise application. --- -# Quickstart: Delete an enterprise application +# Delete an enterprise application + +In this article, you learn how to delete an enterprise application that was added to your Azure Active Directory (Azure AD) tenant. -In this quickstart, you use the Azure Active Directory Admin Center to delete an application that was added to your Azure Active Directory (Azure AD) tenant. +When you delete and enterprise application, it will be held in a suspended state in the recycle bin for 30 days. During the 30 days, you can [Restore the application](restore-application.md). Deleted items are automatically hard deleted after the 30-day period. For more information on frequently asked questions about deletion and recovery of applications, see [Deleting and recovering applications FAQs](delete-recover-faq.yml). -It is recommended that you use a non-production environment to test the steps in this quickstart. ## Prerequisites @@ -27,25 +29,89 @@ To delete an enterprise application, you need: - An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). - One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal. -- Completion of the steps in [Quickstart: Add an enterprise application](add-application-portal.md). +- An [enterprise application added to your tenant](add-application-portal.md) ## Delete an enterprise application -To delete an enterprise application: +:::zone pivot="portal" -1. Go to the [Azure Active Directory Admin Center](https://aad.portal.azure.com) and sign in using one of the roles listed in the prerequisites. +1. Sign in to the [Azure AD portal](https://portal.azure.com) and sign in using one of the roles listed in the prerequisites. 1. In the left menu, select **Enterprise applications**. The **All applications** pane opens and displays a list of the applications in your Azure AD tenant. Search for and select the application that you want to delete. For example, **Azure AD SAML Toolkit 1**. 1. In the **Manage** section of the left menu, select **Properties**. 1. At the top of the **Properties** pane, select **Delete**, and then select **Yes** to confirm you want to delete the application from your Azure AD tenant. :::image type="content" source="media/delete-application-portal/delete-application.png" alt-text="Delete an enterprise application."::: -## Clean up resources +:::zone-end + +:::zone pivot="aad-powershell" + +> [!IMPORTANT] +> Make sure you're using the AzureAD module. This is important if you've installed both the [AzureAD](/powershell/module/azuread/?preserve-view=true&view=azureadps-2.0) module and the AzureADPreview module. +1. Run the following commands: + + ```powershell + Remove-Module AzureADPreview + Import-Module AzureAD + ``` + +1. Connect to Azure AD PowerShell: + + ```powershell + Connect-AzureAD + ``` +1. Get the list of enterprise applications in your tenant. + + ```powershell + Get-AzureADServicePrincipal + ``` +1. Record the object ID of the enterprise app you want to delete. +1. Delete the enterprise application. + + ```powershell + Remove-AzureADServicePrincipal $ObjectId 'd4142c52-179b-4d31-b5b9-08940873507b' + ``` +:::zone-end + +:::zone pivot="ms-powershell" + +1. Connect to Microsoft Graph PowerShell: + + ```powershell + Connect-MgGraph -Scopes 'Application.Read.All' + ``` + +1. Get the list of enterprise applications in your tenant. + + ```powershell + Get-MgServicePrincipal + ``` +1. Record the object ID of the enterprise app you want to delete. +1. Delete the enterprise application. + + ```powershell + Remove-MgServicePrincipal -ServicePrincipalId 'd4142c52-179b-4d31-b5b9-08940873507b' + +:::zone-end + + +:::zone pivot="ms-graph" + +Delete an enterprise application using [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). +1. To get the list of applications in your tenant, run the following query. + + ```http + GET /servicePrincipals + ``` +1. Record the ID of the enterprise app you want to delete. +1. Delete the enterprise application. + + ```http + DELETE /servicePrincipals/{id} + ``` -When you are done with this quickstart series, consider deleting the application to clean up your test tenant. Deleting the application was covered in this quickstart. +:::zone-end ## Next steps -Learn more about planning a single sign-on deployment. -> [!div class="nextstepaction"] -> [Plan single sign-on deployment](plan-sso-deployment.md) +- [Restore a deleted enterprise application](restore-application.md) diff --git a/articles/active-directory/manage-apps/delete-recover-faq.yml b/articles/active-directory/manage-apps/delete-recover-faq.yml new file mode 100644 index 0000000000000..01f0cbbde139b --- /dev/null +++ b/articles/active-directory/manage-apps/delete-recover-faq.yml @@ -0,0 +1,98 @@ +### YamlMime:FAQ +metadata: + title: Deletion and recovery of applications FAQ + description: Find answers to frequently asked questions (FAQs) about recovering deleted apps and service principals. + + services: active-directory + ms.service: active-directory + ms.subservice: app-mgmt + ms.topic: faq + ms.workload: identity + ms.date: 07/28/2021 + ms.author: jomondi + author: omondiatieno + manager: celesteDG + ms.reviewer: sureshja + ms.collection: M365-identity-device-management + +title: Deletion and recovery of applications FAQ +summary: | + The following are some frequently asked questions (FAQs) on deletion and recovery of applications. + +sections: + - name: Single section - ignored + questions: + - question: | + When I create applications, I'm getting Directory_QuotaExceeded error. How can I avoid this problem? + answer: | + > A non-admin user can create no more than 250 Azure AD resources that include applications and service principals. Both active resources and deleted resources that are available to restore count toward this quota. Even if you delete more applications that you don't need, they'll still add count to the quota. To free up the quota, you need to [permanently delete](restore-application.md#permanently-delete-an-enterprise-application) objects in the deleted items container. + > + > For more information about the service limits, see [Azure resource management](/azure/azure-resource-manager/management/azure-subscription-service-limits?msclkid=6cb6cc54c68711ec93eb9539fce3cc28#active-directory-limits). + > + > + - question: | + Where can I find all the deleted applications and service principals? + answer: | + > Soft-deleted application and service principal objects go into the deleted items container and remain available to restore for up to 30 days. After 30 days, they're permanently deleted, and this frees up the quota. + > + > To learn how to view deleted application objects through the Azure portal, see [View restorable applications](/develop/howto-restore-app.md#to-view-your-restorable-applications). + > + > Deleted service principals can't be viewed through the Azure portal. To learn how to view your restorable service principals using PowerShell or Microsoft Graph API, see [View restorable service principals](restore-application.md#view-restorable-enterprise-applications). + > + > + - question: | + How do I restore deleted applications or service principals? + answer: | + > To learn how to restore recently deleted application registrations through the Azure portal, see [Restore application registrations](../develop/howto-restore-app.md). + > + > To learn how to restore recently deleted service principals, see [Restore service principals](restore-application.md). This method is also applicable for restoring recently deleted application registrations using PowerShell or Microsoft Graph API. + - question: | + How do I permanently delete soft deleted applications or service principals? + answer: | + > To permanently delete application registrations through the Azure portal, see [Permanently delete an application](../develop/howto-restore-app.md#permanently-delete-an-application). + > + > To permanently delete a service principal, see [Permanently delete a service principal](restore-application.md#permanently-delete-an-enterprise-application). This method is also applicable for permanently deleting application registrations using PowerShell or Microsoft Graph API. + - question: | + Can I configure the interval in which applications and service principals are permanently deleted by Azure AD? + answer: | + > No. You can't configure the periodicity of hard deletion. + > + - question: | + I lost my SAML SSO configurations after deleting and restoring my application through app registrations in the Azure portal. How can I restore my configurations? + answer: | + > The SAML SSO configurations are stored on the service principal object. When you restore an application from the **App registrations** UI, it recovers the app object but creates a new service principal. The SAML SSO configurations done earlier to the app are lost when restoring a deleted application using the **App registrations** UI. + > + > To correct this problem, delete the new service principal the **App registrations** experience created and [Restore the original service principal](restore-application.md). + > + > If you didn't record the service principal before deleting the application, use the [list deleted items](/graph/api/directory-deleteditems-list?tabs=http) API to fetch the deleted service principal and filter the results by the client's application ID (**appId**) property using the following syntax: + > + > `https://graph.microsoft.com/v1.0/directory/deletedItems/microsoft.graph.servicePrincipal?$filter=appId eq '{appId}'`. + > Once you've retrieved the object ID of the deleted service principal, proceed to [restore](restore-application.md) it. + - question: | + Why can't I recover managed identities? + answer: | + > [Managed identities](../managed-identities-azure-resources/overview.md) are a special type of service principals. Deleted managed identities can't be recovered currently. + > + > + - question: | + I can't see the provisioning data from a recovered service principal. How can I recover it? + answer: | + > After recovering a service principal, you may initially see the error in the following screenshot. This issue will resolve itself between 40 mins and 1 day. If you'd like the provisioning job to start immediately, you can hit restart to force the provisioning service to run again. Hitting restart will trigger an initial cycle that can take time for customers with 100K+ users or group memberships. + > + > :::image type="content" source="media/delete-application-portal/recover-user-provisioning.png" alt-text="Screenshot of recovering user provisioning data."::: + > + - question: | + I recovered my application that was configured for application proxy. I can't see app proxy configurations after the recovery. How can I recover it back? + answer: | + > App proxy configurations can't be recovered through the portal UI. Use the API to recover app proxy settings. Expect a delay of up to 24 hours as the app proxy data gets synced back. + - question: | + I can't see the policies I set on the service principal object after the recovery. How can I recover them? + answer: | + > Policies can't be recovered currently. When you restore a service principal, you'll have to configure the policies again. + > + > + +additionalContent: | + ## Next steps + * [Restore a service principal](restore-application.md) + * [Restore an application registration](../develop/howto-restore-app.md) \ No newline at end of file diff --git a/articles/active-directory/manage-apps/recover-deleted-apps-faq.md b/articles/active-directory/manage-apps/recover-deleted-apps-faq.md deleted file mode 100644 index a646013a67d74..0000000000000 --- a/articles/active-directory/manage-apps/recover-deleted-apps-faq.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Frequently asked questions about recovering deleted apps -titleSuffix: Azure AD -description: Find answers to frequently asked questions (FAQs) about recovering deleted apps and service principals. -services: active-directory -author: omondiatieno -manager: CelesteDG -ms.service: active-directory -ms.subservice: app-mgmt -ms.workload: identity -ms.topic: reference -ms.date: 05/24/2022 -ms.author: jomondi -ms.reviewer: sureshja -ms.collection: M365-identity-device-management - ---- - -# Recover deleted applications in Azure Active Directory FAQs - -This page answers frequently asked questions about deleting and restoring deleted application registrations and service principals. - -## When I create applications, I'm getting Directory_QuotaExceeded error. How can I avoid this problem? -A non-admin user can create no more than 250 Azure AD resources that include applications and service principals. Both active resources and deleted resources that are available to restore count toward this quota. Even if you delete more applications that you don't need, they'll still add count to the quota. Hence, to free up the quota, you need to [permanently delete](/graph/api/directory-deleteditems-delete?tabs=http) objects in the deleted items container. You can learn more about the service limits through [this link](/azure/azure-resource-manager/management/azure-subscription-service-limits?msclkid=6cb6cc54c68711ec93eb9539fce3cc28#active-directory-limits). - -The quota limit set for Azure AD resources is applicable when creating applications or service principals using a delegated flow such as using Azure AD app registrations or Enterprise apps portal. Creating applications using the Microsoft Graph API programmatically using application flow won't have this restriction. - -## Where can I find all the deleted applications and service principals? - -Soft-deleted application and service principal objects go into the [deleted items](/graph/api/resources/directory?tabs=http) container and remain available to restore for up to 30 days. After 30 days, they're permanently deleted, and this frees up the quota. -You find the deleted applications by using one of the following approaches: - -- Using the Azure portal - -Recently deleted application objects can be found under the **Deleted applications** tab on the App registrations blade of Azure portal. - - :::image type="content" source="media/delete-application-portal/recover-deleted-apps.png" alt-text="Screenshot shows list of deleted items."::: - -- Using the Microsoft Graph API - -Recently deleted application and service principal objects can be found using the [List deletedItems](/graph/api/directory-deleteditems-list?tabs=http) API. - -- Using PowerShell - -Recently deleted application and service principal objects can be found using the -[Get-AzureADMSDeletedDirectoryObject](/powershell/module/azuread/get-azureadmsdeleteddirectoryobject?tabs=http) cmdlet. - -## How do I restore deleted applications or service principals? - -- Using Microsoft Graph API - -Deleted objects can be restored using the [Restore deleted item](/graph/api/directory-deleteditems-restore?tabs=http) API. - -- Using PowerShell - -Deleted objects can be restored using the [Restore-AzureADMSDeletedDirectoryObject](/powershell/module/azuread/restore-azureadmsdeleteddirectoryobject?tabs=http) cmdlet. - -## How do I permanently delete soft deleted applications or service principals? - -- Using the Microsoft Graph API - -Soft deleted objects can be permanently deleted by using the [Permanently delete an item from deleted items](/graph/api/directory-deleteditems-delete?tabs=http) API. - -- Using PowerShell - -Soft deleted objects can be permanently deleted using the [Remove-AzureADMSDeletedDirectoryObject](/powershell/module/azuread/remove-azureadmsdeleteddirectoryobject?tabs=http) cmdlet. - -## Can I configure the interval in which applications and service principals are permanently deleted by Azure AD? - -No. You can’t configure the periodicity of hard deletion. - -## I restored a deleted application using the App registrations portal experience. I don't see the SAML SSO configurations I made to the app prior to deletion. - -The SAML SSO configurations are stored on the service principal object. When you restore an application from the App registrations UI, it recovers the app object but creates a new service principal. Hence, the SAML SSO configurations done earlier to the app are lost when restoring a deleted application using the App registrations UI. - -To correct this problem, delete the new service principal the app registrations experience created and restore the original service principal using the [Microsoft Graph API](/graph/api/directory-deleteditems-restore?tabs=http) or the [Microsoft Graph PowerShell cmdlet](/powershell/module/azuread/restore-azureadmsdeleteddirectoryobject?tabs=http). - -If you recorded the object ID of the service principal before deleting the application, use the [Restore deleted item](/graph/api/directory-deleteditems-restore?tabs=http) API to recover the service principal. Otherwise, use the [list deleted items](/graph/api/directory-deleteditems-list?tabs=http) API to fetch the deleted service principal and filter the results by the client's application ID (**appId**) property using the following syntax: - -`https://graph.microsoft.com/v1.0/directory/deletedItems/microsoft.graph.servicePrincipal?$filter=appId eq '{appId}'` - -## Why can’t I recover managed identities? - -[Managed identities](../managed-identities-azure-resources/overview.md) are a special type of service principals. Deleted managed identities can’t be recovered currently. - -## I can’t see the provisioning data from a recovered service principal. How can I recover it back? - -After recovering an SP, you may initially see the error in the following screenshot. This issue will resolve itself between 40 mins and 1 day. If you would like the provisioning job to start immediately, you can hit restart to force the provisioning service to run again. Hitting restart will trigger an initial cycle that can take time for customers with 100 K+ users or group memberships. - -:::image type="content" source="media/delete-application-portal/recover-user-provisioning.png" alt-text="Screenshot of recovering user provisioning data."::: - -## I recovered my application that was configured for application proxy. I can’t see app proxy configurations after the recovery. How can I recover it back? - -App proxy configurations can't be recovered through the portal UI. Use the API to recover app proxy settings. Expect a delay of up to 24 hours as the app proxy data gets synced back. - -## I can’t see the policies I set on the service principal object after the recovery. How can I recover them? - -Policies can't be recovered currently. When you restore a service principal, you'll have to configure the policies again. - -## Next steps - -- [Delete a service principal](delete-application-portal.md) -- [Delete an application registration](../develop/howto-restore-app.md) \ No newline at end of file diff --git a/articles/active-directory/manage-apps/restore-application.md b/articles/active-directory/manage-apps/restore-application.md new file mode 100644 index 0000000000000..321698ec38f8f --- /dev/null +++ b/articles/active-directory/manage-apps/restore-application.md @@ -0,0 +1,153 @@ +--- +title: 'Restore a soft deleted enterprise application' +description: Restore a soft deleted enterprise application in Azure Active Directory. +services: active-directory +author: omondiatieno +manager: CelesteDG +ms.service: active-directory +ms.subservice: app-mgmt +ms.topic: how-to +ms.workload: identity +ms.date: 07/28/2022 +ms.author: jomondi +ms.reviewer: sureshja +ms.custom: mode-other +zone_pivot_groups: enterprise-apps-minus-portal +#Customer intent: As an administrator of an Azure AD tenant, I want to restore a soft deleted enterprise application. +--- + +# Restore an enterprise application in Azure AD + +In this article, you'll learn how to restore a soft deleted enterprise application in your Azure Active Directory (Azure AD) tenant. Soft deleted enterprise applications can be restored from the recycle bin within the first 30 days after their deletion. After the 30-day window, the enterprise application is permanently deleted and can't be restored. + +When an [application registration is deleted](../develop/howto-remove-app.md) in its home tenant through app registrations in the Azure portal, the enterprise application, which is its corresponding service principal also gets deleted. Restoring the deleted application registration through the Azure portal won't restore its corresponding service principal, but will instead create a new one. + +Currently, the [soft deleted enterprise applications](delete-application-portal.md) can't be viewed or restored through the Azure portal. Therefore, if you had configurations on the previous enterprise application, you can't restore them through the Azure portal. To recover your previous configurations, first delete the enterprise application that was restored through the Azure portal, then follow the steps in this article to recover the soft deleted enterprise application. For more information on frequently asked questions about deletion and recovery of applications, see [Deleting and recovering applications FAQs](delete-recover-faq.yml. + + +## Prerequisites + +To restore an enterprise application, you need: + +- An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). +- One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal. +- A [soft deleted enterprise application](delete-application-portal.md) in your tenant. + +## View restorable enterprise applications + +:::zone pivot="aad-powershell" + +> [!IMPORTANT] +> Make sure you're using the AzureAD module. This is important if you've installed both the [AzureAD](/powershell/module/azuread/?preserve-view=true&view=azureadps-2.0) module and the AzureADPreview module. +1. Run the following commands: + + ```powershell + Remove-Module AzureADPreview + Import-Module AzureAD + ``` + +1. Connect to Azure AD PowerShell: + + ```powershell + Connect-AzureAD + ``` + +1. To view the recently deleted enterprise application, run the following command: + + ```powershell + Get-AzureADMSDeletedDirectoryObject -Id 'd4142c52-179b-4d31-b5b9-08940873507b' + ``` +:::zone-end + +:::zone pivot="ms-powershell" + +1. Run `connect-MgGraph -Scopes "Application.ReadWrite.All"` and sign in with a Global Admin user account. + +1. To view the recently deleted enterprise applications, run the following command: + + ```powershell + Get-MgDirectoryDeletedItem -DirectoryObjectId 'd4142c52-179b-4d31-b5b9-08940873507b' + ``` +:::zone-end + +:::zone pivot="ms-graph" + +View and restore recently deleted enterprise applications using [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). + +To get the list of deleted enterprise applications in your tenant, run the following query. + + ```http + GET https://graph.microsoft.com/v1.0/directory/deletedItems/microsoft.graph.servicePrincipal + ``` +Record the ID of the enterprise application you want to restore. + +:::zone-end + +## Restore an enterprise application + +:::zone pivot="aad-powershell" + +1. To restore the enterprise application, run the following command: + + + ```powershell + Restore-AzureADMSDeletedDirectoryObject -Id 'd4142c52-179b-4d31-b5b9-08940873507b' + ``` +:::zone-end + +:::zone pivot="ms-powershell" + +1. To restore the enterprise application, run the following command: + + ```powershell + Restore-MgDirectoryObject -DirectoryObjectId 'd4142c52-179b-4d31-b5b9-08940873507b' + ``` +:::zone-end + +:::zone pivot="ms-graph" + +1. To restore the enterprise application, run the following query: + + ```http + POST https://graph.microsoft.com/v1.0/directory/deletedItems/{id}/restore + ``` +:::zone-end + +## Permanently delete an enterprise application + +>[!WARNING] +> Permanently deleting an enterprise application is an irreversible action. Any present configurations on the app will be completely lost. Carefully review the details of the enterprise application to be sure you still want to hard delete it. + +:::zone pivot="aad-powershell" + +To permanently delete a soft deleted enterprise application, run the following command: + +```powershell +Remove-AzureADMSDeletedDirectoryObject -Id 'd4142c52-179b-4d31-b5b9-08940873507b' +``` +:::zone-end + +:::zone pivot="ms-powershell" + +1. To permanently delete the soft deleted enterprise application, run the following command: + + ```powershell + Remove-MgDirectoryDeletedItem -DirectoryObjectId 'd4142c52-179b-4d31-b5b9-08940873507b' + ``` + +:::zone-end + +:::zone pivot="ms-graph" + +To permanently delete a soft deleted enterprise application, run the following query in Microsoft Graph explorer + +```http +DELETE https://graph.microsoft.com/v1.0/directory/deletedItems/{object-id} +``` + +:::zone-end + +## Next steps + +- [Recovery and deletion FAQ](delete-recover-faq.yml) +- [Applications and service principals](../develop/app-objects-and-service-principals.md) diff --git a/articles/active-directory/manage-apps/toc.yml b/articles/active-directory/manage-apps/toc.yml index 30159bb86c4c9..b5458f932e8cf 100644 --- a/articles/active-directory/manage-apps/toc.yml +++ b/articles/active-directory/manage-apps/toc.yml @@ -16,8 +16,6 @@ href: add-application-portal-assign-users.md - name: View applications href: view-applications-portal.md - - name: Delete applications - href: delete-application-portal.md - name: Tutorials items: - name: Manage access and security @@ -94,6 +92,8 @@ href: assign-app-owners.md - name: Configure properties href: add-application-portal-configure.md + - name: Add enterprise app for multi-tenant app + href: create-service-principal-cross-tenant.md - name: Manage access items: - name: Manage consent and permissions @@ -234,10 +234,16 @@ href: application-sign-in-problem-application-error.md - name: Problem signing into a Microsoft app href: application-sign-in-problem-first-party-microsoft.md + - name: Deprecate + items: + - name: Delete an enterprise application + href: delete-application-portal.md + - name: Restore an enterprise application + href: restore-application.md - name: Reference items: - name: Deletion and recovery FAQ - href: recover-deleted-apps-faq.md + href: delete-recover-faq.yml - name: Admin consent workflow FAQ href: admin-consent-workflow-faq.md - name: App Management certificates FAQ diff --git a/articles/active-directory/manage-apps/what-is-application-management.md b/articles/active-directory/manage-apps/what-is-application-management.md index 6e4f111d6d3f8..0f113f537dc73 100644 --- a/articles/active-directory/manage-apps/what-is-application-management.md +++ b/articles/active-directory/manage-apps/what-is-application-management.md @@ -61,7 +61,7 @@ To [manage access](what-is-access-management.md) for an application, you want to You can [manage user consent settings](configure-user-consent.md) to choose whether users can allow an application or service to access user profiles and organizational data. When applications are granted access, users can sign in to applications integrated with Azure AD, and the application can access your organization's data to deliver rich data-driven experiences. -Users often are unable to consent to the permissions an application is requesting. Configure the [admin consent workflow](configure-admin-consent-workflow.md) to allow users to provide a justification and request an administrator's review and approval of an application. +Users often are unable to consent to the permissions an application is requesting. Configure the admin consent workflow to allow users to provide a justification and request an administrator's review and approval of an application. For training on how to configure admin consent workflow in your Azure AD tenant, see [Configure admin consent workflow](/learn/modules/configure-admin-consent-workflow). As an administrator, you can [grant tenant-wide admin consent](grant-admin-consent.md) to an application. Tenant-wide admin consent is necessary when an application requires permissions that regular users aren't allowed to grant, and allows organizations to implement their own review processes. Always carefully review the permissions the application is requesting before granting consent. When an application has been granted tenant-wide admin consent, all users are able to sign into the application unless it has been configured to require user assignment. diff --git a/articles/active-directory/managed-identities-azure-resources/managed-identities-status.md b/articles/active-directory/managed-identities-azure-resources/managed-identities-status.md index c01e9809d3508..9c3246f48464b 100644 --- a/articles/active-directory/managed-identities-azure-resources/managed-identities-status.md +++ b/articles/active-directory/managed-identities-azure-resources/managed-identities-status.md @@ -64,7 +64,7 @@ The following Azure services support managed identities for Azure resources: | Azure Service Bus | [Authenticate a managed identity with Azure Active Directory to access Azure Service Bus resources](../../service-bus-messaging/service-bus-managed-service-identity.md) | | Azure Service Fabric | [Using Managed identities for Azure with Service Fabric](../../service-fabric/concepts-managed-identity.md) | | Azure SignalR Service | [Managed identities for Azure SignalR Service](../../azure-signalr/howto-use-managed-identity.md) | -| Azure Spring Cloud | [How to enable system-assigned managed identity for Azure Spring Cloud application](../../spring-cloud/how-to-enable-system-assigned-managed-identity.md) | +| Azure Spring Apps | [Enable system-assigned managed identity for an application in Azure Spring Apps](../../spring-apps/how-to-enable-system-assigned-managed-identity.md) | | Azure SQL | [Azure SQL Transparent Data Encryption with customer-managed key](/azure/azure-sql/database/transparent-data-encryption-byok-overview) | | Azure SQL Managed Instance | [Azure SQL Transparent Data Encryption with customer-managed key](/azure/azure-sql/database/transparent-data-encryption-byok-overview) | | Azure Stack Edge | [Manage Azure Stack Edge secrets using Azure Key Vault](../../databox-online/azure-stack-edge-gpu-activation-key-vault.md#recover-managed-identity-access) diff --git a/articles/active-directory/managed-identities-azure-resources/overview-for-developers.md b/articles/active-directory/managed-identities-azure-resources/overview-for-developers.md index 7d9b7c9af5044..668b3edb698f3 100644 --- a/articles/active-directory/managed-identities-azure-resources/overview-for-developers.md +++ b/articles/active-directory/managed-identities-azure-resources/overview-for-developers.md @@ -330,7 +330,7 @@ dr.Close(); #### [Java](#tab/java) -If you use [Azure Spring Apps](../../spring-cloud/index.yml), you can connect to Azure SQL Database with a managed identity without needing to make any changes to your code. +If you use [Azure Spring Apps](../../spring-apps/index.yml), you can connect to Azure SQL Database with a managed identity without needing to make any changes to your code. Open the `src/main/resources/application.properties` file, and add `Authentication=ActiveDirectoryMSI;` at the end of the following line. Be sure to use the correct value for `$AZ_DATABASE_NAME` variable. @@ -338,7 +338,7 @@ Open the `src/main/resources/application.properties` file, and add `Authenticati spring.datasource.url=jdbc:sqlserver://$AZ_DATABASE_NAME.database.windows.net:1433;database=demo;encrypt=true;trustServerCertificate=false;hostNameInCertificate=*.database.windows.net;loginTimeout=30;Authentication=ActiveDirectoryMSI; ``` -Read more about how to [use a managed identity to connect Azure SQL Database to an Azure Spring Apps app](../../spring-cloud/connect-managed-identity-to-azure-sql.md). +Read more about how to [use a managed identity to connect Azure SQL Database to an Azure Spring Apps app](../../spring-apps/connect-managed-identity-to-azure-sql.md). --- diff --git a/articles/active-directory/privileged-identity-management/azure-pim-resource-rbac.md b/articles/active-directory/privileged-identity-management/azure-pim-resource-rbac.md index 7c8d6931a521d..6eb00bdff7358 100644 --- a/articles/active-directory/privileged-identity-management/azure-pim-resource-rbac.md +++ b/articles/active-directory/privileged-identity-management/azure-pim-resource-rbac.md @@ -3,7 +3,7 @@ title: View audit report for Azure resource roles in Privileged Identity Managem description: View activity and audit history for Azure resource roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -12,7 +12,7 @@ ms.subservice: pim ms.topic: how-to ms.workload: identity ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.collection: M365-identity-device-management --- diff --git a/articles/active-directory/privileged-identity-management/concept-privileged-access-versus-role-assignable.md b/articles/active-directory/privileged-identity-management/concept-privileged-access-versus-role-assignable.md index ffc3df9b4d6ef..c0bd13867f9b6 100644 --- a/articles/active-directory/privileged-identity-management/concept-privileged-access-versus-role-assignable.md +++ b/articles/active-directory/privileged-identity-management/concept-privileged-access-versus-role-assignable.md @@ -3,7 +3,7 @@ title: What's the difference between Privileged Access groups and role-assignabl description: Learn how to tell the difference between Privileged Access groups and role-assignable groups in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/groups-activate-roles.md b/articles/active-directory/privileged-identity-management/groups-activate-roles.md index 36ab9ba603eaa..05d208db429b1 100644 --- a/articles/active-directory/privileged-identity-management/groups-activate-roles.md +++ b/articles/active-directory/privileged-identity-management/groups-activate-roles.md @@ -3,7 +3,7 @@ title: Activate privileged access group roles in PIM - Azure AD | Microsoft Docs description: Learn how to activate your privileged access group roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 02/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/groups-approval-workflow.md b/articles/active-directory/privileged-identity-management/groups-approval-workflow.md index 5466fc8c5636e..5dc5205c56fff 100644 --- a/articles/active-directory/privileged-identity-management/groups-approval-workflow.md +++ b/articles/active-directory/privileged-identity-management/groups-approval-workflow.md @@ -3,7 +3,7 @@ title: Approve activation requests for group members and owners in Privileged Id description: Learn how to approve or deny requests for role-assignable groups in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: conceptual @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/groups-assign-member-owner.md b/articles/active-directory/privileged-identity-management/groups-assign-member-owner.md index 11f3d091c04fd..ea1d229f96300 100644 --- a/articles/active-directory/privileged-identity-management/groups-assign-member-owner.md +++ b/articles/active-directory/privileged-identity-management/groups-assign-member-owner.md @@ -3,15 +3,15 @@ title: Assign eligible owners and members for privileged access groups - Azure A description: Learn how to assign eligible owners or members of a role-assignable group in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: conceptual ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim -ms.date: 06/24/2022 -ms.author: mtillman +ms.date: 07/29/2022 +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management @@ -34,7 +34,7 @@ Follow these steps to make a user eligible to be a member or owner of a privileg 1. Sign in to the [Azure AD admin center](https://aad.portal.azure.com/) with a user in the [Global Administrator](../roles/permissions-reference.md#global-administrator) role, the Privileged Role Administrator role, or the group Owner role. -1. Select **Groups** and then select the role-assignable group you want to manage. You can search or filter the list. +1. Select **Groups** and then select the [role-assignable group](concept-privileged-access-versus-role-assignable.md) you want to manage. You can search or filter the list. ![find a role-assignable group to manage in PIM](./media/groups-assign-member-owner/groups-list-in-azure-ad.png) @@ -63,7 +63,7 @@ Follow these steps to make a user eligible to be a member or owner of a privileg - **Active** assignments don't require the member to perform any action to use the role. Members assigned as active have the privileges assigned to the role at all times. -1. If the assignment should be permanent (permanently eligible or permanently assigned), select the **Permanently** checkbox. Depending on your organization's settings, the check box might not appear or might not be editable. +1. If the assignment should be permanent (permanently eligible or permanently assigned), select the **Permanently** checkbox. Depending on your organization's settings, the check box might not appear or might not be editable. For more information, check out the [Configure privileged access group settings](groups-role-settings.md#assignment-duration) article. 1. When finished, select **Assign**. diff --git a/articles/active-directory/privileged-identity-management/groups-audit.md b/articles/active-directory/privileged-identity-management/groups-audit.md index 397f18815e18a..55cac257a6d10 100644 --- a/articles/active-directory/privileged-identity-management/groups-audit.md +++ b/articles/active-directory/privileged-identity-management/groups-audit.md @@ -3,7 +3,7 @@ title: View audit report for privileged access group assignments in Privileged I description: View activity and audit history for privileged access group assignments in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -12,7 +12,7 @@ ms.topic: article ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.collection: M365-identity-device-management --- diff --git a/articles/active-directory/privileged-identity-management/groups-discover-groups.md b/articles/active-directory/privileged-identity-management/groups-discover-groups.md index 8872bf8d5696f..3ef4885c63ca0 100644 --- a/articles/active-directory/privileged-identity-management/groups-discover-groups.md +++ b/articles/active-directory/privileged-identity-management/groups-discover-groups.md @@ -3,7 +3,7 @@ title: Identify a group to manage in Privileged Identity Management - Azure AD | description: Learn how to onboard role-assignable groups to manage as privileged access groups in Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.collection: M365-identity-device-management --- diff --git a/articles/active-directory/privileged-identity-management/groups-features.md b/articles/active-directory/privileged-identity-management/groups-features.md index 02b202dc97e5c..de78c94bee985 100644 --- a/articles/active-directory/privileged-identity-management/groups-features.md +++ b/articles/active-directory/privileged-identity-management/groups-features.md @@ -3,7 +3,7 @@ title: Managing Privileged Access groups in Privileged Identity Management (PIM) description: How to manage members and owners of privileged access groups in Privileged Identity Management (PIM) services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.assetid: @@ -13,7 +13,7 @@ ms.topic: overview ms.tgt_pltfrm: na ms.workload: identity ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/groups-renew-extend.md b/articles/active-directory/privileged-identity-management/groups-renew-extend.md index c61c376dff770..24f543153214b 100644 --- a/articles/active-directory/privileged-identity-management/groups-renew-extend.md +++ b/articles/active-directory/privileged-identity-management/groups-renew-extend.md @@ -3,7 +3,7 @@ title: Renew expired group owner or member assignments in Privileged Identity Ma description: Learn how to extend or renew role-assignable group assignments in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.reviewer: markwahl-msft ms.service: active-directory @@ -12,7 +12,7 @@ ms.tgt_pltfrm: na ms.topic: how-to ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.custom: pim ms.collection: M365-identity-device-management --- diff --git a/articles/active-directory/privileged-identity-management/groups-role-settings.md b/articles/active-directory/privileged-identity-management/groups-role-settings.md index 1dec0d27ea2e1..01117b5ea5514 100644 --- a/articles/active-directory/privileged-identity-management/groups-role-settings.md +++ b/articles/active-directory/privileged-identity-management/groups-role-settings.md @@ -3,7 +3,7 @@ title: Configure privileged access groups settings in PIM - Azure Active Directo description: Learn how to configure role-assignable groups settings in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.custom: pim ms.collection: M365-identity-device-management --- diff --git a/articles/active-directory/privileged-identity-management/media/pim-configure/pim-email.png b/articles/active-directory/privileged-identity-management/media/pim-configure/pim-email.png new file mode 100644 index 0000000000000..6509fb2dfaf73 Binary files /dev/null and b/articles/active-directory/privileged-identity-management/media/pim-configure/pim-email.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-configure/role-activation.png b/articles/active-directory/privileged-identity-management/media/pim-configure/role-activation.png new file mode 100644 index 0000000000000..2d03b98884b16 Binary files /dev/null and b/articles/active-directory/privileged-identity-management/media/pim-configure/role-activation.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-configure/role-assignment.png b/articles/active-directory/privileged-identity-management/media/pim-configure/role-assignment.png new file mode 100644 index 0000000000000..c2b28acf97b1e Binary files /dev/null and b/articles/active-directory/privileged-identity-management/media/pim-configure/role-assignment.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/new-assignment-condition-expression.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/new-assignment-condition-expression.png index 091f95bf436b0..ef461354dc741 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/new-assignment-condition-expression.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/new-assignment-condition-expression.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/new-assignment-conditions.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/new-assignment-conditions.png index 541c4036b7d6f..1a9d50518d955 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/new-assignment-conditions.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/new-assignment-conditions.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-abac-update-remove.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-abac-update-remove.png index fe849779aeed3..6a96c64eaf121 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-abac-update-remove.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-abac-update-remove.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-list.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-list.png index 0ef6774e44fcf..f360508f04734 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-list.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-list.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-membership-settings-type.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-membership-settings-type.png index 0c7eafe80e320..c2b28acf97b1e 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-membership-settings-type.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-membership-settings-type.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-new-assignment-notification.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-new-assignment-notification.png index 6fdd349f0a70f..a51af4008ec2b 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-new-assignment-notification.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-new-assignment-notification.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-roles.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-roles.png index bf507457ffd19..199cd19b1f2e8 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-roles.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-roles.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-select-member-or-group.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-select-member-or-group.png index 1ffa7bc7a3f76..77a77449cf226 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-select-member-or-group.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-select-member-or-group.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-select-role.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-select-role.png index a204f312b92bd..f2b45674d05f2 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-select-role.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-select-role.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-update-remove.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-update-remove.png index 540010dd9657f..5d26023a1c7e3 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-update-remove.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-update-remove.png differ diff --git a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-update-select-role.png b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-update-select-role.png index 4e4251532ab6c..acf0f86be939f 100644 Binary files a/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-update-select-role.png and b/articles/active-directory/privileged-identity-management/media/pim-resource-roles-assign-roles/resources-update-select-role.png differ diff --git a/articles/active-directory/privileged-identity-management/pim-apis.md b/articles/active-directory/privileged-identity-management/pim-apis.md index bed7a6b312585..2369e6ae4413d 100644 --- a/articles/active-directory/privileged-identity-management/pim-apis.md +++ b/articles/active-directory/privileged-identity-management/pim-apis.md @@ -3,7 +3,7 @@ title: API concepts in Privileged Identity management - Azure AD | Microsoft Doc description: Information for understanding the APIs in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -11,7 +11,7 @@ ms.workload: identity ms.subservice: pim ms.topic: how-to ms.date: 04/18/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management @@ -132,4 +132,4 @@ The only link between the PIM entity and the role assignment entity for persiste ## Next steps -- [Azure AD Privileged Identity Management API reference](/graph/api/resources/privilegedidentitymanagementv3-overview) \ No newline at end of file +- [Azure AD Privileged Identity Management API reference](/graph/api/resources/privilegedidentitymanagementv3-overview) diff --git a/articles/active-directory/privileged-identity-management/pim-complete-azure-ad-roles-and-resource-roles-review.md b/articles/active-directory/privileged-identity-management/pim-complete-azure-ad-roles-and-resource-roles-review.md index 9814505834bbf..5635dc4298116 100644 --- a/articles/active-directory/privileged-identity-management/pim-complete-azure-ad-roles-and-resource-roles-review.md +++ b/articles/active-directory/privileged-identity-management/pim-complete-azure-ad-roles-and-resource-roles-review.md @@ -3,7 +3,7 @@ title: Complete an access review of Azure resource and Azure AD roles in PIM - A description: Learn how to complete an access review of Azure resource and Azure AD roles Privileged Identity Management in Azure Active Directory. services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -12,7 +12,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 10/07/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-configure.md b/articles/active-directory/privileged-identity-management/pim-configure.md index 8a82bc803233f..9cd2f40c1f54b 100644 --- a/articles/active-directory/privileged-identity-management/pim-configure.md +++ b/articles/active-directory/privileged-identity-management/pim-configure.md @@ -3,15 +3,15 @@ title: What is Privileged Identity Management? - Azure AD | Microsoft Docs description: Provides an overview of Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory ms.workload: identity ms.subservice: pim ms.topic: overview -ms.date: 10/07/2021 -ms.author: mtillman +ms.date: 07/29/2022 +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim,azuread-video-2020,contperf-fy21q3-portal ms.collection: M365-identity-device-management @@ -57,13 +57,13 @@ Privileged Identity Management provides time-based and approval-based role activ Once you set up Privileged Identity Management, you'll see **Tasks**, **Manage**, and **Activity** options in the left navigation menu. As an administrator, you'll choose between options such as managing **Azure AD roles**, managing **Azure resource** roles, or privileged access groups. When you choose what you want to manage, you see the appropriate set of options for that option. -![Screenshot of Privileged Identity Management in the Azure portal](./media/pim-configure/pim-quickstart.png) +![Screenshot of Privileged Identity Management in the Azure portal.](./media/pim-configure/pim-quickstart.png) ## Who can do what? For Azure AD roles in Privileged Identity Management, only a user who is in the Privileged Role Administrator or Global Administrator role can manage assignments for other administrators. Global Administrators, Security Administrators, Global Readers, and Security Readers can also view assignments to Azure AD roles in Privileged Identity Management. -For Azure resource roles in Privileged Identity Management, only a subscription administrator, a resource Owner, or a resource User Access administrator can manage assignments for other administrators. Users who are Privileged Role Administrators, Security Administrators, or Security Readers do not by default have access to view assignments to Azure resource roles in Privileged Identity Management. +For Azure resource roles in Privileged Identity Management, only a subscription administrator, a resource Owner, or a resource User Access administrator can manage assignments for other administrators. Users who are Privileged Role Administrators, Security Administrators, or Security Readers don't by default have access to view assignments to Azure resource roles in Privileged Identity Management. ## Terminology @@ -81,17 +81,65 @@ To better understand Privileged Identity Management and its documentation, you s | time-bound eligible | Duration | A role assignment where a user is eligible to activate the role only within start and end dates. | | time-bound active | Duration | A role assignment where a user can use the role only within start and end dates. | | just-in-time (JIT) access | | A model in which users receive temporary permissions to perform privileged tasks, which prevents malicious or unauthorized users from gaining access after the permissions have expired. Access is granted only when users need it. | -| principle of least privilege access | | A recommended security practice in which every user is provided with only the minimum privileges needed to accomplish the tasks they are authorized to perform. This practice minimizes the number of Global Administrators and instead uses specific administrator roles for certain scenarios. | +| principle of least privilege access | | A recommended security practice in which every user is provided with only the minimum privileges needed to accomplish the tasks they're authorized to perform. This practice minimizes the number of Global Administrators and instead uses specific administrator roles for certain scenarios. | -## Extend and renew assignments +## Role assignment overview -After you set up your time-bound owner or member assignments, the first question you might ask is what happens if an assignment expires? In this new version, we provide two options for this scenario: +The PIM role assignments give you a secure way to grant access to resources in your organization. This section describes the assignment process. It includes assign roles to members, activate assignments, approve or deny requests, extend and renew assignments. -- Extend – When a role assignment nears expiration, the user can use Privileged Identity Management to request an extension for the role assignment -- Renew – When a role assignment has already expired, the user can use Privileged Identity Management to request a renewal for the role assignment +PIM keeps you informed by sending you and other participants [email notifications](pim-email-notifications.md). These emails might also include links to relevant tasks, such activating, approve or deny a request. + +The following screenshot shows an email message sent by PIM. The email informs Patti that Alex updated a role assignment for Emily. + +![Screenshot shows an email message sent by Privileged Identity Management.](./media/pim-configure/pim-email.png) + +### Assign + +The assignment process starts by assign roles to members. To grant access to a resource, the administrator assigns roles to users, groups, service principals, or managed identities. The assignment includes the following data: + +- The members or owners to assign the role. +- The scope of the assignment. The scope limits the assigned role to a particular set of resources. +- The type of the assignment + - **Eligible** assignments require the member of the role to perform an action to use the role. Actions might include activation, or requesting approval from designated approvers. + - **Active** assignments don't require the member to perform any action to use the role. Members assigned as active have the privileges assigned to the role. +- The duration of the assignment, using start and end dates or permanent. For eligible assignments, the members can activate or requesting approval during the start and end dates. For active assignments, the members can use the assign role during this period of time. + +The following screenshot shows how administrator assigns a role to members. + +![Screenshot of Privileged Identity Management role assignment.](./media/pim-configure/role-assignment.png) + + +For more information, check out the following articles: [Assign Azure AD roles](pim-how-to-add-role-to-user.md), [Assign Azure resource roles](pim-resource-roles-assign-roles.md), and [Assign eligibility for a privileged access group](groups-assign-member-owner.md) + +### Activate + +If users have been made eligible for a role, then they must activate the role assignment before using the role. To activate the role, users select specific activation duration within the maximum (configured by administrators), and the reason for the activation request. + +The following screenshot shows how members activate their role to a limited time. + +![Screenshot of Privileged Identity Management role activation.](./media/pim-configure/role-activation.png) + +If the role requires [approval](pim-resource-roles-approval-workflow.md) to activate, a notification will appear in the upper right corner of the user's browser informing them the request is pending approval. If an approval isn't required, the member can start using the role. + +For more information, check out the following articles: [Activate Azure AD roles](pim-how-to-activate-role.md), [Activate my Azure resource roles](pim-resource-roles-activate-your-roles.md), and [Activate my privileged access group roles](groups-activate-roles.md) + +### Approve or deny + +Delegated approvers receive email notifications when a role request is pending their approval. Approvers can view, approve or deny these pending requests in PIM. After the request has been approved, the member can start using the role. For example, if a user or a group was assigned with Contribution role to a resource group, they'll be able to manage that particular resource group. + +For more information, check out the following articles: [Approve or deny requests for Azure AD roles](azure-ad-pim-approval-workflow.md), [Approve or deny requests for Azure resource roles](pim-resource-roles-approval-workflow.md), and [Approve activation requests for privileged access group](groups-approval-workflow.md) + +### Extend and renew assignments + +After administrators set up time-bound owner or member assignments, the first question you might ask is what happens if an assignment expires? In this new version, we provide two options for this scenario: + +- **Extend** – When a role assignment nears expiration, the user can use Privileged Identity Management to request an extension for the role assignment +- **Renew** – When a role assignment has already expired, the user can use Privileged Identity Management to request a renewal for the role assignment Both user-initiated actions require an approval from a Global Administrator or Privileged Role Administrator. Admins don't need to be in the business of managing assignment expirations. You can just wait for the extension or renewal requests to arrive for simple approval or denial. +For more information, check out the following articles: [Extend or renew Azure AD role assignments](pim-how-to-renew-extend.md), [Extend or renew Azure resource role assignments](pim-resource-roles-renew-extend.md), and [Extend or renew privileged access group assignments](groups-renew-extend.md) + ## Scenarios Privileged Identity Management supports the following scenarios: @@ -131,7 +179,7 @@ With the privileged access groups preview, you can give workload-specific admini ## Invite guest users and assign Azure resource roles in Privileged Identity Management -Azure Active Directory (Azure AD) guest users are part of the business-to-business (B2B) collaboration capabilities within Azure AD so that you can manage external guest users and vendors as guests in Azure AD. For example, you can use these Privileged Identity Management features for Azure identity tasks with guests such as assigning access to specific Azure resources, specifying assignment duration and end date, or requiring two-step verification on active assignment or activation. For more information on how to invite a guest to your organization and manage their access , see [Add B2B collaboration users in the Azure AD portal](../external-identities/add-users-administrator.md). +Azure Active Directory (Azure AD) guest users are part of the business-to-business (B2B) collaboration capabilities within Azure AD so that you can manage external guest users and vendors as guests in Azure AD. For example, you can use these Privileged Identity Management features for Azure identity tasks with guests such as assigning access to specific Azure resources, specifying assignment duration and end date, or requiring two-step verification on active assignment or activation. For more information on how to invite a guest to your organization and manage their access, see [Add B2B collaboration users in the Azure AD portal](../external-identities/add-users-administrator.md). ### When would you invite guests? diff --git a/articles/active-directory/privileged-identity-management/pim-create-azure-ad-roles-and-resource-roles-review.md b/articles/active-directory/privileged-identity-management/pim-create-azure-ad-roles-and-resource-roles-review.md index 10b6e16b22730..b6c4c87b00137 100644 --- a/articles/active-directory/privileged-identity-management/pim-create-azure-ad-roles-and-resource-roles-review.md +++ b/articles/active-directory/privileged-identity-management/pim-create-azure-ad-roles-and-resource-roles-review.md @@ -3,7 +3,7 @@ title: Create an access review of Azure resource and Azure AD roles in PIM - Azu description: Learn how to create an access review of Azure resource and Azure AD roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -11,7 +11,7 @@ ms.workload: identity ms.topic: how-to ms.subservice: pim ms.date: 10/07/2021 -ms.author: mtillman +ms.author: amsliu ms.custom: pim ms.collection: M365-identity-device-management --- diff --git a/articles/active-directory/privileged-identity-management/pim-deployment-plan.md b/articles/active-directory/privileged-identity-management/pim-deployment-plan.md index b52bc6528b234..f9b802c5a33cc 100644 --- a/articles/active-directory/privileged-identity-management/pim-deployment-plan.md +++ b/articles/active-directory/privileged-identity-management/pim-deployment-plan.md @@ -3,7 +3,7 @@ title: Plan a Privileged Identity Management deployment - Azure AD | Microsoft D description: Learn how to deploy Privileged Identity Management (PIM) in your Azure AD organization. services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -11,7 +11,7 @@ ms.workload: identity ms.subservice: pim ms.topic: conceptual ms.date: 12/10/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-email-notifications.md b/articles/active-directory/privileged-identity-management/pim-email-notifications.md index b043ad05ffb72..8f6a78ff7a094 100644 --- a/articles/active-directory/privileged-identity-management/pim-email-notifications.md +++ b/articles/active-directory/privileged-identity-management/pim-email-notifications.md @@ -3,7 +3,7 @@ title: Email notifications in Privileged Identity Management (PIM) - Azure Activ description: Describes email notifications in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.workload: identity @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.topic: conceptual ms.subservice: pim ms.date: 10/07/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-getting-started.md b/articles/active-directory/privileged-identity-management/pim-getting-started.md index 4e67a89e975e7..545aaac42fba0 100644 --- a/articles/active-directory/privileged-identity-management/pim-getting-started.md +++ b/articles/active-directory/privileged-identity-management/pim-getting-started.md @@ -3,7 +3,7 @@ title: Start using PIM - Azure Active Directory | Microsoft Docs description: Learn how to enable and get started using Azure AD Privileged Identity Management (PIM) in the Azure portal. services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -12,7 +12,7 @@ ms.subservice: pim ms.topic: how-to ms.workload: identity ms.date: 10/07/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-how-to-activate-role.md b/articles/active-directory/privileged-identity-management/pim-how-to-activate-role.md index c3803c7e416a7..eb9660f106837 100644 --- a/articles/active-directory/privileged-identity-management/pim-how-to-activate-role.md +++ b/articles/active-directory/privileged-identity-management/pim-how-to-activate-role.md @@ -3,7 +3,7 @@ title: Activate Azure AD roles in PIM - Azure Active Directory | Microsoft Docs description: Learn how to activate Azure AD roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -12,7 +12,7 @@ ms.topic: how-to ms.workload: identity ms.subservice: pim ms.date: 02/02/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-how-to-add-role-to-user.md b/articles/active-directory/privileged-identity-management/pim-how-to-add-role-to-user.md index e96c6a317226f..e23c4c0bd4b9e 100644 --- a/articles/active-directory/privileged-identity-management/pim-how-to-add-role-to-user.md +++ b/articles/active-directory/privileged-identity-management/pim-how-to-add-role-to-user.md @@ -3,7 +3,7 @@ title: Assign Azure AD roles in PIM - Azure Active Directory | Microsoft Docs description: Learn how to assign Azure AD roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -11,7 +11,7 @@ ms.topic: how-to ms.workload: identity ms.subservice: pim ms.date: 02/02/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.collection: M365-identity-device-management ms.custom: subject-rbac-steps diff --git a/articles/active-directory/privileged-identity-management/pim-how-to-change-default-settings.md b/articles/active-directory/privileged-identity-management/pim-how-to-change-default-settings.md index e2ad018a2cfa4..22c1107c4fd84 100644 --- a/articles/active-directory/privileged-identity-management/pim-how-to-change-default-settings.md +++ b/articles/active-directory/privileged-identity-management/pim-how-to-change-default-settings.md @@ -3,7 +3,7 @@ title: Configure Azure AD role settings in PIM - Azure AD | Microsoft Docs description: Learn how to configure Azure AD role settings in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -12,7 +12,7 @@ ms.topic: how-to ms.workload: identity ms.subservice: pim ms.date: 11/12/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-how-to-configure-security-alerts.md b/articles/active-directory/privileged-identity-management/pim-how-to-configure-security-alerts.md index 8fa5d3a8d88a6..a1987062d4e9e 100644 --- a/articles/active-directory/privileged-identity-management/pim-how-to-configure-security-alerts.md +++ b/articles/active-directory/privileged-identity-management/pim-how-to-configure-security-alerts.md @@ -3,7 +3,7 @@ title: Security alerts for Azure AD roles in PIM - Azure AD | Microsoft Docs description: Configure security alerts for Azure AD roles Privileged Identity Management in Azure Active Directory. services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -11,25 +11,25 @@ ms.service: active-directory ms.topic: how-to ms.workload: identity ms.subservice: pim -ms.date: 06/24/2022 -ms.author: mtillman +ms.date: 07/29/2022 +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management --- # Configure security alerts for Azure AD roles in Privileged Identity Management -Privileged Identity Management (PIM) generates alerts when there is suspicious or unsafe activity in your organization in Azure Active Directory (Azure AD), part of Microsoft Entra. When an alert is triggered, it shows up on the Privileged Identity Management dashboard. Select the alert to see a report that lists the users or roles that triggered the alert. +Privileged Identity Management (PIM) generates alerts when there's suspicious or unsafe activity in your organization in Azure Active Directory (Azure AD), part of Microsoft Entra. When an alert is triggered, it shows up on the Privileged Identity Management dashboard. Select the alert to see a report that lists the users or roles that triggered the alert. -![Screenshot that shows the "Alerts" page with a list of alerts and their severity.](./media/pim-how-to-configure-security-alerts/view-alerts.png) +![Screenshot that shows the alerts page with a list of alerts and their severity.](./media/pim-how-to-configure-security-alerts/view-alerts.png) ## Security alerts This section lists all the security alerts for Azure AD roles, along with how to fix and how to prevent. Severity has the following meaning: - **High**: Requires immediate action because of a policy violation. -- **Medium**: Does not require immediate action but signals a potential policy violation. -- **Low**: Does not require immediate action but suggests a preferable policy change. +- **Medium**: Doesn't require immediate action but signals a potential policy violation. +- **Low**: Doesn't require immediate action but suggests a preferable policy change. ### Administrators aren't using their privileged roles @@ -37,8 +37,8 @@ Severity: **Low** | | Description | | --- | --- | -| **Why do I get this alert?** | Users that have been assigned privileged roles they don't need increases the chance of an attack. It is also easier for attackers to remain unnoticed in accounts that are not actively being used. | -| **How to fix?** | Review the users in the list and remove them from privileged roles that they do not need. | +| **Why do I get this alert?** | Users that have been assigned privileged roles they don't need increases the chance of an attack. It's also easier for attackers to remain unnoticed in accounts that aren't actively being used. | +| **How to fix?** | Review the users in the list and remove them from privileged roles that they don't need. | | **Prevention** | Assign privileged roles only to users who have a business justification.
Schedule regular [access reviews](./pim-create-azure-ad-roles-and-resource-roles-review.md) to verify that users still need their access. | | **In-portal mitigation action** | Removes the account from their privileged role. | | **Trigger** | Triggered if a user goes over a specified number of days without activating a role. | @@ -61,7 +61,7 @@ Severity: **Low** | | Description | | --- | --- | -| **Why do I get this alert?** | The current Azure AD organization does not have Azure AD Premium P2. | +| **Why do I get this alert?** | The current Azure AD organization doesn't have Azure AD Premium P2. | | **How to fix?** | Review information about [Azure AD editions](../fundamentals/active-directory-whatis.md). Upgrade to Azure AD Premium P2. | ### Potential stale accounts in a privileged role @@ -71,11 +71,11 @@ Severity: **Medium** | | Description | | --- | --- | -| **Why do I get this alert?** | This alert is no longer triggered based on the last password change date of for an account. This alert is for accounts in a privileged role that haven't signed in during the past *n* days, where *n* is a number of days that is configurable between 1-365 days . These accounts might be service or shared accounts that aren't being maintained and are vulnerable to attackers. | +| **Why do I get this alert?** | This alert is no longer triggered based on the last password change date of for an account. This alert is for accounts in a privileged role that haven't signed in during the past *n* days, where *n* is a number of days that is configurable between 1-365 days. These accounts might be service or shared accounts that aren't being maintained and are vulnerable to attackers. | | **How to fix?** | Review the accounts in the list. If they no longer need access, remove them from their privileged roles. | -| **Prevention** | Ensure that accounts that are shared are rotating strong passwords when there is a change in the users that know the password.
Regularly review accounts with privileged roles using [access reviews](./pim-create-azure-ad-roles-and-resource-roles-review.md) and remove role assignments that are no longer needed. | +| **Prevention** | Ensure that accounts that are shared are rotating strong passwords when there's a change in the users that know the password.
Regularly review accounts with privileged roles using [access reviews](./pim-create-azure-ad-roles-and-resource-roles-review.md) and remove role assignments that are no longer needed. | | **In-portal mitigation action** | Removes the account from their privileged role. | -| **Best practices** | Shared, service, and emergency access accounts that authenticate using a password and are assigned to highly privileged administrative roles such as Global administrator or Security administrator should have their passwords rotated for the following cases:Since multiple people have access to these accounts' credentials, the credentials should be rotated to ensure that people that have left their roles can no longer access the accounts. [Learn more about securing accounts](../roles/security-planning.md) | +| **Best practices** | Shared, service, and emergency access accounts that authenticate using a password and are assigned to highly privileged administrative roles such as Global administrator or Security administrator should have their passwords rotated for the following cases:Since multiple people have access to these accounts' credentials, the credentials should be rotated to ensure that people that have left their roles can no longer access the accounts. [Learn more about securing accounts](../roles/security-planning.md) | ### Roles are being assigned outside of Privileged Identity Management @@ -83,7 +83,7 @@ Severity: **High** | | Description | | --- | --- | -| **Why do I get this alert?** | Privileged role assignments made outside of Privileged Identity Management are not properly monitored and may indicate an active attack. | +| **Why do I get this alert?** | Privileged role assignments made outside of Privileged Identity Management aren't properly monitored and may indicate an active attack. | | **How to fix?** | Review the users in the list and remove them from privileged roles assigned outside of Privileged Identity Management. You can also enable or disable both the alert and its accompanying email notification in the alert settings. | | **Prevention** | Investigate where users are being assigned privileged roles outside of Privileged Identity Management and prohibit future assignments from there. | | **In-portal mitigation action** | Removes the user from their privileged role. | @@ -95,10 +95,10 @@ Severity: **Low** | | Description | | --- | --- | | **Why do I get this alert?** | Global administrator is the highest privileged role. If a Global Administrator is compromised, the attacker gains access to all of their permissions, which puts your whole system at risk. | -| **How to fix?** | Review the users in the list and remove any that do not absolutely need the Global administrator role.
Assign lower privileged roles to these users instead. | +| **How to fix?** | Review the users in the list and remove any that don't absolutely need the Global administrator role.
Assign lower privileged roles to these users instead. | | **Prevention** | Assign users the least privileged role they need. | | **In-portal mitigation action** | Removes the account from their privileged role. | -| **Trigger** | Triggered if two different criteria are met, and you can configure both of them. First, you need to reach a certain threshold of Global administrator role assignments. Second, a certain percentage of your total role assignments must be Global administrators. If you only meet one of these measurements, the alert does not appear. | +| **Trigger** | Triggered if two different criteria are met, and you can configure both of them. First, you need to reach a certain threshold of Global administrator role assignments. Second, a certain percentage of your total role assignments must be Global administrators. If you only meet one of these measurements, the alert doesn't appear. | | **Minimum number of Global Administrators** | This setting specifies the number of Global Administrator role assignments, from 2 to 100, that you consider to be too few for your Azure AD organization. | | **Percentage of Global Administrators** | This setting specifies the minimum percentage of administrators who are Global administrators, from 0% to 100%, below which you do not want your Azure AD organization to dip. | @@ -118,14 +118,22 @@ Severity: **Low** ## Customize security alert settings -On the **Alerts** page, select **Setting**. +Follow these steps to configure security alerts for Azure AD roles in Privileged Identity Management: -![Alerts page with Settings highlighted](media/pim-how-to-configure-security-alerts/alert-settings.png) +1. Sign in to the [Azure portal](https://portal.azure.com/). -Customize settings on the different alerts to work with your environment and security goals. +1. Open **Azure AD Privileged Identity Management**. For information about how to add the Privileged Identity Management tile to your dashboard, see [Start using Privileged Identity Management](pim-getting-started.md). -![Setting page for an alert to enable and configure settings](media/pim-how-to-configure-security-alerts/security-alert-settings.png) +1. From the left menu, select **Azure AD Roles**. + +1. From the left menu, select **Alerts**, and then select **Setting**. + + ![Screenshots of alerts page with the settings highlighted.](media/pim-how-to-configure-security-alerts/alert-settings.png) + +1. Customize settings on the different alerts to work with your environment and security goals. + + ![Screenshots of the alert setting page.](media/pim-how-to-configure-security-alerts/security-alert-settings.png) ## Next steps -- [Configure Azure AD role settings in Privileged Identity Management](pim-how-to-change-default-settings.md) \ No newline at end of file +- [Configure Azure AD role settings in Privileged Identity Management](pim-how-to-change-default-settings.md) diff --git a/articles/active-directory/privileged-identity-management/pim-how-to-renew-extend.md b/articles/active-directory/privileged-identity-management/pim-how-to-renew-extend.md index 9ce125850f438..844976ad60fb8 100644 --- a/articles/active-directory/privileged-identity-management/pim-how-to-renew-extend.md +++ b/articles/active-directory/privileged-identity-management/pim-how-to-renew-extend.md @@ -3,7 +3,7 @@ title: Renew Azure AD role assignments in PIM - Azure Active Directory | Microso description: Learn how to extend or renew Azure Active Directory role assignments in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -12,7 +12,7 @@ ms.tgt_pltfrm: na ms.topic: how-to ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-how-to-require-mfa.md b/articles/active-directory/privileged-identity-management/pim-how-to-require-mfa.md index d0b289a0ae6c9..eebdd1c9ae3de 100644 --- a/articles/active-directory/privileged-identity-management/pim-how-to-require-mfa.md +++ b/articles/active-directory/privileged-identity-management/pim-how-to-require-mfa.md @@ -3,7 +3,7 @@ title: MFA or 2FA and Privileged Identity Management - Azure AD | Microsoft Docs description: Learn how Azure AD Privileged Identity Management (PIM) validates multifactor authentication (MFA). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -12,7 +12,7 @@ ms.topic: how-to ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-how-to-use-audit-log.md b/articles/active-directory/privileged-identity-management/pim-how-to-use-audit-log.md index a8886f903e09f..538bbd3692c57 100644 --- a/articles/active-directory/privileged-identity-management/pim-how-to-use-audit-log.md +++ b/articles/active-directory/privileged-identity-management/pim-how-to-use-audit-log.md @@ -3,7 +3,7 @@ title: View audit log report for Azure AD roles in Azure AD PIM | Microsoft Docs description: Learn how to view the audit log history for Azure AD roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -11,7 +11,7 @@ ms.topic: how-to ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim diff --git a/articles/active-directory/privileged-identity-management/pim-perform-azure-ad-roles-and-resource-roles-review.md b/articles/active-directory/privileged-identity-management/pim-perform-azure-ad-roles-and-resource-roles-review.md index e406e1193dd64..f1971cb2169fa 100644 --- a/articles/active-directory/privileged-identity-management/pim-perform-azure-ad-roles-and-resource-roles-review.md +++ b/articles/active-directory/privileged-identity-management/pim-perform-azure-ad-roles-and-resource-roles-review.md @@ -3,7 +3,7 @@ title: Perform an access review of Azure resource and Azure AD roles in PIM - Az description: Learn how to review access of Azure resource and Azure AD roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -12,7 +12,7 @@ ms.tgt_pltfrm: na ms.topic: how-to ms.subservice: pim ms.date: 10/07/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-activate-your-roles.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-activate-your-roles.md index 96321bbb53330..e28050d90c5bd 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-activate-your-roles.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-activate-your-roles.md @@ -3,7 +3,7 @@ title: Activate Azure resource roles in PIM - Azure AD | Microsoft Docs description: Learn how to activate your Azure resource roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management @@ -82,31 +82,30 @@ The following is a sample HTTP request to activate an eligible assignment for an ### Request ````HTTP -PUT https://management.azure.com/providers/Microsoft.Subscription/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/fea7a502-9a96-4806-a26f-eee560e52045?api-version=2020-10-01 +PUT https://management.azure.com/providers/Microsoft.Subscription/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleEligibilityScheduleRequests/64caffb6-55c0-4deb-a585-68e948ea1ad6?api-version=2020-10-01-preview ```` ### Request body ````JSON -{ -"properties": { - "principalId": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", - "roleDefinitionId": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleDefinitions/c8d4ff99-41c3-41a8-9f60-21dfdad59608", - "requestType": "SelfActivate", - "linkedRoleEligibilityScheduleId": "b1477448-2cc6-4ceb-93b4-54a202a89413", - "scheduleInfo": { - "startDateTime": "2020-09-09T21:35:27.91Z", - "expiration": { - "type": "AfterDuration", - "endDateTime": null, - "duration": "PT8H" - } - }, - "condition": "@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:ContainerName] StringEqualsIgnoreCase 'foo_storage_container'", - "conditionVersion": "1.0" - } -} - +{ + "properties": { + "principalId": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", + "roleDefinitionId": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleDefinitions/c8d4ff99-41c3-41a8-9f60-21dfdad59608", + "requestType": "SelfActivate", + "linkedRoleEligibilityScheduleId": "b1477448-2cc6-4ceb-93b4-54a202a89413", + "scheduleInfo": { + "startDateTime": "2020-09-09T21:35:27.91Z", + "expiration": { + "type": "AfterDuration", + "endDateTime": null, + "duration": "PT8H" + } + }, + "condition": "@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:ContainerName] StringEqualsIgnoreCase 'foo_storage_container'", + "conditionVersion": "1.0" + } +} ```` ### Response @@ -114,58 +113,57 @@ PUT https://management.azure.com/providers/Microsoft.Subscription/subscriptions/ Status code: 201 ````HTTP -{ - "properties": { - "targetRoleAssignmentScheduleId": "c9e264ff-3133-4776-a81a-ebc7c33c8ec6", - "targetRoleAssignmentScheduleInstanceId": null, - "scope": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f", - "roleDefinitionId": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleDefinitions/c8d4ff99-41c3-41a8-9f60-21dfdad59608", - "principalId": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", - "principalType": "User", - "requestType": "SelfActivate", - "status": "Provisioned", - "approvalId": null, - "scheduleInfo": { - "startDateTime": "2020-09-09T21:35:27.91Z", - "expiration": { - "type": "AfterDuration", - "endDateTime": null, - "duration": "PT8H" - } - }, - "ticketInfo": { - "ticketNumber": null, - "ticketSystem": null - }, - "justification": null, - "requestorId": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", - "createdOn": "2020-09-09T21:35:27.91Z", - "condition": "@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:ContainerName] StringEqualsIgnoreCase 'foo_storage_container'", - "conditionVersion": "1.0", - "expandedProperties": { - "scope": { - "id": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f", - "displayName": "Pay-As-You-Go", - "type": "subscription" - }, - "roleDefinition": { - "id": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleDefinitions/c8d4ff99-41c3-41a8-9f60-21dfdad59608", - "displayName": "Contributor", - "type": "BuiltInRole" - }, - "principal": { - "id": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", - "displayName": "User Account", - "email": "user@my-tenant.com", - "type": "User" - } - } - }, - "name": "fea7a502-9a96-4806-a26f-eee560e52045", - "id": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/RoleAssignmentScheduleRequests/fea7a502-9a96-4806-a26f-eee560e52045", - "type": "Microsoft.Authorization/RoleAssignmentScheduleRequests" -} - +{ + "properties": { + "targetRoleAssignmentScheduleId": "c9e264ff-3133-4776-a81a-ebc7c33c8ec6", + "targetRoleAssignmentScheduleInstanceId": null, + "scope": "/providers/Microsoft.Subscription/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f", + "roleDefinitionId": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleDefinitions/c8d4ff99-41c3-41a8-9f60-21dfdad59608", + "principalId": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", + "principalType": "User", + "requestType": "SelfActivate", + "status": "Provisioned", + "approvalId": null, + "scheduleInfo": { + "startDateTime": "2020-09-09T21:35:27.91Z", + "expiration": { + "type": "AfterDuration", + "endDateTime": null, + "duration": "PT8H" + } + }, + "ticketInfo": { + "ticketNumber": null, + "ticketSystem": null + }, + "justification": null, + "requestorId": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", + "createdOn": "2020-09-09T21:35:27.91Z", + "condition": "@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:ContainerName] StringEqualsIgnoreCase 'foo_storage_container'", + "conditionVersion": "1.0", + "expandedProperties": { + "scope": { + "id": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f", + "displayName": "Pay-As-You-Go", + "type": "subscription" + }, + "roleDefinition": { + "id": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleDefinitions/c8d4ff99-41c3-41a8-9f60-21dfdad59608", + "displayName": "Contributor", + "type": "BuiltInRole" + }, + "principal": { + "id": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", + "displayName": "User Account", + "email": "user@my-tenant.com", + "type": "User" + } + } + }, + "name": "fea7a502-9a96-4806-a26f-eee560e52045", + "id": "/providers/Microsoft.Subscription/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/RoleAssignmentScheduleRequests/fea7a502-9a96-4806-a26f-eee560e52045", + "type": "Microsoft.Authorization/RoleAssignmentScheduleRequests" +} ```` ## View the status of your requests diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-approval-workflow.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-approval-workflow.md index 169830263f968..c1f1d4607cb59 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-approval-workflow.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-approval-workflow.md @@ -3,7 +3,7 @@ title: Approve requests for Azure resource roles in PIM - Azure AD | Microsoft D description: Learn how to approve or deny requests for Azure resource roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-assign-roles.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-assign-roles.md index 93cfe5d1fc45c..5221c5fec3c57 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-assign-roles.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-assign-roles.md @@ -3,22 +3,22 @@ title: Assign Azure resource roles in Privileged Identity Management - Azure Act description: Learn how to assign Azure resource roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim -ms.date: 06/24/2022 -ms.author: mtillman +ms.date: 07/29/2022 +ms.author: amsliu ms.custom: pim ms.collection: M365-identity-device-management --- # Assign Azure resource roles in Privileged Identity Management -With Privileged Identity Management (PIM) in Azure Active Directory (Azure AD), part of Microsoft Entra, can manage the built-in Azure resource roles, as well as custom roles, including (but not limited to): +With Privileged Identity Management (PIM) in Azure Active Directory (Azure AD), part of Microsoft Entra, can manage the built-in Azure resource roles, and custom roles, including (but not limited to): - Owner - User Access Administrator @@ -50,61 +50,56 @@ Follow these steps to make a user eligible for an Azure resource role. 1. Select **Azure resources**. -1. Use the resource filter to find the managed resources you're looking for. +1. Select the **Resource type** you want to manage. For example, such as **Resource**, or **Resource group**. Then select the resource you want to manage to open its overview page. - ![List of Azure resources to manage](./media/pim-resource-roles-assign-roles/resources-list.png) - -1. Select the resource that you want to manage to open the resource overview page. + ![Screenshot that shows how to select Azure resources.](./media/pim-resource-roles-assign-roles/resources-list.png) 1. Under **Manage**, select **Roles** to see the list of roles for Azure resources. - ![Azure resources roles](./media/pim-resource-roles-assign-roles/resources-roles.png) - 1. Select **Add assignments** to open the **Add assignments** pane. -1. Select **Select a role** to open the **Select a role** page. + ![Screenshot of Azure resources roles.](./media/pim-resource-roles-assign-roles/resources-roles.png) - ![New assignment pane](./media/pim-resource-roles-assign-roles/resources-select-role.png) +1. Select a **Role** you want to assign. +1. Select **No member selected** link to open the **Select a member or group** pane. -1. Select a role you want to assign and then click **Select**. + ![Screenshot of the new assignment pane.](./media/pim-resource-roles-assign-roles/resources-select-role.png) - The **Select a member or group** pane opens. +1. Select a member or group you want to assign to the role and then choose **Select**. -1. Select a member or group you want to assign to the role and then click **Select**. - - ![Select a member or group pane](./media/pim-resource-roles-assign-roles/resources-select-member-or-group.png) + ![Screenshots that demonstrates how to select a member or group pane](./media/pim-resource-roles-assign-roles/resources-select-member-or-group.png) 1. On the **Settings** tab, in the **Assignment type** list, select **Eligible** or **Active**. - ![Memberships settings pane](./media/pim-resource-roles-assign-roles/resources-membership-settings-type.png) + ![Screenshot of add assignments settings pane.](./media/pim-resource-roles-assign-roles/resources-membership-settings-type.png) Privileged Identity Management for Azure resources provides two distinct assignment types: - **Eligible** assignments require the member of the role to perform an action to use the role. Actions might include performing a multi-factor authentication (MFA) check, providing a business justification, or requesting approval from designated approvers. - - **Active** assignments don't require the member to perform any action to use the role. Members assigned as active have the privileges assigned to the role at all times. + - **Active** assignments don't require the member to perform any action to use the role. Members assigned as active have the privileges assigned ready to use. 1. To specify a specific assignment duration, change the start and end dates and times. 1. If the role has been defined with actions that permit assignments to that role with conditions, then you can select **Add condition** to add a condition based on the principal user and resource attributes that are part of the assignment. - ![New assignment - Conditions](./media/pim-resource-roles-assign-roles/new-assignment-conditions.png) + ![Screenshot of the new assignment conditions pane.](./media/pim-resource-roles-assign-roles/new-assignment-conditions.png) Conditions can be entered in the expression builder. - ![New assignment - Condition built from an expression](./media/pim-resource-roles-assign-roles/new-assignment-condition-expression.png) + ![Screenshot of the new assignment condition built from an expression.](./media/pim-resource-roles-assign-roles/new-assignment-condition-expression.png) 1. When finished, select **Assign**. 1. After the new role assignment is created, a status notification is displayed. - ![New assignment - Notification](./media/pim-resource-roles-assign-roles/resources-new-assignment-notification.png) + ![Screenshot of a new assignment notification.](./media/pim-resource-roles-assign-roles/resources-new-assignment-notification.png) ## Assign a role using ARM API Privileged Identity Management supports Azure Resource Manager (ARM) API commands to manage Azure resource roles, as documented in the [PIM ARM API reference](/rest/api/authorization/roleeligibilityschedulerequests). For the permissions required to use the PIM API, see [Understand the Privileged Identity Management APIs](pim-apis.md). -The following is a sample HTTP request to create an eligible assignment for an Azure role. +The following example is a sample HTTP request to create an eligible assignment for an Azure role. ### Request @@ -121,7 +116,7 @@ PUT https://management.azure.com/providers/Microsoft.Subscription/subscriptions/ "roleDefinitionId": "/subscriptions/dfa2a084-766f-4003-8ae1-c4aeb893a99f/providers/Microsoft.Authorization/roleDefinitions/c8d4ff99-41c3-41a8-9f60-21dfdad59608", "requestType": "AdminAssign", "scheduleInfo": { - "startDateTime": "2020-09-09T21:31:27.91Z", + "startDateTime": "2022-07-05T21:00:00.91Z", "expiration": { "type": "AfterDuration", "endDateTime": null, @@ -151,7 +146,7 @@ Status code: 201 "status": "Provisioned", "approvalId": null, "scheduleInfo": { - "startDateTime": "2020-09-09T21:31:27.91Z", + "startDateTime": "2022-07-05T21:00:00.91Z", "expiration": { "type": "AfterDuration", "endDateTime": null, @@ -164,7 +159,7 @@ Status code: 201 }, "justification": null, "requestorId": "a3bb8764-cb92-4276-9d2a-ca1e895e55ea", - "createdOn": "2020-09-09T21:32:27.91Z", + "createdOn": "2022-07-05T21:00:45.91Z", "condition": "@Resource[Microsoft.Storage/storageAccounts/blobServices/containers:ContainerName] StringEqualsIgnoreCase 'foo_storage_container'", "conditionVersion": "1.0", "expandedProperties": { @@ -200,23 +195,23 @@ Follow these steps to update or remove an existing role assignment. 1. Select **Azure resources**. -1. Select the resource you want to manage to open its overview page. +1. Select the **Resource type** you want to manage. For example, such as **Resource**, or **Resource group**. Then select the resource you want to manage to open its overview page. -1. Under **Manage**, select **Roles** to see the list of roles for Azure resources. + ![Screenshot that shows how to select Azure resources to update.](./media/pim-resource-roles-assign-roles/resources-list.png) - ![Azure resource roles - Select role](./media/pim-resource-roles-assign-roles/resources-update-select-role.png) +1. Under **Manage**, select **Roles** to list the roles for Azure resources. The following screenshot lists the roles of an Azure Storage account. Select the role that you want to update or remove. -1. Select the role that you want to update or remove. + ![Screenshot that shows the roles of an Azure Storage account.](./media/pim-resource-roles-assign-roles/resources-update-select-role.png) 1. Find the role assignment on the **Eligible roles** or **Active roles** tabs. - ![Update or remove role assignment](./media/pim-resource-roles-assign-roles/resources-update-remove.png) + :::image type="content" source="./media/pim-resource-roles-assign-roles/resources-update-remove.png" alt-text="Screenshot demonstrates how to update or remove role assignment." lightbox="./media/pim-resource-roles-assign-roles/resources-update-remove.png"::: 1. To add or update a condition to refine Azure resource access, select **Add** or **View/Edit** in the **Condition** column for the role assignment. Currently, the Storage Blob Data Owner, Storage Blob Data Reader, and the Blob Storage Blob Data Contributor roles in Privileged Identity Management are the only two roles supported as part of the [Azure attribute-based access control public preview](../../role-based-access-control/conditions-overview.md). - ![Update or remove attributes for access control](./media/pim-resource-roles-assign-roles/resources-abac-update-remove.png) +1. Select **Add expression** or **Delete** to update the expression. You can also select **Add condition** to add a new condition to your role. -1. Select **Update** or **Remove** to update or remove the role assignment. + :::image type="content" source="./media/pim-resource-roles-assign-roles/resources-abac-update-remove.png" alt-text="Screenshot that demonstrates how to update or remove attributes of a role assignment." lightbox="./media/pim-resource-roles-assign-roles/resources-abac-update-remove.png"::: For information about extending a role assignment, see [Extend or renew Azure resource roles in Privileged Identity Management](pim-resource-roles-renew-extend.md). diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-configure-alerts.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-configure-alerts.md index 16032052e25da..33f7dc567189b 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-configure-alerts.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-configure-alerts.md @@ -3,15 +3,15 @@ title: Configure security alerts for Azure roles in Privileged Identity Manageme description: Learn how to configure security alerts for Azure resource roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim -ms.date: 06/24/2022 -ms.author: mtillman +ms.date: 07/29/2022 +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management @@ -19,24 +19,24 @@ ms.collection: M365-identity-device-management # Configure security alerts for Azure roles in Privileged Identity Management -Privileged Identity Management (PIM) generates alerts when there is suspicious or unsafe activity in your organization in Azure Active Directory (Azure AD), part of Microsoft Entra. When an alert is triggered, it shows up on the Alerts page. +Privileged Identity Management (PIM) generates alerts when there's suspicious or unsafe activity in your organization in Azure Active Directory (Azure AD), part of Microsoft Entra. When an alert is triggered, it shows up on the Alerts page. -![Azure resources - Alerts page listing alert, risk level, and count](media/pim-resource-roles-configure-alerts/rbac-alerts-page.png) +![Screenshot of the alerts page listing alert, risk level, and count.](media/pim-resource-roles-configure-alerts/rbac-alerts-page.png) ## Review alerts Select an alert to see a report that lists the users or roles that triggered the alert, along with remediation guidance. -![Alert report showing last scan time, description, mitigation steps, type, severity, security impact, and how to prevent next time](media/pim-resource-roles-configure-alerts/rbac-alert-info.png) +![Screenshot of the alert report showing last scan time, description, mitigation steps, type, severity, security impact, and how to prevent next time.](media/pim-resource-roles-configure-alerts/rbac-alert-info.png) ## Alerts Alert | Severity | Trigger | Recommendation --- | --- | --- | --- **Too many owners assigned to a resource** | Medium | Too many users have the owner role. | Review the users in the list and reassign some to less privileged roles. -**Too many permanent owners assigned to a resource** | Medium | Too many users are permanently assigned to a role. | Review the users in the list and re-assign some to require activation for role use. +**Too many permanent owners assigned to a resource** | Medium | Too many users are permanently assigned to a role. | Review the users in the list and reassign some to require activation for role use. **Duplicate role created** | Medium | Multiple roles have the same criteria. | Use only one of these roles. -**Roles are being assigned outside of Privileged Identity Management (Preview)** | High | A role is managed directly through the Azure IAM resource blade or the Azure Resource Manager API | Review the users in the list and remove them from privileged roles assigned outside of Privilege Identity Management. +**Roles are being assigned outside of Privileged Identity Management (Preview)** | High | A role is managed directly through the Azure IAM resource, or the Azure Resource Manager API. | Review the users in the list and remove them from privileged roles assigned outside of Privilege Identity Management. > [!NOTE] > During the public preview of the **Roles are being assigned outside of Privileged Identity Management (Preview)** alert, Microsoft supports only permissions that are assigned at the subscription level. @@ -44,18 +44,28 @@ Alert | Severity | Trigger | Recommendation ### Severity - **High**: Requires immediate action because of a policy violation. -- **Medium**: Does not require immediate action but signals a potential policy violation. -- **Low**: Does not require immediate action but suggests a preferred policy change. +- **Medium**: Doesn't require immediate action but signals a potential policy violation. +- **Low**: Doesn't require immediate action but suggests a preferred policy change. ## Configure security alert settings -From the Alerts page, go to **Settings**. +Follow these steps to configure security alerts for Azure roles in Privileged Identity Management: -![Alerts page with Settings highlighted](media/pim-resource-roles-configure-alerts/rbac-navigate-settings.png) +1. Sign in to the [Azure portal](https://portal.azure.com/). -Customize settings on the different alerts to work with your environment and security goals. +1. Open **Azure AD Privileged Identity Management**. For information about how to add the Privileged Identity Management tile to your dashboard, see [Start using Privileged Identity Management](pim-getting-started.md). -![Setting page for an alert to enable and configure settings](media/pim-resource-roles-configure-alerts/rbac-alert-settings.png) +1. From the left menu, select **Azure resources**. + +1. From the list of resources, select your Azure subscription. + +1. On the **Alerts** page, select **Settings**. + + ![Screenshot of the alerts page with settings highlighted.](media/pim-resource-roles-configure-alerts/rbac-navigate-settings.png) + +1. Customize settings on the different alerts to work with your environment and security goals. + + ![Screenshot of the alert setting.](media/pim-resource-roles-configure-alerts/rbac-alert-settings.png) ## Next steps diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-configure-role-settings.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-configure-role-settings.md index b907951c4d827..a467411e19b5f 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-configure-role-settings.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-configure-role-settings.md @@ -3,7 +3,7 @@ title: Configure Azure resource role settings in PIM - Azure AD | Microsoft Docs description: Learn how to configure Azure resource role settings in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/24/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-custom-role-policy.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-custom-role-policy.md index 3d2254cd797fc..39423b36a4871 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-custom-role-policy.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-custom-role-policy.md @@ -3,7 +3,7 @@ title: Use Azure custom roles in PIM - Azure AD | Microsoft Docs description: Learn how to use Azure custom roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/27/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.collection: M365-identity-device-management --- @@ -46,4 +46,4 @@ Finally, [assign roles](pim-resource-roles-assign-roles.md) to the distinct grou ## Next steps - [Configure Azure resource role settings in Privileged Identity Management](pim-resource-roles-configure-role-settings.md) -- [Custom roles in Azure](../../role-based-access-control/custom-roles.md) \ No newline at end of file +- [Custom roles in Azure](../../role-based-access-control/custom-roles.md) diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-discover-resources.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-discover-resources.md index c9da318d65120..3f48967711def 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-discover-resources.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-discover-resources.md @@ -3,7 +3,7 @@ title: Discover Azure resources to manage in PIM - Azure AD | Microsoft Docs description: Learn how to discover Azure resources to manage in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran ms.service: active-directory ms.topic: how-to @@ -11,7 +11,7 @@ ms.tgt_pltfrm: na ms.workload: identity ms.subservice: pim ms.date: 06/27/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.collection: M365-identity-device-management --- diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-overview-dashboards.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-overview-dashboards.md index 34749cd62d479..8a7eb93425475 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-overview-dashboards.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-overview-dashboards.md @@ -3,7 +3,7 @@ title: Resource dashboards for access reviews in PIM - Azure AD | Microsoft Docs description: Describes how to use a resource dashboard to perform an access review in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: markwahl-msft ms.service: active-directory @@ -12,7 +12,7 @@ ms.tgt_pltfrm: na ms.topic: how-to ms.subservice: pim ms.date: 06/27/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management @@ -38,4 +38,4 @@ Below the charts are listed the number of users and groups with new role assignm ## Next steps -- [Start an access review for Azure resource roles in Privileged Identity Management](./pim-create-azure-ad-roles-and-resource-roles-review.md) \ No newline at end of file +- [Start an access review for Azure resource roles in Privileged Identity Management](./pim-create-azure-ad-roles-and-resource-roles-review.md) diff --git a/articles/active-directory/privileged-identity-management/pim-resource-roles-renew-extend.md b/articles/active-directory/privileged-identity-management/pim-resource-roles-renew-extend.md index 1ef2c40cd481c..42a3c48addaf7 100644 --- a/articles/active-directory/privileged-identity-management/pim-resource-roles-renew-extend.md +++ b/articles/active-directory/privileged-identity-management/pim-resource-roles-renew-extend.md @@ -3,7 +3,7 @@ title: Renew Azure resource role assignments in PIM - Azure AD | Microsoft Docs description: Learn how to extend or renew Azure resource role assignments in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -12,7 +12,7 @@ ms.tgt_pltfrm: na ms.topic: how-to ms.subservice: pim ms.date: 10/19/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/pim-roles.md b/articles/active-directory/privileged-identity-management/pim-roles.md index 1c052839c39bd..1f683ee9eddf7 100644 --- a/articles/active-directory/privileged-identity-management/pim-roles.md +++ b/articles/active-directory/privileged-identity-management/pim-roles.md @@ -3,7 +3,7 @@ title: Roles you cannot manage in Privileged Identity Management - Azure Active description: Describes the roles you cannot manage in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -12,7 +12,7 @@ ms.topic: conceptual ms.workload: identity ms.subservice: pim ms.date: 06/27/2022 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ; H1Hack27Feb2017;oldportal;it-pro; ms.collection: M365-identity-device-management @@ -43,4 +43,4 @@ We support all Microsoft 365 roles in the Azure AD Roles and Administrators port ## Next steps - [Assign Azure AD roles in Privileged Identity Management](pim-how-to-add-role-to-user.md) -- [Assign Azure resource roles in Privileged Identity Management](pim-resource-roles-assign-roles.md) \ No newline at end of file +- [Assign Azure resource roles in Privileged Identity Management](pim-resource-roles-assign-roles.md) diff --git a/articles/active-directory/privileged-identity-management/pim-security-wizard.md b/articles/active-directory/privileged-identity-management/pim-security-wizard.md index c4bca42b4026c..b40d6287f8414 100644 --- a/articles/active-directory/privileged-identity-management/pim-security-wizard.md +++ b/articles/active-directory/privileged-identity-management/pim-security-wizard.md @@ -3,7 +3,7 @@ title: Azure AD roles Discovery and insights (preview) in Privileged Identity Ma description: Discovery and insights (formerly Security Wizard) help you convert permanent Azure AD role assignments to just-in-time assignments with Privileged Identity Management. services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -11,8 +11,8 @@ ms.service: active-directory ms.topic: how-to ms.workload: identity ms.subservice: pim -ms.date: 06/27/2022 -ms.author: mtillman +ms.date: 07/29/2022 +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ; H1Hack27Feb2017 ms.collection: M365-identity-device-management @@ -36,7 +36,7 @@ Also, keep role assignments permanent if a user has a Microsoft account (in othe 1. Open **Azure AD Privileged Identity Management**. -1. Select **Azure AD roles** and then select **Discovery and insights (Preview)**. Opening the page begins the discovery process to find relevant role assignments. +1. From the left menu, select **Azure AD roles** and then select **Discovery and insights (Preview)**. Opening the page begins the discovery process to find relevant role assignments. ![Azure AD roles - Discovery and insights page showing the 3 options](./media/pim-security-wizard/new-preview-link.png) diff --git a/articles/active-directory/privileged-identity-management/pim-troubleshoot.md b/articles/active-directory/privileged-identity-management/pim-troubleshoot.md index 9f7a318f73f07..6f15c22b0d4e3 100644 --- a/articles/active-directory/privileged-identity-management/pim-troubleshoot.md +++ b/articles/active-directory/privileged-identity-management/pim-troubleshoot.md @@ -3,7 +3,7 @@ title: Troubleshoot resource access denied in Privileged Identity Management - A description: Learn how to troubleshoot system errors with roles in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' ms.service: active-directory @@ -11,7 +11,7 @@ ms.topic: how-to ms.workload: identity ms.subservice: pim ms.date: 10/07/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.collection: M365-identity-device-management --- @@ -38,4 +38,4 @@ Assign the User Access Administrator role to the Privileged identity Management - [License requirements to use Privileged Identity Management](subscription-requirements.md) - [Securing privileged access for hybrid and cloud deployments in Azure AD](../roles/security-planning.md?toc=%2fazure%2factive-directory%2fprivileged-identity-management%2ftoc.json) -- [Deploy Privileged Identity Management](pim-deployment-plan.md) \ No newline at end of file +- [Deploy Privileged Identity Management](pim-deployment-plan.md) diff --git a/articles/active-directory/privileged-identity-management/powershell-for-azure-ad-roles.md b/articles/active-directory/privileged-identity-management/powershell-for-azure-ad-roles.md index 794c041440ed6..2559ea4293ea6 100644 --- a/articles/active-directory/privileged-identity-management/powershell-for-azure-ad-roles.md +++ b/articles/active-directory/privileged-identity-management/powershell-for-azure-ad-roles.md @@ -3,7 +3,7 @@ title: PowerShell for Azure AD roles in PIM - Azure AD | Microsoft Docs description: Manage Azure AD roles using PowerShell cmdlets in Azure AD Privileged Identity Management (PIM). services: active-directory documentationcenter: '' -author: mtillman +author: amsliu manager: karenhoran editor: '' @@ -13,7 +13,7 @@ ms.topic: how-to ms.tgt_pltfrm: na ms.workload: identity ms.date: 10/07/2021 -ms.author: mtillman +ms.author: amsliu ms.reviewer: shaunliu ms.custom: pim ms.collection: M365-identity-device-management diff --git a/articles/active-directory/privileged-identity-management/subscription-requirements.md b/articles/active-directory/privileged-identity-management/subscription-requirements.md index 6e5be921e9ac7..12f62fc42522c 100644 --- a/articles/active-directory/privileged-identity-management/subscription-requirements.md +++ b/articles/active-directory/privileged-identity-management/subscription-requirements.md @@ -70,4 +70,4 @@ If an Azure AD Premium P2, EMS E5, or trial license expires, Privileged Identity - [Start using Privileged Identity Management](pim-getting-started.md) - [Roles you can't manage in Privileged Identity Management](pim-roles.md) - [Create an access review of Azure resource roles in PIM](./pim-create-azure-ad-roles-and-resource-roles-review.md) -- [Create an access review of Azure AD roles in PIM](./pim-create-azure-ad-roles-and-resource-roles-review.md) \ No newline at end of file +- [Create an access review of Azure AD roles in PIM](./pim-create-azure-ad-roles-and-resource-roles-review.md) diff --git a/articles/active-directory/saas-apps/8x8-provisioning-tutorial.md b/articles/active-directory/saas-apps/8x8-provisioning-tutorial.md index 66af5935b7fc8..5eef83a6ae109 100644 --- a/articles/active-directory/saas-apps/8x8-provisioning-tutorial.md +++ b/articles/active-directory/saas-apps/8x8-provisioning-tutorial.md @@ -20,7 +20,7 @@ This tutorial describes the steps you need to perform in both 8x8 Admin Console ## Capabilities supported > [!div class="checklist"] > * Create users in 8x8 -> * Remove users in 8x8 when they do not require access anymore +> * Deactivate users in 8x8 when they do not require access anymore > * Keep user attributes synchronized between Azure AD and 8x8 > * [Single sign-on](./8x8virtualoffice-tutorial.md) to 8x8 (recommended) @@ -48,17 +48,17 @@ This section guides you through the steps to configure 8x8 to support provisioni ### To configure a user provisioning access token in 8x8 Admin Console: -1. Sign in to [Admin Console](https://admin.8x8.com). Select **Identity Management**. +1. Sign in to [Admin Console](https://admin.8x8.com). Select **Identity and Security**. - ![Admin](./media/8x8-provisioning-tutorial/8x8-identity-management.png) + [ ![Screenshot showing the 8x8 Admin Console.](./media/8x8-provisioning-tutorial/8x8-identity-and-security.png) ](./media/8x8-provisioning-tutorial/8x8-identity-and-security.png#lightbox) -2. Click the **Show user provisioning information** link to generate a token. +2. In the **User Provisioning Integration (SCIM)** pane, click the toggle to enable and then click **Save**. - ![Show](./media/8x8-provisioning-tutorial/8x8-show-user-provisioning.png) + [ ![Screenshot showing the Identity and Security page of the Admin Console with a callout over the user provisioning integration slider.](./media/8x8-provisioning-tutorial/8x8-enable-user-provisioning.png) ](./media/8x8-provisioning-tutorial/8x8-enable-user-provisioning.png#lightbox) 3. Copy the **8x8 URL** and **8x8 API Token** values. These values will be entered in the **Tenant URL** and **Secret Token** fields respectively in the Provisioning tab of your 8x8 application in the Azure portal. - ![Token](./media/8x8-provisioning-tutorial/8x8-copy-url-token.png) + [ ![Screenshot showing the Identity and Security page of the Admin Console with callout over token fields.](./media/8x8-provisioning-tutorial/8x8-copy-url-token.png) ](./media/8x8-provisioning-tutorial/8x8-copy-url-token.png#lightbox) ## Step 3. Add 8x8 from the Azure AD application gallery @@ -82,19 +82,19 @@ This section guides you through the steps to configure the Azure AD provisioning 1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise Applications**, then select **All applications**. - ![Enterprise applications blade](./media/8x8-provisioning-tutorial/enterprise-applications.png) + ![Screenshot showing the Enterprise applications blade](./media/8x8-provisioning-tutorial/enterprise-applications.png) - ![All applications blade](./media/8x8-provisioning-tutorial/all-applications.png) + ![Screenshot showing the All applications blade](./media/8x8-provisioning-tutorial/all-applications.png) 2. In the applications list, select **8x8**. - ![The 8x8 link in the Applications list](common/all-applications.png) + ![Screenshot showing the 8x8 link in the Applications list](common/all-applications.png) 3. Select the **Provisioning** tab. Click on **Get started**. ![Screenshot of the Manage options with the Provisioning option called out.](common/provisioning.png) - ![Get started blade](./media/8x8-provisioning-tutorial/get-started.png) + ![Screenshot showing the Get started blade](./media/8x8-provisioning-tutorial/get-started.png) 4. Set the **Provisioning Mode** to **Automatic**. @@ -106,7 +106,7 @@ This section guides you through the steps to configure the Azure AD provisioning 6. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box. - ![Notification Email](common/provisioning-notification-email.png) + ![Screenshot showing the Notification Email field.](common/provisioning-notification-email.png) 7. Select **Save**. @@ -160,4 +160,4 @@ Once you've configured provisioning, use the following resources to monitor your ## Next steps -* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md) \ No newline at end of file +* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md) diff --git a/articles/active-directory/saas-apps/articulate360-tutorial.md b/articles/active-directory/saas-apps/articulate360-tutorial.md index 79a7e27754f07..98ded8bf37bdc 100644 --- a/articles/active-directory/saas-apps/articulate360-tutorial.md +++ b/articles/active-directory/saas-apps/articulate360-tutorial.md @@ -9,7 +9,7 @@ ms.service: active-directory ms.subservice: saas-app-tutorial ms.workload: identity ms.topic: tutorial -ms.date: 06/27/2022 +ms.date: 07/19/2022 ms.author: jeedes --- @@ -91,7 +91,7 @@ Follow these steps to enable Azure AD SSO in the Azure portal. ![Screenshot shows the image of attributes.](common/default-attributes.png "Attributes") -1. In addition to above, Articulate 360 application expects few more attributes to be passed back in SAML response, which are shown below. These attributes are also pre populated but you can review them as per your requirements. +1. Articulate 360 application expects the default attributes to be replaced with the specific attributes as shown below. These attributes are also pre populated but you can review them as per your requirements. | Name | Source Attribute| | ------------ | --------- | diff --git a/articles/active-directory/saas-apps/aws-clientvpn-tutorial.md b/articles/active-directory/saas-apps/aws-clientvpn-tutorial.md index 92afb389b267d..3ce0186ac97c5 100644 --- a/articles/active-directory/saas-apps/aws-clientvpn-tutorial.md +++ b/articles/active-directory/saas-apps/aws-clientvpn-tutorial.md @@ -9,7 +9,7 @@ ms.service: active-directory ms.subservice: saas-app-tutorial ms.workload: identity ms.topic: tutorial -ms.date: 06/17/2021 +ms.date: 07/19/2022 ms.author: jeedes --- @@ -96,7 +96,7 @@ Follow these steps to enable Azure AD SSO in the Azure portal. 1. Click on **Manifest** and you need to keep the Reply URL as **http** instead of **https** to get the integration working, click on **Save**. - ![manifest page](./media/aws-clientvpn-tutorial/reply-url.png) + ![The Screenshot for the manifest page.](./media/aws-clientvpn-tutorial/reply-url.png) 1. AWS ClientVPN application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes. @@ -107,11 +107,17 @@ Follow these steps to enable Azure AD SSO in the Azure portal. | Name | Source Attribute| | -------------- | --------- | | memberOf | user.groups | + | FirstName | user.givenname | + | LastName | user.surname | 1. On the **Set up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Federation Metadata XML** and select **Download** to download the certificate and save it on your computer. ![The Certificate download link](common/metadataxml.png) +1. In the **SAML Signing Certificate** section, click the edit icon and change the **Signing Option** to **Sign SAML response and assertion**. Click **Save**. + + ![The screenshot for the SAML Signing Certificate page.](./media/aws-clientvpn-tutorial/signing-certificate.png) + 1. On the **Set up AWS ClientVPN** section, copy the appropriate URL(s) based on your requirement. ![Copy configuration URLs](common/copy-configuration-urls.png) diff --git a/articles/active-directory/saas-apps/cheetah-for-benelux-tutorial.md b/articles/active-directory/saas-apps/cheetah-for-benelux-tutorial.md new file mode 100644 index 0000000000000..babd67165acff --- /dev/null +++ b/articles/active-directory/saas-apps/cheetah-for-benelux-tutorial.md @@ -0,0 +1,138 @@ +--- +title: 'Tutorial: Azure AD SSO integration with Cheetah For Benelux' +description: Learn how to configure single sign-on between Azure Active Directory and Cheetah For Benelux. +services: active-directory +author: jeevansd +manager: CelesteDG +ms.reviewer: CelesteDG +ms.service: active-directory +ms.subservice: saas-app-tutorial +ms.workload: identity +ms.topic: tutorial +ms.date: 07/21/2022 +ms.author: jeedes + +--- + +# Tutorial: Azure AD SSO integration with Cheetah For Benelux + +In this tutorial, you'll learn how to integrate Cheetah For Benelux with Azure Active Directory (Azure AD). When you integrate Cheetah For Benelux with Azure AD, you can: + +* Control in Azure AD who has access to Cheetah For Benelux. +* Enable your users to be automatically signed-in to Cheetah For Benelux with their Azure AD accounts. +* Manage your accounts in one central location - the Azure portal. + +## Prerequisites + +To get started, you need the following items: + +* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/). +* Cheetah For Benelux single sign-on (SSO) enabled subscription. +* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD. +For more information, see [Azure built-in roles](../roles/permissions-reference.md). + +## Scenario description + +In this tutorial, you configure and test Azure AD SSO in a test environment. + +* Cheetah For Benelux supports **SP** initiated SSO. +* Cheetah For Benelux supports **Just In Time** user provisioning. + +> [!NOTE] +> Identifier of this application is a fixed string value so only one instance can be configured in one tenant. + +## Add Cheetah For Benelux from the gallery + +To configure the integration of Cheetah For Benelux into Azure AD, you need to add Cheetah For Benelux from the gallery to your list of managed SaaS apps. + +1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account. +1. On the left navigation pane, select the **Azure Active Directory** service. +1. Navigate to **Enterprise Applications** and then select **All Applications**. +1. To add new application, select **New application**. +1. In the **Add from the gallery** section, type **Cheetah For Benelux** in the search box. +1. Select **Cheetah For Benelux** from results panel and then add the app. Wait a few seconds while the app is added to your tenant. + +## Configure and test Azure AD SSO for Cheetah For Benelux + +Configure and test Azure AD SSO with Cheetah For Benelux using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in Cheetah For Benelux. + +To configure and test Azure AD SSO with Cheetah For Benelux, perform the following steps: + +1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature. + 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon. + 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on. +1. **[Configure Cheetah For Benelux SSO](#configure-cheetah-for-benelux-sso)** - to configure the single sign-on settings on application side. + 1. **[Create Cheetah For Benelux test user](#create-cheetah-for-benelux-test-user)** - to have a counterpart of B.Simon in Cheetah For Benelux that is linked to the Azure AD representation of user. +1. **[Test SSO](#test-sso)** - to verify whether the configuration works. + +## Configure Azure AD SSO + +Follow these steps to enable Azure AD SSO in the Azure portal. + +1. In the Azure portal, on the **Cheetah For Benelux** application integration page, find the **Manage** section and select **single sign-on**. +1. On the **Select a single sign-on method** page, select **SAML**. +1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings. + + ![Screenshot shows to edit Basic S A M L Configuration.](common/edit-urls.png "Basic Configuration") + +1. On the **Basic SAML Configuration** section, perform the following steps: + + a. In the **Reply URL** textbox, type the URL: + `https://ups.eu.sso.cheetah.com/saml2/idpresponse` + + b. In the **Sign-on URL** text box, type the URL: + `https://ups.eu.sso.cheetah.com/login?client_id=5c2m16mhv4cd4o5cpgekmsmlne&response_type=token&scope=aws.cognito.signin.user.admin+openid+profile&redirect_uri=https://prodeditor.eu.cheetah.com/CssWebTask/landing/?cheetah_client=BNLX` + +1. On the **Set-up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Federation Metadata XML** and select **Download** to download the certificate and save it on your computer. + + ![Screenshot shows the Certificate download link.](common/metadataxml.png "Certificate") + +1. On the **Set up Cheetah For Benelux** section, copy the appropriate URL(s) based on your requirement. + + ![Screenshot shows to copy configuration appropriate U R L.](common/copy-configuration-urls.png "Metadata") + +### Create an Azure AD test user + +In this section, you'll create a test user in the Azure portal called B.Simon. + +1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**. +1. Select **New user** at the top of the screen. +1. In the **User** properties, follow these steps: + 1. In the **Name** field, enter `B.Simon`. + 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`. + 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box. + 1. Click **Create**. + +### Assign the Azure AD test user + +In this section, you'll enable B.Simon to use Azure single sign-on by granting access to Cheetah For Benelux. + +1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**. +1. In the applications list, select **Cheetah For Benelux**. +1. In the app's overview page, find the **Manage** section and select **Users and groups**. +1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog. +1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen. +1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected. +1. In the **Add Assignment** dialog, click the **Assign** button. + +## Configure Cheetah For Benelux SSO + +To configure single sign-on on **Cheetah For Benelux** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [Cheetah For Benelux support team](mailto:support@cheetah.com). They set this setting to have the SAML SSO connection set properly on both sides. + +### Create Cheetah For Benelux test user + +In this section, a user called B.Simon is created in Cheetah For Benelux. Cheetah For Benelux supports just-in-time user provisioning, which is enabled by default. There is no action item for you in this section. If a user doesn't already exist in Cheetah For Benelux, a new one is created after authentication. + +## Test SSO + +In this section, you test your Azure AD single sign-on configuration with following options. + +* Click on **Test this application** in Azure portal. This will redirect to Cheetah For Benelux Sign-on URL where you can initiate the login flow. + +* Go to Cheetah For Benelux Sign-on URL directly and initiate the login flow from there. + +* You can use Microsoft My Apps. When you click the Cheetah For Benelux tile in the My Apps, this will redirect to Cheetah For Benelux Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md). + +## Next steps + +Once you configure Cheetah For Benelux you can enforce session control, which protects exfiltration and infiltration of your organization’s sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad). \ No newline at end of file diff --git a/articles/active-directory/saas-apps/ediwin-saas-edi-tutorial.md b/articles/active-directory/saas-apps/ediwin-saas-edi-tutorial.md new file mode 100644 index 0000000000000..de854efa3505d --- /dev/null +++ b/articles/active-directory/saas-apps/ediwin-saas-edi-tutorial.md @@ -0,0 +1,140 @@ +--- +title: 'Tutorial: Azure AD SSO integration with Ediwin SaaS EDI' +description: Learn how to configure single sign-on between Azure Active Directory and Ediwin SaaS EDI. +services: active-directory +author: jeevansd +manager: CelesteDG +ms.reviewer: CelesteDG +ms.service: active-directory +ms.subservice: saas-app-tutorial +ms.workload: identity +ms.topic: tutorial +ms.date: 07/23/2022 +ms.author: jeedes + +--- + +# Tutorial: Azure AD SSO integration with Ediwin SaaS EDI + +In this tutorial, you'll learn how to integrate Ediwin SaaS EDI with Azure Active Directory (Azure AD). When you integrate Ediwin SaaS EDI with Azure AD, you can: + +* Control in Azure AD who has access to Ediwin SaaS EDI. +* Enable your users to be automatically signed-in to Ediwin SaaS EDI with their Azure AD accounts. +* Manage your accounts in one central location - the Azure portal. + +## Prerequisites + +To get started, you need the following items: + +* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/). +* Ediwin SaaS EDI single sign-on (SSO) enabled subscription. +* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD. +For more information, see [Azure built-in roles](../roles/permissions-reference.md). + +## Scenario description + +In this tutorial, you configure and test Azure AD SSO in a test environment. + +* Ediwin SaaS EDI supports **SP** initiated SSO. + +## Add Ediwin SaaS EDI from the gallery + +To configure the integration of Ediwin SaaS EDI into Azure AD, you need to add Ediwin SaaS EDI from the gallery to your list of managed SaaS apps. + +1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account. +1. On the left navigation pane, select the **Azure Active Directory** service. +1. Navigate to **Enterprise Applications** and then select **All Applications**. +1. To add new application, select **New application**. +1. In the **Add from the gallery** section, type **Ediwin SaaS EDI** in the search box. +1. Select **Ediwin SaaS EDI** from results panel and then add the app. Wait a few seconds while the app is added to your tenant. + +## Configure and test Azure AD SSO for Ediwin SaaS EDI + +Configure and test Azure AD SSO with Ediwin SaaS EDI using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in Ediwin SaaS EDI. + +To configure and test Azure AD SSO with Ediwin SaaS EDI, perform the following steps: + +1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature. + 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon. + 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on. +1. **[Configure Ediwin SaaS EDI SSO](#configure-ediwin-saas-edi-sso)** - to configure the single sign-on settings on application side. + 1. **[Create Ediwin SaaS EDI test user](#create-ediwin-saas-edi-test-user)** - to have a counterpart of B.Simon in Ediwin SaaS EDI that is linked to the Azure AD representation of user. +1. **[Test SSO](#test-sso)** - to verify whether the configuration works. + +## Configure Azure AD SSO + +Follow these steps to enable Azure AD SSO in the Azure portal. + +1. In the Azure portal, on the **Ediwin SaaS EDI** application integration page, find the **Manage** section and select **single sign-on**. +1. On the **Select a single sign-on method** page, select **SAML**. +1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings. + + ![Screenshot shows to edit Basic S A M L Configuration.](common/edit-urls.png "Basic Configuration") + +1. On the **Basic SAML Configuration** section, perform the following steps: + + a. In the **Identifier** textbox, type a URL using the following pattern: + `https://web.sedeb2b.com/` + + b. In the **Reply URL** textbox, type a URL using the following pattern: + `https://web.sedeb2b.com/Ediwin/samlLogin/` + + c. In the **Sign-on URL** text box, type a URL using the following pattern: + `https://web.sedeb2b.com/Ediwin/samlLogin/` + + > [!Note] + > These values are not real. Update these values with the actual Identifier, Reply URL and Sign on URL. Contact [Ediwin SaaS EDI support team](mailto:cau@edicomgroup.com) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal. + +1. On the **Set-up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Federation Metadata XML** and select **Download** to download the certificate and save it on your computer. + + ![Screenshot shows the Certificate download link.](common/metadataxml.png "Certificate") + +1. On the **Set up Ediwin SaaS EDI** section, copy the appropriate URL(s) based on your requirement. + + ![Screenshot shows to copy configuration appropriate U R L.](common/copy-configuration-urls.png "Attributes") + +### Create an Azure AD test user + +In this section, you'll create a test user in the Azure portal called B.Simon. + +1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**. +1. Select **New user** at the top of the screen. +1. In the **User** properties, follow these steps: + 1. In the **Name** field, enter `B.Simon`. + 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`. + 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box. + 1. Click **Create**. + +### Assign the Azure AD test user + +In this section, you'll enable B.Simon to use Azure single sign-on by granting access to Ediwin SaaS EDI. + +1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**. +1. In the applications list, select **Ediwin SaaS EDI**. +1. In the app's overview page, find the **Manage** section and select **Users and groups**. +1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog. +1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen. +1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected. +1. In the **Add Assignment** dialog, click the **Assign** button. + +## Configure Ediwin SaaS EDI SSO + +To configure single sign-on on **Ediwin SaaS EDI** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [Ediwin SaaS EDI support team](mailto:cau@edicomgroup.com). They set this setting to have the SAML SSO connection set properly on both sides. + +### Create Ediwin SaaS EDI test user + +In this section, you create a user called Britta Simon in Ediwin SaaS EDI. Work with [Ediwin SaaS EDI support team](mailto:cau@edicomgroup.com) to add the users in the Ediwin SaaS EDI platform. Users must be created and activated before you use single sign-on. + +## Test SSO + +In this section, you test your Azure AD single sign-on configuration with following options. + +* Click on **Test this application** in Azure portal. This will redirect to Ediwin SaaS EDI Sign-on URL where you can initiate the login flow. + +* Go to Ediwin SaaS EDI Sign-on URL directly and initiate the login flow from there. + +* You can use Microsoft My Apps. When you click the Ediwin SaaS EDI tile in the My Apps, this will redirect to Ediwin SaaS EDI Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md). + +## Next steps + +Once you configure Ediwin SaaS EDI you can enforce session control, which protects exfiltration and infiltration of your organization’s sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad). \ No newline at end of file diff --git a/articles/active-directory/saas-apps/expensify-tutorial.md b/articles/active-directory/saas-apps/expensify-tutorial.md index 1fbec529ed216..28e89977d71ba 100644 --- a/articles/active-directory/saas-apps/expensify-tutorial.md +++ b/articles/active-directory/saas-apps/expensify-tutorial.md @@ -119,7 +119,7 @@ In this section, you'll enable B.Simon to use Azure single sign-on by granting a ## Configure Expensify SSO -To enable SSO in Expensify, you first need to enable **Domain Control** in the application. You can enable Domain Control in the application through the steps listed [here](https://help.expensify.com/domain-control). For additional support, work with [Expensify Client support team](mailto:help@expensify.com). Once you have Domain Control enabled, follow these steps: +To enable SSO in Expensify, you first need to enable **Domain Control** in the application. For additional support, work with [Expensify Client support team](mailto:help@expensify.com). Once you have Domain Control enabled, follow these steps: ![Configure Single Sign-On](./media/expensify-tutorial/domain-control.png) diff --git a/articles/active-directory/saas-apps/figbytes-tutorial.md b/articles/active-directory/saas-apps/figbytes-tutorial.md new file mode 100644 index 0000000000000..c98a63a165451 --- /dev/null +++ b/articles/active-directory/saas-apps/figbytes-tutorial.md @@ -0,0 +1,142 @@ +--- +title: 'Tutorial: Azure AD SSO integration with FigBytes' +description: Learn how to configure single sign-on between Azure Active Directory and FigBytes. +services: active-directory +author: jeevansd +manager: CelesteDG +ms.reviewer: CelesteDG +ms.service: active-directory +ms.subservice: saas-app-tutorial +ms.workload: identity +ms.topic: tutorial +ms.date: 07/21/2022 +ms.author: jeedes + +--- + +# Tutorial: Azure AD SSO integration with FigBytes + +In this tutorial, you'll learn how to integrate FigBytes with Azure Active Directory (Azure AD). When you integrate FigBytes with Azure AD, you can: + +* Control in Azure AD who has access to FigBytes. +* Enable your users to be automatically signed-in to FigBytes with their Azure AD accounts. +* Manage your accounts in one central location - the Azure portal. + +## Prerequisites + +To get started, you need the following items: + +* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/). +* FigBytes single sign-on (SSO) enabled subscription. +* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD. +For more information, see [Azure built-in roles](../roles/permissions-reference.md). + +## Scenario description + +In this tutorial, you configure and test Azure AD SSO in a test environment. + +* FigBytes supports **SP** and **IDP** initiated SSO. + +> [!NOTE] +> Identifier of this application is a fixed string value so only one instance can be configured in one tenant. + +## Add FigBytes from the gallery + +To configure the integration of FigBytes into Azure AD, you need to add FigBytes from the gallery to your list of managed SaaS apps. + +1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account. +1. On the left navigation pane, select the **Azure Active Directory** service. +1. Navigate to **Enterprise Applications** and then select **All Applications**. +1. To add new application, select **New application**. +1. In the **Add from the gallery** section, type **FigBytes** in the search box. +1. Select **FigBytes** from results panel and then add the app. Wait a few seconds while the app is added to your tenant. + +## Configure and test Azure AD SSO for FigBytes + +Configure and test Azure AD SSO with FigBytes using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in FigBytes. + +To configure and test Azure AD SSO with FigBytes, perform the following steps: + +1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature. + 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon. + 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on. +1. **[Configure FigBytes SSO](#configure-figbytes-sso)** - to configure the single sign-on settings on application side. + 1. **[Create FigBytes test user](#create-figbytes-test-user)** - to have a counterpart of B.Simon in FigBytes that is linked to the Azure AD representation of user. +1. **[Test SSO](#test-sso)** - to verify whether the configuration works. + +## Configure Azure AD SSO + +Follow these steps to enable Azure AD SSO in the Azure portal. + +1. In the Azure portal, on the **FigBytes** application integration page, find the **Manage** section and select **single sign-on**. +1. On the **Select a single sign-on method** page, select **SAML**. +1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings. + + ![Screenshot shows to edit Basic S A M L Configuration.](common/edit-urls.png "Basic Configuration") + +1. On the **Basic SAML Configuration** section, the user does not have to perform any step as the app is already pre-integrated with Azure. + +1. Click **Set additional URLs** and perform the following step, if you wish to configure the application in **SP** initiated mode: + + In the **Sign-on URL** text box, type the URL: + `https://figbytes.biz/` + +1. On the **Set-up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Federation Metadata XML** and select **Download** to download the certificate and save it on your computer. + + ![Screenshot shows the Certificate download link.](common/metadataxml.png "Certificate") + +1. On the **Set up FigBytes** section, copy the appropriate URL(s) based on your requirement. + + ![Screenshot shows to copy configuration appropriate U R L.](common/copy-configuration-urls.png "Attributes") + +### Create an Azure AD test user + +In this section, you'll create a test user in the Azure portal called B.Simon. + +1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**. +1. Select **New user** at the top of the screen. +1. In the **User** properties, follow these steps: + 1. In the **Name** field, enter `B.Simon`. + 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`. + 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box. + 1. Click **Create**. + +### Assign the Azure AD test user + +In this section, you'll enable B.Simon to use Azure single sign-on by granting access to FigBytes. + +1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**. +1. In the applications list, select **FigBytes**. +1. In the app's overview page, find the **Manage** section and select **Users and groups**. +1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog. +1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen. +1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected. +1. In the **Add Assignment** dialog, click the **Assign** button. + +## Configure FigBytes SSO + +To configure single sign-on on **FigBytes** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [FigBytes support team](mailto:support@figbytes.com). They set this setting to have the SAML SSO connection set properly on both sides. + +### Create FigBytes test user + +In this section, you create a user called Britta Simon in FigBytes. Work with [FigBytes support team](mailto:support@figbytes.com) to add the users in the FigBytes platform. Users must be created and activated before you use single sign-on. + +## Test SSO + +In this section, you test your Azure AD single sign-on configuration with following options. + +#### SP initiated: + +* Click on **Test this application** in Azure portal. This will redirect to FigBytes Sign-on URL where you can initiate the login flow. + +* Go to FigBytes Sign-on URL directly and initiate the login flow from there. + +#### IDP initiated: + +* Click on **Test this application** in Azure portal and you should be automatically signed in to the FigBytes for which you set up the SSO. + +You can also use Microsoft My Apps to test the application in any mode. When you click the FigBytes tile in the My Apps, if configured in SP mode you would be redirected to the application sign-on page for initiating the login flow and if configured in IDP mode, you should be automatically signed in to the FigBytes for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md). + +## Next steps + +Once you configure FigBytes you can enforce session control, which protects exfiltration and infiltration of your organization’s sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad). \ No newline at end of file diff --git a/articles/active-directory/saas-apps/lusid-tutorial.md b/articles/active-directory/saas-apps/lusid-tutorial.md new file mode 100644 index 0000000000000..b9a1af296c130 --- /dev/null +++ b/articles/active-directory/saas-apps/lusid-tutorial.md @@ -0,0 +1,168 @@ +--- +title: 'Tutorial: Azure AD SSO integration with LUSID' +description: Learn how to configure single sign-on between Azure Active Directory and LUSID. +services: active-directory +author: jeevansd +manager: CelesteDG +ms.reviewer: CelesteDG +ms.service: active-directory +ms.subservice: saas-app-tutorial +ms.workload: identity +ms.topic: tutorial +ms.date: 07/21/2022 +ms.author: jeedes + +--- + +# Tutorial: Azure AD SSO integration with LUSID + +In this tutorial, you'll learn how to integrate LUSID with Azure Active Directory (Azure AD). When you integrate LUSID with Azure AD, you can: + +* Control in Azure AD who has access to LUSID. +* Enable your users to be automatically signed-in to LUSID with their Azure AD accounts. +* Manage your accounts in one central location - the Azure portal. + +## Prerequisites + +To get started, you need the following items: + +* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/). +* LUSID single sign-on (SSO) enabled subscription. +* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD. +For more information, see [Azure built-in roles](../roles/permissions-reference.md). + +## Scenario description + +In this tutorial, you configure and test Azure AD SSO in a test environment. + +* LUSID supports **SP** and **IDP** initiated SSO. +* LUSID supports **Just In Time** user provisioning. + +## Add LUSID from the gallery + +To configure the integration of LUSID into Azure AD, you need to add LUSID from the gallery to your list of managed SaaS apps. + +1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account. +1. On the left navigation pane, select the **Azure Active Directory** service. +1. Navigate to **Enterprise Applications** and then select **All Applications**. +1. To add new application, select **New application**. +1. In the **Add from the gallery** section, type **LUSID** in the search box. +1. Select **LUSID** from results panel and then add the app. Wait a few seconds while the app is added to your tenant. + +## Configure and test Azure AD SSO for LUSID + +Configure and test Azure AD SSO with LUSID using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user at LUSID. + +To configure and test Azure AD SSO with LUSID, perform the following steps: + +1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature. + 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon. + 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on. +1. **[Configure LUSID SSO](#configure-lusid-sso)** - to configure the single sign-on settings on application side. + 1. **[Create LUSID test user](#create-lusid-test-user)** - to have a counterpart of B.Simon in LUSID that is linked to the Azure AD representation of user. +1. **[Test SSO](#test-sso)** - to verify whether the configuration works. + +## Configure Azure AD SSO + +Follow these steps to enable Azure AD SSO in the Azure portal. + +1. In the Azure portal, on the **LUSID** application integration page, find the **Manage** section and select **single sign-on**. +1. On the **Select a single sign-on method** page, select **SAML**. +1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings. + + ![Screenshot shows to edit Basic SAML Configuration.](common/edit-urls.png "Basic Configuration") + +1. On the **Basic SAML Configuration** section, perform the following steps: + + a. In the **Identifier** textbox, type a URL using the following pattern: + `https://www.okta.com/saml2/service-provider/` + + b. In the **Reply URL** textbox, type a URL using the following pattern: + `https://.identity.lusid.com/sso/saml2/` + +1. Click **Set additional URLs** and perform the following steps, if you wish to configure the application in **SP** initiated mode: + + a. In the **Sign-on URL** text box, type a URL using the following pattern: + `https://.lusid.com/ ` + + b. In the **Relay State** text box, type a URL using the following pattern: + `https://.lusid.com/app/home` + + > [!Note] + > These values are not real. Update these values with the actual Identifier, Reply URL, Sign on URL and Relay State URL. Contact [LUSID support team](mailto:support@finbourne.com) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal. + +1. LUSID application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes. + + ![Screenshot shows the image of LUSID application.](common/default-attributes.png "Image") + +1. In addition to above, LUSID application expects few more attributes to be passed back in SAML response, which are shown below. These attributes are also pre populated but you can review them as per your requirements. + + | Name | Source Attribute| + | ------------ | --------- | + | email | user.mail | + | firstName | user.givenname | + | lastName | user.surname | + | fbn-groups | user.assignedroles | + + > [!NOTE] + > Please click [here](../develop/howto-add-app-roles-in-azure-ad-apps.md#app-roles-ui) to know how to configure Role in Azure AD. + +1. On the **Set up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Certificate (Base64)** and select **Download** to download the certificate and save it on your computer. + + ![Screenshot shows the Certificate download link.](common/certificatebase64.png "Certificate") + +1. On the **Set up LUSID** section, copy the appropriate URL(s) based on your requirement. + + ![Screenshot shows to copy configuration appropriate URL.](common/copy-configuration-urls.png "Metadata") + +### Create an Azure AD test user + +In this section, you'll create a test user in the Azure portal called B.Simon. + +1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**. +1. Select **New user** at the top of the screen. +1. In the **User** properties, follow these steps: + 1. In the **Name** field, enter `B.Simon`. + 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`. + 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box. + 1. Click **Create**. + +### Assign the Azure AD test user + +In this section, you'll enable B.Simon to use Azure single sign-on by granting access to LUSID. + +1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**. +1. In the applications list, select **LUSID**. +1. In the app's overview page, find the **Manage** section and select **Users and groups**. +1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog. +1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen. +1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected. +1. In the **Add Assignment** dialog, click the **Assign** button. + +## Configure LUSID SSO + +To configure single sign-on on **LUSID** side, you need to send the downloaded **Certificate (Base64)** and appropriate copied URLs from Azure portal to [LUSID support team](mailto:support@finbourne.com). They set this setting to have the SAML SSO connection set properly on both sides. + +### Create LUSID test user + +In this section, a user called B.Simon is created in LUSID. LUSID supports just-in-time user provisioning, which is enabled by default. There is no action item for you in this section. If a user doesn't already exist in LUSID, a new one is created after authentication. + +## Test SSO + +In this section, you test your Azure AD single sign-on configuration with following options. + +#### SP initiated: + +* Click on **Test this application** in Azure portal. This will redirect to LUSID Sign-on URL where you can initiate the login flow. + +* Go to LUSID Sign-on URL directly and initiate the login flow from there. + +#### IDP initiated: + +* Click on **Test this application** in Azure portal and you should be automatically signed in to the LUSID for which you set up the SSO. + +You can also use Microsoft My Apps to test the application in any mode. When you click the LUSID tile in the My Apps, if configured in SP mode you would be redirected to the application sign-on page for initiating the login flow and if configured in IDP mode, you should be automatically signed in to the LUSID for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md). + +## Next steps + +Once you configure LUSID you can enforce session control, which protects exfiltration and infiltration of your organization’s sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad). \ No newline at end of file diff --git a/articles/active-directory/saas-apps/lytx-drivecam-tutorial.md b/articles/active-directory/saas-apps/lytx-drivecam-tutorial.md new file mode 100644 index 0000000000000..b230f418e234c --- /dev/null +++ b/articles/active-directory/saas-apps/lytx-drivecam-tutorial.md @@ -0,0 +1,126 @@ +--- +title: 'Tutorial: Azure AD SSO integration with Lytx DriveCam' +description: Learn how to configure single sign-on between Azure Active Directory and Lytx DriveCam. +services: active-directory +author: jeevansd +manager: CelesteDG +ms.reviewer: CelesteDG +ms.service: active-directory +ms.subservice: saas-app-tutorial +ms.workload: identity +ms.topic: tutorial +ms.date: 07/23/2022 +ms.author: jeedes + +--- + +# Tutorial: Azure AD SSO integration with Lytx DriveCam + +In this tutorial, you'll learn how to integrate Lytx DriveCam with Azure Active Directory (Azure AD). When you integrate Lytx DriveCam with Azure AD, you can: + +* Control in Azure AD who has access to Lytx DriveCam. +* Enable your users to be automatically signed-in to Lytx DriveCam with their Azure AD accounts. +* Manage your accounts in one central location - the Azure portal. + +## Prerequisites + +To get started, you need the following items: + +* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/). +* Lytx DriveCam single sign-on (SSO) enabled subscription. +* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD. +For more information, see [Azure built-in roles](../roles/permissions-reference.md). + +## Scenario description + +In this tutorial, you configure and test Azure AD SSO in a test environment. + +* Lytx DriveCam supports **IDP** initiated SSO. + +## Add Lytx DriveCam from the gallery + +To configure the integration of Lytx DriveCam into Azure AD, you need to add Lytx DriveCam from the gallery to your list of managed SaaS apps. + +1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account. +1. On the left navigation pane, select the **Azure Active Directory** service. +1. Navigate to **Enterprise Applications** and then select **All Applications**. +1. To add new application, select **New application**. +1. In the **Add from the gallery** section, type **Lytx DriveCam** in the search box. +1. Select **Lytx DriveCam** from results panel and then add the app. Wait a few seconds while the app is added to your tenant. + +## Configure and test Azure AD SSO for Lytx DriveCam + +Configure and test Azure AD SSO with Lytx DriveCam using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user at Lytx DriveCam. + +To configure and test Azure AD SSO with Lytx DriveCam, perform the following steps: + +1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature. + 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon. + 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on. +1. **[Configure Lytx DriveCam SSO](#configure-lytx-drivecam-sso)** - to configure the single sign-on settings on application side. + 1. **[Create Lytx DriveCam test user](#create-lytx-drivecam-test-user)** - to have a counterpart of B.Simon in Lytx DriveCam that is linked to the Azure AD representation of user. +1. **[Test SSO](#test-sso)** - to verify whether the configuration works. + +## Configure Azure AD SSO + +Follow these steps to enable Azure AD SSO in the Azure portal. + +1. In the Azure portal, on the **Lytx DriveCam** application integration page, find the **Manage** section and select **single sign-on**. +1. On the **Select a single sign-on method** page, select **SAML**. +1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings. + + ![Screenshot shows to edit Basic SAML Configuration.](common/edit-urls.png "Basic Configuration") + +1. On the **Basic SAML Configuration** section, the application is pre-configured and the necessary URLs are already pre-populated with Azure. The user needs to save the configuration by clicking the **Save** button. + +1. On the **Set up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Certificate (Base64)** and select **Download** to download the certificate and save it on your computer. + + ![Screenshot shows the Certificate download link.](common/certificatebase64.png "Certificate") + +1. On the **Set up Lytx DriveCam** section, copy the appropriate URL(s) based on your requirement. + + ![Screenshot shows to copy configuration appropriate URL.](common/copy-configuration-urls.png "Metadata") + +### Create an Azure AD test user + +In this section, you'll create a test user in the Azure portal called B.Simon. + +1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**. +1. Select **New user** at the top of the screen. +1. In the **User** properties, follow these steps: + 1. In the **Name** field, enter `B.Simon`. + 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`. + 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box. + 1. Click **Create**. + +### Assign the Azure AD test user + +In this section, you'll enable B.Simon to use Azure single sign-on by granting access to Lytx DriveCam. + +1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**. +1. In the applications list, select **Lytx DriveCam**. +1. In the app's overview page, find the **Manage** section and select **Users and groups**. +1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog. +1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen. +1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected. +1. In the **Add Assignment** dialog, click the **Assign** button. + +## Configure Lytx DriveCam SSO + +To configure single sign-on on **Lytx DriveCam** side, you need to send the downloaded **Certificate (Base64)** and appropriate copied URLs from Azure portal to [Lytx DriveCam support team](mailto:support@lytx.com). They set this setting to have the SAML SSO connection set properly on both sides. + +### Create Lytx DriveCam test user + +In this section, you create a user called Britta Simon at Lytx DriveCam. Work with [Lytx DriveCam support team](mailto:support@lytx.com) to add the users in the Lytx DriveCam platform. Users must be created and activated before you use single sign-on. + +## Test SSO + +In this section, you test your Azure AD single sign-on configuration with following options. + +* Click on Test this application in Azure portal and you should be automatically signed in to the Lytx DriveCam for which you set up the SSO. + +* You can use Microsoft My Apps. When you click the Lytx DriveCam tile in the My Apps, you should be automatically signed in to the Lytx DriveCam for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md). + +## Next steps + +Once you configure Lytx DriveCam you can enforce session control, which protects exfiltration and infiltration of your organization’s sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad). \ No newline at end of file diff --git a/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-copy-url-token.png b/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-copy-url-token.png index 23ef44ac4a284..af24a947cb904 100644 Binary files a/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-copy-url-token.png and b/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-copy-url-token.png differ diff --git a/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-enable-user-provisioning.png b/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-enable-user-provisioning.png new file mode 100644 index 0000000000000..c15f018670513 Binary files /dev/null and b/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-enable-user-provisioning.png differ diff --git a/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-identity-and-security.png b/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-identity-and-security.png new file mode 100644 index 0000000000000..5b1bf3ab72223 Binary files /dev/null and b/articles/active-directory/saas-apps/media/8x8-provisioning-tutorial/8x8-identity-and-security.png differ diff --git a/articles/active-directory/saas-apps/media/aws-clientvpn-tutorial/signing-certificate.png b/articles/active-directory/saas-apps/media/aws-clientvpn-tutorial/signing-certificate.png new file mode 100644 index 0000000000000..f6aca03b930d8 Binary files /dev/null and b/articles/active-directory/saas-apps/media/aws-clientvpn-tutorial/signing-certificate.png differ diff --git a/articles/active-directory/saas-apps/media/mist-cloud-admin-tutorial/certificate.png b/articles/active-directory/saas-apps/media/mist-cloud-admin-tutorial/certificate.png new file mode 100644 index 0000000000000..1255e824bf50c Binary files /dev/null and b/articles/active-directory/saas-apps/media/mist-cloud-admin-tutorial/certificate.png differ diff --git a/articles/active-directory/saas-apps/media/mist-cloud-admin-tutorial/settings.png b/articles/active-directory/saas-apps/media/mist-cloud-admin-tutorial/settings.png new file mode 100644 index 0000000000000..df8bdc32de80e Binary files /dev/null and b/articles/active-directory/saas-apps/media/mist-cloud-admin-tutorial/settings.png differ diff --git a/articles/active-directory/saas-apps/mist-cloud-admin-tutorial.md b/articles/active-directory/saas-apps/mist-cloud-admin-tutorial.md new file mode 100644 index 0000000000000..b1ca0c1ffdee5 --- /dev/null +++ b/articles/active-directory/saas-apps/mist-cloud-admin-tutorial.md @@ -0,0 +1,183 @@ +--- +title: 'Tutorial: Azure AD SSO integration with Mist Cloud Admin SSO' +description: Learn how to configure single sign-on between Azure Active Directory and Mist Cloud Admin SSO. +services: active-directory +author: jeevansd +manager: CelesteDG +ms.reviewer: CelesteDG +ms.service: active-directory +ms.subservice: saas-app-tutorial +ms.workload: identity +ms.topic: tutorial +ms.date: 07/28/2022 +ms.author: jeedes + +--- + +# Tutorial: Azure AD SSO integration with Mist Cloud Admin SSO + +In this tutorial, you'll learn how to integrate Mist Cloud Admin SSO with Azure Active Directory (Azure AD). When you integrate Mist Cloud Admin SSO with Azure AD, you can: + +* Control in Azure AD who has access to Mist Cloud Admin SSO. +* Enable your users to be automatically signed-in to Mist Cloud Admin SSO with their Azure AD accounts. +* Manage your accounts in one central location - the Azure portal. + +## Prerequisites + +To get started, you need the following items: + +* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/). +* Mist Cloud Admin SSO single sign-on (SSO) enabled subscription. +* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD. +For more information, see [Azure built-in roles](../roles/permissions-reference.md). + +## Scenario description + +In this tutorial, you configure and test Azure AD SSO in a test environment. + +* Mist Cloud Admin SSO supports **SP** and **IDP** initiated SSO. + +## Add Mist Cloud Admin SSO from the gallery + +To configure the integration of Mist Cloud Admin SSO into Azure AD, you need to add Mist Cloud Admin SSO from the gallery to your list of managed SaaS apps. + +1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account. +1. On the left navigation pane, select the **Azure Active Directory** service. +1. Navigate to **Enterprise Applications** and then select **All Applications**. +1. To add new application, select **New application**. +1. In the **Add from the gallery** section, type **Mist Cloud Admin SSO** in the search box. +1. Select **Mist Cloud Admin SSO** from results panel and then add the app. Wait a few seconds while the app is added to your tenant. + +## Configure and test Azure AD SSO for Mist Cloud Admin SSO + +Configure and test Azure AD SSO with Mist Cloud Admin SSO using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user at Mist Cloud Admin SSO. + +To configure and test Azure AD SSO with Mist Cloud Admin SSO, perform the following steps: + +1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature. + 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon. + 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on. +1. **[Configure Mist Cloud Admin SSO](#configure-mist-cloud-admin-sso)** - to configure the single sign-on settings on application side. + 1. **[Create Mist Cloud Admin SSO test user](#create-mist-cloud-admin-sso-test-user)** - to have a counterpart of B.Simon in Mist Cloud Admin SSO that is linked to the Azure AD representation of user. +1. **[Test SSO](#test-sso)** - to verify whether the configuration works. + +## Configure Azure AD SSO + +Follow these steps to enable Azure AD SSO in the Azure portal. + +1. In the Azure portal, on the **Mist Cloud Admin SSO** application integration page, find the **Manage** section and select **single sign-on**. +1. On the **Select a single sign-on method** page, select **SAML**. +1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings. + + ![Screenshot shows to edit Basic SAML Configuration.](common/edit-urls.png "Basic Configuration") + +1. On the **Basic SAML Configuration** section, perform the following steps: + + a. In the **Identifier** textbox, type a value using the following pattern: + `https://api..mist.com/api/v1/saml//login` + + b. In the **Reply URL** textbox, type a URL using the following pattern: + `https://api..mist.com/api/v1/saml//login` + +1. Click **Set additional URLs** and perform the following step, if you wish to configure the application in **SP** initiated mode: + + In the **Sign-on URL** text box, type the URL: + `https://manage.mist.com` + + > [!Note] + > These values are not real. Update these values with the actual Identifier and Reply URL. Contact [Mist Cloud Admin SSO support team](mailto:support@mist.com) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal. + +1. Mist Cloud Admin SSO application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes. + + ![Screenshot shows the image of attribute mappings.](common/default-attributes.png "Image") + +1. In addition to above, Mist Cloud Admin SSO application expects few more attributes to be passed back in SAML response, which are shown below. These attributes are also pre populated but you can review them as per your requirements. + + | Name | Source Attribute| + | ------------ | --------- | + | FirstName | user.givenname | + | LastName | user.surname | + | Role | user.assignedroles | + + > [!NOTE] + > Please click [here](../develop/howto-add-app-roles-in-azure-ad-apps.md#app-roles-ui) to know how to configure Role in Azure AD. + +1. On the **Set up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Certificate (Base64)** and select **Download** to download the certificate and save it on your computer. + + ![Screenshot shows the Certificate download link.](common/certificatebase64.png "Certificate") + +1. On the **Set up Mist Cloud Admin SSO** section, copy the appropriate URL(s) based on your requirement. + + ![Screenshot shows to copy configuration appropriate URL.](common/copy-configuration-urls.png "Metadata") + +### Create an Azure AD test user + +In this section, you'll create a test user in the Azure portal called B.Simon. + +1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**. +1. Select **New user** at the top of the screen. +1. In the **User** properties, follow these steps: + 1. In the **Name** field, enter `B.Simon`. + 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`. + 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box. + 1. Click **Create**. + +### Assign the Azure AD test user + +In this section, you'll enable B.Simon to use Azure single sign-on by granting access to Mist Cloud Admin SSO. + +1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**. +1. In the applications list, select **Mist Cloud Admin SSO**. +1. In the app's overview page, find the **Manage** section and select **Users and groups**. +1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog. +1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen. +1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected. +1. In the **Add Assignment** dialog, click the **Assign** button. + +## Configure Mist Cloud Admin SSO + +1. Log in to your Mist Cloud Admin SSO company site as an administrator. + +1. Go to **Organization** > **Settings** > **Single Sign-On** > **Add IdP**. + + ![Screenshot that shows the Configuration Settings.](./media/mist-cloud-admin-tutorial/settings.png "Configuration") + +1. In the **Create Identity Provider** section, perform the following steps: + + ![Screenshot that shows the Organization Algorithm.](./media/mist-cloud-admin-tutorial/certificate.png "Organization") + + 1. In the **Issuer** textbox, paste the **Azure AD Identifier** value which you have copied from the Azure portal. + + 1. Open the downloaded **Certificate (Base64)** from the Azure portal into Notepad and paste the content into the **Certificate** textbox. + + 1. In the **SSO URL** textbox, paste the **Login URL** value which you have copied from the Azure portal. + + 1. In the **Custom Logout URL** textbox, paste the **Logout URL** value which you have copied from the Azure portal. + + 1. Copy **ACS URL** value, paste this value into the **Reply URL** text box in the **Basic SAML Configuration** section in the Azure portal. + + 1. Click **Save**. + +### Create Mist Cloud Admin SSO test user + +In this section, you create a user called Britta Simon at Mist Cloud Admin SSO. Work with [Mist Cloud Admin SSO support team](mailto:support@mist.com) to add the users in the Mist Cloud Admin SSO platform. Users must be created and activated before you use single sign-on. + +## Test SSO + +In this section, you test your Azure AD single sign-on configuration with following options. + +#### SP initiated: + +* Click on **Test this application** in Azure portal. This will redirect to Mist Cloud Admin SSO Sign-on URL where you can initiate the login flow. + +* Go to Mist Cloud Admin SSO Sign-on URL directly and initiate the login flow from there. + +#### IDP initiated: + +* Click on **Test this application** in Azure portal and you should be automatically signed in to the Mist Cloud Admin SSO for which you set up the SSO. + +You can also use Microsoft My Apps to test the application in any mode. When you click the Mist Cloud Admin SSO tile in the My Apps, if configured in SP mode you would be redirected to the application sign-on page for initiating the login flow and if configured in IDP mode, you should be automatically signed in to the Mist Cloud Admin SSO for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md). + +## Next steps + +Once you configure Mist Cloud Admin SSO you can enforce session control, which protects exfiltration and infiltration of your organization’s sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad). \ No newline at end of file diff --git a/articles/active-directory/saas-apps/myaos-tutorial.md b/articles/active-directory/saas-apps/myaos-tutorial.md new file mode 100644 index 0000000000000..2b01ffc88bb6f --- /dev/null +++ b/articles/active-directory/saas-apps/myaos-tutorial.md @@ -0,0 +1,126 @@ +--- +title: 'Tutorial: Azure AD SSO integration with myAOS' +description: Learn how to configure single sign-on between Azure Active Directory and myAOS. +services: active-directory +author: jeevansd +manager: CelesteDG +ms.reviewer: CelesteDG +ms.service: active-directory +ms.subservice: saas-app-tutorial +ms.workload: identity +ms.topic: tutorial +ms.date: 07/14/2022 +ms.author: jeedes + +--- + +# Tutorial: Azure AD SSO integration with myAOS + +In this tutorial, you'll learn how to integrate myAOS with Azure Active Directory (Azure AD). When you integrate myAOS with Azure AD, you can: + +* Control in Azure AD who has access to myAOS. +* Enable your users to be automatically signed-in to myAOS with their Azure AD accounts. +* Manage your accounts in one central location - the Azure portal. + +## Prerequisites + +To get started, you need the following items: + +* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/). +* myAOS single sign-on (SSO) enabled subscription. +* Along with Cloud Application Administrator, Application Administrator can also add or manage applications in Azure AD. +For more information, see [Azure built-in roles](../roles/permissions-reference.md). + +## Scenario description + +In this tutorial, you configure and test Azure AD SSO in a test environment. + +* myAOS supports **IDP** initiated SSO. + +## Add myAOS from the gallery + +To configure the integration of myAOS into Azure AD, you need to add myAOS from the gallery to your list of managed SaaS apps. + +1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account. +1. On the left navigation pane, select the **Azure Active Directory** service. +1. Navigate to **Enterprise Applications** and then select **All Applications**. +1. To add new application, select **New application**. +1. In the **Add from the gallery** section, type **myAOS** in the search box. +1. Select **myAOS** from results panel and then add the app. Wait a few seconds while the app is added to your tenant. + +## Configure and test Azure AD SSO for myAOS + +Configure and test Azure AD SSO with myAOS using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in myAOS. + +To configure and test Azure AD SSO with myAOS, perform the following steps: + +1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature. + 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon. + 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on. +1. **[Configure myAOS SSO](#configure-myaos-sso)** - to configure the single sign-on settings on application side. + 1. **[Create myAOS test user](#create-myaos-test-user)** - to have a counterpart of B.Simon in myAOS that is linked to the Azure AD representation of user. +1. **[Test SSO](#test-sso)** - to verify whether the configuration works. + +## Configure Azure AD SSO + +Follow these steps to enable Azure AD SSO in the Azure portal. + +1. In the Azure portal, on the **myAOS** application integration page, find the **Manage** section and select **single sign-on**. +1. On the **Select a single sign-on method** page, select **SAML**. +1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings. + + ![Screenshot shows to edit Basic S A M L Configuration.](common/edit-urls.png "Basic Configuration") + +1. On the **Basic SAML Configuration** section, the application is pre-configured and the necessary URLs are already pre-populated with Azure. The user needs to save the configuration by clicking the **Save** button. + +1. On the **Set-up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Federation Metadata XML** and select **Download** to download the certificate and save it on your computer. + + ![Screenshot shows the Certificate download link.](common/metadataxml.png "Certificate") + +1. On the **Set up myAOS** section, copy the appropriate URL(s) based on your requirement. + + ![Screenshot shows to copy configuration appropriate U R L.](common/copy-configuration-urls.png "Attributes") + +### Create an Azure AD test user + +In this section, you'll create a test user in the Azure portal called B.Simon. + +1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**. +1. Select **New user** at the top of the screen. +1. In the **User** properties, follow these steps: + 1. In the **Name** field, enter `B.Simon`. + 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`. + 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box. + 1. Click **Create**. + +### Assign the Azure AD test user + +In this section, you'll enable B.Simon to use Azure single sign-on by granting access to myAOS. + +1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**. +1. In the applications list, select **myAOS**. +1. In the app's overview page, find the **Manage** section and select **Users and groups**. +1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog. +1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen. +1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected. +1. In the **Add Assignment** dialog, click the **Assign** button. + +## Configure myAOS SSO + +To configure single sign-on on **myAOS** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [myAOS support team](mailto:support@vialto.com). They set this setting to have the SAML SSO connection set properly on both sides. + +### Create myAOS test user + +In this section, you create a user called Britta Simon in myAOS. Work with [myAOS support team](mailto:support@vialto.com) to add the users in the myAOS platform. Users must be created and activated before you use single sign-on. + +## Test SSO + +In this section, you test your Azure AD single sign-on configuration with following options. + +* Click on Test this application in Azure portal and you should be automatically signed in to the myAOS for which you set up the SSO. + +* You can use Microsoft My Apps. When you click the myAOS tile in the My Apps, you should be automatically signed in to the myAOS for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md). + +## Next steps + +Once you configure myAOS you can enforce session control, which protects exfiltration and infiltration of your organization’s sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad). \ No newline at end of file diff --git a/articles/active-directory/saas-apps/toc.yml b/articles/active-directory/saas-apps/toc.yml index 0ef865c0b467f..e4a506880b152 100644 --- a/articles/active-directory/saas-apps/toc.yml +++ b/articles/active-directory/saas-apps/toc.yml @@ -416,6 +416,8 @@ href: check-point-remote-access-vpn-tutorial.md - name: CheckProof href: checkproof-tutorial.md + - name: Cheetah For Benelux + href: cheetah-for-benelux-tutorial.md - name: Cherwell href: cherwell-tutorial.md - name: Chromeriver @@ -706,6 +708,8 @@ href: edcor-tutorial.md - name: eDigitalResearch href: edigitalresearch-tutorial.md + - name: Ediwin SaaS EDI + href: ediwin-saas-edi-tutorial.md - name: EduBrite LMS href: edubrite-lms-tutorial.md - name: edX for Business SAML Integration @@ -837,6 +841,8 @@ href: fidelity-planviewer-tutorial.md - name: Fieldglass href: fieldglass-tutorial.md + - name: FigBytes + href: figbytes-tutorial.md - name: Figma href: figma-tutorial.md - name: FileCloud @@ -923,7 +929,7 @@ href: fuze-tutorial.md - name: gamba! href: gamba-tutorial.md - - name: G Suite + - name: Google Cloud / G Suite Connector href: google-apps-tutorial.md - name: GaggleAMP href: gaggleamp-tutorial.md @@ -1389,10 +1395,14 @@ href: lucid-tutorial.md - name: Lucidchart href: lucidchart-tutorial.md + - name: LUSID + href: lusid-tutorial.md - name: Luum href: luum-tutorial.md - name: Lynda.com href: lynda-tutorial.md + - name: Lytx DriveCam + href: lytx-drivecam-tutorial.md - name: Lyve Cloud href: lyve-cloud-tutorial.md - name: M-Files @@ -1455,6 +1465,8 @@ href: mindwireless-tutorial.md - name: Miro href: miro-tutorial.md + - name: Mist Cloud Admin SSO + href: mist-cloud-admin-tutorial.md - name: Mitel Connect href: mitel-connect-tutorial.md - name: Mixpanel @@ -1495,6 +1507,8 @@ href: mural-identity-tutorial.md - name: MVISION Cloud Azure AD SSO Configuration href: skyhighnetworks-tutorial.md + - name: myAOS + href: myaos-tutorial.md - name: MyAryaka href: myaryaka-tutorial.md - name: My Award Points Top Sub/Top Team diff --git a/articles/active-directory/saas-apps/zylo-tutorial.md b/articles/active-directory/saas-apps/zylo-tutorial.md index 53aa04bfec137..2ef6b3ee03881 100644 --- a/articles/active-directory/saas-apps/zylo-tutorial.md +++ b/articles/active-directory/saas-apps/zylo-tutorial.md @@ -2,21 +2,16 @@ title: 'Tutorial: Azure Active Directory single sign-on (SSO) integration with Zylo | Microsoft Docs' description: Learn how to configure single sign-on between Azure Active Directory and Zylo. services: active-directory -documentationCenter: na author: jeevansd -manager: mtillman -ms.reviewer: barbkess - -ms.assetid: 4041dc39-c98a-4d65-bb4f-455bb5d79541 +manager: CelesteDG +ms.reviewer: CelesteDG ms.service: active-directory ms.subservice: saas-app-tutorial ms.workload: identity -ms.tgt_pltfrm: na ms.topic: tutorial -ms.date: 08/04/2021 +ms.date: 07/19/2022 ms.author: jeedes -ms.collection: M365-identity-device-management --- # Tutorial: Azure Active Directory single sign-on (SSO) integration with Zylo @@ -141,7 +136,7 @@ In this section, you'll enable B.Simon to use Azure single sign-on by granting a c. In the **SAML SSO URL** textbox, paste the **Login URL** value which you have copied from the Azure portal. - d. In the **Identity Provider Issuer** textbox, paste the **Entity ID** value which you have copied from the Azure portal. + d. In the **Identity Provider Issuer** textbox, paste the **Application ID** value which you have copied from Zylo's overview page in Azure portal. e. Open the downloaded **Certificate (Base64)** from the Azure portal into Notepad and paste the content into the **Public Certificate (from Identity Provider)** textbox. diff --git a/articles/active-directory/verifiable-credentials/TOC.yml b/articles/active-directory/verifiable-credentials/TOC.yml index 4c93bcef9987e..2d726eeac6b85 100644 --- a/articles/active-directory/verifiable-credentials/TOC.yml +++ b/articles/active-directory/verifiable-credentials/TOC.yml @@ -1,4 +1,4 @@ -- name: Azure AD Verifiable Credentials documentation +- name: Microsoft Entra Verified ID documentation href: index.yml - name: Overview expanded: true @@ -32,6 +32,8 @@ - name: How-to guides expanded: true items: + - name: How to customize your credentials + href: credential-design.md - name: Create credentials using Quickstart items: - name: Directory based - Employee @@ -42,10 +44,10 @@ href: how-to-use-quickstart-idtoken.md - name: Self Issued credentials href: how-to-use-quickstart-selfissued.md + - name: Use the Verified ID Network + href: how-use-vcnetwork.md - name: Using the Request Service REST API href: get-started-request-api.md - - name: How to customize your credentials - href: credential-design.md - name: Link your domain to your DID href: how-to-dnsbind.md - name: Register your website ID @@ -72,6 +74,10 @@ href: presentation-request-api.md - name: Rules and Display definition model href: rules-and-display-definitions-model.md + - name: Admin API specification + href: admin-api.md + - name: Verified ID Network API specification + href: vc-network-api.md - name: Supported standards href: verifiable-credentials-standards.md - name: Resources @@ -92,4 +98,4 @@ - name: Video overview of decentralized identities href: https://www.youtube.com/watch?v=Whc9Im-U0Wg - + \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/admin-api.md b/articles/active-directory/verifiable-credentials/admin-api.md new file mode 100644 index 0000000000000..bcc0d77f8b970 --- /dev/null +++ b/articles/active-directory/verifiable-credentials/admin-api.md @@ -0,0 +1,1331 @@ +--- +title: Admin API for managing Microsoft Entra Verified ID +titleSuffix: Microsoft Entra Verified ID +description: Learn how to manage your verifiable credential deployment using Admin API. +documentationCenter: '' +author: barclayn +manager: rkarlin +ms.service: decentralized-identity +ms.topic: reference +ms.subservice: verifiable-credentials +ms.date: 07/28/2022 +ms.author: barclayn + +#Customer intent: As an administrator, I am trying to learn how to use the Admin API and automate my tenant. +--- + +# Verifiable credentials admin API + +[!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] + +The Microsoft Entra Verified ID Admin API enables you to manage all aspects of the Verifiable Credential service. It offers a way to set up a brand new service, manage and create Verifiable Credential contracts, revoke Verifiable Credentials and completely opt out the service as well. + +> The API is intended for developers comfortable with RESTful APIs and enough permissions on the Azure Active Directory tenant to enable the service + +## Base URL + +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`. + +## Onboarding + +This API is to help create a new environment so new authorities can be set up. This can be triggered manually by navigating to the Verifiable Credential page in the Azure portal as well. You only need to call this API once and only if you want to set up a brand new environment just with the API. + +#### HTTP request + +`POST /v1.0/verifiableCredentials/onboard` + +Use this endpoint to finish provisioning of the Verifiable Credential service in your tenant. The system creates the rest of the service principals if these aren't provisioned yet. + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +Don't supply a request body for this method. + +#### Return message + +``` +HTTP/1.1 201 Created +Content-type: application/json + +{ + "id": "f5bf2fc6-7135-4d94-a6fe-c26e4543bc5a", + "servicePrincipal": "90e10a26-94cd-49d6-8cd7-cacb10f00686", + "status": "Enabled" +} +``` + +Repeatedly calling this API will result in the exact same return message. + +## Authorities + +This endpoint can be used to create or update a Verifiable Credential service instance. + +### Methods + + +| Methods | Return Type | Description | +| -------- | -------- | -------- | +| [Get Authority](#get-authority) | Authority | Read properties of an authority | +| [List Authority](#list-authorities) | Authority array | Get a list of all configured Authorities/verifiable credential services | +| [Create Authority](#create-authority) | Authority | Create a new authority | +| [Update authority](#update-authority) | Authority | Update authority | +| [Generate Well known DID Configuration](#well-known-did-configuration) | | | +| [Generate DID Document](#generate-did-document) | | | +| [Validate Well-known DID config](#validate-well-known-did-configuration) | | | +| [Rotate Signing Key](#rotate-signing-keys) | | | + + +### Get authority + +Retrieve the properties of a configured authority or verifiable credential service instance. + +#### HTTP request + +`GET /v1.0/verifiableCredentials/authorities/:authorityId` + +Replace the `:authorityId` with the value of one of the configured authorities. + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +Don't supply a request body for this method + +#### Response message + +``` +HTTP/1.1 200 OK +Content-type: application/json + +{ + "id": "ffea7eb3-0000-1111-2222-000000000000", + "name": "ExampleAuthorityName", + "status": "Enabled", + "didModel": { + "did": "did:ion:EiAVvtjqr_Ji8pXGNtherrMW2FPl5Ays9mII2vP_QTgUWA:eyJkZWx...", + "signingKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerSigningKeyIon-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4" + ], + "recoveryKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerRecoveryKeyIon-ffea7eb3-0000-1111-2222-000000000000/5cfb5458af524da88897522690e01a7e" + ], + "updateKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerUpdateKeyIon-ffea7eb3-0000-1111-2222-000000000000/24494dbbbace4a079422dde943e1b6f0" + ], + "encryptionKeys": [], + "linkedDomainUrls": [ + "https://www.contoso.com/" + ], + "didDocumentStatus": "published" + }, + "keyVaultMetadata": { + "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0", + "resourceGroup": "verifiablecredentials", + "resourceName": "vccontosokv", + "resourceUrl": "https://vccontosokv.vault.azure.net/" + } +} + +``` + +The response contains the following properties. + +#### Authority type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `Id` | string | An autogenerated unique ID, which can be used to retrieve or update the specific instance of the verifiable credential service | +| `name` | string | The friendly name of this instance of the verifiable credential service | +| `status` | string | status of the service, this value will always be `enabled` | +| [didModel](#didmodel-type) | didModel | Information about the DID and keys | +| [keyVaultMetadata](#keyvaultmetadata-type) | keyVaultMeta data | Information about the used Key Vault | + + +#### didModel type + +We support two different didModels. One is `ion` and the other supported method is `web` + +#### ION + +| Property | Type | Description | +| -------- | -------- | -------- | +| `did` | string | The DID for this verifiable credential service instance | +| `signingKeys` | string array | URL to the signing key | +| `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`| + +#### Web + +| Property | Type | Description | +| -------- | -------- | -------- | +| `did` | string | The DID for this verifiable credential service instance | +| `signingKeys` | string array | URL to the signing key | +| `linkedDomainUrls` | string array | Domains linked to this DID, expecting one single entry | +| [didModel](#didmodel-type) | didModel | Information about the DID and keys | +| `didDocumentStatus` | string | status of the DID, value is always `published` for this method | + + +#### keyVaultMetadata type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `subscriptionId` | string | The Azure subscription this Key Vault resides | +| `resourceGroup` | string | name of the resource group from this Key Vault | +| `resouceName` | string | Key Vault name | +| `resourceUrl` | string | URL to this Key Vault | + + +### List authorities + +Get all configured authorities or verifiable credential services for this tenant + +#### HTTP request + +`GET /v1.0/verifiableCredentials/authorities` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +Don't supply a request body for this method. + +#### Response message + +Response message is an array of [Authorities](#authority-type) +Example: +``` +HTTP/1.1 200 OK +Content-type: application/json +{ + value: + + [ + { + "id": "ffea7eb3-0000-1111-2222-000000000000", + "name": "ContractName", + "status": "Enabled", + "didModel": { + "did": "did:ion:EiAVvtjqr_Ji8pXGNtherrMW2FPl5Ays9mII2vP_QTgUWA:eyJkZWx...", + "signingKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerSigningKeyIon-ffea7eb3-0000-1111-2222-000000000000/5257c49db8164e198b4c5997e8a31ad4" + ], + "recoveryKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerRecoveryKeyIon-ffea7eb3-0000-1111-2222-000000000000/5cfb5458af524da88897522690e01a7e" + ], + "updateKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerUpdateKeyIon-ffea7eb3-0000-1111-2222-000000000000/24494dbbbace4a079422dde943e1b6f0" + ], + "encryptionKeys": [], + "linkedDomainUrls": [ + "https://www.contoso.com/" + ], + "didDocumentStatus": "published" + }, + "keyVaultMetadata": { + "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0", + "resourceGroup": "verifiablecredentials", + "resourceName": "vccontosokv", + "resourceUrl": "https://vccontosokv.vault.azure.net/" + } + }, + { + "id": "cc55ba22-0000-1111-2222-000000000000", + "name": "APItest6", + "keyVaultUrl": "https://vccontosokv.vault.azure.net/", + "status": "Enabled", + "didModel": { + "did": "did:ion:EiD_mGdhdAXOS1BV6c7r-CCjetaoRKuAENEwsRM1_QEHMg:eyJkZWx0YSI....", + "signingKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerSigningKeyIon-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a" + ], + "recoveryKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerRecoveryKeyIon-cc55ba22-0000-1111-2222-000000000000/68f976cc44014eafb354a6fe305b7d4d" + ], + "updateKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerUpdateKeyIon-cc55ba22-0000-1111-2222-000000000000/b85328af0c1f460ea026fbdda9cd6652" + ], + "encryptionKeys": [], + "linkedDomainUrls": [ + "https://www.contoso.com/" + ], + "didDocumentStatus": "published" + }, + "keyVaultMetadata": { + "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0", + "resourceGroup": "verifiablecredentials", + "resourceName": "vccontosokv", + "resourceUrl": "https://vccontosokv.vault.azure.net/" + } + } + ] +} +``` + +### 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. + +#### HTTP request + +`POST /v1.0/verifiableCredentials/authorities` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +In the request body, supply a JSON representation of the following + +| Property | Type | Description | +| -------- | -------- | -------- | +| `name` | string | The display name of this instance of the service | +| `linkedDomainUrl` | string | The domain linked to this DID | +| `didMethod` | string | option `web` or `ion` | +| `keyVaultMetadata` | keyVaultMetadata | meta data for specific key vault | + +Example message: +``` +{ + "name":"ExampleName", + "linkedDomainUrl":"https://www.contoso.com/", + "didMethod": "web", + "keyVaultMetadata": + { + "subscriptionId":"b593ade1-e353-43ab-9fb8-cccf669478d0", + "resourceGroup":"verifiablecredentials", + "resourceName":"vccontosokv", + "resourceUrl": "https://vccontosokv.vault.azure.net/" + } +} +``` + +#### Response message + +When successful the response message contains the name of the [authority](#authority-type) + +Example message for did:web: +``` +{ + "id": "bacf5333-d68c-01c5-152b-8c9039fbd88d", + "name": "APItesta", + "status": "Enabled", + "didModel": { + "did": "did:web:www.contoso.com", + "signingKeys": [ + "https://vcwingtipskv.vault.azure.net/keys/vcSigningKey-bacf5333-d68c-01c5-152b-8c9039fbd88d/5255b9f2d9b94dc19a369ff0d36e3407" + ], + "recoveryKeys": [], + "updateKeys": [], + "encryptionKeys": [], + "linkedDomainUrls": [ + "https://www.contoso.com/" + ], + "didDocumentStatus": "published" + }, + "keyVaultMetadata": { + "subscriptionId": "1853e356-bc86-4e54-8bb8-6db4e5eacdbd", + "resourceGroup": "verifiablecredentials", + "resourceName": "vcwingtipskv", + "resourceUrl": "https://vcwingtipskv.vault.azure.net/" + }, + "linkedDomainsVerified": false +} +``` + + +Example message for did:ion: + +``` +HTTP/1.1 201 Created +Content-type: application/json + +{ + "id": "cc55ba22-0000-1111-2222-000000000000", + "name": "APItest6", + "status": "Enabled", + "didModel": { + "did": "did:ion:EiD_mGdhdAXOS1BV6c7r-CCjetaoRKuAENEwsRM1_QEHMg", + "signingKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerSigningKeyIon-cc55ba22-0000-1111-2222-000000000000/f8f149eaee194beb83dfca14714ef62a" + ], + "recoveryKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerRecoveryKeyIon-cc55ba22-0000-1111-2222-000000000000/68f976cc44014eafb354a6fe305b7d4d" + ], + "updateKeys": [ + "https://vccontosokv.vault.azure.net/keys/issuerUpdateKeyIon-cc55ba22-0000-1111-2222-000000000000/b85328af0c1f460ea026fbdda9cd6652" + ], + "encryptionKeys": [], + "linkedDomainUrls": [ + "https://www.contoso.com/" + ], + "didDocumentStatus": "submitted" + }, + "keyVaultMetadata": { + "subscriptionId": "b593ade1-e353-43ab-9fb8-cccf669478d0", + "resourceGroup": "verifiablecredentials", + "resourceName": "vccontosokv", + "resourceUrl": "https://vccontosokv.vault.azure.net/" + } +} + +``` + +### Remarks + +>You can create multiple authorities with their own DID and private keys, these will not be visible in the UI of the azure portal. Currently we only support having 1 authority. We have not fully tested all scenarios with multiple created authorities. If you are trying this please let us know your experience. + +### Update authority + +This method can be used to update the display name of this specific instance of the verifiable credential service. + +#### HTTP request + +`POST /v1.0/verifiableCredentials/authorities/:authorityId` + +Replace the value of `:authorityId` with the value of the authority ID you want to update. + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +In the request body, supply a JSON representation of the following. + +| Property | Type | Description | +| -------- | -------- | -------- | +| `name` | string | The display name of this instance of the service | + +Example message +``` +{ + "name":"ExampleIssuerName" +} +``` + +### Linked domains + +It's possible to update the domain related to the DID. This functionality needs to write an update operation to ION to get this update distributed around the world. The update can take some time, currently up to an hour before it's processed and available for other users. + +#### HTTP request + +`POST /v1.0/verifiableCredentials/authorities/:authorityId/updateLinkedDomains` + +replace the value of `:authorityId` with the value of the authority ID you want to update. + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +You need to specify the domain you want to publish to the DID Document. Although the value of domains is an array, you should only specify a **single domain**. + +In the request body, supply a JSON representation of the following: + +| Property | Type | Description | +| -------- | -------- | -------- | +| `domainUrls` | string array | link to domain(s), need to start with https and not contain a path | + +Example message: + +``` +{ + "domainUrls" : ["https://www.mydomain.com"] +} +``` + +#### Response message + +``` +HTTP/1.1 202 Accepted +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. + +If you try to submit a change before the operation is completed, you'll get the following error message: + +``` +HTTP/1.1 409 Conflict +Content-type: application/json + +{ + "requestId":"83047b1c5811284ce56520b63b9ba83a","date":"Mon, 07 Feb 2022 18:36:24 GMT", + "mscv":"tf5p8EaXIY1iWgYM.1", + "error": + { + "code": "conflict", + "innererror": { + "code":"ionOperationNotYetPublished", + "message":"There is already an operation in queue for this organization's DID (decentralized identifier), please wait until the operation is published to submit a new one." + } + } +} +``` + +You need to wait until the didDocumentstatus is back to `published` before you can submit another change. + +The domain URLs must start with https and not contain any path values. + +Possible error messages: + +``` +HTTP/1.1 400 Bad Request +Content-type: application/json + +{ + "requestId":"57c5ac78abb86bbfbc6f9e96d9ae6b18", + "date":"Mon, 07 Feb 2022 18:47:14 GMT", + "mscv":"+QfihZZk87z0nky2.0", + "error": "BadRequest", + "innererror": { + "code":"parameterUrlSchemeMustBeHttps", + "message":"URLs must begin with HTTPS: domains" + } +} +``` + +``` +HTTP/1.1 400 Bad Request +Content-type: application/json + +{ + "requestId":"e65753b03f28f159feaf434eaf140547", + "date":"Mon, 07 Feb 2022 18:48:36 GMT", + "mscv":"QWB4uvgYzCKuMeKg.0", + "error": "BadRequest", + "innererror": { + "code":"parameterUrlPathMustBeEmpty", + "message":"The URL can only include a domain. Please remove any characters after the domain name and try again. linkedDomainUrl" + } +} +``` + + +#### Remarks + +Although it is technically possible to publish multiple domains, we currently only support a single domain per authority. + +### 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). + +#### HTTP request + +`POST /v1.0/verifiableCredentials/authorities/:authorityId/generateWellknownDidConfiguration` + + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +You need to specify one of the domains in the linkedDomains of the specified authority. + +``` +{ + "domainUrl":"https://atest/" +} +``` + +#### Response message + +Example response message: + +``` +HTTP/1.1 200 OK +Content-type: application/json + +{ + "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld", + "linked_dids": [ + "eyJhbGciOiJFUzI1NksiL......" + ] +} +``` + +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: + +``` +HTTP/1.1 400 Bad Request +Content-type: application/json + +{ + "requestId":"079192a95fbf56a661c1b2dd0e012af5", + "date":"Mon, 07 Feb 2022 18:55:53 GMT", + "mscv":"AVQh55YiU3FxMipB.0", + "error": + { + "code":"wellKnownConfigDomainDoesNotExistInIssuer", + "message":"The domain used as an input to generate the well-known document is not registered with your organization. Domain: https://wrongdomain/" + } +} + +``` + +#### Remarks + +You can point multiple DIDs to the same domain. If you choose this configuration, you need to combine generated tokens and put them in the same did-configuration.json file. The file contains an array of these tokens. + +For example: +``` +{ + "@context": "https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld", + "linked_dids": [ + "eyJhbG..token1......", + "eyJhbG..token2......" + ] +} +``` + +### Generate DID document + +This call generates the DID Document used for DID:WEB identifiers. After generating this DID Document, the administrator has to place the file at the https://domain/.well-known/did.json location. + +#### HTTP request + +`POST /v1.0/verifiableCredentials/authorities/:authorityId/generateDidDocument` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +Don't supply a request body for this method. + +#### Response message + +``` +HTTP/1.1 200 OK +Content-type: application/json + +{ + "id": "did:web:www.contoso.com", + "@context": [ + "https://www.w3.org/ns/did/v1", + { + "@base": "did:web:www.contoso.com" + } + ], + "service": [ + { + "id": "#linkeddomains", + "type": "LinkedDomains", + "serviceEndpoint": { + "origins": [ + "https://www.contoso.com/" + ] + } + }, + { + "id": "#hub", + "type": "IdentityHub", + "serviceEndpoint": { + "instances": [ + "https://verifiedid.hub.msidentity.com/v1.0/f640a374-b380-42c9-8e14-d174506838e9" + ] + } + } + ], + "verificationMethod": [ + { + "id": "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b", + "controller": "did:web:www.contoso.com", + "type": "EcdsaSecp256k1VerificationKey2019", + "publicKeyJwk": { + "crv": "secp256k1", + "kty": "EC", + "x": "bFkOsjDB_K-hfz-c-ggspVHETMeZm31CtuzOt0PrmZc", + "y": "sewHrUNpXvJ7k-_4K8Yq78KgKzT1Vb7kmhK8x7_6h0g" + } + } + ], + "authentication": [ + "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b" + ], + "assertionMethod": [ + "#a2518db3b6b44332b3b667928a51b0cavcSigningKey-f0a5b" + ] +} +``` + +#### Remark + +Requires the caller to have the KEY List permissions on the target key vault. + +### Validate well-known DID configuration + +This call checks your DID setup. It downloads the well known DID configuration and validates if the correct DID is used and the signature is correct. + +#### HTTP request + +`POST /v1.0/verifiableCredentials/authorities/:authorityId/validateWellKnownDidConfiguration` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +Don't supply a request body for this method. + + +#### Response message + +``` +HTTP/1.1 204 No Content +Content-type: application/json +``` + +### Rotate signing keys + +The rotate signing keys update the private key for the did:web authority. + +#### HTTP request + +`POST /v1.0/verifiableCredentials/authorities/:authorityId/rotateSigningKey` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request Body + +Don't supply a request body for this method. + +#### Response message + +``` +HTTP/1.1 202 Accepted +Content-type: application/json +``` + + +## Contracts + +This endpoint allows you to create new contracts, and update existing contracts. Contracts consist of two parts represented by two JSON definitions. Information on how to design and create a contract manually can be found [here](credential-design.md). + +- The display definition is used by administrators to control the appearance of a verifiable credential, for example background color, logo and title of the verifiable credential. This file also contains the claims that need to be stored inside the verifiable credential. +- The rules definition contains the information on how to gather and collect attestations like self-attested claims, another verifiable credential as input or perhaps an ID Token received after a user has signed in to an OIDC compatible identity provider. + +### Methods + +| Methods | Return Type | Description | +| -------- | -------- | -------- | +| [Get contract](#get-contract) | Contract | Read properties of a Contract | +| [List contracts](#list-contracts) | Contract collection | Get a list of all configured contracts | +| [Create contract](#create-contract) | Contract | Create a new contract | +| [Update contract](#update-contract) | Contract | Update contract | + + +### Get contract + +#### HTTP request + +`GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts/:contractId` + +Replace the ```:authorityId``` and ```:contractId``` with the correct value of the authority and contract. + + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +Don't supply a request body for this method. + +#### Response message + +example message: +``` +HTTP/1.1 200 OK +Content-type: application/json + +{ + "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg", + "name": "contractname", + "status": "Enabled", + "issueNotificationEnabled": false, + "availableInVcDirectory": false, + "manifestUrl": "...", + "issueNotificationAllowedToGroupOids" : null, + "rules": rulesModel, + "displays": displayModel[] +} +``` + +The response contains the following properties + +#### Contract type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `Id` | string | contract ID | +| `name` | string | The friendly name of this contract | +| `status` | string | Always `Enabled` | +| `manifestUrl` | string | URL to the contract used in the issuance request | +| `issueNotificationEnabled` | boolean | set to true if users will be notified this VC is ready for them to get issued | +| `issueNotificationAllowedToGroupOids` | array of groupId strings | array of group IDs this credential will be offered to | +| `availableInVcDirectory` | boolean | Is this contract published in the Verifiable Credential Network | +| [rules](#rulesmodel-type) | rulesModel | rules definition | +| [displays](#displaymodel-type) | displayModel array| display definitions | + +#### rulesModel type + +| Property | Type | Description | +| -------- | -------- | -------- | +|`attestations`| [idTokenAttestation](#idtokenattestation-type) or [idTokenHintAttestation](#idtokenhintattestation-type) and/or [verifiablePresentationAttestation](#verifiablepresentationattestation-type) and/or [selfIssuedAttestation](#selfissuedattestation-type) and/or [accessTokenAttestation](#accesstokenattestation-type) (array) | 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 | + +If the property `customStatusEndpoint` property isn't specified then the `anonymous` status endpoint is used. + +#### idTokenAttestation type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `mapping` | [claimMapping](#claimmapping-type) (optional) | rules to map input claims into output claims in the verifiable credential | +| `configuration` | string (url) | location of the identity provider's configuration document | +| `clientId` | string | client ID to use when obtaining the ID token | +| `redirectUri` | string | redirect uri to use when obtaining the ID token MUST BE vcclient://openid/ | +| `scope` | string | space delimited list of scopes to use when obtaining the ID token | +| `required` | boolean (default false) | indicating whether this attestation is required or not | + +#### idTokenHintAttestation type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `mapping` | [claimMapping](#claimmapping-type) (optional) | rules to map input claims into output claims in the verifiable credential | +| `required` | boolean (default false) | indicating whether this attestation is required or not | +| `trustedIssuers` | string (array) | a list of DIDs allowed to issue the verifiable credential for this contract | + +#### verifiablePresentationAttestation type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `mapping` | [claimMapping](#claimmapping-type) (optional) | rules to map input claims into output claims in the verifiable credential | +| `credentialType` | string (optional) | required credential type of the input | +| `required` | boolean (default false) | indicating whether this attestation is required or not | +| `trustedIssuers` | string (array) | a list of DIDs allowed to issue the verifiable credential for this contract | + +#### selfIssuedAttestation type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `mapping` | [claimMapping](#claimmapping-type) (optional) | rules to map input claims into output claims in the verifiable credential | +| `required` | boolean (default false) | indicating whether this attestation is required or not | + +#### accessTokenAttestation type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `mapping` | [claimMapping](#claimmapping-type) (optional) | rules to map input claims into output claims in the verifiable credential | +| `required` | boolean (default false) | indicating whether this attestation is required or not | + +> Supported `inputClaim` values for the `mappings` property are: `givenName`, `displayName`, `preferredLanguage`, `userPrincipalName`, `surname`, `mail`, `jobTitle`, `photo`. + +#### claimMapping type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `inputClaim` | string | the name of the claim to use from the input | +| `outputClaim` | string | the name of the claim in the verifiable credential | +| `indexed` | boolean (default false) | indicating whether the value of this claim is used for searching; only one clientMapping object is allowed to be indexed for a given contract | +| `required` | boolean (default false) | indicating whether this mapping is required or not | +| `type` | string (optional) | type of claim | + +#### customStatusEndpoint type + +| Property | Type | Description | +| -------- | -------- | -------- | +| `url` | string (url)| the url of the custom status endpoint | +| `type` | string | the type of the endpoint | +example: + +``` +"rules": { + "attestations": { + "idTokens": [ + { + "clientId": "2f670d73-624a-41fe-a139-6f1f8f2d2e47", + "configuration": "https://bankofwoodgrove.b2clogin.com/bankofwoodgrove.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_si", + "redirectUri": "vcclient://openid/", + "scope": "openid", + "mapping": [ + { + "outputClaim": "givenName", + "required": false, + "inputClaim": "given_name", + "indexed": false + }, + { + "outputClaim": "familyName", + "required": false, + "inputClaim": "family_name", + "indexed": true + } + ], + "required": false + } + ] + }, + "validityInterval": 2592000, + "vc": { + "type": [ + "BankofWoodgroveIdentity" + ] + } +} +``` + +#### displayModel type + +| Property | Type | Description | +| -------- | -------- | -------- | +|`locale`| string | the locale of this display | +|`credential` | [displayCredential](#displaycredential-type) | the display properties of the verifiable credential | +|`consent` | [displayConsent](#displayconsent-type) | supplemental data when the verifiable credential is issued | +|`claims`| [displayClaims](#displayclaims-type) array | labels for the claims included in the verifiable credential | + +#### displayCredential type + +| Property | Type | Description | +| -------- | -------- | -------- | +|`title`| string | title of the credential | +|`issuedBy` | string | the name of the issuer of the credential | +|`backgroundColor` | number (hex)| background color of the credential in hex, for example, #FFAABB | +|`textColor`| number (hex)| text color of the credential in hex, for example, #FFAABB | +|`description`| string | supplemental text displayed alongside each credential | +|`logo`| [displayCredentialLogo](#displaycredentiallogo-type) | the logo to use for the credential | + +#### displayCredentialLogo type + +| Property | Type | Description | +| -------- | -------- | -------- | +|`url`| string (url) | url of the logo (optional if image is specified) | +|`description` | string | the description of the logo | +|`image` | string | the base-64 encoded image (optional if url is specified) | + +#### displayConsent type + +| Property | Type | Description | +| -------- | -------- | -------- | +|`title`| string | title of the consent | +|`instructions` | string | supplemental text to use when displaying consent | + +#### displayClaims type + + +| Property | Type | Description | +| -------- | -------- | -------- | +|`label`| string | the label of the claim in display | +|`claim`| string | the name of the claim to which the label applies | +|`type`| string | the type of the claim | +|`description` | string (optional) | the description of the claim | + +example: +``` +{ + "displays": [ + { + "locale": "en-US", + "card": { + "backgroundColor": "#FFA500", + "description": "ThisisyourBankofWoodgroveIdentity", + "issuedBy": "BankofWoodgrove", + "textColor": "#FFFF00", + "title": "BankofWoodgroveIdentity", + "logo": { + "description": "Defaultbankofwoodgrovelogo", + "uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png" + } + }, + "consent": { + "instructions": "Please login with your bankofWoodgrove account to receive this credential.", + "title": "Do you want to accept the verifiedbankofWoodgrove Identity?" + }, + "claims": [ + { + "claim": "vc.credentialSubject.givenName", + "label": "Name", + "type": "String" + }, + { + "claim": "vc.credentialSubject.familyName", + "label": "Surname", + "type": "String" + } + ] + } + ] +} +``` + +### List contracts + +This API lists all contracts configured in the current tenant for the specified authority. + +#### HTTP request + +`GET /v1.0/verifiableCredentials/authorities/:authorityId/contracts` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +Don't supply a request body for this method. + +#### Response message + +example message: + +``` +{ + value: + [ + { + "id": "ZjViZjJmYzYtNzEzNS00ZDk0LWE2ZmUtYzI2ZTQ1NDNiYzVhPHNjcmlwdD5hbGVydCgneWF5IScpOzwvc2NyaXB0Pg", + "name": "test1", + "authorityId": "ffea7eb3-0000-1111-2222-000000000000", + "status": "Enabled", + "issueNotificationEnabled": false, + "manifestUrl" : "https:/...", + "rules": "", + "displays": [{", + "displays": [{", + "displays": [{", + "displays": [{", + "displays": [{[!WARNING] +> This action cannot be undone and will invalidate all issued verifiable credentials and created contracts. + +#### HTTP Request +`POST /v1.0/verifiableCredentials/optout` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request body + +Don't supply a request body for this method + +#### Response message + +Example response message + +``` +HTTP/1.1 200 OK +Content-type: application/json + +OK +``` + +#### Remark + +>[!NOTE] +> If you don't have delete permissions on Key Vault we will return an error message and still opt-out + +## Next steps + +- [Specify the request service REST API issuance request](issuance-request-api.md) +- [Entra Verified ID Network API](issuance-request-api.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/credential-design.md b/articles/active-directory/verifiable-credentials/credential-design.md index 94a522b06e4dc..141119b62db65 100644 --- a/articles/active-directory/verifiable-credentials/credential-design.md +++ b/articles/active-directory/verifiable-credentials/credential-design.md @@ -16,275 +16,118 @@ ms.author: barclayn [!INCLUDE [verifiable credentials announcement](../../../includes/verifiable-credentials-brand.md)] -Verifiable credentials are made up of two components, *rules* definitions and *display* definitions. A rules definition determines what users need to provide before they receive a verifiable credential. A display definition controls the branding of the credential and styling of the claims. +Verifiable credentials definitions are made up of two components, *display* definitions and *rules* definitions. A display definition controls the branding of the credential and styling of the claims. A rules definition determines what users need to provide before they receive a verifiable credential. -This article explains how to modify both types of files to meet the requirements of your organization. +This article explains how to modify both types of definitions to meet the requirements of your organization. > [!IMPORTANT] > Microsoft Entra Verified ID is currently in 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. > For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). -## Rules definition: Requirements from the user - -The rules definition is a simple JSON document that describes important properties of verifiable credentials. In particular, it describes how claims are used to populate your verifiable credential. - -### User-input types +## Display definition: wallet credential visuals -The following four user-input types are currently available to be configured in the rules definition. They're used by the verifiable credential issuing service to insert claims into a verifiable credential and attest to that information with your decentralized identifier (DID). +Microsoft Entra Verified ID offer a limited set of options that can be used to reflect your brand. This article provides instructions how to customize your credentials, and best practices for designing credentials that look great after they're issued to users. -* **ID token**: When this option is configured, you'll need to provide an Open ID Connect configuration URI and include the claims that should be included in the verifiable credential. Users are prompted to 'Sign in' on the Authenticator app to meet this requirement and add the associated claims from their account. +Microsoft Authenticator, being a decentralized identities wallet, displays verifiable credentials that are issued to users as cards. As a VC administrator, you can choose card colors, icons, and text strings to match your organization's brand. -* **ID token hint**: The sample App and Tutorial use the ID token Hint. When this option is configured, the relying party app will need to provide claims that should be included in the verifiable credential in the Request Service API issuance request. Where the relying party app gets the claims from is up to the app, but it can come from the current sign-in session, from backend CRM systems or even from self asserted user input. - -* **Verifiable credentials**: The end result of an issuance flow is to produce a verifiable credential but you may also ask the user to Present a verifiable credential in order to issue one. The rules definition is able to take specific claims from the presented verifiable credential and include those claims in the newly issued verifiable credential from your organization. +![Screenshot of a verified credential card in Authenticator, calling out key elements.](media/credential-design/detailed-view.png) -* **Self-attested claims**: When this option is selected, the user can type information directly into Authenticator. At this time, strings are the only supported input for self attested claims. - - ![Detailed view of a verifiable credential card.](media/credential-design/issuance-doc.png) - -### Static claims +Cards also contain customizable fields. You can use these fields to let users know the purpose of the card, the attributes it contains, and more. -Additionally, you can declare a static claim in the rules definition, but this input doesn't come from the user. The issuer defines a static claim in the rules definition, and it looks like any other claim in the verifiable credential. You add credentialSubject after vc.type and declare the attribute and the claim. +## Create a credential display definition -```json -"vc": { - "type": [ "StaticClaimCredential" ], - "credentialSubject": { - "staticClaim": true, - "anotherClaim": "Your Claim Here" - }, - } -} -``` +The display definition is a simple JSON document that describes how the wallet app should display the contents of your verifiable credentials. -## Input type: ID token +>[!NOTE] +> This display model is currently used only by Microsoft Authenticator. -To get an ID token as input, the rules definition needs to configure the well-known endpoint of the OpenID Connect (OIDC)-compatible identity system. In that system you need to register an application with the correct information from the [Issuer service communication examples](issuer-openid.md). Additionally, you need to put client_id in the rules definition and fill in a scope parameter with the correct scopes. For example, Azure Active Directory needs the email scope if you want to return an email claim in the ID token. +The display definition has the following structure: ```json - { - "attestations": { - "idTokens": [ - { - "mapping": [ - { - "outputClaim": "firstName", - "inputClaim": "given_name", - "required": true, - "indexed": false - }, - { - "outputClaim": "lastName", - "inputClaim": "family_name", - "required": true, - "indexed": true - } - ], - "configuration": "https://dIdPlayground.b2clogin.com/dIdPlayground.onmicrosoft.com/B2C_1_sisu/v2.0/.well-known/openid-configuration", - "client_id": "8d5b446e-22b2-4e01-bb2e-9070f6b20c90", - "redirect_uri": "vcclient://openid/", - "scope": "openid profile" - } - ] +{ + "locale": "en-US", + "card": { + "title": "Verified Credential Expert", + "issuedBy": "Microsoft", + "backgroundColor": "#000000", + "textColor": "#ffffff", + "logo": { + "uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png", + "description": "Verified Credential Expert Logo" }, - "validityInterval": 2592000, - "vc": { - "type": ["https://schema.org/EducationalCredential", "https://schemas.ed.gov/universityDiploma2020", "https://schemas.contoso.edu/diploma2020" ] - } - } -``` - -For more information about properties, see [idTokenAttestation type](rules-and-display-definitions-model.md#idtokenattestation-type). - -## Input type: ID token hint - -To get an ID token hint as input, the rules definition shouldn't contain configuration for an OIDC identity system. Instead, it should have the special value `https://self-issued.me` for the configuration property. The claims mappings are the same as for the ID token type, but the difference is that the claim values need to be provided by the issuance relying party app in the Request Service API issuance request. - -```json - { - "attestations": { - "idTokenHints": [ - { - "configuration": "https://self-issued.me", - "mapping": [ - { - "outputClaim": "firstName", - "inputClaim": "given_name", - "required": true, - "indexed": false - }, - { - "outputClaim": "lastName", - "inputClaim": "family_name", - "required": true, - "indexed": true - } - ] - } - ] + "description": "Use your verified credential to prove to anyone that you know all about verifiable credentials." + }, + "consent": { + "title": "Do you want to get your Verified Credential?", + "instructions": "Sign in with your account to get your card." + }, + "claims": [ + { + "claim": "vc.credentialSubject.firstName", + "label": "First name", + "type": "String" }, - "validityInterval": 2592000, - "vc": { - "type": ["VerifiedCredentialExpert" ] + { + "claim": "vc.credentialSubject.lastName", + "label": "Last name", + "type": "String" } - } -``` - -For more information about properties, see [idTokenHintAttestation type](rules-and-display-definitions-model.md#idtokenhintattestation-type). - -### vc.type: Choose credential types - -All verifiable credentials must declare their *type* in their rules definition. The credential type distinguishes your verifiable credentials from credentials that are issued by other organizations, and it ensures interoperability between issuers and verifiers. - -To indicate a credential type, provide one or more credential types that the credential satisfies. Each type is represented by a unique string. Often, a URI is used to ensure global uniqueness. The URI doesn't need to be addressable. It's treated as a string. - -As an example, a diploma credential issued by Contoso University might declare the following types: - -| Type | Purpose | -| ---- | ------- | -| `https://schema.org/EducationalCredential` | Declares that diplomas issued by Contoso University contain attributes defined by the schema.org `EducationaCredential` object. | -| `https://schemas.ed.gov/universityDiploma2020` | Declares that diplomas issued by Contoso University contain attributes defined by the U.S. Department of Education. | -| `https://schemas.contoso.edu/diploma2020` | Declares that diplomas issued by Contoso University contain attributes defined by Contoso University. | - -By declaring three types of diplomas, Contoso can issue credentials that satisfy different requests from verifiers. A bank can request a set of `EducationCredential`s from a user, and the diploma can be used to satisfy the request. Or the Contoso University Alumni Association can request a credential of type `https://schemas.contoso.edu/diploma2020`, and the diploma can also satisfy the request. - -To ensure interoperability of your credentials, we recommend that you work closely with related organizations to define credential types, schemas, and URIs for use in your industry. Many industry bodies provide guidance on the structure of official documents that can be repurposed for defining the contents of verifiable credentials. You should also work closely with the verifiers of your credentials to understand how they intend to request and consume your verifiable credentials. - -## Input type: Verifiable credential - -> [!NOTE] -> Rules definitions that ask for a verifiable credential don't use the presentation exchange format for requesting credentials. This approach will be updated when the issuing service supports the standard, Credential Manifest. - -```json -{ - "attestations": { - "presentations": [ - { - "mapping": [ - { - "outputClaim": "first_name", - "inputClaim": "$.vc.credentialSubject.firstName ", - "required": true, - "indexed": false - }, - { - "outputClaim": "last_name", - "inputClaim": ""$.vc.credentialSubject.lastName ", - "required": true, - "indexed": true - }, - "credentialType": "VerifiedCredentialNinja", - "contracts": [ - "https://beta.did.msidentity.com/v1.0/3c32ed40-8a10-465b-8ba4-0b1e86882668/verifiableCredential/contracts/VerifiedCredentialNinja" - ], - "issuers": [ - { - "iss": "did:ion:123" - } - ] - } - ] - }, - "validityInterval": 25920000, - "vc": { - "type": [ - "ProofOfNinjaNinja" - ] - } + ] } ``` -For more information about properties, see [verifiablePresentationAttestation type](rules-and-display-definitions-model.md#verifiablepresentationattestation-type). +For more information about properties, see [displayModel type](rules-and-display-definitions-model.md#displaymodel-type). -## Input type: Self-attested claims +## Rules definition: Requirements from the user -During the issuance flow, users can be asked to input some self-attested information. As of now, the only input type is 'string'. +The rules definition is a simple JSON document that describes important properties of verifiable credentials. In particular, it describes how claims are used to populate your verifiable credential and the credential type. ```json { "attestations": { - "selfIssued" : - { - "mapping": [ - { - "outputClaim": "firstName", - "inputClaim": "firstName", - "required": true, - "indexed": false - }, - { - "outputClaim": "lasttName", - "inputClaim": "lastName", - "required": true, - "indexed": true - } - - - } + ... }, - "validityInterval": 2592001, + "validityInterval": 2592000, "vc": { - "type": [ "VerifiedCredentialExpert" ] + "type": [ + "VerifiedCredentialExpert" + ] } } ``` -For more information about properties, see [selfIssuedAttestation type](rules-and-display-definitions-model.md#selfissuedattestation-type). +### Attestations -## Display definition: Verifiable credentials in Microsoft Authenticator +The following four attestation types are currently available to be configured in the rules definition. They're used by the verifiable credential issuing service to insert claims into a verifiable credential and attest to that information with your decentralized identifier (DID). -Verifiable credentials offer a limited set of options that can be used to reflect your brand. This article provides instructions how to customize your credentials, and best practices for designing credentials that look great after they're issued to users. +* **ID token**: When this option is configured, you'll need to provide an Open ID Connect configuration URI and include the claims that should be included in the verifiable credential. Users are prompted to 'Sign in' on the Authenticator app to meet this requirement and add the associated claims from their account. To configure this option, see this [how to guide](how-to-use-quickstart-idtoken.md) -Authenticator displays verifiable credentials that are issued to users as cards. As an administrator, you can choose card colors, icons, and text strings to match your organization's brand. -![Image of a verified credential card in Authenticator, calling out key elements.](media/credential-design/detailed-view.png) +* **ID token hint**: The sample App and Tutorial use the ID token Hint. When this option is configured, the relying party app will need to provide claims that should be included in the verifiable credential in the Request Service API issuance request. Where the relying party app gets the claims from is up to the app, but it can come from the current sign-in session, from backend CRM systems or even from self asserted user input. To configure this option, please see this [how to guide](how-to-use-quickstart.md) -Cards also contain customizable fields. You can use these fields to let users know the purpose of the card, the attributes it contains, and more. +* **Verifiable credentials**: The end result of an issuance flow is to produce a verifiable credential but you may also ask the user to Present a verifiable credential in order to issue one. The rules definition is able to take specific claims from the presented verifiable credential and include those claims in the newly issued verifiable credential from your organization. -## Create a credential display definition +* **Self-attested claims**: When this option is selected, the user can type information directly into Authenticator. At this time, strings are the only supported input for self attested claims. To configure this option, please see this [how to guide](how-to-use-quickstart-selfissued.md) -Much like the rules definition, the display definition is a simple JSON document that describes how the Authenticator app should display the contents of your verifiable credentials. +For more information about the rules JSON model, see [rulesModel type](rules-and-display-definitions-model.md#rulesmodel-type). ->[!NOTE] -> This display model is currently used only by Microsoft Authenticator. +### Credential Types -The display definition has the following structure: +All verifiable credentials must declare their *type* in their [rules definition](rules-and-display-definitions-model.md#rulesmodel-type). The credential type distinguishes a verifiable credentials schema from other credentials and it ensures interoperability between issuers and verifiers. To indicate a credential type, provide one or more credential types that the credential satisfies. Each type is represented by a unique string. Often, a URI is used to ensure global uniqueness. The URI doesn't need to be addressable. It's treated as a string. As an example, a diploma credential issued by Contoso University might declare the following types: -```json -{ - "default": { - "locale": "en-US", - "card": { - "title": "University Graduate", - "issuedBy": "Contoso University", - "backgroundColor": "#212121", - "textColor": "#FFFFFF", - "logo": { - "uri": "https://contoso.edu/images/logo.png", - "description": "Contoso University Logo" - }, - "description": "This digital diploma is issued to students and alumni of Contoso University." - }, - "consent": { - "title": "Do you want to get your digital diploma from Contoso U?", - "instructions": "Please log in with your Contoso U account to receive your digital diploma." - }, - "claims": [ - { - "claim": "vc.credentialSubject.name", - "type": "String", - "label": "Name" - } - ] - } -} -``` +| Type | Purpose | +| ---- | ------- | +| `https://schema.org/EducationalCredential` | Declares that diplomas issued by Contoso University contain attributes defined by the schema.org `EducationaCredential` object. | +| `https://schemas.ed.gov/universityDiploma2020` | Declares that diplomas issued by Contoso University contain attributes defined by the U.S. Department of Education. | +| `https://schemas.contoso.edu/diploma2020` | Declares that diplomas issued by Contoso University contain attributes defined by Contoso University. | -For more information about properties, see [displayModel type](rules-and-display-definitions-model.md#displaymodel-type). +By declaring three types of diplomas, Contoso can issue credentials that satisfy different requests from verifiers. A bank can request a set of `EducationCredential`s from a user, and the diploma can be used to satisfy the request. Or the Contoso University Alumni Association can request a credential of type `https://schemas.contoso.edu/diploma2020`, and the diploma can also satisfy the request. + +To ensure interoperability of your credentials, we recommend that you work closely with related organizations to define credential types, schemas, and URIs for use in your industry. Many industry bodies provide guidance on the structure of official documents that can be repurposed for defining the contents of verifiable credentials. You should also work closely with the verifiers of your credentials to understand how they intend to request and consume your verifiable credentials. ## Next steps Now that you have a better understanding of verifiable credential design and how to create your own, see: - [Issuer service communication examples](issuer-openid.md) -- [Rules and display definition reference](rules-and-display-definitions-model.md) +- [Rules and display definition reference](rules-and-display-definitions-model.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/decentralized-identifier-overview.md b/articles/active-directory/verifiable-credentials/decentralized-identifier-overview.md index f32ced5376b54..ae8cfba790772 100644 --- a/articles/active-directory/verifiable-credentials/decentralized-identifier-overview.md +++ b/articles/active-directory/verifiable-credentials/decentralized-identifier-overview.md @@ -1,5 +1,5 @@ --- -title: Introduction to Azure Active Directory Verifiable Credentials (preview) +title: Introduction to Microsoft Entra Verified ID (preview) description: An overview Azure Verifiable Credentials. services: active-directory author: barclayn @@ -8,27 +8,27 @@ editor: ms.service: decentralized-identity ms.subservice: verifiable-credentials ms.topic: overview -ms.date: 06/16/2022 +ms.date: 06/02/2022 ms.author: barclayn ms.reviewer: --- -# Introduction to Azure Active Directory Verifiable Credentials (preview) +# Introduction to Microsoft Entra Verified ID (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] > [!IMPORTANT] -> Azure Active Directory Verifiable Credentials is currently in public preview. +> Microsoft Entra Verified ID 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. > For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). Our digital and physical lives are increasingly linked to the apps, services, and devices we use to access a rich set of experiences. This digital transformation allows us to interact with hundreds of companies and thousands of other users in ways that were previously unimaginable. -But identity data has too often been exposed in security breaches. These breaches affect our social, professional, and financial lives. Microsoft believes that there’s a better way. Every person has a right to an identity that they own and control, one that securely stores elements of their digital identity and preserves privacy. We are building an open, trustworthy, interoperable, and standards-based Decentralized Identity (DID) solution for individuals and organizations. +But identity data has too often been exposed in security breaches. These breaches affect our social, professional, and financial lives. Microsoft believes that there’s a better way. Every person has a right to an identity that they own and control, one that securely stores elements of their digital identity and preserves privacy. This primer explains how we are joining hands with a diverse community to build an open, trustworthy, interoperable, and standards-based Decentralized Identity (DID) solution for individuals and organizations. ## Why we need Decentralized Identity -Today we use our digital identity at work, home, and across every app, service, and device we use. Our digital identity is made up of everything we say, do, and experience in our lives. Activities like purchasing tickets for an event, checking into a hotel, or even ordering lunch become part of our identity. Today our identity and information about our online activity are owned and controlled by others. In some cases, even without our knowledge. +Today we use our digital identity at work, at home, and across every app, service, and device we use. It’s made up of everything we say, do, and experience in our lives—purchasing tickets for an event, checking into a hotel, or even ordering lunch. Currently, our identity and all our digital interactions are owned and controlled by other parties, some of whom we aren’t even aware of. Generally, users grant consent to several apps and devices. This approach requires a high degree of vigilance on the user's part to track who has access to what information. On the enterprise front, collaboration with consumers and partners requires high-touch orchestration to securely exchange data in a way that maintains privacy and security for all involved. @@ -36,7 +36,7 @@ We believe a standards-based Decentralized Identity system can unlock a new set ## Lead with open standards -We’re committed to working closely with customers, partners, and the community to unlock the next generation of Decentralized Identity–based experiences. We are excited to partner with individuals and organizations making incredible contributions in this space. If the DID ecosystem is to grow, standards, technical components, and code deliverables must be open source and accessible to all. +We’re committed to working closely with customers, partners, and the community to unlock the next generation of Decentralized Identity–based experiences, and we’re excited to partner with the individuals and organizations that are making incredible contributions in this space. If the DID ecosystem is to grow, standards, technical components, and code deliverables must be open source and accessible to all. Microsoft is actively collaborating with members of the Decentralized Identity Foundation (DIF), the W3C Credentials Community Group, and the wider identity community. We’ve worked with these groups to identify and develop critical standards, and the following standards have been implemented in our services. @@ -52,7 +52,7 @@ Microsoft is actively collaborating with members of the Decentralized Identity F Before we can understand DIDs, it helps to compare them with current identity systems. Email addresses and social network IDs are human-friendly aliases for collaboration but are now overloaded to serve as the control points for data access across many scenarios beyond collaboration. This creates a potential problem, because access to these IDs can be removed at any time by external parties. -Decentralized Identifiers (DIDs) are different. DIDs are user-generated, self-owned, globally unique identifiers rooted in decentralized systems like ION. They possess unique characteristics, like greater assurance of immutability, censorship resistance, and tamper evasiveness. These attributes are critical for any ID system that is intended to provide self-ownership and user control. +Decentralized Identifiers (DIDs) are different. DIDs are user-generated, self-owned, globally unique identifiers rooted in decentralized systems like ION. They possess unique characteristics, like greater assurance of immutability, censorship resistance, and tamper evasiveness. These attributes are critical for any ID system that is intended to provide self-ownership and user control. Microsoft’s verifiable credential solution uses decentralized credentials (DIDs) to cryptographically sign as proof that a relying party (verifier) is attesting to information proving they are the owners of a verifiable credential. A basic understanding of DIDs is recommended for anyone creating a verifiable credential solution based on the Microsoft offering. @@ -71,35 +71,38 @@ To deliver on these promises, we need a technical foundation made up of seven ke ![overview of Microsoft's verifiable credential environment](media/decentralized-identifier-overview/microsoft-did-system.png) -**1. W3C Decentralized Identifiers (DIDs)** +**1. W3C Decentralized Identifiers (DIDs)**. IDs users create, own, and control independently of any organization or government. DIDs are globally unique identifiers linked to Decentralized Public Key Infrastructure (DPKI) metadata composed of JSON documents that contain public key material, authentication descriptors, and service endpoints. -**2. Decentralized system** +**2. Trust System**. +In order to be able to resolve DID documents, DIDs are typically recorded on an underlying network of some kind that represents a trust system. Microsoft currently supports two trust systems, which are: -- ION (Identity Overlay Network) ION is a Layer 2 open, permissionless network based on the purely deterministic Sidetree protocol, which requires no special tokens, trusted validators, or other consensus mechanisms. The linear progression of Bitcoin's time chain is all that's required for its operation. We have open sourced a [npm package](https://www.npmjs.com/package/@decentralized-identity/ion-tools) to make working with the ION network easy to integrate into your apps and services. Libraries include creating a new DID, generating keys and anchoring your DID on the Bitcoin blockchain. +- ION (Identity Overlay Network) ION is a Layer 2 open, permissionless network based on the purely deterministic Sidetree protocol, which requires no special tokens, trusted validators, or other consensus mechanisms; the linear progression of Bitcoin's time chain is all that's required for its operation. We have open sourced a [npm package](https://www.npmjs.com/package/@decentralized-identity/ion-tools) to make working with the ION network easy to integrate into your apps and services. Libraries include creating a new DID, generating keys and anchoring your DID on the Bitcoin blockchain. -- `did:web` is a permission based model that allows trust using a web domain’s existing reputation. +- DID:Web is a permission based model that allows trust using a web domain’s existing reputation. -**3. DID User Agent/Wallet: Microsoft Authenticator App** +**3. DID User Agent/Wallet: Microsoft Authenticator App**. Enables real people to use decentralized identities and Verifiable Credentials. Authenticator creates DIDs, facilitates issuance and presentation requests for verifiable credentials and manages the backup of your DID's seed through an encrypted wallet file. -**4. Microsoft Resolver** +**4. Microsoft Resolver**. An API that connects to our ION node to look up and resolve DIDs using the ```did:ion``` method and return the DID Document Object (DDO). The DDO includes DPKI metadata associated with the DID such as public keys and service endpoints. -**5. Azure Active Directory Verified Credentials Service** +**5. Azure Active Directory Verified Credentials Service**. An issuance and verification service in Azure and a REST API for [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/) that are signed with the ```did:ion``` method. They enable identity owners to generate, present, and verify claims. This forms the basis of trust between users of the systems. ## A sample scenario -The scenario we use to explain how Verifiable Credentials work involves: +The scenario we use to explain how VCs work involves: -- WoodGrove Inc. a company. -- ProseWare, a company that offers WoodGrove employees discounts. -- Alice, an employee at WoodGrove, Inc. who wants to get a discount from ProseWare +- Woodgrove Inc. a company. +- Proseware, a company that offers Woodgrove employees discounts. +- Alice, an employee at Woodgrove, Inc. who wants to get a discount from Proseware -Today, Alice provides a username and password to sign in WoodGrove’s networked environment. WoodGrove is deploying a verifiable credential solution to provide a more manageable way for Alice to prove that she's an employee of WoodGrove. ProseWare accepts verifiable credentials issued by WoodGrove as proof of employment to offer corporate discounts as part of their corporate discount program. -Alice requests WoodGrove Inc for a proof of employment verifiable credential. WoodGrove Inc attests Alice's identity and issues a signed verifiable credential that Alice can accept and store in her digital wallet application. Alice can now present this verifiable credential as a proof of employment on the ProseWare site. After a successful presentation of the credential, ProsWare offers discount to Alice and the transaction is logged in Alice's wallet application so that she can track where and to whom she's presented her proof of employment verifiable credential. + +Today, Alice provides a username and password to log onto Woodgrove’s networked environment. Woodgrove is deploying a verifiable credential solution to provide a more manageable way for Alice to prove that she is an employee of Woodgrove. Proseware accepts verifiable credentials issued by Woodgrove as proof of employment to offer corporate discounts as part of their corporate discount program. + +Alice requests Woodgrove Inc for a proof of employment verifiable credential. Woodgrove Inc attests Alice's identity and issues a signed verfiable credential that Alice can accept and store in her digital wallet application. Alice can now present this verifiable credential as a proof of employement on the Proseware site. After a succesfull presentation of the credential, Prosware offers discount to Alice and the transaction is logged in Alice's wallet application so that she can track where and to whom she has presented her proof of employment verifiable credential. ![microsoft-did-overview](media/decentralized-identifier-overview/did-overview.png) @@ -115,11 +118,11 @@ The roles in this scenario are: ![roles in a verifiable credential environment](media/decentralized-identifier-overview/issuer-user-verifier.png) -**issuer** – The issuer is an organization that creates an issuance solution requesting information from a user. The information is used to verify the user’s identity. For example, WoodGrove, Inc. has an issuance solution that enables them to create and distribute verifiable credentials (VCs) to all their employees. The employee uses the Authenticator app to sign in with their username and password, which passes an ID token to the issuing service. Once WoodGrove, Inc. validates the ID token submitted, the issuance solution creates a VC that includes claims about the employee and is signed with WoodGrove, Inc. DID. The employee now has a verifiable credential that is signed by their employer, which includes the employees DID as the subject DID. +**issuer** – The issuer is an organization that creates an issuance solution requesting information from a user. The information is used to verify the user’s identity. For example, Woodgrove, Inc. has an issuance solution that enables them to create and distribute verifiable credentials (VCs) to all their employees. The employee uses the Authenticator app to sign in with their username and password, which passes an ID token to the issuing service. Once Woodgrove, Inc. validates the ID token submitted, the issuance solution creates a VC that includes claims about the employee and is signed with Woodgrove, Inc. DID. The employee now has a verifiable credential that is signed by their employer, which includes the employees DID as the subject DID. -**user** – The user is the person or entity that is requesting a VC. For example, Alice is a new employee of WoodGrove, Inc. and was previously issued her proof of employment verifiable credential. When Alice needs to provide proof of employment in order to get a discount at ProseWare, she can grant access to the credential in her Authenticator app by signing a verifiable presentation that proves Alice is the owner of the DID. ProseWare is able to validate the credential was issued by WoodGrove, Inc.and Alice is the owner of the credential. +**user** – The user is the person or entity that is requesting a VC. For example, Alice is a new employee of Woodgrove, Inc. and was previously issued her proof of employment verifiable credential. When Alice needs to provide proof of employment in order to get a discount at Proseware, she can grant access to the credential in her Authenticator app by signing a verifiable presentation that proves Alice is the owner of the DID. Proseware is able to validate the credential was issued by Woodgrove, Inc.and Alice is the owner of the credential. -**verifier** – The verifier is a company or entity who needs to verify claims from one or more issuers they trust. For example, ProseWare trusts WoodGrove, Inc. does an adequate job of verifying their employees’ identity and issuing authentic and valid VCs. When Alice tries to order the equipment she needs for her job, ProseWare will use open standards such as SIOP and Presentation Exchange to request credentials from the user proving they are an employee of WoodGrove, Inc. For example, ProseWare might provide Alice a link to a website with a QR code she scans with her phone camera. This initiates the request for a specific VC, which Authenticator will analyze and give Alice the ability to approve the request to prove her employment to ProseWare. ProseWare can use the verifiable credentials service API or SDK, to verify the authenticity of the verifiable presentation. Based on the information provided by Alice they give Alice the discount. If other companies and organizations know that WoodGrove, Inc. issues VCs to their employees, they can also create a verifier solution and use the WoodGrove, Inc. verifiable credential to provide special offers reserved for WoodGrove, Inc. employees. +**verifier** – The verifier is a company or entity who needs to verify claims from one or more issuers they trust. For example, Proseware trusts Woodgrove, Inc. does an adequate job of verifying their employees’ identity and issuing authentic and valid VCs. When Alice tries to order the equipment she needs for her job, Proseware will use open standards such as SIOP and Presentation Exchange to request credentials from the User proving they are an employee of Woodgrove, Inc. For example, Proseware might provide Alice a link to a website with a QR code she scans with her phone camera. This initiates the request for a specific VC, which Authenticator will analyze and give Alice the ability to approve the request to prove her employment to Proseware. Proseware can use the verifiable credentials service API or SDK, to verify the authenticity of the verifiable presentation. Based on the information provided by Alice they give Alice the discount. If other companies and organizations know that Woodgrove, Inc. issues VCs to their employees, they can also create a verifier solution and use the Woodgrove, Inc. verifiable credential to provide special offers reserved for Woodgrove, Inc. employees. ## Next steps diff --git a/articles/active-directory/verifiable-credentials/error-codes.md b/articles/active-directory/verifiable-credentials/error-codes.md new file mode 100644 index 0000000000000..16bc18e5d5635 --- /dev/null +++ b/articles/active-directory/verifiable-credentials/error-codes.md @@ -0,0 +1,151 @@ +--- +title: API Error codes reference +titleSuffix: Microsoft Entra Verified ID +description: Reference of error codes for Microsoft Entra Verified ID APIs +documentationCenter: '' +author: barclayn +manager: rkarlin +ms.service: decentralized-identity +ms.topic: reference +ms.subservice: verifiable-credentials +ms.date: 07/29/2022 +ms.author: barclayn + +#Customer intent: As an administrator, I am trying to learn how to use the Request Service API and integrate it into my business application. +--- + +# Request Service API error codes + +[!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] + +Microsoft Entra Verified ID includes the Request Service REST API that allows you to issue and verify a credential. This article specifies the error codes for the Request Service API. + +## Error object + +During public preview, the Request Service API returned errors in the following format. + +```json +{ + "requestId": "4bb6726f77af7623ab52962323016442", + "date": "Thu, 28 Apr 2022 14:30:54 GMT", + "mscv": "17ppwf3uxR10MfRR.1", + "error": { + "code": "client_request.invalid_include_qr_code", + "message": "The request contains `includeQRCode`, but it is not boolean." + } +} + +``` + +This format is now changed into the following to enable both simpler error handling and better support for troubleshooting. In the new format, the outer [error](#error-type) code and message fields have standardized values while the [```innererror```](#inner-error-type) object provide details on what caused the error. + +```json +{ + "requestId": "782628eb-503a-4978-84f2-d7c634f25b15", + "date": "Fri, 29 Apr 2022 11:20:19 GMT", + "mscv": "QbBLwF7XAp0dt4Lw.1", + "error": { + "code": "badRequest", + "message": "The request is invalid.", + "innererror": { + "code": "badOrMissingField", + "message": "The request contains `includeQRCode`, but it is not boolean.", + "target": "includeQRCode" + } + } +} +``` + +|Property |Type |Description | +|---------|---------|---------| +| `requestId`| string | An autogenerated request ID.| +| `date`| date| The time of the error. | +| `mscv`| string| Internal Microsoft code. | +| `error` | [Error](#error-type)| The outer error object | + +### Error type + +The `error` object is now matching the HTTP Status Code returned from the API Call to enable easier error handling for developers. + +|Property |Type |Description | +|---------|---------|---------| +| `code` | string| The return error code matching the HTTP Status Code. | +| `message`| string| A standardized error message that is also dependent on the HTTP status code returned. | +| `innererror` | [Innererror](#inner-error-type)| Provide details on what caused the error. | + + +### Error codes and messages + +The following are the possible top level `code` values that maps to the different HTTP status codes returned. + +|HTTP Status Code |code |message | +|---------|---------|---------| +| 400 | badRequest |The request is invalid.| +| 401 | unauthorized |The requested resource requires authentication| +| 403 | forbidden |Missing permissions to fulfill this request.| +| 404 | notFound |The requested resource doesn't exist.| +| 405 | methodNotAllowed |The requested method isn't allowed on the requested resource.| +| 406 | notAcceptable |Requested response format not supported.| +| 408 | requestTimeout |The request timed out.| +| 409 | conflict |The server can't fulfill the request due to a server conflict.| +| 410 | gone |The requested resource is no longer available.| +| 411 | contentLengthRequired |The Content-Length header is missing.| +| 412 | preconditionFailed |A precondition for this request failed.| +| 413 | payloadTooLarge |The payload is too large.| +| 414 | uriTooLong |The URI is too long.| +| 415 | unsupportedMediaType |The specified media type is unsupported.| +| 416 | rangeNotSatisfiable |The requested range of data requested can't be satisfied.| +| 417 | expectationFailed |The Expect header couldn't be satisfied.| +| 421 | misdirectedRequest |Unable to produce a response for this request.| +| 422 | unprocessableEntity |The request contains semantic errors.| +| 423 | locked |The source or destination resource is locked.| +| 429 | tooManyRequests |Too many requests, try again later.| +| 431 | requestHeaderFieldsTooLarge |The request header field is too large.| +| 500 | internalServerError |A generic error has occurred on the server.| +| 501 | notImplemented |The server doesn't support the requested function.| +| 502 | badGateway |bad response received from another gateway.| +| 503 | serviceUnavailable |The server is temporarily unavailable, please try again later.| +| 504 | gatewayTimeout |Time out received from another gateway.| +| 507 | insufficientStorage |Unable to save data for the request.| + +### Inner error type + +The inner error object contains error specific details useful to the developer to help investigate the current failure. + +```json +{ + "requestId": "782628eb-503a-4978-84f2-d7c634f25b15", + "date": "Fri, 29 Apr 2022 11:20:19 GMT", + "mscv": "QbBLwF7XAp0dt4Lw.1", + "error": { + "code": "badRequest", + "message": "The request is invalid.", + "innererror": { + "code": "badOrMissingField", + "message": "The request contains `includeQRCode`, but it is not boolean.", + "target": "includeQRCode" + } + } +} +``` + +|Property |Type |Description | +|---------|---------|---------| +| `code` | string| The internal error code. Contains a standardized code, based on the type of the error | +| `message`| string| The internal error message. Contains a detailed message of the error. In this example, the `inlcudeQRCode` field is of the wrong type.| +| `target` | string| Optional. Target contains the field in the request that is causing this error. This field is optional and may not be present, depending on the error type. | + + +### Inner error codes + +|Code|Description| +|-|-| +|`badOrMissingField`|returned when validation issues on the request occur. The `target` field contains the field in the request that is causing the issue.| +|`notFound`|returned when a resource the client is requesting isn't found. The `target` field contains the resource name/id that isn't found.| +|`tokenError`|returned for any validation issues on tokens like JWT and the likes. The `target` field contains the token name causing the issue, when applicable.| +|`transientError`|returned for all the cases where the client might be able to get a successful response if they retry the request at a later stage. A common example of when this code is returned is when an HTTP 429 code is returned back| + +## Next steps + +- [Issuance API specification](issuance-request-api.md) +- [Presentation API specification](presentation-request-api.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/get-started-request-api.md b/articles/active-directory/verifiable-credentials/get-started-request-api.md index bef36df8dca73..435c38695d7f3 100644 --- a/articles/active-directory/verifiable-credentials/get-started-request-api.md +++ b/articles/active-directory/verifiable-credentials/get-started-request-api.md @@ -17,7 +17,7 @@ ms.author: barclayn [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] -Azure Active Directory (Azure AD) Verifiable Credentials includes the Request Service REST API. This API allows you to issue and verify credentials. This article shows you how to start using the Request Service REST API. +Microsoft Entra Verified ID includes the Request Service REST API. This API allows you to issue and verify credentials. This article shows you how to start using the Request Service REST API. > [!IMPORTANT] > The Request Service REST API is currently in preview. This preview version is provided without a service level agreement, and you can occasionally expect breaking changes and deprecation of the API while in preview. The preview version of the API isn't recommended for production workloads. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). @@ -35,7 +35,14 @@ Use the [OAuth 2.0 client credentials grant flow](../../active-directory/develop # [HTTP](#tab/http) ```http -Refer to to the Microsoft Authentication Library (MSAL) documentation for more information on how to acquire tokens via HTTP. +POST /{tenant}/oauth2/v2.0/token HTTP/1.1 //Line breaks for clarity +Host: login.microsoftonline.com +Content-Type: application/x-www-form-urlencoded + +client_id=535fb089-9ff3-47b6-9bfb-4f1264799865 +&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default +&client_secret=sampleCredentia1s +&grant_type=client_credentials ``` # [C#](#tab/csharp) @@ -74,7 +81,7 @@ const msalConfig = { }; const cca = new msal.ConfidentialClientApplication(msalConfig); const msalClientCredentialRequest = { - scopes: ["bbb94529-53a3-4be5-a069-7eaf2712b826/.default"], + scopes: ["3db474b9-6a0c-4840-96ac-1fceb342124f/.default"], skipCache: false, }; module.exports.msalCca = cca; @@ -87,6 +94,41 @@ const result = await mainApp.msalCca.acquireTokenByClientCredential(mainApp.msal } ``` +# [Python](#tab/python) + +```python +# Initialize MSAL library by using the following code +msalCca = msal.ConfidentialClientApplication( config["azClientId"], + authority="https://login.microsoftonline.com/" + config["azTenantId"], + client_credential=config["azClientSecret"], + ) + +# Acquire an access token +accessToken = "" +result = msalCca.acquire_token_for_client( scopes="3db474b9-6a0c-4840-96ac-1fceb342124f/.default" ) +if "access_token" in result: + accessToken = result['access_token'] +``` + +# [Java](#tab/java) + +```java +// Initialize MSAL library by using the following code +ConfidentialClientApplication app = ConfidentialClientApplication.builder( + clientId, + ClientCredentialFactory.createFromSecret(clientSecret)) + .authority(authority) + .build(); + +// Acquire an access token +ClientCredentialParameters clientCredentialParam = ClientCredentialParameters.builder( + Collections.singleton(scope)) + .build(); +CompletableFuture future = app.acquireToken(clientCredentialParam); +IAuthenticationResult result = future.get(); +return result.accessToken(); +``` + --- In the preceding code, provide the following parameters: @@ -96,7 +138,7 @@ In the preceding code, provide the following parameters: | Authority | Required | The directory tenant the application plans to operate against. For example: `https://login.microsoftonline.com/{your-tenant}`. (Replace `your-tenant` with your [tenant ID or name](../fundamentals/active-directory-how-to-find-tenant.md).) | | Client ID | Required | The application ID that's assigned to your app. You can find this information in the Azure portal, where you registered your app. | | Client secret | Required | The client secret that you generated for your app.| -| Scopes | Required | Must be set to `bbb94529-53a3-4be5-a069-7eaf2712b826/.default`. | +| Scopes | Required | Must be set to `3db474b9-6a0c-4840-96ac-1fceb342124f/.default`. This will produce an access token with a **roles** claim of `VerifiableCredential.Create.All`. | For more information about how to get an access token by using a console app's identity, see one of the following articles: [C#](../develop/quickstart-v2-netcore-daemon.md), [Python](../develop/quickstart-v2-python-daemon.md), [Node.js](../develop/quickstart-v2-nodejs-console.md), or [Java](../develop/quickstart-v2-java-daemon.md). @@ -110,7 +152,7 @@ Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencoded client_id=12345678-0000-0000-00000000000000000 -&scope=bbb94529-53a3-4be5-a069-7eaf2712b826/.default +&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer &client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg &grant_type=client_credentials @@ -156,7 +198,7 @@ const msalConfig = { }; const cca = new msal.ConfidentialClientApplication(msalConfig); const msalClientCredentialRequest = { - scopes: ["bbb94529-53a3-4be5-a069-7eaf2712b826/.default"], + scopes: ["3db474b9-6a0c-4840-96ac-1fceb342124f/.default"], skipCache: false, }; module.exports.msalCca = cca; @@ -169,16 +211,69 @@ const result = await mainApp.msalCca.acquireTokenByClientCredential(mainApp.msal } ``` +# [Python](#tab/python) + +```python +# Initialize MSAL library by using the following code +with open(config["azCertificatePrivateKeyLocation"], "rb") as file: + private_key = file.read() +with open(config["azCertificateLocation"]) as file: + public_certificate = file.read() +cert = load_pem_x509_certificate(data=bytes(public_certificate, 'UTF-8'), backend=default_backend()) +thumbprint = (cert.fingerprint(hashes.SHA1()).hex()) +msalCca = msal.ConfidentialClientApplication( config["azClientId"], + authority="https://login.microsoftonline.com/" + config["azTenantId"], + client_credential={ + "private_key": private_key, + "thumbprint": thumbprint, + "public_certificate": public_certificate + } +) +# Acquire an access token +accessToken = "" +result = msalCca.acquire_token_for_client( scopes="3db474b9-6a0c-4840-96ac-1fceb342124f/.default" ) +if "access_token" in result: + accessToken = result['access_token'] +``` + +# [Java](#tab/java) + +```java +// Initialize MSAL library by using the following code +PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(Files.readAllBytes(Paths.get(certKeyLocation))); +PrivateKey key = KeyFactory.getInstance("RSA").generatePrivate(spec); +java.io.InputStream certStream = (java.io.InputStream)new ByteArrayInputStream(Files.readAllBytes(Paths.get(certLocation))); +X509Certificate cert = (X509Certificate) CertificateFactory.getInstance("X.509").generateCertificate(certStream); +ConfidentialClientApplication app = ConfidentialClientApplication.builder( + clientId, + ClientCredentialFactory.createFromCertificate(key, cert)) + .authority(authority) + .build(); +// Acquire an access token +ClientCredentialParameters clientCredentialParam = ClientCredentialParameters.builder( + Collections.singleton(scope)) + .build(); +CompletableFuture future = app.acquireToken(clientCredentialParam); +IAuthenticationResult result = future.get(); +return result.accessToken(); +``` + --- ## Call the API To issue or verify a verifiable credential, follow these steps: -1. Construct an HTTP POST request to the Request Service REST API. Replace the `{tenantID}` with your tenant ID, or your tenant name. +1. Construct an HTTP POST request to the Request Service REST API. The `tenantId` is not needed in the URL anymore as it is present as a claim in the `access_token`. + + **Issue** + ```http + POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest + ``` + **Verify** ```http - POST https://beta.did.msidentity.com/v1.0/{tenantID}/verifiablecredentials/request + POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest ``` 1. Attach the access token as a bearer token to the authorization header in an HTTP request. @@ -193,12 +288,14 @@ 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 a 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 + ## Issuance request example The following example demonstrates a verifiable credentials issuance request. For information about the payload, see [Request Service REST API issuance specification](issuance-request-api.md). ```http -POST https://beta.did.msidentity.com/v1.0/contoso.onmicrosoft.com/verifiablecredentials/request +POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest Content-Type: application/json Authorization: Bearer @@ -208,24 +305,22 @@ Authorization: Bearer "url": "https://www.contoso.com/api/issuer/issuanceCallback", "state": "de19cb6b-36c1-45fe-9409-909a51292a9c", "headers": { - "api-key": "OPTIONAL API-KEY for VERIFIER CALLBACK API" + "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS" } }, "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDek...", "registration": { "clientName": "Verifiable Credential Expert Sample" }, - "issuance": { - "type": "VerifiedCredentialExpert", - "manifest": "https://beta.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredential/contracts/VerifiedCredentialExpert1", - "pin": { - "value": "3539", - "length": 4 - }, - "claims": { - "given_name": "Megan", - "family_name": "Bowen" - } + "type": "VerifiedCredentialExpert", + "manifestUrl": "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredential/contracts/VerifiedCredentialExpert1", + "pin": { + "value": "3539", + "length": 4 + }, + "claims": { + "given_name": "Megan", + "family_name": "Bowen" } } ``` @@ -234,13 +329,15 @@ For the complete code, see one of the following code samples: - [C#](https://github.com/Azure-Samples/active-directory-verifiable-credentials-dotnet/blob/main/1-asp-net-core-api-idtokenhint/IssuerController.cs) - [Node.js](https://github.com/Azure-Samples/active-directory-verifiable-credentials-node/blob/main/1-node-api-idtokenhint/issuer.js) +- [Python](https://github.com/Azure-Samples/active-directory-verifiable-credentials-python/blob/main/1-python-api-idtokenhint/issuer.py) +- [Java](https://github.com/Azure-Samples/active-directory-verifiable-credentials-java/blob/main/1-java-api-idtokenhint/src/main/java/com/verifiablecredentials/javaaadvcapiidtokenhint/controller/IssuerController.java) ## Presentation request example The following example demonstrates a verifiable credentials presentation request. For information about the payload, see [Request Service REST API presentation specification](presentation-request-api.md). ```http -POST https://beta.did.msidentity.com/v1.0/contoso.onmicrosoft.com/verifiablecredentials/request +POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest Content-Type: application/json Authorization: Bearer @@ -250,25 +347,29 @@ Authorization: Bearer "url": "https://www.contoso.com/api/verifier/presentationCallback", "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58", "headers": { - "api-key": "OPTIONAL API-KEY for VERIFIER CALLBACK API" + "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS" } }, "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiOiJiRWo5MDY...", "registration": { "clientName": "Veritable Credential Expert Verifier" }, - "presentation": { - "includeReceipt": true, - "requestedCredentials": [ - { - "type": "VerifiedCredentialExpert", - "purpose": "So we can see that you a veritable credentials expert", - "acceptedIssuers": [ - "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..." - ] + "includeReceipt": true, + "requestedCredentials": [ + { + "type": "VerifiedCredentialExpert", + "purpose": "So we can see that you a veritable credentials expert", + "acceptedIssuers": [ + "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..." + ], + "configuration": { + "validation": { + "allowRevoked": true, + "validateLinkedDomain": true + } } - ] - } + } + ] } ``` @@ -276,10 +377,12 @@ For the complete code, see one of the following code samples: - [C#](https://github.com/Azure-Samples/active-directory-verifiable-credentials-dotnet/blob/main/1-asp-net-core-api-idtokenhint/VerifierController.cs) - [Node.js](https://github.com/Azure-Samples/active-directory-verifiable-credentials-node/blob/main/1-node-api-idtokenhint/verifier.js) +- [Python](https://github.com/Azure-Samples/active-directory-verifiable-credentials-python/blob/main/1-python-api-idtokenhint/verifier.py) +- [Java](https://github.com/Azure-Samples/active-directory-verifiable-credentials-java/blob/main/1-java-api-idtokenhint/src/main/java/com/verifiablecredentials/javaaadvcapiidtokenhint/controller/VerifierController.java) ## Callback events -The request payload contains the [issuance](issuance-request-api.md#callback-events) and [presentation](presentation-request-api.md#callback-events) callback endpoint. The endpoint is part of your web application, and should be publicly available. Azure AD Verifiable Credentials calls your endpoint to inform your app on certain events. For example, such events might be when a user scans the QR code, uses the deep link the authenticator app, or finishes the presentation process. +The request payload contains the [issuance](issuance-request-api.md#callback-events) and [presentation](presentation-request-api.md#callback-events) callback endpoint. The endpoint is part of your web application, and should be publicly available via the HTTPS protocol. The Request Service API calls your endpoint to inform your app on certain events. For example, such events might be when a user scans the QR code, uses the deep link the authenticator app, or finishes the presentation process. The following diagram describes the call your app makes to the Request Service REST API, and the callbacks to your application. @@ -351,6 +454,82 @@ mainApp.app.post('/api/issuer/issuance-request-callback', parser, async (req, re }) ``` +# [Python](#tab/python) + +```python +@app.route("/api/issuer/issuance-request-callback", methods = ['POST']) +def issuanceRequestApiCallback(): + if request.headers['api-key'] != apiKey: + return Response( jsonify({'error':'api-key wrong or missing'}), status=401, mimetype='application/json') + + issuanceResponse = request.json + if issuanceResponse["code"] == "request_retrieved": + cacheData = { + "status": issuanceResponse["code"], + "message": "QR Code is scanned. Waiting for issuance to complete..." + } + cache.set( issuanceResponse["state"], json.dumps(cacheData) ) + return "" + + if issuanceResponse["code"] == "issuance_successful": + cacheData = { + "status": issuanceResponse["code"], + "message": "Credential successfully issued" + } + cache.set( issuanceResponse["state"], json.dumps(cacheData) ) + return "" + + if issuanceResponse["code"] == "issuance_error": + cacheData = { + "status": issuanceResponse["code"], + "message": issuanceResponse["error"]["message"] + } + cache.set( issuanceResponse["state"], json.dumps(cacheData) ) + return "" + + return "" +``` + +# [Java](#tab/java) + +```java +@RequestMapping(value = "/api/issuer/issue-request-callback", method = RequestMethod.POST, produces = "application/json", consumes = "application/json") + public ResponseEntity issueRequestCallback( HttpServletRequest request + , @RequestHeader HttpHeaders headers + , @RequestBody String body ) { + ObjectMapper objectMapper = new ObjectMapper(); + try { + if ( !request.getHeader("api-key").equals(apiKey) ) { + lgr.info( "api-key wrong or missing" ); + return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body( "api-key wrong or missing" ); + } + JsonNode presentationResponse = objectMapper.readTree( body ); + String code = presentationResponse.path("code").asText(); + ObjectNode data = null; + if ( code.equals( "request_retrieved" ) ) { + data = objectMapper.createObjectNode(); + data.put("message", "QR Code is scanned. Waiting for issuance to complete..." ); + } + if ( code.equals("issuance_successful") ) { + data = objectMapper.createObjectNode(); + data.put("message", "Credential successfully issued" ); + } + if ( code.equals( "issuance_error" ) ) { + data = objectMapper.createObjectNode(); + data.put("message", presentationResponse.path("error").path("message").asText() ); + } + if ( data != null ) { + data.put("status", code ); + cache.put( presentationResponse.path("state").asText(), objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(data) ); + } + } catch (java.io.IOException ex) { + ex.printStackTrace(); + return ResponseEntity.status(HttpStatus.BAD_REQUEST).body( "Technical error" ); + } + return ResponseEntity.ok().body( "{}" ); + } +``` + For the complete code, see the [issuance](https://github.com/Azure-Samples/active-directory-verifiable-credentials-node/blob/main/1-node-api-idtokenhint/issuer.js) and [presentation](https://github.com/Azure-Samples/active-directory-verifiable-credentials-node/blob/main/1-node-api-idtokenhint/verifier.js) code on the GitHub repo. --- @@ -360,4 +539,4 @@ For the complete code, see the [issuance](https://github.com/Azure-Samples/activ Learn more about these specifications: - [Issuance API specification](issuance-request-api.md) -- [Presentation API specification](presentation-request-api.md) +- [Presentation API specification](presentation-request-api.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/how-to-dnsbind.md b/articles/active-directory/verifiable-credentials/how-to-dnsbind.md index 6e658055ba931..a8813032662aa 100644 --- a/articles/active-directory/verifiable-credentials/how-to-dnsbind.md +++ b/articles/active-directory/verifiable-credentials/how-to-dnsbind.md @@ -37,7 +37,7 @@ Linking a DID to a domain solves the initial trust problem by allowing any entit ## 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. You can update the domain in your DID directly from the Azure AD Verifiable Credential portal +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). ## How do we link DIDs and domains? @@ -132,7 +132,7 @@ Yes. You need to wait until the config.json file gets updated before you publish ### 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 Azure AD Verifiable Credentials 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 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. >[!IMPORTANT] > No changes to your domain are possible while publishing is in progress. diff --git a/articles/active-directory/verifiable-credentials/how-to-issuer-revoke.md b/articles/active-directory/verifiable-credentials/how-to-issuer-revoke.md index b7d6596a37ebf..fb2c40d046981 100644 --- a/articles/active-directory/verifiable-credentials/how-to-issuer-revoke.md +++ b/articles/active-directory/verifiable-credentials/how-to-issuer-revoke.md @@ -7,7 +7,7 @@ manager: rkarlin ms.service: decentralized-identity ms.topic: how-to ms.subservice: verifiable-credentials -ms.date: 06/03/2022 +ms.date: 07/28/2022 ms.author: barclayn #Customer intent: As an administrator, I am trying to learn the process of revoking verifiable credentials that I have issued @@ -17,123 +17,155 @@ ms.author: barclayn [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] -As part of the process of working with verifiable credentials (VCs), you not only have to issue credentials, but sometimes you also have to revoke them. In this article we go over the **Status** property part of the VC specification and take a closer look at the revocation process, why we may want to revoke credentials and some data and privacy implications. +As part of the process of working with verifiable credentials (VCs), you not only have to issue credentials, but sometimes you also have to revoke them. In this article, we go over the **Status** property part of the VC specification and take a closer look at the revocation process, why we may want to revoke credentials and some data and privacy implications. > [!IMPORTANT] -> Azure Active Directory Verifiable Credentials is currently in public preview. +> Microsoft Entra Verified ID 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. > For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). -## Status property in verifiable credentials specification - -Before we can understand the implications of revoking a verifiable credential, it may help to know what the **status check** is and how it works today. - -The [W3C Verifiable Credentials spec](https://www.w3.org/TR/vc-data-model/) references the **status** property in section [4.9:](https://www.w3.org/TR/vc-data-model/#status) - -"This specification defines the following **credentialStatus** property for the discovery of information about the current status of a verifiable credential, such as whether it is suspended or revoked." +## Why you may want to revoke a VC? -However, the W3C specification does not define a format on how **status check** should be implemented. +Each customer will have their own unique reason's for wanting to revoke a verifiable credential, but here are some of the common themes we've heard thus far. -"Defining the data model, formats, and protocols for status schemes are out of scope for this specification. A Verifiable Credential Extension Registry [VC-EXTENSION-REGISTRY] exists that contains available status schemes for implementers who want to implement verifiable credential status checking." +- Student ID: the student is no longer an active student at the University. +- Employee ID: the employee is no longer an active employee. +- State Drivers License: the driver no longer lives in that state. ->[!NOTE] ->For now, Microsoft's status check implementation is proprietary but we are actively working with the DID community to align on a standard. +## How do I revoke a verifiable credential -## How does the **status** property work? +Using the indexed claim in verifiable credentials, you can search for issued verifiable credentials by that claim in the portal and revoke it. -In every Microsoft issued verifiable credential, there is an attribute called credentialStatus. It's populated with a status API that Microsoft manages on your behalf. Here is an example of what it looks like. +1. Navigate to the verifiable credentials blade in Azure Active Directory. +1. Select the verifiable credential type +1. On the left-hand menu, choose **Revoke a credential** + ![Revoke a credential](media/how-to-issuer-revoke/settings-revoke.png) +1. Search for the index claim of the user you want to revoke. If you haven't indexed a claim, search won't work, and you won't be able to revoke the verifiable credential. -```json - "credentialStatus": { - "id": "https://portableidentitycards.azure-api.net/v1.0/7952032d-d1f3-4c65-993f-1112dab7e191/portableIdentities/card/status", - "type": "PortableIdentityCardServiceCredentialStatus2020" - } -``` + ![Screenshot of the credential to revoke](media/how-to-issuer-revoke/revoke-search.png) -The open source Verifiable Credentials SDK handles calling the status API and providing the necessary data. + >[!NOTE] + >Since we are only storing a hash of the indexed claim from the verifiable credential, only an exact match will populate the search results. We take the input as searched by the IT Admin and we use the same hashing algorithm to see if we have a hash match in our database. + +1. Once you've found a match, select the **Revoke** option to the right of the credential you want to revoke. -Once the API is called and provided the right information, the API will return either a True or False. True being the verifiable credential is still active with the Issuer and False signifying the verifiable credential has been actively revoked by the Issuer. + ![Screenshot of a warning letting you know that after revocation the user still has the credential](media/how-to-issuer-revoke/warning.png) -## Why you may want to revoke a VC? +1. After successful revocation, you see the status update and a green banner will appear at the top of the page. + + ![screenshot of a successfully revoked verifiable credential message](media/how-to-issuer-revoke/revoke-successful.png) -Each customer will have their own unique reason's for wanting to revoke a verifiable credential, but here are some of the common themes we have heard thus far. - -- Student ID: the student is no longer an active student at the University. -- Employee ID: the employee is no longer an active employee. -- State Drivers License: the driver no longer lives in that state. +Now whenever a presentation is sent to the Request Service API it will check if the VC has been revoked. ## How to set up a verifiable credential with the ability to revoke -All verifiable credential data is not stored with Microsoft by default. Therefore, we do not have any data to reference to revoke a specific verifiable credential ID. The issuer needs to specify a specific field from the verifiable credential attribute for Microsoft to index and subsequently salt and hash. +Verifiable credential data isn't stored by Microsoft. Therefore, the issuer needs to make one claim, the indexed claim, before the VC is searchable. There can be only one claim that is indexed and if there is none, you won't be able to revoke credentials. The selected claim to index is then salted and hashed and isn't stored as its original value. >[!NOTE] >Hashing is a one way cryptographic operation that turns an input, called a ```preimage```, and produces an output called a hash that has a fixed length. It is not computationally feasible at this time to reverse a hash operation. -You can tell Microsoft which attribute of the verifiable credential you would like to index. The implication of indexing is that indexed values may be used to search your verifiable credentials for the VCs you want to revoke. - -**Example:** Alice is a Woodgrove employee. Alice left Woodgrove to work at Contoso. Jane, the IT admin for Woodgrove, searches for Alice's email in the Verifiable Credentials Revoke search query. In this example, Jane, indexed the email field of the Woodgrove verified employee credential. - -See below for an example of how the Rules file is modified to include the index. +**Example:** In the below example, the displayName is the index claim and searching can be done via the users full name and nothing else. ```json { "attestations": { "idTokens": [ - { + { + "clientId": "8d5b446e-22b2-4e01-bb2e-9070f6b20c90", + "configuration": "https://didplayground.b2clogin.com/didplayground.onmicrosoft.com/B2C_1_sisu/v2.0/.well-known/openid-configuration", + "redirectUri": "vcclient://openid", + "scope": "openid profile email", "mapping": [ - { - "outputClaim": "Name", - "inputClaim": "name", - "required": true, - "indexed": false - }, - { - "outputClaim": "email", - "inputClaim": "email", - "required": true, - "indexed": true - } + { + "outputClaim": "displayName", + "required": true, + "inputClaim": "$.name", + "indexed": true + }, + { + "outputClaim": "firstName", + "required": true, + "inputClaim": "$.given_name", + "indexed": false + }, + { + "outputClaim": "lastName", + "required": true, + "inputClaim": "$.family_name", + "indexed": false + } ], - "configuration": "https://login.microsoftonline.com/tenant-id-here7/v2.0/.well-known/openid-configuration", - "client_id": "c0d6b785-7a08-494e-8f63-c30744c3be2f", - "redirect_uri": "vcclient://openid" + "required": false } ] }, - "validityInterval": 25920000, + "validityInterval": 2592000, "vc": { - "type": ["WoodgroveEmployee"] + "type": [ + "VerifiedCredentialExpert" + ] } } ``` >[!NOTE] ->Only one attribute can be indexed from a rules claims mapping. +>Only one claim can be indexed from a rules claims mapping. -## How do I revoke a verifiable credential -Once an index claim has been set and verifiable credentials have been issued to your users, it's time to see how you can revoke a verifiable credential in the VC blade. +## How does revocation work? -1. Navigate to the verifiable credentials blade in Azure Active Directory. -1. Choose the verifiable credential where you've previously set up the index claim and issued a verifiable credential to a user. = -1. On the left-hand menu, choose **Revoke a credential** - ![Revoke a credential](media/how-to-issuer-revoke/settings-revoke.png) -1. Search for the index attribute of the user you want to revoke. +Microsoft Entra Verified ID implements the [W3C StatusList2021](https://github.com/w3c-ccg/vc-status-list-2021/tree/343b8b59cddba4525e1ef355356ae760fc75904e). When presentation to the Request Service API happens, the API will do the revocation check for you. The revocation check happens over an anonymous API call to Identity Hub and does not contain any data who is checking if the verifiable credential is still valid or revoked. With the **statusList2021**, Microsoft Entra Verified ID just keeps a flag by the hashed value of the indexed claim to keep track of the revocation status. - ![Find the credential to revoke](media/how-to-issuer-revoke/revoke-search.png) +### Verifiable credential data - >[!NOTE] - >Since we are only storing a hash of the indexed claim from the verifiable credential, only an exact match will populate the search results. We take the input as searched by the IT Admin and we use the same hashing algorithm to see if we have a hash match in our database. - -1. Once you've found a match, select the **Revoke** option to the right of the credential you want to revoke. +In every Microsoft issued verifiable credential, there is a claim called `credentialStatus`. This data is a navigational map to where in a block of data this VC has its revocation flag. - ![A warning letting you know that after revocation the user still has the credential](media/how-to-issuer-revoke/warning.png) +```json +... +"credentialStatus": { + "id": "urn:uuid:625dfcad-0000-1111-2222-333444445555?bit-index=31", + "type": "RevocationList2021Status", + "statusListIndex": 31, + "statusListCredential": "did:ion:EiDR0Y6zfvnUy2NjO293XNfe9AOL......?service=IdentityHub&queries=...data..." +... +``` + +### Issuers Identity Hub API endpoint -1. After successful revocation you see the status update and a green banner will appear at the top of the page. - ![Verify this domain in settings](media/how-to-issuer-revoke/revoke-successful.png) +In the issuing party's DID document, the Identity Hub's endpoint is available in the `service` section. -Now whenever a relying party calls to check the status of this specific verifiable credential, Microsoft's status API, acting on behalf of the tenant, returns a 'false' response. +```json +didDocument": { + "id": "did:ion:EiD...", + "@context": [ + "https://www.w3.org/ns/did/v1", + { + "@base": "did:ion:EiD......" + } + ], + "service": [ + { + "id": "#linkeddomains", + "type": "LinkedDomains", + "serviceEndpoint": { + "origins": [ + "https://contoso.com/" + ] + } + }, + { + "id": "#hub", + "type": "IdentityHub", + "serviceEndpoint": { + "instances": [ + "https://verifiedid.hub.msidentity.com/v1.0/11111111-2222-3333-4444-000000000000" + ], + "origins": [ ] + } + } + ], +``` ## Next steps -Test out the functionality on your own with a test credential to get used to the flow. You can see information on how to configure your tenant to issue verifiable credentials by [reviewing our tutorials](get-started-verifiable-credentials.md). \ No newline at end of file +- [How to customize your Microsoft Entra Verified ID](credential-design.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/how-to-opt-out.md b/articles/active-directory/verifiable-credentials/how-to-opt-out.md index eea336e3e6cbf..2a27ad61cb423 100644 --- a/articles/active-directory/verifiable-credentials/how-to-opt-out.md +++ b/articles/active-directory/verifiable-credentials/how-to-opt-out.md @@ -1,5 +1,5 @@ --- -title: Opt out of the Azure Active Directory Verifiable Credentials (preview) +title: Opt out of the Microsoft Entra Verified ID (preview) description: Learn how to Opt Out of the Verifiable Credentials Preview documentationCenter: '' author: barclayn @@ -7,7 +7,7 @@ manager: rkarlin ms.service: decentralized-identity ms.topic: how-to ms.subservice: verifiable-credentials -ms.date: 06/16/2022 +ms.date: 06/02/2022 ms.author: barclayn #Customer intent: As an administrator, I am looking for information to help me disable @@ -25,7 +25,7 @@ In this article: - Effect on existing verifiable credentials. > [!IMPORTANT] -> Azure Active Directory Verifiable Credentials is currently in public preview. +> Microsoft Entra Verified ID 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. > For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). @@ -35,15 +35,15 @@ In this article: ## When do you need to opt out? -Opting out is a one-way operation, after you opt out your Azure Active Directory Verifiable Credentials environment will be reset. During the public preview, opting out may be required to: +Opting out is a one-way operation, after you opt-out your Microsoft Entra Verified ID environment will be reset. During the Public Preview opting out may be required to: - Enable new service capabilities. - Reset your service configuration. - Switch between trust systems ION and Web -## What happens to your data when you opt out? +## What happens to your data when you opt-out? -When you complete opting out of the Azure Active Directory Verifiable Credentials service, the following actions will take place: +When you complete opting out of the Microsoft Entra Verified ID service, the following actions will take place: - The DID keys in Key Vault will be [soft deleted](../../key-vault/general/soft-delete-overview.md). - The issuer object will be deleted from our database. @@ -55,9 +55,9 @@ Once an opt-out takes place, you won't be able to recover your DID or conduct an ## Effect on existing verifiable credentials All verifiable credentials already issued will continue to exist. They won't be cryptographically invalidated as your DID will remain resolvable through ION. -However, when relying parties call the status API, they'll always receive back a failure message. +However, when relying parties call the status API, they will always receive back a failure message. -## How to opt out from the Azure Active Directory Verifiable Credentials Public Preview? +## How to opt-out from the Microsoft Entra Verified ID Public Preview? 1. From the Azure portal search for verifiable credentials. 2. Choose **Organization Settings** from the left side menu. diff --git a/articles/active-directory/verifiable-credentials/how-to-register-didwebsite.md b/articles/active-directory/verifiable-credentials/how-to-register-didwebsite.md index e076803658099..589fa9297b91a 100644 --- a/articles/active-directory/verifiable-credentials/how-to-register-didwebsite.md +++ b/articles/active-directory/verifiable-credentials/how-to-register-didwebsite.md @@ -18,7 +18,7 @@ ms.author: barclayn [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] > [!IMPORTANT] -> Azure Active Directory Verifiable Credentials is currently in public preview. +> Microsoft Entra Verified ID 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. > For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). diff --git a/articles/active-directory/verifiable-credentials/how-to-use-quickstart-idtoken.md b/articles/active-directory/verifiable-credentials/how-to-use-quickstart-idtoken.md index d8def2eae1d89..56d903d125a96 100644 --- a/articles/active-directory/verifiable-credentials/how-to-use-quickstart-idtoken.md +++ b/articles/active-directory/verifiable-credentials/how-to-use-quickstart-idtoken.md @@ -233,4 +233,4 @@ After you've switched to the custom issue, you have access to a text box with a ## Next steps -See the [Rules and display definitions reference](rules-and-display-definitions-model.md). +See the [Rules and display definitions reference](rules-and-display-definitions-model.md). \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/how-to-use-quickstart-selfissued.md b/articles/active-directory/verifiable-credentials/how-to-use-quickstart-selfissued.md index 26633fb38e701..12fe2ec98b1ce 100644 --- a/articles/active-directory/verifiable-credentials/how-to-use-quickstart-selfissued.md +++ b/articles/active-directory/verifiable-credentials/how-to-use-quickstart-selfissued.md @@ -128,4 +128,4 @@ After you've switched to the custom issue, you have access to a text box with a ## Next steps -See the [Rules and display definitions reference](rules-and-display-definitions-model.md). +See the [Rules and display definitions reference](rules-and-display-definitions-model.md). \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/how-to-use-quickstart-verifiedemployee.md b/articles/active-directory/verifiable-credentials/how-to-use-quickstart-verifiedemployee.md index 0d90dc376ff87..56d84a2f61c8e 100644 --- a/articles/active-directory/verifiable-credentials/how-to-use-quickstart-verifiedemployee.md +++ b/articles/active-directory/verifiable-credentials/how-to-use-quickstart-verifiedemployee.md @@ -1,5 +1,5 @@ --- -title: Tutorial - Issue a Verifiable Credential for directory based claims +title: Tutorial - Issue a Microsoft Entra Verified ID credential for directory based claims description: In this tutorial, you learn how to issue verifiable credentials, from directory based claims, by using a sample app. ms.service: decentralized-identity ms.subservice: verifiable-credentials @@ -31,7 +31,7 @@ In this article, you learn how to: ## Prerequisites -- [Set up a tenant for Azure AD Verifiable Credentials](verifiable-credentials-configure-tenant.md). +- [Set up a tenant for Microsoft Entra Verified ID Credentials](verifiable-credentials-configure-tenant.md). - Complete the tutorial for [issuance](verifiable-credentials-configure-issuer.md) and [verification](verifiable-credentials-configure-verifier.md) of verifiable credentials. - A mobile phone with Microsoft Authenticator that can be used as the test user account. @@ -111,4 +111,4 @@ The configuration file depends on the sample in-use. ## Next steps -Learn [how to customize your verifiable credentials](credential-design.md). +Learn [how to customize your verifiable credentials](credential-design.md). \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/how-to-use-quickstart.md b/articles/active-directory/verifiable-credentials/how-to-use-quickstart.md index d1fe9a20057f4..1fce97e362485 100644 --- a/articles/active-directory/verifiable-credentials/how-to-use-quickstart.md +++ b/articles/active-directory/verifiable-credentials/how-to-use-quickstart.md @@ -135,4 +135,4 @@ After you've switched to the custom issue, you have access to a text box with a ## Next steps For more information, see: -- [Rules and display definitions reference](rules-and-display-definitions-model.md) +- [Rules and display definitions reference](rules-and-display-definitions-model.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/how-use-vcnetwork.md b/articles/active-directory/verifiable-credentials/how-use-vcnetwork.md new file mode 100644 index 0000000000000..f6a33a101b71d --- /dev/null +++ b/articles/active-directory/verifiable-credentials/how-use-vcnetwork.md @@ -0,0 +1,72 @@ +--- +title: How to use the Microsoft Entra Verified ID Network +description: In this article, you learn how to use the Microsoft Entra Verified ID Network to verify credentials +documentationCenter: '' +author: barclayn +manager: rkarlin +ms.service: decentralized-identity +ms.topic: how-to +ms.subservice: verifiable-credentials +ms.date: 07/28/2022 +ms.author: barclayn + +#Customer intent: As a verifiable credentials administrator, I want to configure verifying credentials from another party +--- + +# Verifying credentials using the Microsoft Entra Verified ID Network + +[!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] + +> [!IMPORTANT] +> Microsoft Entra Verified ID is currently in 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. +> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). + +## Prerequisites + +To use the Entra Verified ID Network, 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). + +## What is the Entra Verified ID Network? + +In our scenario, Proseware is a verifier. Woodgrove is the issuer. The verifier needs to know Woodgrove's issuer DID and the verifiable credential (VC) type that represents Woodgrove employees before it can create a presentation request for a verified credential for Woodgrove employees. The necessary information may come from some kind of manual exchange between the companies, this approach would be both a manual and a complex. The Entra Verified ID Network makes this process much easier. Woodgrove, as an issuer, can publish credential types to the Entra Verified ID Network and Proseware, as the verifier, can search for published credential types and schemas in the Entra Verified ID Network. Using this information, Woodgrove can create a [presentation request](presentation-request-api.md#presentation-request-payload) and easily invoke the Request Service API. + +![Diagram of Microsoft DID implementation overview](media/decentralized-identifier-overview/did-overview.png) + + +## How do I use the Entra Verified ID Network? + +1. In the start page of Microsoft Entra Verified ID in the Azure portal, you have a Quickstart named **Verification request**. Clicking on **start** will take you to a page where you can browse the Verifiable Credentials Network + + ![Screenshot of the Verified ID Network Quickstart](media/how-use-vcnetwork/vcnetwork-quickstart.png) + +1. When you select on the **Select first issuer**, a panel opens on the right side of the screen where you can search for issuers by their linked domains. So if you are looking for something from Woodgrove, you just type `woodgrove` in the search textbox. When you select an issuer in the list, the available credential types will show in the lower part labeled Step 2. Check the type you want to use and select the Add button to get back to the first screen. If the expected linked domain isn't in the list it means that the linked domain isn't verified yet. If the list of credentials is empty, it means that the issuer has verified the linked domain but haven't published any credential types yet. + + ![Screenshot of Verified ID Network Search and select](media/how-use-vcnetwork/vcnetwork-search-select.png) + +1. In the first screen we now have Woodgrove in the issuer list and the next step is to select the **Review** button. + + ![Verified ID Network list of isuers](media/how-use-vcnetwork/vcnetwork-issuer-list.png) + +1. The Review screen displays a skeleton presentation request JSON payload for the Request Service API. The important pieces of information are the DID inside the **acceptedIssuers** collection and the **type** value. This information is needed to create a presentation request. The request prompts the user for a credential of a certain type issued by a trusted organization. + + ![Verified ID Network issuers details](media/how-use-vcnetwork/vcnetwork-issuer-details.png) + +## How do I make my linked domain searchable? + +Linked domains that are verified will be searchable. Unverified domains won't be searchable. + +## How do I make my credential types visible in the list? + +Each credential type that is created has an attribute named `availableInVcDirectory` that makes it visible in the list. You can update this attribute to make the credential type visible or not. See [Admin API reference](admin-api.md#contract-type). + +## What is public when a credential type is made visible? + +When you make a credential type available in the Entra Verified ID Network, only the **issuing DID**, the credential **type** and its **schema** are made public. Important to note is that this information was already public before making it visible due to how decentralized identities work. Making the credential type visible is just making it searchable in the Entra Verified ID Network. + +## Next steps + +For more information, see: + +- [Learn how to verify Microsoft Entra Verified ID credentials](verifiable-credentials-configure-verifier.md). +- [Presentation API specification](presentation-request-api.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/index.yml b/articles/active-directory/verifiable-credentials/index.yml index 78e144a5780d9..2fea4c930606f 100644 --- a/articles/active-directory/verifiable-credentials/index.yml +++ b/articles/active-directory/verifiable-credentials/index.yml @@ -1,7 +1,7 @@ ### YamlMime:Landing title: Microsoft Entra Verified ID documentation (preview) -summary: Azure Active Directory Verifiable Credentials is now Microsoft Entra Verified ID and part of the Microsoft Entra family of products. We'll be updating our documentation in the next few months as we move toward general availability. +summary: Verifiable credentials help you build solutions that empower customers to manage their own data. metadata: author: barclayn @@ -9,7 +9,7 @@ metadata: manager: rkarlin ms.author: barclayn ms.collection: na - ms.date: 10/13/2021 + ms.date: 07/28/2022 ms.service: decentralized-identity ms.subservice: na ms.topic: landing-page @@ -23,7 +23,7 @@ landingContent: linkLists: - linkListType: overview links: - - text: Introduction to Azure Active Directory Verifiable Credentials + - text: Introduction to Microsoft Entra Verified ID url: decentralized-identifier-overview.md - linkListType: overview links: @@ -35,7 +35,7 @@ landingContent: url: https://www.youtube.com/watch?v=r20hCF9NbTo # Card - - title: Learn about the Azure Active Directory Verifiable Credentials Service + - title: Learn about the Microsoft Entra Verified ID Service linkLists: - linkListType: tutorial links: diff --git a/articles/active-directory/verifiable-credentials/introduction-to-verifiable-credentials-architecture.md b/articles/active-directory/verifiable-credentials/introduction-to-verifiable-credentials-architecture.md index fde4ca5991a1e..727b3db11a954 100644 --- a/articles/active-directory/verifiable-credentials/introduction-to-verifiable-credentials-architecture.md +++ b/articles/active-directory/verifiable-credentials/introduction-to-verifiable-credentials-architecture.md @@ -7,20 +7,20 @@ manager: martinco ms.service: decentralized-identity ms.topic: how-to ms.subservice: verifiable-credentials -ms.date: 06/02/2022 +ms.date: 07/19/2022 ms.author: barclayn --- -# Azure AD Verifiable Credentials architecture overview (preview) +# Microsoft Entra Verified ID architecture overview (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] > [!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. For more information, see [**Supplemental Terms of Use for Microsoft Azure Previews**](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). +> Microsoft Entra Verified ID 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. For more information, see [**Supplemental Terms of Use for Microsoft Azure Previews**](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). -It’s important to plan your verifiable credential solution so that in addition to issuing and or validating credentials, you have a complete view of the architectural and business impacts of your solution. If you haven’t reviewed them already, we recommend you review [Introduction to Azure Active Directory Verifiable Credentials](decentralized-identifier-overview.md) and the [FAQs](verifiable-credentials-faq.md), and then complete the [Getting Started](get-started-verifiable-credentials.md) tutorial. +It’s important to plan your verifiable credential solution so that in addition to issuing and or validating credentials, you have a complete view of the architectural and business impacts of your solution. If you haven’t reviewed them already, we recommend you review [Introduction to Microsoft Entra Verified ID](decentralized-identifier-overview.md) and the [FAQs](verifiable-credentials-faq.md), and then complete the [Getting Started](get-started-verifiable-credentials.md) tutorial. -This architectural overview introduces the capabilities and components of the Azure Active Directory Verifiable Credentials service. For more detailed information on issuance and validation, see +This architectural overview introduces the capabilities and components of the Microsoft Entra Verified ID service. For more detailed information on issuance and validation, see * [Plan your issuance solution](plan-issuance-solution.md) @@ -76,7 +76,7 @@ Terminology for verifiable credentials (VCs) might be confusing if you're not fa “A ***decentralized identifier*** is a portable URI-based identifier, also known as a DID, associated with an entity. These identifiers are often used in a verifiable credential and are associated with subjects, issuers, and verifiers.”. -* In the preceding diagram, the public keys of the actor’s DIDs are shown stored in the decentralized ledger (ION).- in the decentralized identifier document. +* In the preceding diagram, the public keys of the actor’s DIDs are made available via trust system (Web or ION). “A ***decentralized identifier document***, also referred to as a ***DID document***, is a document that is accessible using a verifiable data registry and contains information related to a specific decentralized identifier, such as the associated repository and public key information.” @@ -84,6 +84,8 @@ Terminology for verifiable credentials (VCs) might be confusing if you're not fa * Woodgrove (issuer) signs their employees’ VCs with its public key; similarly, Proseware (verifier) signs requests to present a VC using its key, which is also associated with its DID. +A ***trust system*** is the foundation in establishing trust between decentralized systems. It can be a distributed ledger or it can be something centralized, such as [DID Web](https://w3c-ccg.github.io/did-method-web/). + “A ***distributed ledger*** is a non-centralized system for recording events. These systems establish sufficient confidence for participants to rely upon the data recorded by others to make operational decisions. They typically use distributed databases where different nodes use a consensus protocol to confirm the ordering of cryptographically signed transactions. The linking of digitally signed transactions over time often makes the history of the ledger effectively immutable.” * The Microsoft solution uses the ***Identity Overlay Network (ION)*** to provide decentralized public key infrastructure (PKI) capability. As an alternative to ION, Microsoft also offers DID Web as the trust system. @@ -192,11 +194,11 @@ With decentralized identifiers, Woodgrove can provide Alice with a verifiable cr -By providing Alice the VC, Woodgrove is attesting that Alice is an employee. Woodgrove is a trusted VC issuer in Proseware’s validation solution. This trust in Woodgrove’s issuance process allows Proseware to electronically accept the VC as proof that Alice is a Woodgrove employee and provide Alice the discount. As part of validation of the VC Alice presents, Proseware checks the validity of the VC by using the distributed ledger. In this solution: +By providing Alice the VC, Woodgrove is attesting that Alice is an employee. Woodgrove is a trusted VC issuer in Proseware’s validation solution. This trust in Woodgrove’s issuance process allows Proseware to electronically accept the VC as proof that Alice is a Woodgrove employee and provide Alice the discount. As part of validation of the VC Alice presents, Proseware checks the validity of the VC by using the trust system. In this solution: * Woodgrove enables Alice to provide Proseware proof of employment without Woodgrove having to extend its trust boundary. -* Proseware doesn’t need to expand their trust boundary to validate Alice is an employee of Woodgrove. Proseware can use the VC that Woodgrove provides instead. Because the trust boundary isn’t expanded, managing the trust relationship is easier and Proseware can easily end the relationship by not accepting the VCs anymore. +* Proseware doesn’t need to expand their trust boundary to validate Alice is an employee of Woodgrove. Proseware can use the VC that Woodgrove provides instead. Because the trust boundary isn’t expanded, managing the trust relationship is easier, and Proseware can easily end the relationship by not accepting the VCs anymore. * Alice doesn’t need to provide Proseware personal information, such as an email. Alice maintains the VC in a wallet application on a personal device. The only person that can use the VC is Alice, and Alice must initiate usage of the credential. Each usage of the VC is recorded by the wallet application, so Alice has a record of when and where the VC is used. @@ -214,9 +216,9 @@ By combining centralized and decentralized identity architectures, the responsib ## How decentralized identity systems work -In decentralized identity architectures, the issuer, user, and relying party (RP) each have a role in establishing and ensuring ongoing trusted exchange of each other’s credentials. The public keys of the actors’ DIDs are resolvable in ION, which allows signature validation and therefore trust of any artifact, including a verifiable credential. Relying parties can consume verifiable credentials without establishing trust relationships with the issuer. Instead, the issuer provides the subject a credential to present as proof to relying parties. All messages between actors are signed with the actor’s DID; DIDs from issuers and verifiers also need to own the DNS domains that generated the requests. +In decentralized identity architectures, the issuer, user, and relying party (RP) each have a role in establishing and ensuring ongoing trusted exchange of each other’s credentials. The public keys of the actors’ DIDs are resolvable via the trust system, which allows signature validation and therefore trust of any artifact, including a verifiable credential. Relying parties can consume verifiable credentials without establishing trust relationships with the issuer. Instead, the issuer provides the subject a credential to present as proof to relying parties. All messages between actors are signed with the actor’s DID; DIDs from issuers and verifiers also need to own the DNS domains that generated the requests. -For example: When VC holders need to access a resource, they must present the VC to that relying party. They do so by using a wallet application to read the RP’s request to present a VC. As a part of reading the request, the wallet application uses the RP’s DID to find the RPs public keys using ION, validating that the request to present the VC hasn't been tampered with. The wallet also checks that the DID is referenced in a metadata document hosted in the DNS domain of the RP, to prove domain ownership. +For example: When VC holders need to access a resource, they must present the VC to that relying party. They do so by using a wallet application to read the RP’s request to present a VC. As a part of reading the request, the wallet application uses the RP’s DID to find the RPs public keys using the trust system, validating that the request to present the VC hasn't been tampered with. The wallet also checks that the DID is referenced in a metadata document hosted in the DNS domain of the RP, to prove domain ownership. ![How a decentralized identity system works](media/introduction-to-verifiable-credentials-architecture/how-decentralized-works.png) @@ -229,7 +231,7 @@ In this flow, the credential holder interacts with the issuer to request a verif 1. The holder starts the flow by using a browser or native application to access the issuer’s web frontend. There, the issuer website drives the user to collect data and executes issuer-specific logic to determine whether the credential can be issued, and its content.) -1. The issuer web frontend calls the Azure AD VC Service to generate a VC issuance request. +1. The issuer web frontend calls the Entra Verified ID service to generate a VC issuance request. 1. The web frontend renders a link to the request as a QR code or a device-specific deep link (depending on the device). @@ -237,7 +239,7 @@ In this flow, the credential holder interacts with the issuer to request a verif 1. The wallet downloads the request from the link. The request includes: - * DID of the issuer. This is used by the wallet app to resolve in ION to find the public keys and linked domains. + * DID of the issuer. This is used by the wallet app to resolve via the trust system to find the public keys and linked domains. * URL with the VC manifest, which specifies the contract requirements to issue the VC. This can include id_token, self-attested attributes that must be provided, or the presentation of another VC. @@ -245,15 +247,15 @@ In this flow, the credential holder interacts with the issuer to request a verif 1. The wallet validates the issuance requests and processes the contract requirements: - 1. Validates that the issuance request message is signed by the issuer’ keys found in the DID document resolved in ION. This ensures that the message hasn't been tampered with. + 1. Validates that the issuance request message is signed by the issuer’ keys found in the DID document resolved via the trust system. This ensures that the message hasn't been tampered with. 1. Validates that the DNS domain referenced in the issuer’s DID document is owned by the issuer. 1. Depending on the VC contract requirements, the wallet might require the holder to collect additional information, for example asking for self-issued attributes, or navigating through an OIDC flow to obtain an id_token. -1. Submits the artifacts required by the contract to the Azure AD VC Service. The Azure AD VC service returns the VC, signed with the issuer’s DID key and the wallet securely stores the VC. +1. Submits the artifacts required by the contract to the Entra Verified ID service. The Entra Verified ID service returns the VC, signed with the issuer’s DID key and the wallet securely stores the VC. -For detailed information on how to build an issuance solution and architectural considerations, see [Plan your Azure Active Directory Verifiable Credentials issuance solution](plan-issuance-solution.md). +For detailed information on how to build an issuance solution and architectural considerations, see [Plan your Microsoft Entra Verified ID issuance solution](plan-issuance-solution.md). ### Flow 2: Verifiable credential presentation @@ -263,7 +265,7 @@ In this flow, a holder interacts with a relying party (RP) to present a VC as pa 1. The holder starts the flow by using a browser or native application to access the relying party’s web frontend. -1. The web frontend calls the Azure AD VC Service to generate a VC presentation request. +1. The web frontend calls the Entra Verified ID service to generate a VC presentation request. 1. The web frontend renders a link to the request as a QR code or a device-specific deep link (depending on the device). @@ -273,14 +275,14 @@ In this flow, a holder interacts with a relying party (RP) to present a VC as pa * a [standards based request for credentials](https://identity.foundation/presentation-exchange/) of a schema or credential type. - * the DID of the RP, which the wallet looks up in ION. + * the DID of the RP, which the wallet looks up in the trust system. 1. The wallet validates that the presentation request and finds stored VC(s) that satisfy the request. Based on the required VCs, the wallet guides the subject to select and consent to use the VCs. * After the subject consents to use of the VC, the wallet generates a unique pairwise DID between the subject and the RP. - Then, the wallet sends a presentation response payload to the Azure AD VC Service signed by the subject. It contains: + Then, the wallet sends a presentation response payload to the Entra Verified ID service signed by the subject. It contains: * The VC(s) the subject consented to. @@ -288,11 +290,11 @@ In this flow, a holder interacts with a relying party (RP) to present a VC as pa * The RP DID as the “audience” of the payload. -1. The Azure AD VC service validates the response sent by the wallet. Depending on how the original presentation request was created in step 2, this validation can include checking the status of the presented VC with the VC issuer for cases such as revocation. +1. The Entra Verified ID service validates the response sent by the wallet. Depending on how the original presentation request was created in step 2, this validation can include checking the status of the presented VC with the VC issuer for cases such as revocation. -1. Upon validation, the Azure AD VC service calls back the RP with the result. +1. Upon validation, the Entra Verified ID service calls back the RP with the result. -For detailed information on how to build a validation solution and architectural considerations, see [Plan your Azure Active Directory Verifiable Credentials verification solution](plan-verification-solution.md). +For detailed information on how to build a validation solution and architectural considerations, see [Plan your Microsoft Entra Verified ID verification solution](plan-verification-solution.md). ## Key Takeaways @@ -302,7 +304,7 @@ To deliver on the aspirations of the [Decentralized Identity Foundation](https:/ * There are no central points of trust establishment between actors in the system. That is, trust boundaries aren't expanded through federation because actors trust specific VCs. - * ION enables the discovery of any actor’s decentralized identifier (DID). + * The trust system enables the discovery of any actor’s decentralized identifier (DID). * The solution enables verifiers to validate any verifiable credentials (VCs) from any issuer. @@ -324,4 +326,4 @@ Learn more about architecture for verifiable credentials * [Plan your verification solution](plan-verification-solution.md) -* [Get started with Azure Active Directory Verifiable Credentials](get-started-verifiable-credentials.md) +* [Get started with Microsoft Entra Verified ID](verifiable-credentials-configure-tenant.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/issuance-request-api.md b/articles/active-directory/verifiable-credentials/issuance-request-api.md index 399d83afcf013..fe605465ce208 100644 --- a/articles/active-directory/verifiable-credentials/issuance-request-api.md +++ b/articles/active-directory/verifiable-credentials/issuance-request-api.md @@ -1,5 +1,6 @@ --- title: Specify the Request Service REST API issuance request (preview) +titleSuffix: Microsoft Entra Verified ID description: Learn how to issue a verifiable credential that you've issued. documentationCenter: '' author: barclayn @@ -7,17 +8,17 @@ manager: rkarlin ms.service: decentralized-identity ms.topic: reference ms.subservice: verifiable-credentials -ms.date: 10/08/2021 +ms.date: 07/19/2022 ms.author: barclayn -#Customer intent: As an administrator, I am trying to learn the process of revoking verifiable credentials that I have issued. +#Customer intent: As an administrator, I am trying to learn how to use the Request Service API and integrate it into my business application. --- # Request Service REST API issuance specification (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] -Azure Active Directory (Azure AD) Verifiable Credentials includes the Request Service REST API. This API allows you to issue and verify a credential. This article specifies the Request Service REST API for an issuance request. +Microsoft Entra Verified ID includes the Request Service REST API. This API allows you to issue and verify a credential. This article specifies the Request Service REST API for an issuance request. Another article describes [how to call the Request Service REST API](get-started-request-api.md). ## HTTP request @@ -37,25 +38,25 @@ The Request Service REST API issuance request requires the following HTTP header Construct an HTTP POST request to the Request Service REST API. Replace the `{tenantID}` with your tenant ID or tenant name. ```http -https://beta.did.msidentity.com/v1.0/{tenantID}/verifiablecredentials/request +https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest ``` The following HTTP request demonstrates a request to the Request Service REST API: ```http -POST https://beta.did.msidentity.com/v1.0/contoso.onmicrosoft.com/verifiablecredentials/request +POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest Content-Type: application/json Authorization: Bearer { "includeQRCode": true, - "callback": { - "url": "https://wwww.contoso.com/vc/callback", - "state": "Aaaabbbb11112222", - "headers": { - "api-key": "an-api-key-can-go-here" -      } - }, + "callback": { + "url": "https://wwww.contoso.com/vc/callback", + "state": "Aaaabbbb11112222", + "headers": { + "api-key": "an-api-key-can-go-here" +   } + }, ... } ``` @@ -64,7 +65,7 @@ The following permission is required to call the Request Service REST API. For m | Permission type | Permission | |---------|---------| -| Application | bbb94529-53a3-4be5-a069-7eaf2712b826/.default| +| Application | 3db474b9-6a0c-4840-96ac-1fceb342124f/.default| ## Issuance request payload @@ -72,30 +73,28 @@ The issuance request payload contains information about your verifiable credenti ```json { - "includeQRCode": true, - "callback": { - "url": "https://www.contoso.com/api/issuer/issuanceCallback", - "state": "de19cb6b-36c1-45fe-9409-909a51292a9c", - "headers": { - "api-key": "OPTIONAL API-KEY for VERIFIER CALLBACK API" - } - }, - "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDek...", - "registration": { - "clientName": "Verifiable Credential Expert Sample" - }, - "issuance": { - "type": "VerifiedCredentialExpert", - "manifest": "https://beta.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredential/contracts/VerifiedCredentialExpert", - "pin": { - "value": "3539", - "length": 4 - }, - "claims": { - "given_name": "Megan", - "family_name": "Bowen" - } + "includeQRCode": true, + "callback": { + "url": "https://www.contoso.com/api/issuer/issuanceCallback", + "state": "de19cb6b-36c1-45fe-9409-909a51292a9c", + "headers": { + "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS" } + }, + "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDek...", + "registration": { + "clientName": "Verifiable Credential Expert Sample" + }, + "type": "VerifiedCredentialExpert", + "manifest": "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredential/contracts/VerifiedCredentialExpert", + "claims": { + "given_name": "Megan", + "family_name": "Bowen" + }, + "pin": { + "value": "3539", + "length": 4 + } } ``` @@ -104,10 +103,22 @@ The payload contains the following properties: |Parameter |Type | Description | |---------|---------|---------| | `includeQRCode` | Boolean | Determines whether a QR code is included in the response of this request. Present the QR code and ask the user to scan it. Scanning the QR code launches the authenticator app with this issuance request. Possible values are `true` (default) or `false`. When you set the value to `false`, use the return `url` property to render a deep link. | +|`callback`| [Callback](#callback-type)| Mandatory. Allows the developer to asynchronously get information on the flow during the verifiable credential issuance process. For example, the developer might want a call when the user has scanned the QR code or if the issuance request succeeds or fails.| | `authority` | string| The issuer's decentralized identifier (DID). For more information, see [Gather credentials and environment details to set up your sample application](verifiable-credentials-configure-issuer.md).| | `registration` | [RequestRegistration](#requestregistration-type)| Provides information about the issuer that can be displayed in the authenticator app. | -| `issuance` | [RequestIssuance](#requestissuance-type)| Provides information about the issuance request. | -|`callback`| [Callback](#callback-type)| Mandatory. Allows the developer to asynchronously get information on the flow during the verifiable credential issuance process. For example, the developer might want a call when the user has scanned the QR code or if the issuance request succeeds or fails.| +| `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. | + +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: + +- ID token +- ID token hint +- Verifiable credentials via a verifiable presentation +- Self-attested claims + +You can find detailed information about the input types in [Customizing your verifiable credential](credential-design.md). ### RequestRegistration type @@ -122,26 +133,17 @@ The `RequestRegistration` type provides information registration for the issuer. > [!NOTE] > At this time, the `RequestRegistration` information isn't presented during the issuance in the Microsoft Authenticator app. This information can, however, be used in the payload. -### RequestIssuance type - -The `RequestIssuance` type provides information required for verifiable credential issuance. There are currently three input types that you can send in `RequestIssuance`. Azure AD Verifiable Credentials uses these types to insert claims into a verifiable credential, and attest to that information with the issuer's DID. The following are the three types: - -- ID token -- Verifiable credentials via a verifiable presentation -- Self-attested claims - -You can find detailed information about the input types in [Customizing your verifiable credential](credential-design.md). +### Callback type -The `RequestIssuance` type contains the following properties: +The Request Service REST API generates several events to the callback endpoint. Those events allow you to update the UI and continue the process after the results are returned to the application. The `Callback` type contains the following properties: |Property |Type |Description | |---------|---------|---------| -| `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. 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. | +| `url` | string| URI to the callback endpoint of your application. The URI must point to a reachable endpoint on the internet otherwise the service will throw callback URL unreadable error. Accepted formats IPv4, IPv6 or DNS resolvable hostname | +| `state` | string| Correlates the callback event with the state passed in the original payload. | +| `headers` | string| Optional. You can include a collection of HTTP headers required by the receiving end of the POST message. The current supported header values are the `api-key` or the `Authorization` headers. Any other header will throw an invalid callback header error| -### pin type +### Pin type The `pin` type defines a PIN code that can be displayed as part of the issuance. `pin` is optional, and, if used, should always be sent out-of-band. When you're using a HASH PIN code, you must define the `salt`, `alg`, and `iterations` properties. `pin` contains the following properties: @@ -154,24 +156,14 @@ The `pin` type defines a PIN code that can be displayed as part of the issuance. | `alg` | string| The hashing algorithm for the hashed PIN. Supported algorithm: `sha256`. | | `iterations` | integer| The number of hashing iterations. Possible value: `1`.| -### Callback type - -The Request Service REST API generates several events to the callback endpoint. Those events allow you to update the UI and continue the process after the results are returned to the application. The `Callback` type contains the following properties: - -|Property |Type |Description | -|---------|---------|---------| -| `url` | string| URI to the callback endpoint of your application. The URI must point to a reachable endpoint on the internet otherwise the service will throw callback URL unreadable error. Accepted formats IPv4, IPv6 or DNS resolvable hostname | -| `state` | string| Associates with the state passed in the original payload. | -| `headers` | string| Optional. You can include a collection of HTTP headers required by the receiving end of the POST message. The current supported header values are the `api-key` or the `Authorization` headers. Any other header will throw an invalid callback header error| - ## Successful response If successful, this method returns a response code (*HTTP 201 Created*), and a collection of event objects in the response body. The following JSON demonstrates a successful response: ```json { - "requestId": :"799f23ea-5241-45af-99ad-cf8e5018814e", - "url": "openid://vc?request_uri=https://beta.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiablecredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e", + "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e", + "url": "openid://vc?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/178319f7-20be-4945-80fb-7d52d47ae82e", "expiry": 1622227690, "qrCode": "data:image/png;base64,iVBORw0KggoA" } @@ -181,7 +173,7 @@ The response contains the following properties: |Property |Type |Description | |---------|---------|---------| -| `requestId`| string | An autogenerated correlation ID. The [callback](#callback-events) uses the same request, allowing you to keep track of the issuance request and its callbacks. | +| `requestId`| string | An autogenerated request ID. The [callback](#callback-events) uses the same request, allowing you to keep track of the issuance request and its callbacks. | | `url`| string| A URL that launches the authenticator app and starts the issuance process. You can present this URL to the user if they can't scan the QR code. | | `expiry`| integer| Indicates when the response will expire. | | `qrCode`| string | A QR code that user can scan to start the issuance flow. | @@ -190,28 +182,7 @@ When your app receives the response, the app needs to present the QR code to the ## Error response -Error responses also can be returned so that the app can handle them appropriately. The following JSON shows an unauthorized error message: - - -```json -{ - "requestId": "d60b068e7fbd975896e179b99347866a", - "date": "Wed, 29 Sep 2021 21:49:00 GMT", - "error": { - "code": "unauthorized", - "message": "Failed to authenticate the request." - } -} -``` - -The response contains the following properties: - -|Property |Type |Description | -|---------|---------|---------| -| `requestId`| string | An autogenerated request ID.| -| `date`| date| The time of the error. | -| `error.code` | string| The return error code. | -| `error.message`| string| The error message. | +If there is an error with the request, an [error responses](error-codes.md) will be returned and should be handled appropriately by the app. ## Callback events @@ -220,7 +191,7 @@ The callback endpoint is called when a user scans the QR code, uses the deep lin |Property |Type |Description | |---------|---------|---------| | `requestId`| string | Mapped to the original request when the payload was posted to the Verifiable Credentials service.| -| `code` |string |The code returned when the request has an error. Possible values:
  • `request_retrieved`: The user scanned the QR code or selected the link that starts the issuance flow.
  • `issuance_successful`: The issuance of the verifiable credentials was successful.
  • `Issuance_error`: There was an error during issuance. For details, see the `error` property.
| +| `code` |string |The code returned when the request has an error. Possible values:
  • `request_retrieved`: The user scanned the QR code or selected the link that starts the issuance flow.
  • `issuance_successful`: The issuance of the verifiable credentials was successful.
  • `issuance_error`: There was an error during issuance. For details, see the `error` property.
| | `state` |string| Returns the state value that you passed in the original payload. | | `error`| error | When the `code` property value is `Issuance_error`, this property contains information about the error.| | `error.code` | string| The return error code. | @@ -230,9 +201,9 @@ The following example demonstrates a callback payload when the authenticator app ```json { -    "requestId":"aef2133ba45886ce2c38974339ba1057", +    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",     "code":"request_retrieved", -    "state":"Wy0ThUz1gSasAjS1" +    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c" } ``` @@ -240,9 +211,9 @@ The following example demonstrates a callback payload after the user successfull ```json { -    "requestId":"87e1cb24-9096-409f-81cb-9e645f23a4ba", +    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",     "code":"issuance_successful", -    "state":"f3d94e35-ca5f-4b1b-a7d7-a88caa05e322", +    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c" }  ``` @@ -252,7 +223,7 @@ The callback endpoint might be called with an error message. The following table |Message |Definition  | |---------|---------| -| `fetch_contract_error*`| Unable to fetch the verifiable credential contract. This error usually happens when the API can't fetch the manifest you specify in the request payload [RequestIssuance object](#requestissuance-type).| +| `fetch_contract_error*`| Unable to fetch the verifiable credential contract. This error usually happens when the API can't fetch the manifest you specify in the request payload [RequestIssuance object](#issuance-request-payload).| | `issuance_service_error*` | The Verifiable Credentials service isn't able to validate requirements, or something went wrong in Verifiable Credentials.| | `unspecified_error`| This error is uncommon, but worth investigating. | @@ -260,9 +231,9 @@ The following example demonstrates a callback payload when an error occurred: ```json { -    "requestId":"87e1cb24-9096-409f-81cb-9e645f23a4ba", +    "requestId": "799f23ea-5241-45af-99ad-cf8e5018814e",     "code": "issuance_error", -    "state":"f3d94e35-ca5f-4b1b-a7d7-a88caa05e322", +    "state": "de19cb6b-36c1-45fe-9409-909a51292a9c", "error": { "code":"IssuanceFlowFailed", "message":"issuance_service_error”, diff --git a/articles/active-directory/verifiable-credentials/issuer-openid.md b/articles/active-directory/verifiable-credentials/issuer-openid.md index c4f7384130cfa..aa1171d8cdf70 100644 --- a/articles/active-directory/verifiable-credentials/issuer-openid.md +++ b/articles/active-directory/verifiable-credentials/issuer-openid.md @@ -17,7 +17,7 @@ ms.author: barclayn [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] -The Azure AD Verifiable Credential service can issue verifiable credentials by retrieving claims from an ID token generated by your organization's OpenID compliant identity provider. This article instructs you on how to set up your identity provider so Authenticator can communicate with it and retrieve the correct ID Token to pass to the issuing service. +The Microsoft Entra Verified ID service can issue verifiable credentials by retrieving claims from an ID token generated by your organization's OpenID compliant identity provider. This article instructs you on how to set up your identity provider so Authenticator can communicate with it and retrieve the correct ID Token to pass to the issuing service. > [!IMPORTANT] > Azure Active Directory Verifiable Credentials is currently in public preview. @@ -144,4 +144,4 @@ The ID token must use the JWT compact serialization format, and must not be encr ## Next steps -- [How to customize your Azure Active Directory Verifiable Credentials](credential-design.md) +- [How to customize your Azure Active Directory Verifiable Credentials](credential-design.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/media/decentralized-identifier-overview/did-overview.png b/articles/active-directory/verifiable-credentials/media/decentralized-identifier-overview/did-overview.png index 5c880ecd4672f..40a1a892c76e9 100644 Binary files a/articles/active-directory/verifiable-credentials/media/decentralized-identifier-overview/did-overview.png and b/articles/active-directory/verifiable-credentials/media/decentralized-identifier-overview/did-overview.png differ diff --git a/articles/active-directory/verifiable-credentials/media/decentralized-identifier-overview/microsoft-did-system.png b/articles/active-directory/verifiable-credentials/media/decentralized-identifier-overview/microsoft-did-system.png index ca1c4a10a0e40..7ac048318474f 100644 Binary files a/articles/active-directory/verifiable-credentials/media/decentralized-identifier-overview/microsoft-did-system.png and b/articles/active-directory/verifiable-credentials/media/decentralized-identifier-overview/microsoft-did-system.png differ diff --git a/articles/active-directory/verifiable-credentials/media/how-to-issuer-revoke/settings-revoke.png b/articles/active-directory/verifiable-credentials/media/how-to-issuer-revoke/settings-revoke.png index 7efa45f245114..e994bedcbf0a5 100644 Binary files a/articles/active-directory/verifiable-credentials/media/how-to-issuer-revoke/settings-revoke.png and b/articles/active-directory/verifiable-credentials/media/how-to-issuer-revoke/settings-revoke.png differ diff --git a/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-config-sample-1.png b/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-config-sample-1.png index 22e9c2618b27c..b85c1d7893943 100644 Binary files a/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-config-sample-1.png and b/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-config-sample-1.png differ diff --git a/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-config-sample-2.png b/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-config-sample-2.png index 93f9db9514f03..a0444253b956c 100644 Binary files a/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-config-sample-2.png and b/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-config-sample-2.png differ diff --git a/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-create-new.png b/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-create-new.png index 9da9a03583e2a..494ac84385430 100644 Binary files a/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-create-new.png and b/articles/active-directory/verifiable-credentials/media/how-to-use-quickstart/quickstart-create-new.png differ diff --git a/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-issuer-details.png b/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-issuer-details.png new file mode 100644 index 0000000000000..9c49cea187b1b Binary files /dev/null and b/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-issuer-details.png differ diff --git a/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-issuer-list.png b/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-issuer-list.png new file mode 100644 index 0000000000000..978536f9a57c7 Binary files /dev/null and b/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-issuer-list.png differ diff --git a/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-quickstart.png b/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-quickstart.png new file mode 100644 index 0000000000000..e1109cc5b9848 Binary files /dev/null and b/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-quickstart.png differ diff --git a/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-search-select.png b/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-search-select.png new file mode 100644 index 0000000000000..8adb6d4980a76 Binary files /dev/null and b/articles/active-directory/verifiable-credentials/media/how-use-vcnetwork/vcnetwork-search-select.png differ diff --git a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/decentralized-architecture.png b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/decentralized-architecture.png index dc51ae85ef9d6..409283048a265 100644 Binary files a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/decentralized-architecture.png and b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/decentralized-architecture.png differ diff --git a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/external-resources.png b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/external-resources.png index ea77dc7764b39..fe6338aa4b582 100644 Binary files a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/external-resources.png and b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/external-resources.png differ diff --git a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/how-decentralized-works.png b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/how-decentralized-works.png index f28eb40dc2b24..15591744acf17 100644 Binary files a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/how-decentralized-works.png and b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/how-decentralized-works.png differ diff --git a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/issuance.png b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/issuance.png index 76876ced419b0..43c790a95b0e8 100644 Binary files a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/issuance.png and b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/issuance.png differ diff --git a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/presentation.png b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/presentation.png index 1b44de3294235..00f86535cc320 100644 Binary files a/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/presentation.png and b/articles/active-directory/verifiable-credentials/media/introduction-to-verifiable-credentials-architecture/presentation.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-architecture.png b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-architecture.png index 898950445e0b1..296a2ff644919 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-architecture.png and b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-architecture.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-authenticator.png b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-authenticator.png index 20cd97c263da5..eebc0443ced07 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-authenticator.png and b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-authenticator.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-azure-active-directory-verifiable-credentials-vc-services.png b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-azure-active-directory-verifiable-credentials-vc-services.png index acc7ae5181143..a4012ab77a192 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-azure-active-directory-verifiable-credentials-vc-services.png and b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-azure-active-directory-verifiable-credentials-vc-services.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-azure-services.png b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-azure-services.png index 00fa7ce607b71..ac57331cf0df3 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-azure-services.png and b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-azure-services.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-business-logic.png b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-business-logic.png index a321d95b17226..735384354727c 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-business-logic.png and b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-business-logic.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-employment-proof-use-case.png b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-employment-proof-use-case.png index ddca2302bba61..00e262199fe83 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-employment-proof-use-case.png and b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-employment-proof-use-case.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-identity-verification-use-case.png b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-identity-verification-use-case.png index f045f845a5412..e3b29566796f5 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-identity-verification-use-case.png and b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-identity-verification-use-case.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-ion.png b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-ion.png index eabe99d7efb99..353d866671c43 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-ion.png and b/articles/active-directory/verifiable-credentials/media/plan-issuance-solution/plan-for-issuance-solution-ion.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-account-recovery.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-account-recovery.png index c61e950e0f068..6ba5d238d2f7c 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-account-recovery.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-account-recovery.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-apis.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-apis.png index e71e3aeaa5532..0865c43bff5f0 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-apis.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-apis.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-architecture.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-architecture.png index fb4d8486cf15f..c8c1a48f86fff 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-architecture.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-architecture.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-authenticator.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-authenticator.png index bcd6189e2ae03..cfcb61ddcfee6 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-authenticator.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-authenticator.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-inside-trust-boundary-access.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-inside-trust-boundary-access.png index cdd18d109cf5a..1ed29153f4802 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-inside-trust-boundary-access.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-inside-trust-boundary-access.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-ion.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-ion.png index e96d4c0848e88..80aff8bad0c3b 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-ion.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-ion.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-key-vault.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-key-vault.png index 91bff334eca23..28a6a2865ec14 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-key-vault.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-key-vault.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-onboarding.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-onboarding.png index 0dbc72086f184..6c77add200107 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-onboarding.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-onboarding.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-outside-trust-boundary-access.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-outside-trust-boundary-access.png index 3ab394de09e91..bb13fb07836fa 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-outside-trust-boundary-access.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-outside-trust-boundary-access.png differ diff --git a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-relying-party.png b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-relying-party.png index 46d4ca0bf9602..31ad8be8c615f 100644 Binary files a/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-relying-party.png and b/articles/active-directory/verifiable-credentials/media/plan-verification-solution/plan-verification-solution-relying-party.png differ diff --git a/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-issuer/issue-credential-custom-view.png b/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-issuer/issue-credential-custom-view.png index 21cd4b2b3457c..39aa5bf645470 100644 Binary files a/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-issuer/issue-credential-custom-view.png and b/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-issuer/issue-credential-custom-view.png differ diff --git a/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-issuer/issue-credential.png b/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-issuer/issue-credential.png new file mode 100644 index 0000000000000..b85c1d7893943 Binary files /dev/null and b/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-issuer/issue-credential.png differ diff --git a/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-tenant/set-key-vault-admin-access-policy.png b/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-tenant/set-key-vault-admin-access-policy.png index f304e29a55370..23b43855b3148 100644 Binary files a/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-tenant/set-key-vault-admin-access-policy.png and b/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-tenant/set-key-vault-admin-access-policy.png differ diff --git a/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-tenant/verifiable-credentials-getting-started.png b/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-tenant/verifiable-credentials-getting-started.png index 9922c3db88080..23f0d9e687d1d 100644 Binary files a/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-tenant/verifiable-credentials-getting-started.png and b/articles/active-directory/verifiable-credentials/media/verifiable-credentials-configure-tenant/verifiable-credentials-getting-started.png differ diff --git a/articles/active-directory/verifiable-credentials/plan-issuance-solution.md b/articles/active-directory/verifiable-credentials/plan-issuance-solution.md index ef7da15571a31..4ebba1f5c035f 100644 --- a/articles/active-directory/verifiable-credentials/plan-issuance-solution.md +++ b/articles/active-directory/verifiable-credentials/plan-issuance-solution.md @@ -1,5 +1,5 @@ --- -title: Plan your Azure Active Directory Verifiable Credentials issuance solution(preview) +title: Plan your Microsoft Entra Verified ID issuance solution(preview) description: Learn to plan your end-to-end issuance solution. documentationCenter: '' author: barclayn @@ -7,25 +7,25 @@ manager: martinco ms.service: decentralized-identity ms.topic: how-to ms.subservice: verifiable-credentials -ms.date: 06/03/2022 +ms.date: 07/28/2022 ms.author: barclayn ms.custom: references_regions --- -# Plan your Azure Active Directory Verifiable Credentials issuance solution (preview) +# Plan your Microsoft Entra Verified ID issuance solution (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] >[!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. For more information, see [**Supplemental Terms of Use for Microsoft Azure Previews**](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). +> Microsoft Entra Verified ID 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. For more information, see [**Supplemental Terms of Use for Microsoft Azure Previews**](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). -It’s important to plan your issuance solution so that in addition to issuing credentials, you have a complete view of the architectural and business impacts of your solution. If you haven’t done so, we recommend you view the [Azure Active Directory Verifiable Credentials architecture overview](introduction-to-verifiable-credentials-architecture.md) for foundational information. +It’s important to plan your issuance solution so that in addition to issuing credentials, you have a complete view of the architectural and business impacts of your solution. If you haven’t done so, we recommend you view the [Microsoft Entra Verified ID architecture overview](introduction-to-verifiable-credentials-architecture.md) for foundational information. ## Scope of guidance -This article covers the technical aspects of planning for a verifiable credential issuance solution using Microsoft products to interoperate with the Identity Overlay Network (ION). The Microsoft solution for verifiable credentials follows the World Wide Web Consortium (W3C) [Verifiable Credentials Data Model 1.0](https://www.w3.org/TR/vc-data-model/) and [Decentralized Identifiers (DIDs) V1.0](https://www.w3.org/TR/did-core/) standards so can interoperate with non-Microsoft services. However, the examples in this content reflect the Microsoft solution stack for verifiable credentials. +This article covers the technical aspects of planning for a verifiable credential issuance solution. The Microsoft solution for verifiable credentials follows the World Wide Web Consortium (W3C) [Verifiable Credentials Data Model 1.0](https://www.w3.org/TR/vc-data-model/) and [Decentralized Identifiers (DIDs) V1.0](https://www.w3.org/TR/did-core/) standards so can interoperate with non-Microsoft services. However, the examples in this content reflect the Microsoft solution stack for verifiable credentials. -Out of scope for this content are topics covering supporting technologies that aren't specific to issuance solutions. For example, websites are used in a verifiable credential issuance solution but planning a website deployment isn't covered in detail. +Out of scope for this content is articles covering supporting technologies that aren't specific to issuance solutions. For example, websites are used in a verifiable credential issuance solution but planning a website deployment isn't covered in detail. ## Components of the solution @@ -38,34 +38,34 @@ As part of your plan for an issuance solution, you must design a solution that e ### Azure Active Directory tenant -A prerequisite for running the Azure AD Verifiable Credentials service is that it's hosted in an Azure Active Directory (Azure AD) tenant. The Azure AD tenant provides an Identity and Access Management (IAM) control plane for the Azure resources that are part of the solution. +A prerequisite for running the Microsoft Entra Verified ID service is that it's hosted in an Azure Active Directory (Azure AD) tenant. The Azure AD tenant provides an Identity and Access Management (IAM) control plane for the Azure resources that are part of the solution. -Each tenant has a single instance of the Azure AD Verifiable Credentials service, and a single decentralized identifier (DID). The DID provides proof that the issuer owns the domain incorporated into the DID. The DID is used by the subject and the verifier to validate the issuer. +Each tenant uses the multi-tenant Microsoft Entra Verified ID service, and has a decentralized identifier (DID). The DID provides proof that the issuer owns the domain incorporated into the DID. The DID is used by the subject and the verifier to validate the issuer. ### Microsoft Azure services ![Components of an issuance solution, focusing on Azure services](media/plan-issuance-solution/plan-for-issuance-solution-azure-services.png) -The **Azure Key Vault** service stores your issuer keys, which are generated when you initiate the Azure AD Verifiable Credentials issuance service. The keys and metadata are used to execute credential management operations and provide message security. +The **Azure Key Vault** service stores your issuer keys, which are generated when you initiate the Microsoft Entra Verified ID issuance service. The keys and metadata are used to execute credential management operations and provide message security. Each issuer has a single key set used for signing, updating, and recovery. This key set is used for every issuance of every verifiable credential you produce. -**Azure AD Verifiable Credentials Service** is used to store credential metadata and definitions; specifically, the rules and display definitions for your credentials. +**Microsoft Entra Verified ID Service** is used to store credential metadata and definitions; specifically, the rules and display definitions for your credentials. -* Display definitions determine which claims are stored in the VC and how it's displayed in the holder’s wallet. The display definition also includes branding and other elements. Rules definitions are limited in size to 50 KB, while display definitions are limited to 150 KB. See [How to customize your verifiable credentials](../verifiable-credentials/credential-design.md). +* Display definitions determine how claims are displayed in the holder’s wallet and also includes branding and other elements. The Display definition can be localized into multiple languages. See [How to customize your verifiable credentials](../verifiable-credentials/credential-design.md). -* Rules are an issuer-defined model that describes the required inputs of a verifiable credential, the trusted sources of the inputs, and the mapping of input claims to output claims. +* Rules are an issuer-defined model that describes the required inputs of a verifiable credential. Rules also defined trusted input sources, and the mapping of input claims to output claims stored in the VC. Depending on the type of attestation defined in the rules definition, the input claims can come from different providers. Input claims may come from an OIDC Identity Provider, from an id_token_hint or they may be self asserted during issuance via user input in the wallet. * **Input** – Are a subset of the model in the rules file for client consumption. The subset must describe the set of inputs, where to obtain the inputs and the endpoint to call to obtain a verifiable credential. -### Azure AD Verifiable Credentials service +### Microsoft Entra Verified ID service -![Microsoft Azure AD Verifiable Credentials service](media/plan-issuance-solution/plan-for-issuance-solution-azure-active-directory-verifiable-credentials-vc-services.png) +![Diagram of Microsoft Microsoft Entra Verified ID service](media/plan-issuance-solution/plan-for-issuance-solution-azure-active-directory-verifiable-credentials-vc-services.png) -The Azure AD Verifiable Credentials service enables you to issue and revoke VCs based on your configuration. The service: +The Microsoft Entra Verified ID service enables you to issue and revoke VCs based on your configuration. The service: -* Provisions the decentralized identifier (DID) and writes the DID document to ION, where it can be used by subjects and verifiers. Each issuer has a single DID per tenant. +* Provisions the decentralized identifier (DID). Each issuer has a single DID per tenant. * Provisions key sets to Key Vault. @@ -73,17 +73,17 @@ The Azure AD Verifiable Credentials service enables you to issue and revoke VCs * Provides REST APIs interface for issuer and verifier web front ends -### ION +### Trust System ![ION](media/plan-issuance-solution/plan-for-issuance-solution-ion.png) -As one alternative for the tenants trust system, Microsoft uses the [Identity Overlay Network (ION)](https://identity.foundation/ion/), [a Sidetree-based network](https://identity.foundation/sidetree/spec/) that uses Bitcoin’s blockchain for decentralized identifier (DID) implementation. The DID document of the issuer is stored in ION and is used to perform cryptographic signature checks by parties to the transaction. The other alternative for trust system is Web, where the DID document is hosted on the issuers webserver. +Microsoft Entra Verified ID currently supports two trust system. One is the [Identity Overlay Network (ION)](https://identity.foundation/ion/), [a Sidetree-based network](https://identity.foundation/sidetree/spec/) that uses Bitcoin’s blockchain for decentralized identifier (DID) implementation. The DID document of the issuer is stored in ION and is used to perform cryptographic signature checks by parties to the transaction. The other alternative for trust system is [DID Web](https://w3c-ccg.github.io/did-method-web/), where the DID document is hosted on the issuers webserver. ### Microsoft Authenticator application ![Microsoft Authenticator application](media/plan-issuance-solution/plan-for-issuance-solution-authenticator.png) -Microsoft Authenticator is the mobile application that orchestrates the interactions between the user, the Azure AD Verifiable Credentials service, and dependencies that are described in the contract used to issue VCs. It acts as a digital wallet in which the holder of the VC stores the VC, including the private key of the subject of the VC. Authenticator is also the mechanism used to present VCs for verification. +Microsoft Authenticator is the mobile application that orchestrates the interactions between the user, the Microsoft Entra Verified ID service, and dependencies that are described in the contract used to issue VCs. It acts as a digital wallet in which the holder of the VC stores the VC, including the private key of the subject of the VC. Authenticator is also the mechanism used to present VCs for verification. ### Issuance business logic @@ -93,7 +93,7 @@ Your issuance solution includes a web front end where users request a VC, an ide A web front end serves issuance requests to the subject’s wallet by generating deep links or QR codes. Based on the configuration of the contract, other components might be required to satisfy the requirements to create a VC. -These services provide supporting roles that don't necessarily need to integrate with ION or Azure AD Verifiable Credentials issuance service. This layer typically includes: +These services provide supporting roles that don't necessarily need to integrate with ION or Microsoft Entra Verified ID issuance service. This layer typically includes: * **Open ID Connect (OIDC)-compliant service or services** are used to obtain id_tokens needed to issue the VC. Existing identity systems such as Azure AD or Azure AD B2C can provide the OIDC-compliant service, as can custom solutions such as Identity Server. @@ -115,11 +115,9 @@ Your specific use cases determine your credential design. The use case will dete * if credentials will ever need to be revoked - - ### Credential Use Cases -With Azure AD Verifiable Credentials, the most common credential use cases are: +With Microsoft Entra Verified ID, the most common credential use cases are: **Identity Verification**: a credential is issued based on multiple criteria. This may include verifying the authenticity of government-issued documents like a passport or driver’s license and corelating the information in that document with other information such as: @@ -129,8 +127,6 @@ With Azure AD Verifiable Credentials, the most common credential use cases are: This kind of credential is a good fit for identity onboarding scenarios of new employees, partners, service providers, students, and other instances where identity verification is essential. - - ![Identity verification use case](media/plan-issuance-solution/plan-for-issuance-solution-identity-verification-use-case.png) **Proof of employment/membership**: a credential is issued to prove a relationship between the user and an institution. This kind of credential is a good fit to access loosely coupled business-to-business applications, such as retailers offering discounts to employees or students. One main value of VCs is their portability: Once issued, the user can use the VC in many scenarios. @@ -143,33 +139,41 @@ For more use cases, see [Verifiable Credentials Use Cases (w3.org)](https://www. As part of the design process, investigate industry-specific schemas, namespaces, and identifiers to which you can align to maximize interoperability and usage. Examples can be found in [Schema.org](https://schema.org/) and the [DIF - Claims and Credentials Working Group.](https://identity.foundation/working-groups/claims-credentials.html) -Note that common schemas are an area where standards are still emerging. One example of such an effort is the [Verifiable Credentials for Education Task Force](https://github.com/w3c-ccg/vc-ed). We encourage you to investigate and contribute to emerging standards in your organization's industry. +Common schemas are an area where standards are still emerging. One example of such an effort is the [Verifiable Credentials for Education Task Force](https://github.com/w3c-ccg/vc-ed). We encourage you to investigate and contribute to emerging standards in your organization's industry. + +### Credential Type and Attributes + +After establishing the use case for a credential, you need to decide the credential type and what attributes to include in the credential. Verifiers can read the claims in the VC presented by the users. -### Credential Attributes +All verifiable credentials must declare their *type* in their [rules definition](rules-and-display-definitions-model.md#rulesmodel-type). The credential type distinguishes a verifiable credentials schema from other credentials and it ensures interoperability between issuers and verifiers. To indicate a credential type, provide one or more credential types that the credential satisfies. Each type is represented by a unique string. Often, a URI is used to ensure global uniqueness. The URI doesn't need to be addressable. It's treated as a string. As an example, a diploma credential issued by Contoso University might declare the following types: -After establishing the use case for a credential, you need to decide what attributes to include in the credential. Verifiers can read the claims in the VC presented by the users. +| Type | Purpose | +| ---- | ------- | +| `https://schema.org/EducationalCredential` | Declares that diplomas issued by Contoso University contain attributes defined by the schema.org `EducationaCredential` object. | +| `https://schemas.ed.gov/universityDiploma2020` | Declares that diplomas issued by Contoso University contain attributes defined by the U.S. Department of Education. | +| `https://schemas.contoso.edu/diploma2020` | Declares that diplomas issued by Contoso University contain attributes defined by Contoso University. | In addition to the industry-specific standards and schemas that might be applicable to your scenarios, consider the following aspects: -* **Minimize private information**: Meet the use cases with the minimal amount of private information necessary. For example, a VC used for e-commerce websites that offers discounts to employees and alumni can be fulfilled by presenting the credential with just the first and last name claims. Additional information such as hiring date, title, department, etc. are not needed. +* **Minimize private information**: Meet the use cases with the minimal amount of private information necessary. For example, a VC used for e-commerce websites that offers discounts to employees and alumni can be fulfilled by presenting the credential with just the first and last name claims. Additional information such as hiring date, title, department, aren't needed. * **Favor abstract claims**: Each claim should meet the need while minimizing the detail. For example, a claim named “ageOver” with discrete values such as “13”,”21”,”60”, is more abstract than a date of birth claim. -* **Plan for revocability**: We recommend you define an index claim to enable mechanisms to find and revoke credentials. You are limited to defining one index claim per contract. It is important to note that values for indexed claims are not stored in the backend, only a hash of the claim value. For more information, see [Revoke a previously issued verifiable credential](../verifiable-credentials/how-to-issuer-revoke.md). +* **Plan for revocability**: We recommend you define an index claim to enable mechanisms to find and revoke credentials. You are limited to defining one index claim per contract. It is important to note that values for indexed claims aren't stored in the backend, only a hash of the claim value. For more information, see [Revoke a previously issued verifiable credential](../verifiable-credentials/how-to-issuer-revoke.md). -For additional considerations on credential attributes, refer to the [Verifiable Credentials Data Model 1.0 (w3.org)](https://www.w3.org/TR/vc-data-model/) specification. +For other considerations on credential attributes, refer to the [Verifiable Credentials Data Model 1.0 (w3.org)](https://www.w3.org/TR/vc-data-model/) specification. ## Plan quality attributes ### Plan for performance -As with any solution, you must plan for performance. The key areas to focus on are latency, throughput storage, and scalability. During initial phases of a release cycle, performance should not be a concern. However, when adoption of your issuance solution results in many verifiable credentials being issued, performance planning might become a critical part of your solution. +As with any solution, you must plan for performance. The key areas to focus on are latency and scalability. During initial phases of a release cycle, performance shouldn't be a concern. However, when adoption of your issuance solution results in many verifiable credentials being issued, performance planning might become a critical part of your solution. The following provides areas to consider when planning for performance: -* The Azure AD Verifiable Credentials issuance service is deployed in West Europe, North Europe, West US 2, and West Central US Azure regions. You do not select a region to deploy the service to. +* The Microsoft Entra Verified ID issuance service is deployed in West Europe, North Europe, West US 2, and West Central US Azure regions. If your Azure Active Directory tenant resides within EU, the Microsoft Entra Verified ID service will be in EU too. -* To limit latency, deploy your issuance frontend website, key vault, and storage in the region listed above that is closest to where requests are expected to originate. +* To limit latency, deploy your issuance frontend website and key vault in the region listed above that is closest to where requests are expected to originate. Model based on throughput: * The Issuer service is subject to [Azure Key Vault service limits](../../key-vault/general/service-limits.md). @@ -184,15 +188,9 @@ Model based on throughput: * Maximum signing performance of a Key Vault is 2,000 signing/~10 seconds. This is about 12,000 signings per minute. This means your solution can support up to 4,000 VC issuances per minute. -* You cannot control throttling; however, we recommend you read [Azure Key Vault throttling guidance](../../key-vault/general/overview-throttling.md). +* You can't control throttling; however, we recommend you read [Azure Key Vault throttling guidance](../../key-vault/general/overview-throttling.md). -* If you are planning a large rollout and onboarding of VCs, consider batching VC creation to ensure you do not exceed limits. - -* The issuance service is subject to Azure storage limits. In typical use cases storage should not be a concern. However, if you feel you might exceed storage limits or feel storage might be a bottleneck, review the following: - - * We recommend reading [Scalability and performance targets for Blob storage](../../storage/blobs/scalability-targets.md) as part of your planning process. Azure AD Verifiable Credentials issuance service reads rules and displays files, and results are cached by the service. - - * We also recommend you review [Performance and scalability checklist for Blob storage - Azure Storage](../../storage/blobs/storage-performance-checklist.md). +* If you are planning a large rollout and onboarding of VCs, consider batching VC creation to ensure you don't exceed limits. As part of your plan for performance, determine what you will monitor to better understand the performance of the solution. In addition to application-level website monitoring, consider the following as you define your VC issuance monitoring strategy: @@ -206,7 +204,7 @@ For scalability, consider implementing metrics for the following: * Attribute lookup - * Calls to Azure AD Verifiable Credentials issuance service + * Calls to Microsoft Entra Verified ID issuance service * Credential issued @@ -218,7 +216,7 @@ For scalability, consider implementing metrics for the following: * Time spent (latency) -* Monitor Azure Key Vault and Storage using the following: +* Monitor Azure Key Vault using the following: * [Azure Key Vault monitoring and alerting](../../key-vault/general/alert.md) @@ -234,13 +232,13 @@ To plan for reliability, we recommend: * For frontend and business layer, your solution can manifest in an unlimited number of ways. As with any solution, for the dependencies you identify, ensure that the dependencies are resilient and monitored. -If the rare event that the Azure AD Verifiable Credentials issuance service, Azure Key Vault, or Azure Storage services become unavailable, the entire solution will become unavailable. +If the rare event that the Microsoft Entra Verified ID issuance service or Azure Key Vault services become unavailable, the entire solution will become unavailable. ### Plan for compliance Your organization may have specific compliance needs related to your industry, type of transactions, or country of operation. -**Data residency**: The Azure AD Verifiable Credentials issuance service is deployed in a subset of Azure regions. The service is used for compute functions only. We do not store values of verifiable credentials in Microsoft systems. However, as part of the issuance process, personal data is sent and used when issuing VCs. Using the VC service should not impact data residency requirements. If, as a part of identity verification you store any personal information, that should be stored in a manner and region that meets your compliance requirements. For Azure-related guidance, visit the Microsoft Trust Center website. +**Data residency**: The Microsoft Entra Verified ID issuance service is deployed in a subset of Azure regions. The service is used for compute functions only. We don't store values of verifiable credentials in Microsoft systems. However, as part of the issuance process, personal data is sent and used when issuing VCs. Using the VC service shouldn't impact data residency requirements. If, as a part of identity verification you store any personal information, that should be stored in a manner and region that meets your compliance requirements. For Azure-related guidance, visit the Microsoft Trust Center website. **Revoking credentials**: Determine if your organization will need to revoke credentials. For example, an admin may need to revoke credentials when an employee leaves the company. Or if a credential is issued for a driver’s license, and the holder is caught doing something that would cause the driver’s license to be suspended, the VC might need to be revoked. For more information, see [Revoke a previously issued verifiable credential](how-to-issuer-revoke.md). @@ -248,7 +246,7 @@ Your organization may have specific compliance needs related to your industry, t ## Plan for operations -When planning for operations, it is critical you develop a schema to use for troubleshooting, reporting, and distinguishing various customers you support. Additionally, if the operations team is responsible for executing VC revocation, that process must be defined. Each step in the process should be correlated so that you can determine which log entries can be associated with each unique issuance request. For auditing, we recommend you capture each attempt of credential issuing individually. Specifically: +When planning for operations, it is critical you develop a schema to use for troubleshooting, reporting and distinguishing various customers you support. Additionally, if the operations team is responsible for executing VC revocation, that process must be defined. Each step in the process should be correlated so that you can determine which log entries can be associated with each unique issuance request. For auditing, we recommend you capture each attempt of credential issuing individually. Specifically: * Generate unique transaction IDs that customers and support engineers can refer to as needed. @@ -264,7 +262,7 @@ As part of your design considerations focused on security, we recommend the foll * For key management: - * Create a dedicated Key Vault for VC issuance. Limit Azure Key Vault permissions to the Azure AD Verifiable Credentials issuance service and the issuance service frontend website service principal. + * Create a dedicated Key Vault for VC issuance. Limit Azure Key Vault permissions to the Microsoft Entra Verified ID issuance service and the issuance service frontend website service principal. * Treat Azure Key Vault as a highly privileged system - Azure Key Vault issues credentials to customers. We recommend that no human identities have standing permissions over the Azure Key Vault service. Administrators should have only just I time access to Key Vault. For more best practices for Azure Key Vault usage, refer to [Azure Security Baseline for Key Vault](/security/benchmark/azure/baselines/key-vault-security-baseline). @@ -278,8 +276,6 @@ For security logging and monitoring, we recommend the following: * Enable logging and alerting of Azure Key Vault to track credential issuance operations, key extraction attempts, permission changes, and to monitor and send alert for configuration changes. More information can be found at [How to enable Key Vault logging](../../key-vault/general/howto-logging.md). -* Enable logging of your Azure Storage account to monitor and send alert for configuration changes. More information can be found at [Monitoring Azure Blob Storage](../../storage/blobs/monitor-blob-storage.md). - * Archive logs in a security information and event management (SIEM) systems, such as [Microsoft Sentinel](https://azure.microsoft.com/services/azure-sentinel) for long-term retention. * Mitigate spoofing risks by using the following @@ -306,4 +302,4 @@ For more information on Key Vault implementation and operation, refer to [Best p [Plan your verification solution](plan-verification-solution.md) -[Get started with verifiable credentials](get-started-verifiable-credentials.md) +[Get started with verifiable credentials](get-started-verifiable-credentials.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/plan-verification-solution.md b/articles/active-directory/verifiable-credentials/plan-verification-solution.md index 5373e61c22692..9dfc0c782c4bd 100644 --- a/articles/active-directory/verifiable-credentials/plan-verification-solution.md +++ b/articles/active-directory/verifiable-credentials/plan-verification-solution.md @@ -1,5 +1,5 @@ --- -title: Plan your Azure Active Directory Verifiable Credentials verification solution (preview) +title: Plan your Microsoft Entra Verified ID verification solution (preview) description: Learn foundational information to plan and design your verification solution documentationCenter: '' author: barclayn @@ -7,25 +7,25 @@ manager: martinco ms.service: decentralized-identity ms.topic: how-to ms.subservice: verifiable-credentials -ms.date: 06/02/2022 +ms.date: 07/28/2022 ms.author: barclayn ms.custom: references_regions --- -# Plan your Azure Active Directory Verifiable Credentials verification solution (preview) +# Plan your Microsoft Entra Verified ID verification solution (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] >[!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. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). +> Microsoft Entra Verified ID 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. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). -Microsoft’s Azure Active Directory Verifiable Credentials (Azure AD VC) service enables you to trust proofs of user identity without expanding your trust boundary. With Azure AD VC, you create accounts or federate with another identity provider. By using verifiable credentials based on an open standard, a verification exchange enables applications to request credentials that aren't bound to a specific domain. This approach makes it easier to request and verify credentials at scale. +Microsoft’s Microsoft Entra Verified ID (Azure AD VC) service enables you to trust proofs of user identity without expanding your trust boundary. With Azure AD VC, you create accounts or federate with another identity provider. When a solution implements a verification exchange using verifiable credentials, it enables applications to request credentials that aren't bound to a specific domain. This approach makes it easier to request and verify credentials at scale. -If you haven’t already, we suggest you review the [Azure AD Verifiable Credentials architecture overview](introduction-to-verifiable-credentials-architecture.md). You may also want to review [Plan your Azure AD Verifiable Credentials issuance solution](plan-issuance-solution.md). +If you haven’t already, we suggest you review the [Microsoft Entra Verified ID architecture overview](introduction-to-verifiable-credentials-architecture.md). You may also want to review [Plan your Microsoft Entra Verified ID issuance solution](plan-issuance-solution.md). ## Scope of guidance -This content covers the technical aspects of planning for a verifiable credential (VC) verification solution using Microsoft products and services. The solution interfaces with the Identity Overlay Network (ION) which acts as the decentralized public key infrastructure (DPKI). +This content covers the technical aspects of planning for a verifiable credential (VC) verification solution using Microsoft products and services. The solution interfaces with a trust system, where currently supported trust systems are Identity Overlay Network (ION) or DID Web. ION acts as the decentralized public key infrastructure (DPKI) while DID Web is a centralized public key infrastructure. Supporting technologies that aren't specific to verification solutions are out of scope. For example, websites are used in a verifiable credential verification solution but planning a website deployment isn't covered in detail. @@ -35,49 +35,49 @@ As you plan your verification solution, you must consider what business capabili As part of your plan for a verification solution, you must enable the interactions between the verifier, the subject, and the issuer. In this article, the terms relying party and verifier are used interchangeably. The following diagram shows the components of your verification architecture. -![Components of a verification solution](media/plan-verification-solution/plan-verification-solution-architecture.png) +![Diagram of the components of a verification solution.](media/plan-verification-solution/plan-verification-solution-architecture.png) -### Azure AD Verifiable Credentials service +### Microsoft Entra Verified ID service -In the context of a verifier solution, the Azure AD Verifiable Credentials service is the interface between the Microsoft components of the solution and ION. The service provisions the key set to Key Vault, provisions the decentralized identifier (DID), and writes the DID document to ION, where it can be used by subjects and issuers. +In the context of a verifier solution, the Microsoft Entra Verified ID service is the interface between the Microsoft components of the solution and the trust system. The service provisions the key set to Key Vault, provisions the decentralized identifier (DID). In the case of ION, the service writes the DID document to the distributed ledger, where it can be used by subjects and issuers. ### Azure Active Directory tenant -The service requires an Azure AD tenant that provides an Identity and Access Management (IAM) control plane for the Azure resources that are part of the solution. There's a single instance of the Azure AD VC service within a tenant, and it issues a single DID document representing the verifier. If you have multiple relying parties using your verification service, they all use the same verifier DID. The verifier DID provides pointers to the public key that allows subjects and issuers to validate messages that come from the relying party. +The service requires an Azure AD tenant that provides an Identity and Access Management (IAM) control plane for the Azure resources that are part of the solution. Each Azure AD tenant uses the multi-tenant Microsoft Entra Verified ID service, and it issues a single DID document representing the verifier. If you have multiple relying parties using your verification service, they all use the same verifier DID. The verifier DID provides pointers to the public key that allows subjects and issuers to validate messages that come from the relying party. + ### Azure Key Vault -![Azure Key Vault](./media/plan-verification-solution/plan-verification-solution-key-vault.png) +![Diagram of the components of a verification solution with Azure Key Vault highlighted.](./media/plan-verification-solution/plan-verification-solution-key-vault.png) -The Azure Key Vault service stores your verifier keys, which are generated when you enable the Azure AD Verifiable Credentials issuance service. The keys are used to provide message security. Each verifier has a single key set used for signing, updating, and recovering VCs. This key set is used each time you service a verification request. Microsoft key set currently uses Elliptic Curve Cryptography (ECC) [SECP256k1](https://en.bitcoin.it/wiki/Secp256k1). We're exploring other cryptographic signature schemas that will be adopted by the broader DID community. +The Azure Key Vault service stores your verifier keys, which are generated when you enable the Microsoft Entra Verified ID issuance service. The keys are used to provide message security. Each verifier has a single key set used for signing, updating, and recovering VCs. This key set is used each time you service a verification request. Microsoft key set currently uses Elliptic Curve Cryptography (ECC) [SECP256k1](https://en.bitcoin.it/wiki/Secp256k1). We're exploring other cryptographic signature schemas that will be adopted by the broader DID community. -### Azure AD VC APIs +### Request Service API -![Azure AD VC APIs](./media/plan-verification-solution/plan-verification-solution-apis.png) +![Diagram of the components of a verification solution with request Service API highlighted.](./media/plan-verification-solution/plan-verification-solution-apis.png) Application programming interfaces (APIs) provide developers a method to abstract interactions between components of the solution to execute verification operations. -### ION - -![Azure AD VC ION](./media/plan-verification-solution/plan-verification-solution-ion.png) +### Trust System -As one alternative for the tenants trust system, Microsoft uses the [Identity Overlay Network (ION)](https://identity.foundation/ion/), [a Sidetree-based network](https://identity.foundation/sidetree/spec/)that uses Bitcoin’s blockchain for decentralized identifier (DID) implementation. The DID document of the issuer is stored in ION and is used to perform cryptographic signature checks by parties to the transaction. The other alternative for trust system is Web, where the DID document is hosted on the issuers webserver. +![Diagram of the components of a verification solution with the trust system highlighted.](./media/plan-verification-solution/plan-verification-solution-ion.png) +Microsoft Entra Verified ID currently supports two trust system. One is [Identity Overlay Network (ION)](https://identity.foundation/ion/), [a Sidetree-based network](https://identity.foundation/sidetree/spec/)that uses Bitcoin’s blockchain for decentralized identifier (DID) implementation. The DID document of the issuer is stored in ION and is used to perform cryptographic signature checks by parties to the transaction. The other alternative for trust system is [DID Web](https://w3c-ccg.github.io/did-method-web/), where the DID document is hosted on the issuers webserver. ### Microsoft Authenticator application -![Microsoft Authenticator application](media/plan-verification-solution/plan-verification-solution-authenticator.png) +![Diagram of the components of a verification solution with Microsoft Authenticator application highlighted.](media/plan-verification-solution/plan-verification-solution-authenticator.png) -Microsoft Authenticator is the mobile application that orchestrates the interactions between the relying party, the user, the Azure AD Verifiable Credentials issuance service, and dependencies described in the contract used to issue VCs. Microsoft Authenticator acts as a digital wallet in which the holder of the VC stores the VC. It's also the mechanism used to present VCs for verification. +Microsoft Authenticator is the mobile application that orchestrates the interactions between the relying party, the user, the Microsoft Entra Verified ID issuance service, and dependencies described in the contract used to issue VCs. Microsoft Authenticator acts as a digital wallet in which the holder of the VC stores the VC. It's also the mechanism used to present VCs for verification. ### Relying party (RP) -![Relying party components](media/plan-verification-solution/plan-verification-solution-relying-party.png) +![Diagram of the components of a verification solution with Relying party components highlighted.](media/plan-verification-solution/plan-verification-solution-relying-party.png) #### Web front end -The relying party web front end uses the Azure AD VC APIs to verify VCs by generating deep links or QR codes that are consumed by the subject’s wallet. Depending on the scenario, the front end can be a publicly accessible or internal website to enable end-user experiences that require verification. However, the endpoints that the wallet accesses must be publicly accessible. Specifically, it controls redirection to the wallet with specific request parameters. This is accomplished using the Microsoft-provided APIs. +The relying party web front end uses the Request Service API to verify VCs by generating deep links or QR codes that are consumed by the subject’s wallet. Depending on the scenario, the front end can be a publicly accessible or internal website to enable end-user experiences that require verification. However, the endpoints that the wallet accesses must be publicly accessible. Specifically, it controls redirection to the wallet with specific request parameters. This is accomplished using the Microsoft-provided APIs. #### Business logic @@ -89,13 +89,13 @@ The following are examples of designs to satisfy specific use cases. The first i ### Account onboarding -Verifiable credentials can also be used to enable faster onboarding by replacing some human interactions. VCs can be used to onboard employees, students, citizens, or others to access services. For example, rather than an employee needing to go to a central office to activate an employee badge, they can use a VC to verify their identity to activate a badge that is delivered to them remotely. Rather than a citizen receiving a code they must redeem to access governmental services, they can use a VC to prove their identity and gain access. +Verifiable credentials can be used to enable faster onboarding by replacing some human interactions. VCs can be used to onboard employees, students, citizens, or others to access services. For example, rather than an employee needing to go to a central office to activate an employee badge, they can use a VC to verify their identity to activate a badge that is delivered to them remotely. Rather than a citizen receiving a code they must redeem to access governmental services, they can use a VC to prove their identity and gain access. -![Account onboarding scenario](media/plan-verification-solution/plan-verification-solution-onboarding.png) +![Diagram showing the account onboarding scenario.](media/plan-verification-solution/plan-verification-solution-onboarding.png) #### Other elements -**Onboarding portal**: A web front end that orchestrates the Azure AD VC APIs calls for VC presentation and validation, and the logic to onboard accounts. +**Onboarding portal**: A web front end that orchestrates the Request Service API calls for VC presentation and validation, and the logic to onboard accounts. **Custom logic / workflows**: Specific logic with organization-specific steps before and after updating the user account. Examples might include approval workflows, other validations, logging, notifications, and so on. @@ -125,17 +125,17 @@ Verifiable credentials can also be used to enable faster onboarding by replacing * To invite users to Azure AD using B2B collaboration, the RP website can use a service principal that is granted the MS Graph scope of User.Invite.All to create invitations. - * If your RP is running in Azure, use Managed Identities to call Microsoft Graph; this will remove the risks of managing service principal credentials in code or configuration files. To learn more about Managed identities, go to [Managed identities for Azure resources.](../managed-identities-azure-resources/overview.md) + * If your RP is running in Azure, use Managed Identities to call Microsoft Graph. Using managed identities removes the risks of managing service principal credentials in code or configuration files. To learn more about Managed identities, go to [Managed identities for Azure resources.](../managed-identities-azure-resources/overview.md) ### Accessing high-value applications inside organizations Verifiable credentials can be used as other proof to access to sensitive applications inside the organization. For example, VCs can also be used to provide employees with access to line-of-business applications based on achieving specific criteria, such as a certification. -![Access inside of the trust boundary](media/plan-verification-solution/plan-verification-solution-inside-trust-boundary-access.png) +![Diagram of the components of a verification solution with other elements included.](media/plan-verification-solution/plan-verification-solution-inside-trust-boundary-access.png) #### Other elements -**Relying party web frontend**: This is the web frontend of the application that is enhanced through Azure AD Verifiable Credential API calls for VC presentation and validation, based on your business requirements. +**Relying party web frontend**: This is the web frontend of the application that is enhanced through Request Service API calls for VC presentation and validation, based on your business requirements. **User access authorization logic**: Logic layer in the application that authorizes user access and is enhanced to consume the user attributes inside the VC to make authorization decisions. @@ -163,11 +163,11 @@ Verifiable credentials can also be used by relying parties that want to grant ac The decentralized nature of verifiable credentials enables this scenario without establishing federation relationships. -![Access outside of the trust boundary](media/plan-verification-solution/plan-verification-solution-outside-trust-boundary-access.png) +![Diagram of the components of a verification solution showing that access is taking place from outside of the trust boundary.](media/plan-verification-solution/plan-verification-solution-outside-trust-boundary-access.png) #### Other elements -**Relying party web frontend**: This is the web frontend of the application that is enhanced through Azure AD Verifiable Credential API calls for VC presentation and validation, based on your business requirements. +**Relying party web frontend**: This is the web frontend of the application that is enhanced through Request Service API calls for VC presentation and validation, based on your business requirements. **User access authorization logic**: Logic layer in the application that authorizes user access and is enhanced to consume the user attributes inside the VC to make authorization decisions. @@ -192,7 +192,7 @@ Verifiable credentials can be used as an approach to account recovery. For examp Note: While the scenario we describe in this section is specific to recover Azure AD accounts, this approach can also be used to recover accounts in other systems. -![Account recovery solution](media/plan-verification-solution/plan-verification-solution-account-recovery.png) +![Diagram of the components of a verification solution showing the account recovery scenario.](media/plan-verification-solution/plan-verification-solution-account-recovery.png) #### Other Elements @@ -254,7 +254,7 @@ You can use information in presented VCs to build a user profile. If you want to * Consider using the “sub” claim as an immutable identifier of the user. This is an opaque unique attribute that will be constant for a given subject/RP pair. - * Define a mechanism to deprovision the user profile from the application. Due to the decentralized nature of the Azure AD Verifiable Credentials system, there is no application user provisioning lifecycle. + * Define a mechanism to deprovision the user profile from the application. Due to the decentralized nature of the Microsoft Entra Verified ID system, there is no application user provisioning lifecycle. * Do not store personal data claims returned in the VC token. @@ -262,11 +262,11 @@ You can use information in presented VCs to build a user profile. If you want to ## Plan for performance -As with any solution, you must plan for performance. Focus areas include latency, throughput, and scalability. During initial phases of a release cycle, performance should not be a concern. However, when adoption of your solution results in many verifiable credentials being verified, performance planning might become a critical part of your solution. +As with any solution, you must plan for performance. Focus areas include latency, throughput, and scalability. During initial phases of a release cycle, performance shouldn't be a concern. However, when adoption of your solution results in many verifiable credentials being verified, performance planning might become a critical part of your solution. The following provides areas to consider when planning for performance: -* The Azure AD Verifiable Credentials issuance service is deployed in West Europe, North Europe, West US 2, and West Central US Azure regions. To limit latency, deploy your verification front end (website) and key vault in the region listed above that is closest to where requests are expected to originate from. +* The Microsoft Entra Verified ID issuance service is deployed in West Europe, North Europe, West US 2, and West Central US Azure regions. To limit latency, deploy your verification front end (website) and key vault in the region listed above that is closest to where requests are expected to originate from. * Model based on throughput: @@ -282,7 +282,7 @@ The following provides areas to consider when planning for performance: To best plan for high availability and disaster recovery, we suggest the following: -* Azure AD Verifiable Credentials service is deployed in the West Europe, North Europe, West US 2, and West Central US Azure regions. Consider deploying your supporting web servers and supporting applications in one of those regions, specifically in the ones from which you expect most of your validation traffic to originate. +* Microsoft Entra Verified ID service is deployed in the West Europe, North Europe, West US 2, and West Central US Azure regions. Consider deploying your supporting web servers and supporting applications in one of those regions, specifically in the ones from which you expect most of your validation traffic to originate. * Review and incorporate best practices from [Azure Key Vault availability and redundancy](../../key-vault/general/disaster-recovery-guidance.md) as you design for your availability and redundancy goals. @@ -294,7 +294,7 @@ As you are designing for security, consider the following: * Define a dedicated service principal for a website accessing the Key Vault. -* Only the Azure AD Verifiable Credentials service and the website service principals should have permissions to use Key Vault to sign messages with the private key. +* Only the Microsoft Entra Verified ID service and the website service principals should have permissions to use Key Vault to sign messages with the private key. * Don't assign any human identity administrative permissions to the Key Vault. For more information on Key Vault best practices, see [Azure Security Baseline for Key Vault](../../key-vault/general/security-baseline.md). @@ -338,14 +338,14 @@ As part of your operational planning, consider monitoring the following: Learn more about architecting VC solutions - * [Azure AD Verifiable Credentials overview](introduction-to-verifiable-credentials-architecture.md) + * [Microsoft Entra Verified ID overview](introduction-to-verifiable-credentials-architecture.md) - * [Plan your Azure AD Verifiable Credentials issuance solution](plan-issuance-solution.md) + * [Plan your Microsoft Entra Verified ID issuance solution](plan-issuance-solution.md) Implement Verifiable Credentials - * [Introduction to Azure Active Directory Verifiable Credentials](decentralized-identifier-overview.md) + * [Introduction to Microsoft Entra Verified ID](decentralized-identifier-overview.md) * [Get started with Verifiable Credentials](get-started-verifiable-credentials.md) -[FAQs](verifiable-credentials-faq.md) +[FAQs](verifiable-credentials-faq.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/presentation-request-api.md b/articles/active-directory/verifiable-credentials/presentation-request-api.md index f72d1fe503141..197620223f89f 100644 --- a/articles/active-directory/verifiable-credentials/presentation-request-api.md +++ b/articles/active-directory/verifiable-credentials/presentation-request-api.md @@ -1,5 +1,6 @@ --- title: Specify the Request Service REST API verify request (preview) +titleSuffix: Microsoft Entra Verified ID description: Learn how to start a presentation request in Verifiable Credentials documentationCenter: '' author: barclayn @@ -7,17 +8,18 @@ manager: rkarlin ms.service: decentralized-identity ms.topic: reference ms.subservice: verifiable-credentials -ms.date: 06/02/2022 +ms.date: 07/28/2022 ms.author: barclayn -#Customer intent: As an administrator, I am trying to learn the process of revoking verifiable credentials that I have issued. +#Customer intent: As an administrator, I am trying to learn how to use the Request Service API and integrate it into my business application. --- # Request Service REST API presentation specification (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] -Azure Active Directory (Azure AD) Verifiable Credentials includes the Request Service REST API. This API allows you to issue and verify a credential. This article specifies the Request Service REST API for a presentation request. The presentation request asks the user to present a verifiable credential, and then verify the credential. +Microsoft Entra Verified ID includes the Request Service REST API. This API allows you to issue and verify a credential. This article specifies the Request Service REST API for a presentation request. The presentation request asks the user to present a verifiable credential, and then verify the credential. +Another article describes [how to call the Request Service REST API](get-started-request-api.md). ## HTTP request @@ -34,16 +36,16 @@ The Request Service REST API presentation request requires the following HTTP he |`Authorization`| Attach the access token as a bearer token to the authorization header in an HTTP request. For example, `Authorization: Bearer `.| |`Content-Type`| `Application/json`| -Construct an HTTP POST request to the Request Service REST API. Replace the `{tenantID}` with your tenant ID or tenant name. +Construct an HTTP POST request to the Request Service REST API. The `tenantId` isn't needed in the URL anymore since it is present as a claim in the `access_token`. ```http -https://beta.did.msidentity.com/v1.0/{tenantID}/verifiablecredentials/request +https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest ``` The following HTTP request demonstrates a presentation request to the Request Service REST API: ```http -POST https://beta.did.msidentity.com/v1.0/contoso.onmicrosoft.com/verifiablecredentials/request +POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest Content-Type: application/json Authorization: Bearer @@ -73,29 +75,33 @@ The presentation request payload contains information about your verifiable cred ```json { "includeQRCode": true, + "includeReceipt": true, + "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ......", + "registration": { + "clientName": "Veritable Credential Expert Verifier" + }, "callback": { "url": "https://www.contoso.com/api/verifier/presentationCallback", "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58", "headers": { - "api-key": "OPTIONAL API-KEY for VERIFIER CALLBACK API" + "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS" } }, - "authority": "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiOiJiRWo5MDY...", - "registration": { - "clientName": "Veritable Credential Expert Verifier" - }, - "presentation": { - "includeReceipt": true, - "requestedCredentials": [ - { - "type": "VerifiedCredentialExpert", - "purpose": "So we can see that you a veritable credentials expert", - "acceptedIssuers": [ - "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OkIjO6uUKyF5zM7fQZ8Jg:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfOTAyZmM2NmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiTEdUOWk3aFYzN1dUcFhHcUg5c1VDekxTVlFWcVl3S2JNY1Fsc0RILUZJUSIsInkiO..." - ] + "requestedCredentials": [ + { + "type": "VerifiedCredentialExpert", + "purpose": "So we can see that you a veritable credentials expert", + "acceptedIssuers": [ + "did:ion:EiCLL8lzCqlGLYTGbjwgR6SN6OABCO6uUKyF5zM7fQZ8Jg:eyJ......" + ], + "configuration": { + "validation": { + "allowRevoked": false, + "validateLinkedDomain": false + } } - ] - } + } + ] } ``` @@ -103,11 +109,13 @@ The payload contains the following properties. |Parameter |Type | Description | |---------|---------|---------| -| `includeQRCode` | Boolean | Determines whether a QR code is included in the response of this request. Present the QR code and ask the user to scan it. Scanning the QR code launches the authenticator app with this presentation request. Possible values are `true` (default) or `false`. When you set the value to `false`, use the return `url` property to render a deep link. | +| `includeQRCode` | Boolean | Determines whether a QR code is included in the response of this request. Present the QR code and ask the user to scan it. Scanning the QR code launches the authenticator app with this presentation request. Possible values are `true` (default) or `false`. When you set the value to `false`, use the return `url` property to render a deep link. | +| `includeReceipt` | Boolean | Determines whether a receipt should be included in the response of this request. Possible values are `true` or `false` (default). The receipt contains the original payload sent from the authenticator to the Verifiable Credentials service. The receipt is useful for troubleshooting or if you have the need to ge the full details of the payload. There's otherwise no need be set this value to `true `by default. In the `OpenId Connect SIOP` request, the receipt contains the ID token from the original request. | | `authority` | string| Your decentralized identifier (DID) of your verifier Azure AD tenant. For more information, see [Gather tenant details to set up your sample application](verifiable-credentials-configure-verifier.md#gather-tenant-details-to-set-up-your-sample-application).| | `registration` | [RequestRegistration](#requestregistration-type)| Provides information about the verifier. | -| `presentation` | [RequestPresentation](#requestpresentation-type)| Provides information about the verifiable credentials presentation request. | |`callback`| [Callback](#callback-type)| Mandatory. Allows the developer to update the UI during the verifiable credential presentation process. When the user completes the process, continue the process after the results are returned to the application.| +| `requestedCredentials` | collection| A collection of [RequestCredential](#requestcredential-type) objects.| + ### RequestRegistration type @@ -121,14 +129,15 @@ The following screenshot shows the `clientName` property and the display name of ![Screenshot that shows how to approve the presentation request.](media/presentation-request-api/approve-presentation-request.jpg) -### RequestPresentation type +### Callback type -The `RequestPresentation` type provides information required for verifiable credential presentation. `RequestPresentation` contains the following properties: +The Request Service REST API generates several events to the callback endpoint. Those events allow you to update the UI and continue the process after the results are returned to the application. The `Callback` type contains the following properties: |Property |Type |Description | |---------|---------|---------| -| `includeReceipt` | Boolean | Determines whether a receipt should be included in the response of this request. Possible values are `true` or `false` (default). The receipt contains the original payload sent from the authenticator to the Verifiable Credentials service. The receipt is useful for troubleshooting, and shouldn't be set by default. In the `OpenId Connect SIOP` request, the receipt contains the ID token from the original request. | -| `requestedCredentials` | collection| A collection of [RequestCredential](#requestcredential-type) objects.| +| `url` | string| URI to the callback endpoint of your application. The URI must point to a reachable endpoint on the internet otherwise the service will throw a callback URL unreadable error. Accepted inputs IPv4, IPv6 or DNS resolvable hostname. | +| `state` | string| Correlates the callback event with the state passed in the original payload. | +| `headers` | string| Optional. You can include a collection of HTTP headers required by the receiving end of the POST message. The current supported header values are the `api-key` or the `Authorization` headers. Any other header will throw an invalid callback header error.| ### RequestCredential type @@ -139,16 +148,16 @@ The `RequestCredential` provides information about the requested credentials the | `type`| string| The verifiable credential type. The `type` must match the type as defined in the `issuer` verifiable credential manifest (for example, `VerifiedCredentialExpert`). To get the issuer manifest, see [Gather credentials and environment details to set up your sample application](verifiable-credentials-configure-issuer.md). Copy the **Issue credential URL**, open it in a web browser, and check the **id** property. | | `purpose`| string | Provide information about the purpose of requesting this verifiable credential. | | `acceptedIssuers`| string collection | A collection of issuers' DIDs that could issue the type of verifiable credential that subjects can present. To get your issuer DID, see [Gather credentials and environment details to set up your sample application](verifiable-credentials-configure-issuer.md), and copy the value of the **Decentralized identifier (DID)**. | +| `configuration.validation` | [Configuration.Validation](#configurationvalidation-type) | Optional settings for presentation validation.| -### Callback type +### Configuration.Validation type -The Request Service REST API generates several events to the callback endpoint. Those events allow you to update the UI and continue the process after the results are returned to the application. The `Callback` type contains the following properties: +The `Configuration.Validation` provides information about the presented credentials should be validated. It contains the following properties: |Property |Type |Description | |---------|---------|---------| -| `url` | string| URI to the callback endpoint of your application. The URI must point to a reachable endpoint on the internet otherwise the service will throw a callback URL unreadable error. Accepted inputs IPv4, IPv6 or DNS resolvable hostname. | -| `state` | string| Associates with the state passed in the original payload. | -| `headers` | string| Optional. You can include a collection of HTTP headers required by the receiving end of the POST message. The current supported header values are the `api-key` or the `Authorization` headers. Any other header will throw an invalid callback header error.| +| `allowRevoked` | Boolean | Determines if a revoked credential should be accepted. Default is `false` (it shouldn't be accepted). | +| `validateLinkedDomain` | Boolean | Determines if the linked domain should be validated. Default is `true` (it should be validated). Setting this flag to `false` means you'll accept credentials from unverified linked domain. Setting this flag to `true` means the linked domain will be validated and only verified domains will be accepted. | ## Successful response @@ -157,7 +166,7 @@ If successful, this method returns a response code (*HTTP 201 Created*), and a c ```json { "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11", - "url": "openid://vc/?request_uri=https://beta.did.msidentity.com/v1.0/87654321-0000-0000-0000-000000000000/verifiablecredentials/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11", + "url": "openid://vc/?request_uri=https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/request/e4ef27ca-eb8c-4b63-823b-3b95140eac11", "expiry": 1633017751, "qrCode": "data:image/png;base64,iVBORw0KGgoA" } @@ -167,7 +176,7 @@ The response contains the following properties: |Property |Type |Description | |---------|---------|---------| -| `requestId`| string | An autogenerated correlation ID. The [callback](#callback-events) uses the same request, allowing you to keep track of the presentation request and its callbacks. | +| `requestId`| string | An autogenerated request ID. The [callback](#callback-events) uses the same request, allowing you to keep track of the presentation request and its callbacks. | | `url`| string| A URL that launches the authenticator app and starts the presentation process. You can present this URL to the user if they can't scan the QR code. | | `expiry`| integer| Indicates when the response will expire. | | `qrCode`| string | A QR code that the user can scan to start the presentation flow. | @@ -176,28 +185,7 @@ When your app receives the response, the app needs to present the QR code to the ## Error response -Error responses also can be returned so that the app can handle them appropriately. The following JSON shows an unauthorized error message: - - -```json -{ - "requestId": "fb888ac646c96083de83b099b2678de0", - "date": "Wed, 29 Sep 2021 21:49:00 GMT", - "error": { - "code": "unauthorized", - "message": "Failed to authenticate the request." - } -} -``` - -The response contains the following properties: - -|Property |Type |Description | -|---------|---------|---------| -| `requestId`| string | An autogenerated request ID.| -| `date`| date | The time of the error. | -| `error.code` | string | The return error code. | -| `error.message`| string | The error message. | +If there's an error with the request, an [error responses](error-codes.md) is returned, and should be handled appropriately by the app. ## Callback events @@ -210,15 +198,15 @@ The callback endpoint is called when a user scans the QR code, uses the deep lin | `state` |string| Returns the state value that you passed in the original payload. | | `subject`|string | The verifiable credential user DID.| | `issuers`| array |Returns an array of verifiable credentials requested. For each verifiable credential, it provides:
  • The verifiable credential type(s).
  • The issuer's DID
  • The claims retrieved.
  • The verifiable credential issuer's domain.
  • The verifiable credential issuer's domain validation status.
    • | -| `receipt`| string | Optional. The receipt contains the original payload sent from the wallet to the Verifiable Credentials service. The receipt should be used for troubleshooting/debugging only. The format in the receipt is not fix and can change based on the wallet and version used.| +| `receipt`| string | Optional. The receipt contains the original payload sent from the wallet to the Verifiable Credentials service. The receipt should be used for troubleshooting/debugging only. The format in the receipt isn't fix and can change based on the wallet and version used.| The following example demonstrates a callback payload when the authenticator app starts the presentation request: ```json { -    "requestId":"aef2133ba45886ce2c38974339ba1057", +    "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11",     "code":"request_retrieved", -    "state":"Wy0ThUz1gSasAjS1" +    "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58" } ``` @@ -226,9 +214,9 @@ The following example demonstrates a callback payload after the verifiable crede ```json { - "requestId": "87e1cb24-9096-409f-81cb-9e645f23a4ba", + "requestId": "e4ef27ca-eb8c-4b63-823b-3b95140eac11", "code": "presentation_verified", - "state": "f3d94e35-ca5f-4b1b-a7d7-a88caa05e322", + "state": "92d076dd-450a-4247-aa5b-d2e75a1a5d58", "subject": "did:ion:EiAlrenrtD3Lsw0GlbzS1O2YFdy3Xtu8yo35W…", "issuers": [ { @@ -237,12 +225,12 @@ The following example demonstrates a callback payload after the verifiable crede "VerifiedCredentialExpert" ], "claims": { - "firstName": "John", - "lastName": "Doe" + "firstName": "Megan", + "lastName": "Bowen" }, "domain": "https://contoso.com/", "verified": "DNS", - "issuer": "did:ion:….." + "authority": "did:ion:….." } ], "receipt": { diff --git a/articles/active-directory/verifiable-credentials/vc-network-api.md b/articles/active-directory/verifiable-credentials/vc-network-api.md new file mode 100644 index 0000000000000..9ac4046577e47 --- /dev/null +++ b/articles/active-directory/verifiable-credentials/vc-network-api.md @@ -0,0 +1,135 @@ +--- +title: Entra Verified ID Network API +titleSuffix: Microsoft Entra Verified ID +description: Learn how to use the Entra Verified ID Network API +documentationCenter: '' +author: barclayn +manager: rkarlin +ms.service: decentralized-identity +ms.topic: reference +ms.subservice: verifiable-credentials +ms.date: 07/29/2022 +ms.author: barclayn + +#Customer intent: As a verifiable credentials developer, I want to configure verifying credentials from another party +--- + +# Entra Verified ID network API + +[!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] + +The Microsoft Entra Verified ID Network API enables you to search for published credentials in the [Entra Verified ID Network](how-use-vcnetwork.md). + +>[!NOTE] +>The API is intended for developers comfortable with RESTful APIs. + +## Base URL + +The Entra Verified Network API is served 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`. + +## Searching for issuers + +This API is used to search for issuers available in the Entra Verified ID Network. You can search for issuers by their **linked domain** name. The value supplied for the `filter` parameter will be used to find issuers that have onboarded to Entra Verified ID and have a verified linked domain. Currently you can only filter by `linkeddomainurls` and with operator `like`. There will be a maximum of 15 issuers in the response. + +#### HTTP request + +`GET /v1.0/verifiableCredentialsNetwork/authorities?filter=linkeddomainurls%20like%20Woodgrove` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request parameters + +| Parameter | value | +| -------- | -------- | +| filter | linkeddomainurls like Woodgrove | + + +#### Return message + +``` +HTTP/1.1 200 OK +Content-type: application/json + +[ + { + "id": "0459a193-1111-2222-3333-444455556666", + "tenantId": "55eafede-1111-2222-3333-444455556666", + "did": "did:web:bank.woodgrove.com......", + "name": "WoodgroveBank", + "linkedDomainUrls": [ + "https://bank.woodgrove.com/" + ] + }, + { + "id": "6e0e41cb-1111-2222-3333-444455556666", + "tenantId": "7f448f57-1111-2222-3333-444455556666", + "did": "did:web:woodgrove.com......", + "name": "Woodgrove", + "linkedDomainUrls": [ + "https://woodgrove.com/" + ] + } +] +``` + +## Searching for published credential types by an issuer + +This API is used search for published credential types for a specific issuer. You need to know the issuers `tenantId` and `issuerId`. The return message is a collection of published credential types and their respective claims. There will be a maximum of 100 credential types in the response. + +#### HTTP request + +`GET /v1.0/tenants/:tenantId/verifiableCredentialsNetwork/authorities/:issuerId/contracts/` + +#### Request headers + +| Header | Value | +| -------- | -------- | +| Authorization | Bearer (token). Required | +| Content-Type | application/json | + +#### Request parameters + +| Parameter | value | +| -------- | -------- | +| tenantId | TenantId obtained from the search by linked domain name | +| issuerId | IssuerId obtained from the search by linked domain name | + + +#### Return message + +``` +HTTP/1.1 200 OK +Content-type: application/json + +[ + { + "name": "Verified employee 1", + "types": [ + "VerifiedEmployee" + ], + "claims": [ + "displayName", + "givenName", + "jobTitle", + "preferredLanguage", + "surname", + "mail", + "revocationId", + "photo" + ] + } +] +``` + +## Next steps + +Learn more about [Entra Verified ID Network](how-use-vcnetwork.md). diff --git a/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-issuer.md b/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-issuer.md index c03dda5326c5f..106270d1f518d 100644 --- a/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-issuer.md +++ b/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-issuer.md @@ -1,5 +1,5 @@ --- -title: Tutorial - Issue Azure AD Verifiable Credentials from an application (preview) +title: Tutorial - Issue Microsoft Entra Verified ID credentials from an application (preview) description: In this tutorial, you learn how to issue verifiable credentials by using a sample app. ms.service: decentralized-identity ms.subservice: verifiable-credentials @@ -13,7 +13,7 @@ ms.date: 06/16/2022 --- -# Issue Azure AD Verifiable Credentials from an application (preview) +# Issue Microsoft Entra Verified ID credentials from an application (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] @@ -30,13 +30,13 @@ In this article, you learn how to: > - Run the sample application and issue your first verified credential expert card. > - Verify your verified credential expert card. -The following diagram illustrates the Azure AD Verifiable Credentials architecture and the component you configure. +The following diagram illustrates the Microsoft Entra Verified ID architecture and the component you configure. ![Diagram that illustrates the Azure A D Verifiable Credentials architecture.](media/verifiable-credentials-configure-issuer/verifiable-credentials-architecture.png) ## Prerequisites -- [Set up a tenant for Azure AD Verifiable Credentials](./verifiable-credentials-configure-tenant.md). +- [Set up a tenant for Microsoft Entra Verified ID](./verifiable-credentials-configure-tenant.md). - To clone the repository that hosts the sample app, install [GIT](https://git-scm.com/downloads). - [Visual Studio Code](https://code.visualstudio.com/Download), or similar code editor. - [.NET 5.0](https://dotnet.microsoft.com/download/dotnet/5.0). @@ -47,7 +47,7 @@ The following diagram illustrates the Azure AD Verifiable Credentials architectu ## Create the verified credential expert card in Azure -In this step, you create the verified credential expert card by using Azure AD Verifiable Credentials. After you create the credential, your Azure AD tenant can issue it to users who initiate the process. +In this step, you create the verified credential expert card by using Microsoft Entra Verified ID. After you create the credential, your Azure AD tenant can issue it to users who initiate the process. 1. Using the [Azure portal](https://portal.azure.com/), search for *verifiable credentials*. Then select **Verifiable Credentials (Preview)**. 1. After you [set up your tenant](verifiable-credentials-configure-tenant.md), the **Create credential** should appear. Alternatively, you can select **Credentials** in the left hand menu and select **+ Add a credential**. @@ -111,13 +111,13 @@ In this step, you create the verified credential expert card by using Azure AD V ], "required": false } - ] - }, - "validityInterval": 2592000, - "vc": { - "type": [ - "VerifiedCredentialExpert" - ] + ], + "validityInterval": 2592000, + "vc": { + "type": [ + "VerifiedCredentialExpert" + ] + } } } ``` @@ -183,7 +183,7 @@ Now you'll make modifications to the sample app's issuer code to update it with 1. Under the *active-directory-verifiable-credentials-dotnet-main* folder, open Visual Studio Code, and select the project inside the *1-asp-net-core-api-idtokenhint* folder. -1. Under the project root folder, open the *appsettings.json* file. This file contains information about your Azure AD Verifiable Credentials. Update the following properties with the information that you recorded in earlier steps: +1. Under the project root folder, open the *appsettings.json* file. This file contains information about your Microsoft Entra Verified ID environment. Update the following properties with the information that you recorded in earlier steps: 1. **Tenant ID:** your tenant ID 1. **Client ID:** your client ID @@ -199,7 +199,7 @@ The following JSON demonstrates a complete *appsettings.json* file: ```json { "AppSettings": { - "Endpoint": "https://beta.did.msidentity.com/v1.0/{0}/verifiablecredentials/request", + "Endpoint": "https://verifiedid.did.msidentity.com/v1.0", "VCServiceScope": "3db474b9-6a0c-4840-96ac-1fceb342124f/.default", "Instance": "https://login.microsoftonline.com/{0}", "TenantId": "12345678-0000-0000-0000-000000000000", @@ -208,7 +208,7 @@ The following JSON demonstrates a complete *appsettings.json* file: "CertificateName": "[Or instead of client secret: Enter here the name of a certificate (from the user cert store) as registered with your application]", "IssuerAuthority": "did:web:example.com...", "VerifierAuthority": "did:web:example.com...", - "CredentialManifest": "https://beta.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredential/contracts/VerifiedCredentialExpert" + "CredentialManifest": "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredential/contracts/VerifiedCredentialExpert" } } ``` @@ -220,7 +220,9 @@ Now you're ready to issue your first verified credential expert card by running 1. From Visual Studio Code, run the *Verifiable_credentials_DotNet* project. Or, from your operating system's command line, run: ``` - cd active-directory-verifiable-credentials-dotnet/1-asp-net-core-api-idtokenhint dotnet build "AspNetCoreVerifiableCredentials.csproj" -c Debug -o .\\bin\\Debug\\netcoreapp3. dotnet run + cd active-directory-verifiable-credentials-dotnet/1-asp-net-core-api-idtokenhint + dotnet build "AspNetCoreVerifiableCredentials.csproj" -c Debug -o .\\bin\\Debug\\netcoreapp3. + dotnet run ``` 1. In another command prompt window, run the following command. This command runs [ngrok](https://ngrok.com/) to set up a URL on 5000, and make it publicly available on the internet. @@ -326,4 +328,3 @@ public async Task issuanceRequest() ## Next steps In the [next step](verifiable-credentials-configure-verifier.md), learn how a third-party application, also known as a relying party application, can verify your credentials with its own Azure AD tenant verifiable credentials API service. - diff --git a/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-tenant.md b/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-tenant.md index 91b22bd4edd96..589a846842554 100644 --- a/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-tenant.md +++ b/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-tenant.md @@ -1,5 +1,5 @@ --- -title: Tutorial - Configure your tenant for Azure AD Verifiable Credentials (preview) +title: Tutorial - Configure your tenant for Microsoft Entra Verified ID (preview) description: In this tutorial, you learn how to configure your tenant to support the Verifiable Credentials service. ms.service: decentralized-identity ms.subservice: verifiable-credentials @@ -12,11 +12,11 @@ ms.date: 06/27/2022 --- -# Configure your tenant for Azure AD Verifiable Credentials (preview) +# Configure your tenant for Microsoft Entra Verified ID (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] -Azure Active Directory (Azure AD) Verifiable Credentials safeguards your organization with an identity solution that's seamless and decentralized. The service allows you to issue and verify credentials. For issuers, Azure AD provides a service that they can customize and use to issue their own verifiable credentials. For verifiers, the service provides a free REST API that makes it easy to request and accept verifiable credentials in your apps and services. +Microsoft Entra Verified ID safeguards your organization with an identity solution that's seamless and decentralized. The service allows you to issue and verify credentials. For issuers, Azure AD provides a service that they can customize and use to issue their own verifiable credentials. For verifiers, the service provides a free REST API that makes it easy to request and accept verifiable credentials in your apps and services. In this tutorial, you learn how to configure your Azure AD tenant so it can use the verifiable credentials service. @@ -27,9 +27,9 @@ Specifically, you learn how to: > - Set up the Verifiable Credentials service. > - Register an application in Azure AD. -The following diagram illustrates the Azure AD Verifiable Credentials architecture and the component you configure. +The following diagram illustrates the Microsoft Entra Verified ID architecture and the component you configure. -![Diagram that illustrates the Azure AD Verifiable Credentials architecture.](media/verifiable-credentials-configure-tenant/verifiable-credentials-architecture.png) +![Diagram that illustrates the Microsoft Entra Verified ID architecture.](media/verifiable-credentials-configure-tenant/verifiable-credentials-architecture.png) ## Prerequisites @@ -41,14 +41,14 @@ The following diagram illustrates the Azure AD Verifiable Credentials architectu [Azure Key Vault](../../key-vault/general/basic-concepts.md) is a cloud service that enables the secure storage and access of secrets and keys. The Verifiable Credentials service stores public and private keys in Azure Key Vault. These keys are used to sign and verify credentials. -If you don't have an Azure Key Vault instance available, follow [these steps](../../key-vault/general/quick-create-portal.md) to create a key vault using the Azure portal. +If you don't have an Azure Key Vault instance available, follow [these steps](/azure/key-vault/general/quick-create-portal) to create a key vault using the Azure portal. >[!NOTE] >By default, the account that creates a vault is the only one with access. The Verifiable Credentials service needs access to the key vault. You must configure the key vault with an access policy that allows the account used during configuration to create and delete keys. The account used during configuration also requires permission to sign to create the domain binding for Verifiable Credentials. If you use the same account while testing, modify the default policy to grant the account sign permission, in addition to the default permissions granted to vault creators. ### Set access policies for the key vault -A Key Vault [access policy](../../key-vault/general/assign-access-policy.md) defines whether a specified security principal can perform operations on Key Vault secrets and keys. Set access policies in your key vault for both the Azure AD Verifiable Credentials service administrator account, and for the Request Service API principal that you created. +A Key Vault [access policy](../../key-vault/general/assign-access-policy.md) defines whether a specified security principal can perform operations on Key Vault secrets and keys. Set access policies in your key vault for both the Microsoft Entra Verified ID service administrator account, and for the Request Service API principal that you created. After you create your key vault, Verifiable Credentials generates a set of keys used to provide message security. These keys are stored in Key Vault. You use a key set for signing, updating, and recovering verifiable credentials. ### Set access policies for the Verifiable Credentials Admin user @@ -79,7 +79,7 @@ The Verifiable Credentials Service Request is the Request Service API, and it ne ## Set up Verifiable Credentials -To set up Azure AD Verifiable Credentials, follow these steps: +To set up Microsoft Entra Verified ID, follow these steps: 1. In the [Azure portal](https://portal.azure.com/), search for *verifiable credentials*. Then, select **Verifiable Credentials (Preview)**. @@ -108,7 +108,7 @@ To set up Azure AD Verifiable Credentials, follow these steps: ## Register an application in Azure AD -Azure AD Verifiable Credentials Service Request needs to get access tokens to issue and verify. To get access tokens, register a web application and grant API permission for the API Verifiable Credential Request Service that you set up in the previous step. +Microsoft Entra Verified ID needs to get access tokens to issue and verify. To get access tokens, register a web application and grant API permission for the API Verifiable Credential Request Service that you set up in the previous step. 1. Sign in to the [Azure portal](https://portal.azure.com/) with your administrative account. @@ -128,7 +128,7 @@ Azure AD Verifiable Credentials Service Request needs to get access tokens to is ### Grant permissions to get access tokens -In this step, you grant permissions to the Verifiable Credentials Service Request Service principal. +In this step, you grant permissions to the **Verifiable Credentials Service Request** Service principal. To add the required permissions, follow these steps: @@ -166,5 +166,5 @@ Once that you have successfully completed the verification steps, you are ready ## Next steps -- [Learn how to issue Azure AD Verifiable Credentials from a web application](verifiable-credentials-configure-issuer.md). -- [Learn how to verify Azure AD Verifiable Credentials](verifiable-credentials-configure-verifier.md). \ No newline at end of file +- [Learn how to issue Microsoft Entra Verified ID credentials from a web application](verifiable-credentials-configure-issuer.md). +- [Learn how to verify Microsoft Entra Verified ID credentials](verifiable-credentials-configure-verifier.md). \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-verifier.md b/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-verifier.md index 553784310a7cb..f17a9ca940b81 100644 --- a/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-verifier.md +++ b/articles/active-directory/verifiable-credentials/verifiable-credentials-configure-verifier.md @@ -1,5 +1,5 @@ --- -title: Tutorial - Configure Azure AD Verifiable Credentials verifier (preview) +title: Tutorial - Configure Microsoft Entra Verified ID verifier (preview) description: In this tutorial, you learn how to configure your tenant to verify credentials. ms.service: decentralized-identity ms.subservice: verifiable-credentials @@ -12,11 +12,11 @@ ms.date: 06/16/2022 --- -# Configure Azure AD Verifiable Credentials verifier (preview) +# Configure Microsoft Entra Verified ID verifier (preview) [!INCLUDE [Verifiable Credentials announcement](../../../includes/verifiable-credentials-brand.md)] -In [Issue Azure AD Verifiable Credentials from an application (preview)](verifiable-credentials-configure-issuer.md), you learn how to issue and verify credentials by using the same Azure Active Directory (Azure AD) tenant. In this tutorial, you go over the steps needed to present and verify your first verifiable credential: a verified credential expert card. +In [Issue Microsoft Entra Verified ID credentials from an application (preview)](verifiable-credentials-configure-issuer.md), you learn how to issue and verify credentials by using the same Azure Active Directory (Azure AD) tenant. In this tutorial, you go over the steps needed to present and verify your first verifiable credential: a verified credential expert card. As a verifier, you unlock privileges to subjects that possess verified credential expert cards. In this tutorial, you run a sample application from your local computer that asks you to present a verified credential expert card, and then verifies it. @@ -25,13 +25,13 @@ In this article, you learn how to: > [!div class="checklist"] > > - Download the sample application code to your local computer -> - Set up Azure AD Verifiable Credentials on your Azure AD tenant +> - Set up Microsoft Entra Verified ID on your Azure AD tenant > - Gather credentials and environment details to set up your sample application, and update the sample application with your verified credential expert card details > - Run the sample application and initiate a verifiable credential issuance process ## Prerequisites -- [Set up a tenant for Azure AD Verifiable Credentials](verifiable-credentials-configure-tenant.md). +- [Set up a tenant for Microsoft Entra Verified ID](verifiable-credentials-configure-tenant.md). - If you want to clone the repository that hosts the sample app, install [Git](https://git-scm.com/downloads). - [Visual Studio Code](https://code.visualstudio.com/Download) or similar code editor. - [.NET 5.0](https://dotnet.microsoft.com/download/dotnet/5.0). @@ -42,7 +42,7 @@ In this article, you learn how to: ## Gather tenant details to set up your sample application -Now that you've set up your Azure AD Verifiable Credentials service, you're going to gather some information about your environment and the verifiable credentials you set. You use these pieces of information when you set up your sample application. +Now that you've set up your Microsoft Entra Verified ID service, you're going to gather some information about your environment and the verifiable credentials you set. You use these pieces of information when you set up your sample application. 1. From **Verifiable credentials (Preview)**, select **Organization settings**. 1. Copy the **Tenant identifier** value, and record it for later. @@ -50,7 +50,7 @@ Now that you've set up your Azure AD Verifiable Credentials service, you're goin The following screenshot demonstrates how to copy the required values: -![Screenshot that demonstrates how to copy the required values from Azure AD Verifiable Credentials.](media/verifiable-credentials-configure-verifier/tenant-settings.png) +![Screenshot that demonstrates how to copy the required values from Microsoft Entra Verified ID.](media/verifiable-credentials-configure-verifier/tenant-settings.png) ## Download the sample code @@ -92,7 +92,7 @@ Now make modifications to the sample app's issuer code to update it with your ve 1. In the *active-directory-verifiable-credentials-dotnet-main* directory, open **Visual Studio Code**. Select the project inside the *1. asp-net-core-api-idtokenhint* directory. -1. Under the project root folder, open the *appsettings.json* file. This file contains information about your credentials in Azure AD Verifiable Credentials. Update the following properties with the information that you collected during earlier steps. +1. Under the project root folder, open the *appsettings.json* file. This file contains information about your credentials in Microsoft Entra Verified ID environment. Update the following properties with the information that you collected during earlier steps. 1. **Tenant ID**: Your tenant ID 1. **Client ID**: Your client ID @@ -108,14 +108,14 @@ The following JSON demonstrates a complete *appsettings.json* file: { "AppSettings": { - "Endpoint": "https://beta.did.msidentity.com/v1.0/{0}/verifiablecredentials/request", - "VCServiceScope": "bbb94529-53a3-4be5-a069-7eaf2712b826/.default", + "Endpoint": "https://verifiedid.did.msidentity.com/v1.0", + "VCServiceScope": "3db474b9-6a0c-4840-96ac-1fceb342124f/.default", "Instance": "https://login.microsoftonline.com/{0}", "TenantId": "987654321-0000-0000-0000-000000000000", "ClientId": "555555555-0000-0000-0000-000000000000", "ClientSecret": "123456789012345678901234567890", "VerifierAuthority": "did:ion:EiDJzvzaBMb_EWTWUFEasKzL2nL-BJPhQTzYWjA_rRz3hQ:eyJkZWx0YSI6eyJwYXRjaGVzIjpbeyJhY3Rpb24iOiJyZXBsYWNlIiwiZG9jdW1lbnQiOnsicHVibGljS2V5cyI6W3siaWQiOiJzaWdfMmNhMzY2YmUiLCJwdWJsaWNLZXlKd2siOnsiY3J2Ijoic2VjcDI1NmsxIiwia3R5IjoiRUMiLCJ4IjoiZDhqYmduRkRGRElzR1ZBTWx5aDR1b2RwOGV4Q2dpV3dWUGhqM0N...", - "CredentialManifest": " https://beta.did.msidentity.com/v1.0/987654321-0000-0000-0000-000000000000/verifiableCredential/contracts/VerifiedCredentialExpert" + "CredentialManifest": " https://verifiedid.did.msidentity.com/v1.0/987654321-0000-0000-0000-000000000000/verifiableCredential/contracts/VerifiedCredentialExpert" } } ``` @@ -127,14 +127,15 @@ Now you are ready to present and verify your first verified credential expert ca 1. From Visual Studio Code, run the *Verifiable_credentials_DotNet* project. Or from the command shell, run the following commands: ```bash - cd active-directory-verifiable-credentials-dotnet/1. asp-net-core-api-idtokenhint dotnet build "asp-net-core-api-idtokenhint.csproj" -c Debug -o .\bin\Debug\netcoreapp3.1 + cd active-directory-verifiable-credentials-dotnet/1. asp-net-core-api-idtokenhint + dotnet build "asp-net-core-api-idtokenhint.csproj" -c Debug -o .\bin\Debug\netcoreapp3.1 dotnet run ``` -1. In another terminal, run the following command. This command runs the [ngrok](https://ngrok.com/) to set up a URL on 3000 and make it publicly available on the internet. +1. In another terminal, run the following command. This command runs the [ngrok](https://ngrok.com/) to set up a URL on 5000 and make it publicly available on the internet. ```bash - ngrok http 3000 + ngrok http 5000 ``` >[!NOTE] @@ -181,4 +182,4 @@ Now you are ready to present and verify your first verified credential expert ca ## Next steps -Learn [how to customize your verifiable credentials](credential-design.md). +Learn [how to customize your verifiable credentials](credential-design.md). \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/verifiable-credentials-faq.md b/articles/active-directory/verifiable-credentials/verifiable-credentials-faq.md index 477309ea67804..c10e47216e8c7 100644 --- a/articles/active-directory/verifiable-credentials/verifiable-credentials-faq.md +++ b/articles/active-directory/verifiable-credentials/verifiable-credentials-faq.md @@ -179,7 +179,7 @@ Resetting requires that you opt out and opt back into the Azure Active Directory 1. In the [Azure portal](https://portal.azure.com), go to Azure Active Directory for the subscription you use for your Azure Active Directory Verifiable credentials deployment. 1. Under Manage, select Properties :::image type="content" source="media/verifiable-credentials-faq/region.png" alt-text="settings delete and opt out"::: -1. See the value for Country or Region. If the value is a country or a region in Europe, your Azure AD Verifiable Credentials service will be set up in Europe. +1. See the value for Country or Region. If the value is a country or a region in Europe, your Microsoft Entra Verified ID service will be set up in Europe. ### How can I check if my tenant has the new Hub endpoint? @@ -205,7 +205,7 @@ Resetting requires that you opt out and opt back into the Azure Active Directory "type": "IdentityHub", "serviceEndpoint": { "instances": [ - "https://beta.hub.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000" + "https://verifiedid.hub.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000" ], "origins": [] } @@ -223,4 +223,4 @@ No, at this point it isn't possible to keep your tenant's DID after you have opt ## Next steps -- [How to customize your Azure Active Directory Verifiable Credentials](credential-design.md) +- [How to customize your Azure Active Directory Verifiable Credentials](credential-design.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/verifiable-credentials-standards.md b/articles/active-directory/verifiable-credentials/verifiable-credentials-standards.md index 2ea4ccbb5b5f4..2526952fcaa62 100644 --- a/articles/active-directory/verifiable-credentials/verifiable-credentials-standards.md +++ b/articles/active-directory/verifiable-credentials/verifiable-credentials-standards.md @@ -61,4 +61,4 @@ Today, we have a working JWT verifiable credentials presentation profile that su ## Next steps -- [Get started with verifiable credentials](verifiable-credentials-configure-tenant.md) +- [Get started with verifiable credentials](verifiable-credentials-configure-tenant.md) \ No newline at end of file diff --git a/articles/active-directory/verifiable-credentials/whats-new.md b/articles/active-directory/verifiable-credentials/whats-new.md index 932324fb640c7..30fec747a8cc1 100644 --- a/articles/active-directory/verifiable-credentials/whats-new.md +++ b/articles/active-directory/verifiable-credentials/whats-new.md @@ -6,7 +6,7 @@ manager: rkarlin ms.service: decentralized-identity ms.subservice: verifiable-credentials ms.topic: reference -ms.date: 06/27/2022 +ms.date: 07/28/2022 ms.custom: references_regions ms.author: barclayn @@ -20,6 +20,20 @@ ms.author: barclayn This article lists the latest features, improvements, and changes in the Microsoft Entra Verified ID service. +## July 2022 + +- The Request Service APIs have a **new hostname** `verifiedid.did.msidentity.com`. The `beta.did.msidentity` and the `beta.eu.did.msidentity` will continue to work, but you should change your application and configuration. Also, you no longer need to specify `.eu.` for an EU tenant. +- Request Service API have **new endpoints** and **updated JSON payloads**. For issuance, see [Issuance API specification](issuance-request-api.md#issuance-request-payload) and for presentation, see [Presentation API specification](presentation-request-api.md#presentation-request-payload). The old endpoints and JSON payloads will continue to work, but you should change your applications to use the new endpoints and payloads. +- Request Service API **[Error codes](error-codes.md)** have been **updated** +- The **[Admin API](admin-api.md)** is made **public** and is documented. The Azure portal is using the Admin API and with this REST API you can automate the onboarding or your tenant and creation of credential contracts. +- Find issuers and credentials to verify via the [The Microsoft Entra Verified ID Network](how-use-vcnetwork.md). +- For migrating your Azure Storage based credentials to become Managed Credentials there is a PowerShell script in the [github samples repo](https://github.com/Azure-Samples/active-directory-verifiable-credentials/tree/contractmigration/scripts/contractmigration) for the task. + +- We also made the following updates to our Plan and design docs: + - (updated) [architecture planning overview](introduction-to-verifiable-credentials-architecture.md). + - (updated) [Plan your issuance solution](plan-issuance-solution.md). + - (updated) [Plan your verification solution](plan-verification-solution.md). + ## June 2022 - We are adding support for the [did:web](https://w3c-ccg.github.io/did-method-web/) method. Any new tenant that starts using the Verifiable Credentials Service after June 14, 2022 will have Web as a new, default, trust system when [onboarding](verifiable-credentials-configure-tenant.md#set-up-verifiable-credentials). VC Administrators can still choose to use ION when setting a tenant. If you want to use did:web instead of ION or viceversa, you will need to [reconfigure your tenant](verifiable-credentials-faq.md?#how-do-i-reset-the-azure-ad-verifiable-credentials-service). @@ -32,12 +46,12 @@ This article lists the latest features, improvements, and changes in the Microso > You need to migrate your Azure Storage based credentials to become Managed Credentials. We'll soon provide migration instructions. - We made the following updates to our docs: - - (new) [Current supported open standards for Microsoft Entra Verified ID](verifiable-credentials-standards.md). - - (new) [How to create verifiable credentials for ID token hint](how-to-use-quickstart.md). - - (new) [How to create verifiable credentials for ID token](how-to-use-quickstart-idtoken.md). - - (new) [How to create verifiable credentials for self-asserted claims](how-to-use-quickstart-selfissued.md). - - (new) [Rules and Display definition model specification](rules-and-display-definitions-model.md). - - (new) [Creating an Azure AD tenant for development](how-to-create-a-free-developer-account.md). + - (new) [Current supported open standards for Microsoft Entra Verified ID](verifiable-credentials-standards.md). + - (new) [How to create verifiable credentials for ID token hint](how-to-use-quickstart.md). + - (new) [How to create verifiable credentials for ID token](how-to-use-quickstart-idtoken.md). + - (new) [How to create verifiable credentials for self-asserted claims](how-to-use-quickstart-selfissued.md). + - (new) [Rules and Display definition model specification](rules-and-display-definitions-model.md). + - (new) [Creating an Azure AD tenant for development](how-to-create-a-free-developer-account.md). ## May 2022 @@ -159,4 +173,4 @@ It's a good idea to start using the API soon, because the NodeJS SDK will be dep ## April 2021 -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. +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. \ No newline at end of file diff --git a/articles/advisor/advisor-cost-recommendations.md b/articles/advisor/advisor-cost-recommendations.md index bbdacb8ed69ec..d398680f87c95 100644 --- a/articles/advisor/advisor-cost-recommendations.md +++ b/articles/advisor/advisor-cost-recommendations.md @@ -26,9 +26,9 @@ Advisor uses machine-learning algorithms to identify low utilization and to iden Advisor identifies resources that have not been used at all over the last 7 days and makes a recommendation to shut them down. -- Metrics considered are CPU and Outbound Network utilization (memory is not considered for shutdown recommendations since we’ve found that relying on CPU and Network provide enough signals for this recommendation) -- The last 7 days of utilization data are considered -- Metrics are sampled every 30 seconds, aggregated to 1 min and then further aggregated to 30 mins (we take the average of max values while aggregating to 30 mins) +- Recommendation criteria include **CPU** and **Outbound Network utilization** metrics. **Memory** is not considered since we’ve found that **CPU** and **Outbound Network utilization** are sufficient. +- The last 7 days of utilization data are analyzed +- Metrics are sampled every 30 seconds, aggregated to 1 min and then further aggregated to 30 mins (we take the max of average values while aggregating to 30 mins) - A shutdown recommendation is created if: - P95th of the maximum value of CPU utilization summed across all cores is less than 3%. - P100 of average CPU in last 3 days (sum over all cores) <= 2% @@ -36,11 +36,11 @@ Advisor identifies resources that have not been used at all over the last 7 days ### Resize SKU recommendations -Advisor considers resizing virtual machines when it's possible to fit the current load on a more appropriate SKU, which costs less than the current one (we currently consider retail rates only during recommendation generation). +Advisor recommends resizing virtual machines when it's possible to fit the current load on a more appropriate SKU, which is less expensive (based on retail rates). -- Metrics considered are CPU, Memory and Outbound Network utilization -- The last 7 days of utilization data are considered -- Metrics are sampled every 30 seconds, aggregated to 1 min and then further aggregated to 30 mins (we take the average of max values while aggregating to 30 mins) +- Recommendation criteria include **CPU**, **Memory** and **Outbound Network utilization**. +- The last 7 days of utilization data are analyzed +- Metrics are sampled every 30 seconds, aggregated to 1 min and then further aggregated to 30 mins (we take the max of average values while aggregating to 30 mins) - An appropriate SKU is determined based on the following criteria: - Performance of the workloads on the new SKU should not be impacted. - Target for user-facing workloads: @@ -52,15 +52,15 @@ Advisor considers resizing virtual machines when it's possible to fit the curren - The new SKU has the same Accelerated Networking and Premium Storage capabilities - The new SKU is supported in the current region of the Virtual Machine with the recommendation - The new SKU is less expensive -- Advisor determines the type of workload (user-facing/non user-facing) by analyzing the CPU utilization characteristics of the workload. This is based on some fascinating findings by Microsoft Research. You can find more details here: [Prediction-Based Power Oversubscription in Cloud Platforms - Microsoft Research](https://www.microsoft.com/research/publication/prediction-based-power-oversubscription-in-cloud-platforms/). -- Advisor recommends not just smaller SKUs in the same family (for example D3v2 to D2v2) but also SKUs in a newer version (for example D3v2 to D2v3) or even a completely different family (for example D3v2 to E3v2) based on the best fit and the cheapest costs with no performance impacts. +- Advisor determines if a workload is user-facing by analyzing its CPU utilization characteristics. The approach is based on findings by Microsoft Research. You can find more details here: [Prediction-Based Power Oversubscription in Cloud Platforms - Microsoft Research](https://www.microsoft.com/research/publication/prediction-based-power-oversubscription-in-cloud-platforms/). +- Advisor recommends not just smaller SKUs in the same family (for example D3v2 to D2v2) but also SKUs in a newer version (for example D3v2 to D2v3) or a different family (for example D3v2 to E3v2) based on the best fit and the cheapest costs with no performance impacts. ### Burstable recommendations -This is a special type of resize recommendation, where Advisor analyzes workloads to determine eligibility to run on specialized SKUs called Burstable SKUs that allow for variable workload performance requirements and are generally cheaper than general purpose SKUs. Learn more about burstable SKUs here: [B-series burstable - Azure Virtual Machines](../virtual-machines/sizes-b-series-burstable.md). +We evaluate is workloads are eligible to run on specialized SKUs called **Burstable SKUs** that support variable workload performance requirements and are less expensive than general purpose SKUs. Learn more about burstable SKUs here: [B-series burstable - Azure Virtual Machines](../virtual-machines/sizes-b-series-burstable.md). - A burstable SKU recommendation is made if: -- The average CPU utilization is less than a burstable SKUs' baseline performance +- The average **CPU utilization** is less than a burstable SKUs' baseline performance - If the P95 of CPU is less than two times the burstable SKUs' baseline performance - If the current SKU does not have accelerated networking enabled (burstable SKUs don’t support accelerated networking yet) - If we determine that the Burstable SKU credits are sufficient to support the average CPU utilization over 7 days diff --git a/articles/advisor/advisor-reference-operational-excellence-recommendations.md b/articles/advisor/advisor-reference-operational-excellence-recommendations.md index 93aeaf3f8f774..6314eafebb3d7 100644 --- a/articles/advisor/advisor-reference-operational-excellence-recommendations.md +++ b/articles/advisor/advisor-reference-operational-excellence-recommendations.md @@ -23,17 +23,17 @@ You can get these recommendations on the **Operational Excellence** tab of the A ## Spring Cloud -### Update your outdated Azure Spring Cloud SDK to the latest version +### Update your outdated Azure Spring Apps SDK to the latest version -We have identified API calls from an outdated Azure Spring Cloud SDK. We recommend upgrading to the latest version for the latest fixes, performance improvements, and new feature capabilities. +We have identified API calls from an outdated Azure Spring Apps SDK. We recommend upgrading to the latest version for the latest fixes, performance improvements, and new feature capabilities. -Learn more about [Spring Cloud Service - SpringCloudUpgradeOutdatedSDK (Update your outdated Azure Spring Cloud SDK to the latest version)](../spring-cloud/index.yml). +Learn more about [Spring Cloud Service - SpringCloudUpgradeOutdatedSDK (Update your outdated Azure Spring Apps SDK to the latest version)](../spring-apps/index.yml). -### Update Azure Spring Cloud API Version +### Update Azure Spring Apps API Version -We have identified API calls from outdated Azure Spring Cloud API for resources under this subscription. We recommend switching to the latest Spring Cloud API version. You need to update your existing code to use the latest API version. Also, you need to upgrade your Azure SDK and Azure CLI to the latest version. This ensures you receive the latest features and performance improvements. +We have identified API calls from outdated Azure Spring Apps API for resources under this subscription. We recommend switching to the latest Spring Cloud API version. You need to update your existing code to use the latest API version. Also, you need to upgrade your Azure SDK and Azure CLI to the latest version. This ensures you receive the latest features and performance improvements. -Learn more about [Spring Cloud Service - UpgradeAzureSpringCloudAPI (Update Azure Spring Cloud API Version)](../spring-cloud/index.yml). +Learn more about [Spring Cloud Service - UpgradeAzureSpringCloudAPI (Update Azure Spring Apps API Version)](../spring-apps/index.yml). ## Automation diff --git a/articles/advisor/advisor-reference-performance-recommendations.md b/articles/advisor/advisor-reference-performance-recommendations.md index f7da3198b68f2..1ee2d4ddb3829 100644 --- a/articles/advisor/advisor-reference-performance-recommendations.md +++ b/articles/advisor/advisor-reference-performance-recommendations.md @@ -814,12 +814,6 @@ We have detected that you do not have up-to-date table statistics which may be i Learn more about [SQL data warehouse - UpdateTableStatisticsSqlDW (Update statistics on table columns)](https://aka.ms/learnmorestatistics). -### Right-size overutilized SQL Databases - -We've analyzed the DTU consumption of your SQL Database over the past 14 days and identified SQL Databases with high usage. You can improve your database performance by right-sizing to the recommended SKU based on the 95th percentile of your everyday workload - -Learn more about [SQL database - sqlRightsizePerformance (Right-size overutilized SQL Databases)](https://aka.ms/SQLDBrecommendation). - ### Scale up to optimize cache utilization with SQL Data Warehouse We have detected that you had high cache used percentage with a low hit percentage. This indicates high cache eviction which can impact the performance of your workload. diff --git a/articles/aks/kubernetes-service-principal.md b/articles/aks/kubernetes-service-principal.md index 02308f193943b..e2121b22c8e0d 100644 --- a/articles/aks/kubernetes-service-principal.md +++ b/articles/aks/kubernetes-service-principal.md @@ -241,6 +241,10 @@ ls -la $HOME/.azure/aksServicePrincipal.json The default expiration time for the service principal credentials is one year. If your *aksServicePrincipal.json* file is older than one year, delete the file and retry deploying the AKS cluster. +**General Azure CLI troubleshooting** + +[!INCLUDE [azure-cli-troubleshooting.md](../../includes/azure-cli-troubleshooting.md)] + ### [Azure PowerShell](#tab/azure-powershell) The service principal credentials for an AKS cluster are cached by Azure PowerShell. If these credentials have expired, you encounter errors during deployment of the AKS cluster. The following error message when running [New-AzAksCluster][new-azakscluster] may indicate a problem with the cached service principal credentials: diff --git a/articles/aks/learn/quick-kubernetes-deploy-cli.md b/articles/aks/learn/quick-kubernetes-deploy-cli.md index ec926d0eba586..b826d89f1d932 100644 --- a/articles/aks/learn/quick-kubernetes-deploy-cli.md +++ b/articles/aks/learn/quick-kubernetes-deploy-cli.md @@ -81,10 +81,10 @@ The following output example resembles successful creation of the resource group ## Create AKS cluster -Create an AKS cluster using the [az aks create][az-aks-create] command with the *--enable-addons monitoring* parameter to enable [Container insights][azure-monitor-containers]. The following example creates a cluster named *myAKSCluster* with one node and enables a system-assigned managed identity: +Create an AKS cluster using the [az aks create][az-aks-create] command with the `--enable-addons monitoring` and `--enable-msi-auth-for-monitoring` parameter to enable [Azure Monitor Container insights][azure-monitor-containers] with managed identity authentication (preview). The following example creates a cluster named *myAKSCluster* with one node and enables a system-assigned managed identity: ```azurecli-interactive -az aks create -g myResourceGroup -n myAKSCluster --enable-managed-identity --node-count 1 --enable-addons monitoring +az aks create -g myResourceGroup -n myAKSCluster --enable-managed-identity --node-count 1 --enable-addons monitoring --enable-msi-auth-for-monitoring --generate-ssh-keys ``` After a few minutes, the command completes and returns JSON-formatted information about the cluster. diff --git a/articles/app-service/configure-connect-to-azure-storage.md b/articles/app-service/configure-connect-to-azure-storage.md index 0415dd4c0049b..44b0dd4a7f136 100644 --- a/articles/app-service/configure-connect-to-azure-storage.md +++ b/articles/app-service/configure-connect-to-azure-storage.md @@ -106,6 +106,7 @@ The following features are supported for Linux containers: - Mapping `/mounts`, `mounts/foo/bar`, `/`, and `/mounts/foo.bar/` to custom-mounted storage is not supported (you can only use /mounts/pathname for mounting custom storage to your web app.) - Storage mounts cannot be used together with clone settings option during [deployment slot](deploy-staging-slots.md) creation. - Storage mounts are not backed up when you [back up your app](manage-backup.md). Be sure to follow best practices to back up the Azure Storage accounts. +- Only Azure Files [SMB](/azure/storage/files/files-smb-protocol) are supported. Azure Files [NFS](/azure/storage/files/files-nfs-protocol) is not currently supported for Linux App Services. ::: zone-end @@ -212,12 +213,6 @@ Verify your storage is mounted by running the following command: az webapp config storage-account list --resource-group --name ``` -Verify your configuration by running the following command: - -```azurecli -az webapp config storage-account list --resource-group --name -``` - --- > [!NOTE] diff --git a/articles/app-service/deploy-ftp.md b/articles/app-service/deploy-ftp.md index 453df3782b2c0..ea0bd52625d88 100644 --- a/articles/app-service/deploy-ftp.md +++ b/articles/app-service/deploy-ftp.md @@ -42,7 +42,7 @@ In the same management page for your app where you copied the deployment credent # [Azure CLI](#tab/cli) -Run the [az webapp deployment list-publishing-profiles](/cli/azure/webapp/deployment#az-webapp-deployment-list-publishing-profiles) command. The following example uses a [JMES path](https://jmespath.org/) to extract the FTP/S endpoints from the output. +Run the [az webapp deployment list-publishing-profiles](/cli/azure/webapp/deployment#az-webapp-deployment-list-publishing-profiles) command. The following example uses a [JMESPath query](/cli/azure/query-azure-cli) to extract the FTP/S endpoints from the output. ```azurecli-interactive az webapp deployment list-publishing-profiles --name --resource-group --query "[?ends_with(profileName, 'FTP')].{profileName: profileName, publishUrl: publishUrl}" diff --git a/articles/app-service/environment/networking.md b/articles/app-service/environment/networking.md index 9d575afc4ab41..e7b6f34db80e0 100644 --- a/articles/app-service/environment/networking.md +++ b/articles/app-service/environment/networking.md @@ -3,7 +3,7 @@ title: App Service Environment networking description: App Service Environment networking details author: madsd ms.topic: overview -ms.date: 02/17/2022 +ms.date: 08/01/2022 ms.author: madsd --- @@ -83,6 +83,9 @@ You can put your web application firewall devices, such as Azure Application Gat Your application will use one of the default outbound addresses for egress traffic to public endpoints. If you want to customize the outbound address of your applications on an App Service Environment, you can add a NAT gateway to your subnet. +> [!NOTE] +> Outbound SMTP connectivity (port 25) is supported for App Service Environment v3. However, the supportability is determined by the subscription where the virtual network is deployed. For virtual networks created before 1. August 2022, you will have to re-enable outbound SMTP connectivity support on the subscription. For more information on subscription type support and how to request support to re-enable outbound SMTP connectivity, see [Troubleshoot outbound SMTP connectivity problems in Azure](../../virtual-network/troubleshoot-outbound-smtp-connectivity.md). + ## Private endpoint In order to enable Private Endpoints for apps hosted in your App Service Environment, you must first enable this feature at the App Service Environment level. @@ -96,7 +99,6 @@ az appservice ase update --name myasename --allow-new-private-endpoint-connectio For more information about Private Endpoint and Web App, see [Azure Web App Private Endpoint][privateendpoint] - ## DNS The following sections describe the DNS considerations and configuration that apply inbound to and outbound from your App Service Environment. @@ -137,10 +139,7 @@ The apps in your App Service Environment will use the DNS that your virtual netw ## Limitations -While App Service Environment does deploy into your virtual network, there are a few networking features that aren't available: - -* Sending SMTP traffic. Although you can still have email-triggered alerts, your app can't send outbound traffic on port 25. -* Using Azure Network Watcher or NSG flow to monitor outbound traffic. +While App Service Environment does deploy into your virtual network, you currently cannot use Azure Network Watcher or NSG flow to monitor outbound traffic. ## More resources diff --git a/articles/app-service/environment/overview.md b/articles/app-service/environment/overview.md index 388bc6092a5d5..4327329163ec7 100644 --- a/articles/app-service/environment/overview.md +++ b/articles/app-service/environment/overview.md @@ -3,7 +3,7 @@ title: App Service Environment overview description: This article discusses the Azure App Service Environment feature of Azure App Service. author: madsd ms.topic: overview -ms.date: 06/30/2022 +ms.date: 07/28/2022 ms.author: madsd ms.custom: references_regions --- @@ -15,7 +15,6 @@ An App Service Environment is an Azure App Service feature that provides a fully > [!NOTE] > This article covers the features, benefits, and use cases of App Service Environment v3, which is used with App Service Isolated v2 plans. > - An App Service Environment can host your: - Windows web apps @@ -96,40 +95,47 @@ Reserved Instance pricing for Isolated v2 is available and is described in [How App Service Environment v3 is available in the following regions: -| Normal and dedicated host regions | Availability zone regions | -|---|---| -| Australia East | Australia East | -| Australia Southeast | Brazil South | -| Brazil South | Canada Central | -| Canada Central | Central India | -| Canada East | Central US | -| Central India | East Asia | -| Central US | East US | -| East Asia | East US 2 | -| East US | France Central | -| East US 2 | Germany West Central | -| France Central | Japan East | -| Germany West Central | Korea Central | -| Japan East | North Europe | -| Korea Central | Norway East | -| North Central US | South Africa North | -| North Europe | South Central US | -| Norway East | Southeast Asia | -| South Africa North | UK South | -| South Central US | West Europe | -| Southeast Asia | West US 2 | -| Switzerland North | West US 3 | -| UAE North | | -| UK South | | -| UK West | | -| West Central US | | -| West Europe | | -| West US | | -| West US 2 | | -| West US 3 | | -| US Gov Texas | | -| US Gov Arizona | | -| US Gov Virginia | | +### Azure Public: + +| Region | Normal and dedicated host | Availability zone support | +| -------------------- | :-------------------------: | :-------------------------: | +| Australia East | x | x | +| Australia Southeast | x | | +| Brazil South | x | x | +| Canada Central | x | x | +| Canada East | x | | +| Central India | x | x | +| Central US | x | x | +| East Asia | x | x | +| East US | x | x | +| East US 2 | x | x | +| France Central | x | x | +| Germany West Central | x | x | +| Japan East | x | x | +| Korea Central | x | x | +| North Central US | x | | +| North Europe | x | x | +| Norway East | x | x | +| South Africa North | x | x | +| South Central US | x | x | +| Southeast Asia | x | x | +| Switzerland North | x | | +| UAE North | x | | +| UK South | x | x | +| UK West | x | | +| West Central US | x | | +| West Europe | x | x | +| West US | x | | +| West US 2 | x | x | +| West US 3 | x | x | + +### Azure Government: + +| Region | Normal and dedicated host | Availability zone support | +| -------------------- | :-------------------------: | :-------------------------: | +| US Gov Texas | x | | +| US Gov Arizona | x | | +| US Gov Virginia | x | | ## App Service Environment v2 @@ -138,4 +144,4 @@ App Service Environment has three versions: App Service Environment v1, App Serv ## Next steps > [!div class="nextstepaction"] -> [Whitepaper on Using App Service Environment v3 in Compliance-Oriented Industries](https://azure.microsoft.com/resources/using-app-service-environment-v3-in-compliance-oriented-industries/) \ No newline at end of file +> [Whitepaper on Using App Service Environment v3 in Compliance-Oriented Industries](https://azure.microsoft.com/resources/using-app-service-environment-v3-in-compliance-oriented-industries/) diff --git a/articles/app-service/environment/using-an-ase.md b/articles/app-service/environment/using-an-ase.md index 73cd7f8577f18..6355c05a59a9e 100644 --- a/articles/app-service/environment/using-an-ase.md +++ b/articles/app-service/environment/using-an-ase.md @@ -78,7 +78,7 @@ To create an app in an ASE: Every App Service app runs in an App Service plan. App Service Environments hold App Service plans, and App Service plans hold apps. When you scale an app, you also scale the App Service plan and all the apps in that same plan. -When you scale an App Service plan, the needed infrastructure is added automatically. There's a time delay to scale operations while the infrastructure is being added. If you do several scale operations in sequence, the first infrastructure scale request is acted on and the others are queued. When the first scale operation finishes, the other infrastructure requests all operate together. And when the infrastructure is added, the App Service plans are assigned as appropriate. Creating a new App Service plan is itself a scale operation because it requests additional hardware. +When you scale an App Service plan, the needed infrastructure is added automatically. There's a time delay to scale operations while the infrastructure is being added. If you do several scale operations in sequence, the first infrastructure scale request is acted on and the others are queued. When the first scale operation finishes, the other infrastructure requests all operate together. And when the infrastructure is added, the App Service plans are assigned as appropriate. Creating a new App Service plan is itself a scale operation because it requests additional hardware. A scale operation usually takes 30-60 minutes to complete. In the multitenant App Service, scaling is immediate because a pool of resources is readily available to support it. In an ASE, there's no such buffer, and resources are allocated based on need. diff --git a/articles/app-service/includes/quickstart-java/quickstart-java-linux-azure-portal-pivot.md b/articles/app-service/includes/quickstart-java/quickstart-java-linux-azure-portal-pivot.md index 682a66dcfb90c..504e82fcaacf1 100644 --- a/articles/app-service/includes/quickstart-java/quickstart-java-linux-azure-portal-pivot.md +++ b/articles/app-service/includes/quickstart-java/quickstart-java-linux-azure-portal-pivot.md @@ -69,7 +69,7 @@ To complete this quickstart you need: # [JBoss EAP](#tab/jbosseap) -1. In your browser, navigate to the repository containing [the sample code](https://github.com/agoncal/agoncall-application-petstore-ee7). +1. In your browser, navigate to the repository containing [the sample code](https://github.com/agoncal/agoncal-application-petstore-ee7). 1. In the upper right corner, select **Fork**. diff --git a/articles/app-service/overview-vnet-integration.md b/articles/app-service/overview-vnet-integration.md index 94d8b5b86e8cd..c4a5f60555980 100644 --- a/articles/app-service/overview-vnet-integration.md +++ b/articles/app-service/overview-vnet-integration.md @@ -3,7 +3,7 @@ title: Integrate your app with an Azure virtual network description: Integrate your app in Azure App Service with Azure virtual networks. author: madsd ms.topic: conceptual -ms.date: 06/30/2022 +ms.date: 08/01/2022 ms.author: madsd --- @@ -86,24 +86,20 @@ Through application routing or configuration routing options, you can configure Application routing applies to traffic that is sent from your app after it has been started. See [configuration routing](#configuration-routing) for traffic during start up. When you configure application routing, you can either route all traffic or only private traffic (also known as [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918#section-3) traffic) into your virtual network. You configure this behavior through the **Route All** setting. If **Route All** is disabled, your app only routes private traffic into your virtual network. If you want to route all your outbound app traffic into your virtual network, make sure that **Route All** is enabled. -> [!NOTE] -> * Only traffic configured in application or configuration routing is subject to the NSGs and UDRs that are applied to your integration subnet. -> * When **Route All** is enabled, outbound traffic from your app is still sent from the addresses that are listed in your app properties, unless you provide routes that direct the traffic elsewhere. +* Only traffic configured in application or configuration routing is subject to the NSGs and UDRs that are applied to your integration subnet. +* When **Route All** is enabled, outbound traffic from your app is still sent from the addresses that are listed in your app properties, unless you provide routes that direct the traffic elsewhere. Learn [how to configure application routing](./configure-vnet-integration-routing.md). We recommend that you use the **Route All** configuration setting to enable routing of all traffic. Using the configuration setting allows you to audit the behavior with [a built-in policy](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2Fproviders%2FMicrosoft.Authorization%2FpolicyDefinitions%2F33228571-70a4-4fa1-8ca1-26d0aba8d6ef). The existing `WEBSITE_VNET_ROUTE_ALL` app setting can still be used, and you can enable all traffic routing with either setting. +> [!NOTE] +> Outbound SMTP connectivity (port 25) is supported for App Service when the SMTP traffic is routed through the virtual network integration. The supportability is determined by the subscription where the virtual network is deployed. For virtual networks created before 1. August 2022, you will have to re-enable outbound SMTP connectivity support on the subscription. For more information on subscription type support and how to request support to re-enable outbound SMTP connectivity, see [Troubleshoot outbound SMTP connectivity problems in Azure](../virtual-network/troubleshoot-outbound-smtp-connectivity.md). + #### Configuration routing When you are using virtual network integration, you can configure how parts of the configuration traffic is managed. By default, configuration traffic will go directly over the public route, but for the mentioned individual components, you can actively configure it to be routed through the virtual network integration. -> [!NOTE] -> * Windows containers don't support pulling custom container images over virtual network integration. -> * Backup/restore to private storage accounts is currently not supported. -> * Configure SSL/TLS certificates from private Key Vaults is currently not supported. -> * App Service Logs to private storage accounts is currently not supported. We recommend using Diagnostics Logging and allowing Trusted Services for the storage account. - ##### Content storage Bringing your own storage for content in often used in Functions where [content storage](./../azure-functions/configure-networking-how-to.md#restrict-your-storage-account-to-a-virtual-network) is configured as part of the Functions app. @@ -118,6 +114,12 @@ When using custom containers for Linux, you can pull the container over the virt App settings using Key Vault references will attempt to get secrets over the public route. If the Key Vault is blocking public traffic and the app is using virtual network integration, an attempt will then be made to get the secrets through the virtual network integration. +> [!NOTE] +> * Windows containers don't support pulling custom container images over virtual network integration. +> * Backup/restore to private storage accounts is currently not supported. +> * Configure SSL/TLS certificates from private Key Vaults is currently not supported. +> * App Service Logs to private storage accounts is currently not supported. We recommend using Diagnostics Logging and allowing Trusted Services for the storage account. + #### Network routing You can use route tables to route outbound traffic from your app without restriction. Common destinations can include firewall devices or gateways. You can also use a [network security group](../virtual-network/network-security-groups-overview.md) (NSG) to block outbound traffic to resources in your virtual network or the internet. An NSG that's applied to your integration subnet is in effect regardless of any route tables applied to your integration subnet. diff --git a/articles/app-service/overview.md b/articles/app-service/overview.md index f4712d789b8ee..6086a8197e767 100644 --- a/articles/app-service/overview.md +++ b/articles/app-service/overview.md @@ -32,7 +32,7 @@ Azure App Service is a fully managed platform as a service (PaaS) offering for d * **API and mobile features** - App Service provides turn-key CORS support for RESTful API scenarios, and simplifies mobile app scenarios by enabling authentication, offline data sync, push notifications, and more. * **Serverless code** - Run a code snippet or script on-demand without having to explicitly provision or manage infrastructure, and pay only for the compute time your code actually uses (see [Azure Functions](../azure-functions/index.yml)). -Besides App Service, Azure offers other services that can be used for hosting websites and web applications. For most scenarios, App Service is the best choice. For microservice architecture, consider [Azure Spring-Cloud Service](../spring-cloud/index.yml) or [Service Fabric](https://azure.microsoft.com/documentation/services/service-fabric). If you need more control over the VMs on which your code runs, consider [Azure Virtual Machines](https://azure.microsoft.com/documentation/services/virtual-machines/). For more information about how to choose between these Azure services, see [Azure App Service, Virtual Machines, Service Fabric, and Cloud Services comparison](/azure/architecture/guide/technology-choices/compute-decision-tree). +Besides App Service, Azure offers other services that can be used for hosting websites and web applications. For most scenarios, App Service is the best choice. For microservice architecture, consider [Azure Spring Apps](../spring-apps/index.yml) or [Service Fabric](https://azure.microsoft.com/documentation/services/service-fabric). If you need more control over the VMs on which your code runs, consider [Azure Virtual Machines](https://azure.microsoft.com/documentation/services/virtual-machines/). For more information about how to choose between these Azure services, see [Azure App Service, Virtual Machines, Service Fabric, and Cloud Services comparison](/azure/architecture/guide/technology-choices/compute-decision-tree). ## App Service on Linux diff --git a/articles/applied-ai-services/form-recognizer/includes/get-started/csharp.md b/articles/applied-ai-services/form-recognizer/includes/get-started/csharp.md index 67e3739799f20..47f2ac8296132 100644 --- a/articles/applied-ai-services/form-recognizer/includes/get-started/csharp.md +++ b/articles/applied-ai-services/form-recognizer/includes/get-started/csharp.md @@ -117,8 +117,7 @@ private static readonly AzureKeyCredential credential = new AzureKeyCredential(k * [**Prebuilt Invoice**](#try-it-prebuilt-model) > [!IMPORTANT] -> -> Remember to remove the key from your code when you're done, and never post it publicly. For production, use secure methods to store and access your credentials. See the Cognitive Services [security](.(/azure/cognitive-services/cognitive-services-security.md) article for more information. +> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../../key-vault/general/overview.md). See the Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md) article for more information. ## **Try it**: Layout model diff --git a/articles/applied-ai-services/form-recognizer/includes/get-started/java.md b/articles/applied-ai-services/form-recognizer/includes/get-started/java.md index 9fece4ff29320..2bf8241292366 100644 --- a/articles/applied-ai-services/form-recognizer/includes/get-started/java.md +++ b/articles/applied-ai-services/form-recognizer/includes/get-started/java.md @@ -117,8 +117,7 @@ import com.azure.core.util.polling.SyncPoller; * [**Prebuilt Invoice**](#try-it-prebuilt-model) > [!IMPORTANT] -> -> Remember to remove the key from your code when you're done, and never post it publicly. For production, use secure methods to store and access your credentials. For more information, _see_ Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md). +> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../../key-vault/general/overview.md). See the Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md) article for more information. ## **Try it**: Layout model diff --git a/articles/applied-ai-services/form-recognizer/includes/get-started/javascript.md b/articles/applied-ai-services/form-recognizer/includes/get-started/javascript.md index 38ec3d1cc5f2d..35ea9787e8dfd 100644 --- a/articles/applied-ai-services/form-recognizer/includes/get-started/javascript.md +++ b/articles/applied-ai-services/form-recognizer/includes/get-started/javascript.md @@ -94,8 +94,7 @@ In this quickstart, you'll use the following APIs to extract structured data fro * [**Prebuilt Invoice**](#try-it-prebuilt-model) > [!IMPORTANT] -> -> Remember to remove the key from your code when you're done, and never post it publicly. For production, use secure methods to store and access your credentials. See our Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md) article for more information. +> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../../key-vault/general/overview.md). See the Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md) article for more information. ## **Try it**: Layout model diff --git a/articles/applied-ai-services/form-recognizer/includes/get-started/python.md b/articles/applied-ai-services/form-recognizer/includes/get-started/python.md index e46dda63c0258..2795e5a6e9a7c 100644 --- a/articles/applied-ai-services/form-recognizer/includes/get-started/python.md +++ b/articles/applied-ai-services/form-recognizer/includes/get-started/python.md @@ -88,8 +88,7 @@ key = "YOUR_FORM_RECOGNIZER_KEY" * [**Prebuilt Invoice**](#try-it-prebuilt-model) > [!IMPORTANT] -> -> Remember to remove the key from your code when you're done, and never post it publicly. For production, use secure methods to store and access your credentials. See the Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md) article for more information. +> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../../key-vault/general/overview.md). See the Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md) article for more information. ## **Try it**: Layout model diff --git a/articles/applied-ai-services/form-recognizer/includes/get-started/rest-api.md b/articles/applied-ai-services/form-recognizer/includes/get-started/rest-api.md index bc363eb393025..368f269ee91b8 100644 --- a/articles/applied-ai-services/form-recognizer/includes/get-started/rest-api.md +++ b/articles/applied-ai-services/form-recognizer/includes/get-started/rest-api.md @@ -51,8 +51,7 @@ In this quickstart, you'll use the following APIs to extract structured data fro * [**Prebuilt Invoice**](#try-it-prebuilt-model) > [!IMPORTANT] -> -> Remember to remove the key from your code when you're done, and never post it publicly. For production, use secure methods to store and access your credentials. See the Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md) article for more information. +> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../../key-vault/general/overview.md). See the Cognitive Services [security](../../../../cognitive-services/cognitive-services-security.md) article for more information. ## **Try it**: Layout model diff --git a/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-csharp-sdk.md b/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-csharp-sdk.md index 1a44f401c86b3..4ab9f8ee9f09b 100644 --- a/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-csharp-sdk.md +++ b/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-csharp-sdk.md @@ -145,9 +145,7 @@ To interact with the Form Recognizer service, you'll need to create an instance * [**Prebuilt model**](#prebuilt-model) > [!IMPORTANT] -> -> * Remember to remove the key from your code when you're done, and never post it publicly. For production, use secure methods to store and access your credentials. For more information, *see* Cognitive Services [security](../../../cognitive-services/cognitive-services-security.md). - +> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../key-vault/general/overview.md). See the Cognitive Services [security](../../../cognitive-services/cognitive-services-security.md) article for more information. diff --git a/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-python-sdk.md b/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-python-sdk.md index 2a908f1fecc50..51c53fee65e76 100644 --- a/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-python-sdk.md +++ b/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-python-sdk.md @@ -74,8 +74,7 @@ To interact with the Form Recognizer service, you'll need to create an instance * [**Prebuilt Invoice**](#prebuilt-model) > [!IMPORTANT] -> -> Remember to remove the key from your code when you're done, and never post it publicly. For production, use secure methods to store and access your credentials. For more information, *see* Cognitive Services [security](../../../cognitive-services/cognitive-services-security.md). +> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../key-vault/general/overview.md). See the Cognitive Services [security](../../../cognitive-services/cognitive-services-security.md) article for more information. diff --git a/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-rest-api.md b/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-rest-api.md index 12ec09688bfd5..ca88d3e345656 100644 --- a/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-rest-api.md +++ b/articles/applied-ai-services/form-recognizer/quickstarts/try-v3-rest-api.md @@ -84,6 +84,9 @@ Before you run the cURL command, make the following changes: 1. You'll need a document file at a URL. For this quickstart, you can use the sample forms provided in the table below for each feature. +> [!IMPORTANT] +> Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../../key-vault/general/overview.md). See the Cognitive Services [security](../../../cognitive-services/cognitive-services-security.md) article for more information. + #### POST request ```bash diff --git a/articles/attestation/faq.yml b/articles/attestation/faq.yml index 036037200ef21..67b5bf1411f33 100644 --- a/articles/attestation/faq.yml +++ b/articles/attestation/faq.yml @@ -36,12 +36,11 @@ sections: - question: | What validations does Azure Attestation perform for attesting SGX enclaves answer: | - Azure Attestation is a unified framework for remotely attesting different types of TEEs. Azure Attestation: + During SGX attestation process, Azure Attestation performs the following validations: - - Validates if the trusted root of a signed enclave quote belongs to Intel. - - Validates if the enclave quote meets the Azure security baseline as defined by Trusted Hardware Identity Management (THIM). - - Validates if the SHA256 hash of Enclave Held Data (EHD) in the attestation request object matches the first 32 bytes of reportData field in the enclave quote. - - Allows customers to create an attestation provider and configure a custom policy. In addition to the above validations, Azure Attestation evaluates the enclave quote against the policy. Policies define authorization rules for the enclave and also dictate issuance rules for generating the attestation token. To confirm if intended software is running in an enclave, customers can add authorization rules to verify if **mrsigner** and **mrenclave** fields in the enclave quote matches the values of customer binaries. + - Validates if the trusted root of signed enclave quote belongs to Intel + - Validates if the TEE quote meets Azure security baseline as defined by Trusted Hardware Identity Management (THIM) + - If customer created an attestation provider and configured a custom policy, in addition to the above validations, Azure Attestation evaluates the TEE quote against the attestation policy. Using attestation policies, customers can define authorization rules for the TEE and also dictate issuance rules for generating the attestation token - question: | How can a verifier obtain the collateral for SGX attestation supported by Azure Attestation @@ -54,14 +53,14 @@ sections: How to shift to Azure Attestation from other SGX attestation models answer: | - After installing Azure Confidential computing virtual machine, install Azure DCAP library ([Windows/](https://www.nuget.org/packages/Microsoft.Azure.DCAP/) [Linux](https://packages.microsoft.com/ubuntu/18.04/prod/pool/main/a/az-dcap-client/)) to leverage the benefits offered by Trusted Hardware Identity Management (THIM). - - Remote attestation client needs to be authored which can retrieve the enclave evidence and send requests to Azure Attestation. See [code samples](/samples/browse/?expanded=azure&terms=attestation) for reference + - Remote attestation client needs to be authored which can retrieve the enclave evidence and send requests to Azure Attestation. See [code samples](https://github.com/Azure-Samples/microsoft-azure-attestation) for reference - Attestation requests can be sent to the REST API endpoint of default providers or custom attestation providers - In [2018-09-01-preview](https://github.com/Azure/azure-rest-api-specs/tree/master/specification/attestation/data-plane/Microsoft.Attestation/stable/2018-09-01-preview) API version, the client needs to send Azure AD access token along with the evidence to SGX attest API endpoint. The Azure AD access token is not a required parameter to perform SGX attestation in [2020-10-01](https://github.com/Azure/azure-rest-api-specs/tree/master/specification/attestation/data-plane/Microsoft.Attestation/stable/2020-10-01) API version - question: | How can the relying party verify the integrity of attestation token and confirm that Azure Attestation is running inside an enclave answer: | - Attestation token generated by Azure Attestation is signed using a self-signed certificate. The signing certificates are exposed via an [OpenID metadata endpoint](/rest/api/attestation/metadataconfiguration/get). Relying party can retrieve the signing certificates from this endpoint and perform signature verification of the attestation token. The signing certificate also includes SGX quote of the TEE inside which Azure Attestation runs. If relying party also prefers to check if Azure Attestation is running inside a valid SGX enclave, the SGX quote can be retrieved from the signing certificate and locally validated. + Attestation token generated by Azure Attestation is signed using a self-signed certificate. The signing certificates are exposed via an [OpenID metadata endpoint](/rest/api/attestation/metadataconfiguration/get). Relying party can retrieve the signing certificates from this endpoint and perform signature verification of the attestation token. The signing certificate also includes SGX quote of the TEE inside which Azure Attestation runs. If relying party also prefers to check if Azure Attestation is running inside a valid SGX enclave, the SGX quote can be retrieved from the signing certificate and locally validated. See [code samples](https://github.com/Azure-Samples/microsoft-azure-attestation/tree/master/sgx.attest.sample.oe.sdk) for more information - question: | How long is an attestation token valid? @@ -76,7 +75,7 @@ sections: - question: | Is it possible for the relying party to share secrets with the validated Trusted Execution Environments (TEEs) answer: | - Public key generated within an enclave can be expressed in the Enclave Held Data (EHD) property of the attestation request object sent by the client to Azure Attestation. After confirming if SHA256 hash of EHD is expressed in reportData field of the quote, Azure Attestation includes EHD in the attestation token. Relying party can use the EHD from the verified attestation response to encrypt the secrets and share with the enclave. See [Azure Attestation basic concepts](basic-concepts.md) for more information. + At the time of TEE evidence creation, code running inside the TEE can include arbitrary information in the evidence. For e.g. the TEE can create one or more asymmetric key pairs, serialize the public key components of these key pairs as JWKS JSON string and include the JWKS JSON string in the TEE evidence as RunTimeData { quote, JWKS JSON string }. Azure Attestation checks if SHA256 hash of the RuntimeData matches the lower 32 bytes of the quote's "report data" attribute. Post evaluating the TEE evidence, Azure Attestation generates JWT with the JWKS available as a claim named "keys" under the "x-ms-runtime" claim. The RunTimeData can be further used by relying party to establish secure channel and securely transmit data to the TEE. - question: | Where does Azure Attestation store customer data? diff --git a/articles/automation/add-user-assigned-identity.md b/articles/automation/add-user-assigned-identity.md index e75e8da731b1d..5a567b949a4b3 100644 --- a/articles/automation/add-user-assigned-identity.md +++ b/articles/automation/add-user-assigned-identity.md @@ -26,7 +26,7 @@ If you don't have an Azure subscription, create a [free account](https://azure.m - An Azure resource that you want to access from your Automation runbook. This resource needs to have a role defined for the user-assigned managed identity, which helps the Automation runbook authenticate access to the resource. To add roles, you need to be an owner for the resource in the corresponding Azure AD tenant. -- To assign an Azure role, you must have ```Microsoft.Authorization/roleAssignments/write``` permissions, such as [User Access Administrator](/azure/role-based-access-control/built-in-roles.md#user-access-administrator) or [Owner](/azure/role-based-access-control/built-in-roles.md.md#owner). +- To assign an Azure role, you must have ```Microsoft.Authorization/roleAssignments/write``` permissions, such as [User Access Administrator](/azure/role-based-access-control/built-in-roles#user-access-administrator) or [Owner](/azure/role-based-access-control/built-in-roles#owner). ## Add user-assigned managed identity for Azure Automation account diff --git a/articles/automation/change-tracking/manage-change-tracking.md b/articles/automation/change-tracking/manage-change-tracking.md index 0bb0bd7ecf215..87ceb518ecd3e 100644 --- a/articles/automation/change-tracking/manage-change-tracking.md +++ b/articles/automation/change-tracking/manage-change-tracking.md @@ -99,6 +99,9 @@ File content tracking allows you to view the contents of a file before and after * You can connect the storage account to only one Automation account. * Change Tracking and Inventory must be enabled in your Automation account. +>[!NOTE] +> If the file size appears >1.25MB, then FileContentChecksum is incorrect due to memory constraints in the checksum calculation. + ### Enable tracking for file content changes Use the following steps to enable tracking for changes to file contents: diff --git a/articles/automation/change-tracking/overview.md b/articles/automation/change-tracking/overview.md index 2185606a175c1..9e17feedffc6c 100644 --- a/articles/automation/change-tracking/overview.md +++ b/articles/automation/change-tracking/overview.md @@ -48,6 +48,7 @@ Change Tracking and Inventory doesn't support or has the following limitations: - ***.exe** files stored on Windows - The **Max File Size** column and values are unused in the current implementation. - If you are tracking file changes, it is limited to a file size of 5 MB or less. +- If the file size appears >1.25MB, then FileContentChecksum is incorrect due to memory constraints in the checksum calculation. - If you try to collect more than 2500 files in a 30-minute collection cycle, Change Tracking and Inventory performance might be degraded. - If network traffic is high, change records can take up to six hours to display. - If you modify a configuration while a machine or server is shut down, it might post changes belonging to the previous configuration. diff --git a/articles/availability-zones/TOC.yml b/articles/availability-zones/TOC.yml index a443d0a14772f..c575f09ac7670 100644 --- a/articles/availability-zones/TOC.yml +++ b/articles/availability-zones/TOC.yml @@ -22,7 +22,7 @@ href: migrate-app-service-environment.md - name: App Service href: migrate-app-service.md - - name: Application Gateway v2 + - name: Application Gateway href: migrate-app-gateway-v2.md - name: Cache for Redis href: migrate-cache-redis.md diff --git a/articles/availability-zones/cross-region-replication-azure.md b/articles/availability-zones/cross-region-replication-azure.md index b6817ef865bb7..9678c73358b8b 100644 --- a/articles/availability-zones/cross-region-replication-azure.md +++ b/articles/availability-zones/cross-region-replication-azure.md @@ -32,7 +32,7 @@ For applications that support multiple active regions, we recommend that you use ## Benefits of cross-region replication -Architecting cross-regional replication for your services and data can be decided on a per-service basis. You'll necessarily take a cost-benefit analysis approach based on your organization's strategic and business requirements. Primary and ripple benefits of cost-region replication are complex, extensive, and deserve elaboration. These benefits include: +Architecting cross-regional replication for your services and data can be decided on a per-service basis. You'll necessarily take a cost-benefit analysis approach based on your organization's strategic and business requirements. Primary and ripple benefits of cross-region replication are complex, extensive, and deserve elaboration. These benefits include: - **Region recovery sequence**: If a geography-wide outage occurs, recovery of one region is prioritized out of every enabled set of regions. Applications that are deployed across enabled region sets are guaranteed to have one of the regions prioritized for recovery. If an application is deployed across regions, any of which isn't enabled for cross-regional replication, recovery can be delayed. - **Sequential updating**: Planned Azure system updates for your enabled regions are staggered chronologically to minimize downtime, impact of bugs, and any logical failures in the rare event of a faulty update. diff --git a/articles/availability-zones/migrate-app-gateway-v2.md b/articles/availability-zones/migrate-app-gateway-v2.md index 28cee58c12518..e97355083b048 100644 --- a/articles/availability-zones/migrate-app-gateway-v2.md +++ b/articles/availability-zones/migrate-app-gateway-v2.md @@ -1,10 +1,10 @@ --- -title: Migrate Azure Application Gateway and WAF deployments to availability zone support +title: Migrate Azure Application Gateway Standard and WAF v2 deployments to availability zone support description: Learn how to migrate your Azure Application Gateway and WAF deployments to availability zone support. author: anaharris-ms ms.service: application-gateway ms.topic: conceptual -ms.date: 07/26/2022 +ms.date: 07/28/2022 ms.author: anaharris ms.reviewer: anaharris ms.custom: references_regions @@ -12,13 +12,13 @@ ms.custom: references_regions # Migrate Application Gateway and WAF deployments to availability zone support -[Application Gateway Standard v2](/azure/application-gateway/overview-v2) or [WAF v2](/azure/web-application-firewall/ag/ag-overview) supports zonal and zone redundant deployments. For more information about zone redundancy, see [Regions and availability zones](az-overview.md). +[Application Gateway Standard v2](/azure/application-gateway/overview-v2) and Application Gateway with [WAF v2](/azure/web-application-firewall/ag/ag-overview) supports zonal and zone redundant deployments. For more information about zone redundancy, see [Regions and availability zones](az-overview.md). -If you previously deployed Azure Application Gateway Standard v2 or WAF v2 without zonal support, you must redeploy these services to enable zone redundancy. Two migration options to redeploy these services are described in this article. +If you previously deployed **Azure Application Gateway Standard v2** or **Azure Application Gateway Standard v2 + WAF v2** without zonal support, you must redeploy these services to enable zone redundancy. Two migration options to redeploy these services are described in this article. ## Prerequisites -- Your deployment must be Standard v2 or WAF v2 SKU. Earlier SKUs (Standard and WAF) don't support zone awareness. +- Your deployment must be Standard v2 or WAF v2 SKU. Earlier SKUs (Standard and WAF) don't support availability zones. ## Downtime requirements @@ -38,7 +38,7 @@ Use this option to: To create a separate Application Gateway, WAF (optional) and IP address: 1. Go to the [Azure portal](https://portal.azure.com). -2. Follow the steps in [Create an application gateway](../application-gateway/quick-create-portal.md#create-an-application-gateway) or [Create an application gateway with a Web Application Firewall](/azure/web-application-firewall/ag/application-gateway-web-application-firewall-portal) to create a new Application Gateway v2 or Application Gateway V2 + WAF v2, respectively. You can reuse your existing Virtual Network or create a new one, but you must create a new frontend Public IP address. +2. Follow the steps in [Create an application gateway](../application-gateway/quick-create-portal.md#create-an-application-gateway) or [Create an application gateway with a Web Application Firewall](/azure/web-application-firewall/ag/application-gateway-web-application-firewall-portal) to create a new Application Gateway v2 or Application Gateway v2 + WAF v2, respectively. You can reuse your existing Virtual Network or create a new one, but you must create a new frontend Public IP address. 3. Verify that the application gateway and WAF are working as intended. 4. Migrate your DNS configuration to the new public IP address. 5. Delete the old Application gateway and WAF resources. @@ -57,7 +57,7 @@ To delete the Application Gateway and WAF and redeploy: 1. Go to the [Azure portal](https://portal.azure.com). 2. Select **All resources**, and then select the resource group that contains the Application Gateway. 3. Select the Application Gateway resource and then select **Delete**. Type **yes** to confirm deletion, and then click **Delete**. -4. Follow the steps in [Create an application gateway](../application-gateway/quick-create-portal.md#create-an-application-gateway) or [Create an application gateway with a Web Application Firewall](/azure/web-application-firewall/ag/application-gateway-web-application-firewall-portal) to create a new Application Gateway v2 or Application Gateway V2 + WAF v2, respectively, using the same Virtual Network, subnets, and Public IP address that you used previously. +4. Follow the steps in [Create an application gateway](../application-gateway/quick-create-portal.md#create-an-application-gateway) or [Create an application gateway with a Web Application Firewall](/azure/web-application-firewall/ag/application-gateway-web-application-firewall-portal) to create a new Application Gateway v2 or Application Gateway v2 + WAF v2, respectively, using the same Virtual Network, subnets, and Public IP address that you used previously. ## Next steps diff --git a/articles/azure-arc/data/active-directory-prerequisites.md b/articles/azure-arc/data/active-directory-prerequisites.md index fafd2be89973f..df200653593f1 100644 --- a/articles/azure-arc/data/active-directory-prerequisites.md +++ b/articles/azure-arc/data/active-directory-prerequisites.md @@ -120,7 +120,6 @@ Whether you have created a new account for the DSA or are using an existing Acti - **Write all properties** - **Create User objects** - **Delete User objects** - - **Reset Password for Descendant User objects** - Select **OK**. diff --git a/articles/azure-arc/data/uninstall-azure-arc-data-controller.md b/articles/azure-arc/data/uninstall-azure-arc-data-controller.md index 6ede2f9648181..9ed00ffcb4f5c 100644 --- a/articles/azure-arc/data/uninstall-azure-arc-data-controller.md +++ b/articles/azure-arc/data/uninstall-azure-arc-data-controller.md @@ -1,13 +1,13 @@ --- -title: Cleanup from partial deployment -description: Cleanup from partial deployment +title: Uninstall Azure Arc-enabled data services +description: Uninstall Azure Arc-enabled data services services: azure-arc ms.service: azure-arc ms.subservice: azure-arc-data author: dnethi ms.author: dinethi ms.reviewer: mikeray -ms.date: 11/30/2021 +ms.date: 07/28/2022 ms.topic: how-to --- diff --git a/articles/azure-arc/data/validation-program.md b/articles/azure-arc/data/validation-program.md index 6d914ccba9a16..8384ee7d2a61d 100644 --- a/articles/azure-arc/data/validation-program.md +++ b/articles/azure-arc/data/validation-program.md @@ -92,7 +92,7 @@ To see how all Azure Arc-enabled components are validated, see [Validation progr |Solution and version | Kubernetes version | Azure Arc-enabled data services version | SQL engine version | PostgreSQL Hyperscale version |-----|-----|-----|-----|-----| -|WindRiver| v1.22.5|v1.1.0_2021-11-02 |15.0.2195.191|postgres 12.3 (Ubuntu 12.3-1) | +|WindRiver| v1.23.1|v1.9.0_2022-07-12 |16.0.312.4243|postgres 12.3 (Ubuntu 12.3-1) | ## Data services validation process diff --git a/articles/azure-arc/kubernetes/quickstart-connect-cluster.md b/articles/azure-arc/kubernetes/quickstart-connect-cluster.md index 69f726bfab16e..ae7800cc2cc9a 100644 --- a/articles/azure-arc/kubernetes/quickstart-connect-cluster.md +++ b/articles/azure-arc/kubernetes/quickstart-connect-cluster.md @@ -2,7 +2,7 @@ title: "Quickstart: Connect an existing Kubernetes cluster to Azure Arc" description: In this quickstart, you learn how to connect an Azure Arc-enabled Kubernetes cluster. ms.topic: quickstart -ms.date: 05/24/2022 +ms.date: 07/28/2022 ms.custom: template-quickstart, mode-other, devx-track-azurecli, devx-track-azurepowershell ms.devlang: azurecli --- @@ -267,7 +267,7 @@ If your cluster is behind an outbound proxy server, requests must be routed via export NO_PROXY=: ``` -2. Run the connect command with proxy parameters specified: +2. Run the connect command with the `proxy-https` and `proxy-http` parameters specified. If your proxy server is set up with both HTTP and HTTPS, be sure to use `--proxy-http` for the HTTP proxy and `--proxy-https` for the HTTPS proxy. If your proxy server only uses HTTP, you can use that value for both parameters. ```azurecli az connectedk8s connect --name --resource-group --proxy-https https://: --proxy-http http://: --proxy-skip-range , --proxy-cert diff --git a/articles/azure-arc/servers/onboard-group-policy.md b/articles/azure-arc/servers/onboard-group-policy.md index 00e7a9b2efe22..b609804a91b04 100644 --- a/articles/azure-arc/servers/onboard-group-policy.md +++ b/articles/azure-arc/servers/onboard-group-policy.md @@ -52,6 +52,9 @@ The group policy will project machines as Arc-enabled servers in the Azure subsc Before you can run the script to connect your machines, you'll need to save the onboarding script to the remote share. This will be referenced when creating the Group Policy Object. +> [!NOTE] +> If you're using a proxy server, you'll need to modify the `Invoke-WebRequest` command in the script to include the `Proxy` parameter and web address, as in: `Invoke-WebRequest -Uri "https://aka.ms/azcmagent-windows" -Proxy "http://xx.x.x.xx:xxxx -TimeoutSec 30 -OutFile "$InstallationFolder\install_windows_azcmagent.ps1"` +