+- CBA with federation is only supported for Federated environments for browser applications, native clients using modern authentication, or MSAL libraries. The one exception is Exchange Active Sync (EAS) for Exchange Online (EXO), which can be used for federated and managed accounts. To configure Azure AD CBA without needing federation, see [How to configure Azure AD certificate-based authentication](how-to-certificate-based-authentication.md).

+# How to use additional context in Microsoft Authenticator app notifications (Preview) - Authentication Methods Policy

+This topic covers how to improve the security of user sign-in by adding the application name and geographic location of the sign-in to Microsoft Authenticator push and passwordless notifications. The schema for the API to enable application name and geographic location is currently being updated. **While the API is updated over the next two weeks, you should only use the Azure AD portal to enable application name and geographic location.**

+## Enable additional context

+To enable application name or geographic location, complete the following steps:

+[Authentication methods in Azure Active Directory - Microsoft Authenticator app](concept-authentication-authenticator-app.md)

+This topic covers how to enable number matching in Microsoft Authenticator push notifications to improve user sign-in security. The schema for the API to enable number match is currently being updated. **While the API is updated over the next two weeks, you should only use the Azure AD portal to enable number match.**

+<!check below with Mayur. The bit about the policy came from the number match FAQ at the end.>

+To enable number matching, complete the following steps:

+[Authentication methods in Azure Active Directory](concept-authentication-authenticator-app.md)

+c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value ==

+"YourGroupSID"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders",

+not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",

+"http://schemas.microsoft.com/claims/authnmethodsproviders", Value =

+"http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "false"] => issue(type =

+"http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value =

+"http://schemas.microsoft.com/claims/multipleauthn" );

+ c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value ==

+"YourGroupSID"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders",

+not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",

+"http://schemas.microsoft.com/claims/authnmethodsproviders", Value =

+"http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "false"] => issue(type =

+"http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value =

+"http://schemas.microsoft.com/claims/multipleauthn" );

+c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value ==

+"YourGroupSID"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders",

+not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",

+"http://schemas.microsoft.com/claims/authnmethodsproviders", Value =

+c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value ==

+"**YourGroupSID**"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders",

+not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid",

+"http://schemas.microsoft.com/claims/authnmethodsproviders", Value =

+**Active Directory Federation Services (AD FS) Integration** - When a user enables the Authenticator passwordless credential, authentication for that user defaults to sending a notification for approval. Users in a hybrid tenant are prevented from being directed to AD FS for sign-in unless they select "Use your password instead." This process also bypasses any on-premises Conditional Access policies, and pass-through authentication (PTA) flows. However, if a login_hint is specified, the user is forwarded to AD FS and bypasses the option to use the passwordless credential. For non-Microsoft 365 applications which use AD FS for authentication, Azure AD Conditional Access policies will not be applied and you will need to set up access control policies within AD FS.

+# Tutorial: Enable cloud sync self-service password reset writeback to an on-premises environment

+Azure Active Directory Connect cloud sync can synchronize Azure AD password changes in real time between users in disconnected on-premises Active Directory Domain Services (AD DS) domains. Azure AD Connect cloud sync can run side-by-side with [Azure Active Directory Connect](tutorial-enable-sspr-writeback.md) at the domain level to simplify password writeback for additional scenarios, such as users who are in disconnected domains because of a company split or merge. You can configure each service in different domains to target different sets of users depending on their needs. Azure Active Directory Connect cloud sync uses the lightweight Azure AD cloud provisioning agent to simplify the setup for self-service password reset (SSPR) writeback and provide a secure way to send password changes in the cloud back to an on-premises directory.

+- An account with:

+- An on-premises AD DS environment configured with [Azure AD Connect cloud sync version 1.1.972.0 or later](../app-provisioning/provisioning-agent-release-version-history.md). Learn how to [identify the agent's current version](../cloud-sync/how-to-automatic-upgrade.md). If needed, configure Azure AD Connect cloud sync using [this tutorial](tutorial-enable-sspr.md).

+1. [Enable password writeback in Azure AD Connect cloud sync](#enable-password-writeback-in-sspr)

+1. [Enable password writeback for SSPR](#enable-password-writeback-in-sspr)

+### Enable password writeback in SSPR

+You can enable Azure AD connect cloud sync provisioning directly in Azure portal or through PowerShell.

+#### Enable password writeback in Azure portal

+1. Sign in to the [Azure portal](https://portal.azure.com) using a Global Administrator account.

+1. Search for and select **Azure Active Directory**, select **Password reset**, then choose **On-premises integration**.

+1. Check the option for **Write back passwords to your on-premises directory** .

+1. (optional) If Azure AD Connect provisioning agents are detected, you can additionally check the option for **Write back passwords with Azure AD Connect cloud sync**.

+3. Check the option for **Allow users to unlock accounts without resetting their password** to *Yes*.

+ 

+1. When ready, select **Save**.

+#### PowerShell

+With PowerShell you can enable Azure AD Connect cloud sync by using the Set-AADCloudSyncPasswordWritebackConfiguration cmdlet on the servers with the provisioning agents. You will need global administrator credentials:

+```powershell

+Import-Module 'C:\\Program Files\\Microsoft Azure AD Connect Provisioning Agent\\Microsoft.CloudSync.Powershell.dll'

+Set-AADCloudSyncPasswordWritebackConfiguration -Enable $true -Credential $(Get-Credential)

+```

+If you no longer want to use the SSPR writeback functionality you have configured as part of this tutorial, complete the following steps:

+1. Sign in to the [Azure portal](https://portal.azure.com).

+1. Search for and select **Azure Active Directory**, select **Password reset**, then choose **On-premises integration**.

+1. Uncheck the option for **Write back passwords to your on-premises directory**.

+1. Uncheck the option for **Write back passwords with Azure AD Connect cloud sync**.

+1. Uncheck the option for **Allow users to unlock accounts without resetting their password**.

+1. When ready, select **Save**.

+If you no longer want to use the Azure AD Connect cloud sync for SSPR writeback functionality but want to continue using Azure AD Connect sync agent for writebacks complete the following steps:

+1. Sign in to the [Azure portal](https://portal.azure.com).

+1. Search for and select **Azure Active Directory**, select **Password reset**, then choose **On-premises integration**.

+1. Uncheck the option for **Write back passwords with Azure AD Connect cloud sync**.

+1. When ready, select **Save**.

+You can also use PowerShell to disable Azure AD Connect cloud sync for SSPR writeback functionality, from your Azure AD Connect cloud sync server, run `Set-AADCloudSyncPasswordWritebackConfiguration` using Hybrid Identity Administrator credentials to disable password writeback with Azure AD Connect cloud sync.

+- The Azure AD Connect cloud sync group Managed Service Account should have the following permissions set to writeback the passwords by default:

+ - Reset password

+ - Write permissions on lockoutTime

+ - Write permissions on pwdLastSet

+ - Extended rights for "Unexpire Password" on the root object of each domain in that forest, if not already set.

+

+ If these permissions are not set, you can set the PasswordWriteBack permission on the service account by using the Set-AADCloudSyncPermissions cmdlet and on-premises enterprise administrator credentials:

+ ```powershell

+ Import-Module ΓÇÿC:\\Program Files\\Microsoft Azure AD Connect Provisioning Agent\\Microsoft.CloudSync.Powershell.dllΓÇÖ

+ Set-AADCloudSyncPermissions -PermissionType PasswordWriteBack -EACredential $(Get-Credential)

+ ```

+ After you have updated the permissions, it may take up to an hour or more for these permissions to replicate to all the objects in your directory.

+

+- If passwords for some user accounts aren't written back to the on-premises directory, make sure that inheritance isn't disabled for the account in the on-premises AD DS environment. Write permissions for passwords must be applied to descendant objects for the feature to work correctly.

+- Password policies in the on-premises AD DS environment may prevent password resets from being correctly processed. If you are testing this feature and want to reset password for users more than once per day, the group policy for Minimum password age must be set to 0. This setting can be found under Computer Configuration > Policies > Windows Settings > Security Settings > Account Policies within gpmc.msc.

+- If you update the group policy, wait for the updated policy to replicate, or use the gpupdate /force command.

+- For passwords to be changed immediately, Minimum password age must be set to 0. However, if users adhere to the on-premises policies, and the Minimum password age is set to a value greater than zero, password writeback will not work after the on-premises policies are evaluated.

+With password writeback enabled in Azure AD Connect, now configure Azure AD SSPR for writeback. SSPR can be configured to writeback through Azure AD Connect sync agents and Azure AD Connect provisioning agents (cloud sync). When you enable SSPR to use password writeback, users who change or reset their password have that updated password synchronized back to the on-premises AD DS environment as well.

+1. Check the option for **Write back passwords to your on-premises directory** .

+1. (optional) If Azure AD Connect provisioning agents are detected, you can additionally check the option for **Write back passwords with Azure AD Connect cloud sync**.

+3. Check the option for **Allow users to unlock accounts without resetting their password** to *Yes*.

+ 

+1. Uncheck the option for **Write back passwords to your on-premises directory**.

+1. Uncheck the option for **Write back passwords with Azure AD Connect cloud sync**.

+1. Uncheck the option for **Allow users to unlock accounts without resetting their password**.

+1. When ready, select **Save**.

+If you no longer want to use the Azure AD Connect cloud sync for SSPR writeback functionality but want to continue using Azure AD Connect sync agent for writebacks complete the following steps:

+1. Sign in to the [Azure portal](https://portal.azure.com).

+1. Search for and select **Azure Active Directory**, select **Password reset**, then choose **On-premises integration**.

+1. Uncheck the option for **Write back passwords with Azure AD Connect cloud sync**.

+1. When ready, select **Save**.

+ - Policy 1: All users with the directory role of Global Administrator, accessing the Microsoft Azure Management cloud app, and for Access controls, Grant access, but require multifactor authentication and require device to be marked as compliant.

+ - Policy 2: All users with the directory role of Global Administrator, accessing the Microsoft Azure Management cloud app, excluding a filter for devices using rule expression device.extensionAttribute1 equals SAW and for Access controls, Block. Learn how to [update extensionAttributes on an Azure AD device object](/graph/api/device-update?view=graph-rest-1.0&tabs=http&preserve-view=true).

+Policy 1: All users with the directory role of Global Administrator, accessing the Microsoft Azure Management cloud app, and for Access controls, Grant access, but require multifactor authentication and require device to be marked as compliant.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+ 1. Under **Include**, select **Directory roles** and choose **Global Administrator**.

+Policy 2: All users with the directory role of Global Administrator, accessing the Microsoft Azure Management cloud app, excluding a filter for devices using rule expression device.extensionAttribute1 equals SAW and for Access controls, Block.

+ 1. Under **Include**, select **Directory roles** and choose **Global Administrator**.

+- Microsoft Power Apps

+- Microsoft Field Service (Dynamics 365)

+ 1. [Multi-factor authenticationΓÇï](concept-conditional-access-grant.md#require-multi-factor-authentication)

+ 2. [Device to be marked as compliant](./concept-conditional-access-grant.md#require-device-to-be-marked-as-compliant)

+ 3. [Hybrid Azure AD joined device](./concept-conditional-access-grant.md#require-hybrid-azure-ad-joined-device)

+ 4. [Approved client app](./concept-conditional-access-grant.md#require-approved-client-app)

+ 5. [App protection policy](./concept-conditional-access-grant.md#require-app-protection-policy)

+ 6. [Password change](./concept-conditional-access-grant.md#require-password-change)

+ 7. [Terms of use](concept-conditional-access-grant.md#terms-of-use)

+ 8. [Custom controls](./concept-conditional-access-grant.md#custom-controls-preview)

+ - Allows administrators to select specific [built-in Azure AD directory roles](../roles/permissions-reference.md) used to determine policy assignment. For example, organizations may create a more restrictive policy on users assigned the Global Administrator role. Other role types aren't supported, including administrative unit-scoped roles and custom roles.

+ - Allows administrators to select specific Azure AD directory roles used to determine assignment. For example, organizations may create a more restrictive policy on users assigned the Global Administrator role.

+In the following example, a Conditional Access Administrator has configured a location based Conditional Access policy to only allow access from specific IP ranges:

+Microsoft Teams desktop clients for Windows and Mac support modern authentication. Modern authentication brings sign-in to Microsoft Office client applications across platforms.

+- Conditional Access Administrator

+- Global Reader

+- Global Administrator

+1. Sign into the **Azure portal** as a Conditional Access Administrator, security administrator, or Global Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+ - Global Administrator

+ - Conditional Access Administrator

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+ 1. Select **Directory roles** and choose **Global Administrator**

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+* An account with Conditional Access Administrator privileges.

+1. Sign in to your [Azure portal](https://portal.azure.com) as Global Administrator, Security Administrator, or a Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Global Reader.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+To build an environment for either work and school accounts or personal Microsoft accounts (MSA), you can use an existing Azure AD tenant or create a new one.

+- **Tenant type** - Choose between an Azure AD and Azure AD B2C tenant

+To begin building external facing applications that sign in social and local accounts, create an Azure AD B2C tenant. To begin, see [Create an Azure AD B2C tenant](../../active-directory-b2c/tutorial-create-tenant.md).

+| AADSTS50078 | UserStrongAuthExpired- Presented multi-factor authentication has expired due to policies configured by your administrator, you must refresh your multi-factor authentication to access '{resource}'.|

+- The Azure AD Global Administrator role

+To view and update the membership of the Global Administrator role, see:

+1. Sign in to the [Azure portal](https://portal.azure.com) as a Global Administrator.

+| C | If the user is managed, CloudAP will get the nonce from Azure AD. If the user is federated, CloudAP plugin requests a SAML token from the federation provider with the userΓÇÖs credentials. Nonce is requested before the SAML token is sent to Azure AD. |

+| D | If the user is federated, CloudAP plugin requests a SAML token from the federation provider with the userΓÇÖs credentials. Nonce is requested before the SAML token is sent to Azure AD. If the user is managed, CloudAP will directly get the nonce from Azure AD. |

+- Global Administrator credentials for your Azure AD tenant.

+1. In **Connect to Azure AD**, enter the credentials of a Global Administrator for your Azure AD tenant.

+1. On the **Connect to Azure AD** page, enter the credentials of a Global Administrator for your Azure AD tenant, and then select **Next**.

+- Global Administrator credentials for your Azure AD tenant.

+- Any sponsorships, access reviews, account verifications, etc. that are performed on the cloud B2B user applies to the on-premises users. For example, if the cloud user is deleted through your lifecycle management policies, the on-premises user is also deleted by MIM Sync or through the Azure AD B2B script. For more information, see [Manage guest access with Azure AD access reviews](../governance/manage-guest-access-with-access-reviews.md).

+ - If you're using a personal account or email one-time passcode, you'll need to use a My Account URL that includes your tenant name or tenant ID, for example: https://myaccount.microsoft.com?tenantId=wingtiptoys.onmicrosoft.com or https://myaccount.microsoft.com?tenantId=ab123456-cd12-ef12-gh12-ijk123456789.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+>You must have a Global administrator, Privileged authentication administrator or User administrator role assignment to delete users in your organization. Global admins and Privileged authentication admins can delete any users including other admins. User administrators can delete any non-admin users, Helpdesk administrators and other User administrators. For more information, see [Administrator role permissions in Azure AD](../roles/permissions-reference.md).

+Or you can do other user management tasks, such as [adding guest users from another directory](../external-identities/what-is-b2b.md) or [restoring a deleted user](active-directory-users-restore.md). For more information about other available actions, see [Azure Active Directory user management documentation](../enterprise-users/index.yml).

+ Title: Road to the cloud - Establish a footprint for moving identity and access management from Active Directory to Azure AD

+description: Establish an Azure AD footprint as part of planning your migration of IAM from Active Directory to Azure AD.

+Before you migrate identity and access management (IAM) from Active Directory to Azure Active Directory (Azure AD), you need to set up Azure AD.

+If you're using Microsoft Office 365, Exchange Online, or Teams, then you're already using Azure AD. Your next step is to establish more Azure AD capabilities:

+* Establish hybrid identity synchronization between Active Directory and Azure AD by using [Azure AD Connect](../hybrid/whatis-azure-ad-connect.md) or [Azure AD Connect cloud sync](../cloud-sync/what-is-cloud-sync.md).

+* [Select authentication methods](../hybrid/choose-ad-authn.md). We strongly recommend password hash synchronization.

+* Secure your hybrid identity infrastructure by following [Five steps to securing your identity infrastructure](../../security/fundamentals/steps-secure-identity.md).

+The following functions aren't specific or mandatory to move from Active Directory to Azure AD, but we recommend incorporating them into your environment. These items are also recommended in the [Zero Trust](/security/zero-trust/) guidance.

+### Deploy passwordless authentication

+In addition to the security benefits of [passwordless credentials](../authentication/concept-authentication-passwordless.md), passwordless authentication simplifies your environment because the management and registration experience is already native to the cloud. Azure AD provides passwordless credentials that align with various use cases. Use the information in this article to plan your deployment: [Plan a passwordless authentication deployment in Azure Active Directory](../authentication/howto-authentication-passwordless-deployment.md).

+After you roll out passwordless credentials to your users, consider reducing the use of password credentials. You can use the [reporting and insights dashboard](../authentication/howto-authentication-methods-activity.md) to continue to drive the use of passwordless credentials and reduce the use of passwords in Azure AD.

+You can configure hybrid Azure AD join for existing Active Directory-joined Windows clients to benefit from cloud-based security features such as [co-management](/mem/configmgr/comanage/overview), conditional access, and Windows Hello for Business. New devices should be Azure AD joined and not hybrid Azure AD joined.

+To learn more, check [Plan your hybrid Azure Active Directory join implementation](../devices/hybrid-azuread-join-plan.md).

+ Title: Road to the cloud - Implement a cloud-first approach when moving identity and access management from Active Directory to Azure AD

+description: Implement a cloud-first approach as part of planning your migration of IAM from Active Directory to Azure AD.

+# Implement a cloud-first approach

+It's mainly a process and policy-driven phase to stop, or limit as much as possible, adding new dependencies to Active Directory and implement a cloud-first approach for new demand of IT solutions.

+It's key at this point to identify the internal processes that would lead to adding new dependencies on Active Directory. For example, most organizations would have a change management process that has to be followed before the implementation of new scenarios, features, and solutions. We strongly recommend making sure that these change approval processes are updated to:

+- Include a step to evaluate whether the proposed change would add new dependencies on Active Directory.

+- Request the evaluation of Azure Active Directory (Azure AD) alternatives when possible.

+* App provisioning: The data source of app provisioning is Azure AD, and necessary user attributes must be in there.

+* Application authorization: A token that Azure AD issues can include claims generated from user attributes so that applications can make authorization decisions based on the claims in the token.

+* Group membership population and maintenance: Dynamic groups enable dynamic population of group membership based on user attributes, such as department information.

+These links provide more information on this topic but are not specific to changing the schema:

+* [What are custom security attributes in Azure AD (preview)?](../fundamentals/custom-security-attributes-overview.md)

+* [Customize Azure Active Directory attribute mappings in application provisioning](../app-provisioning/customize-application-attributes.md)

+These links provide more information about groups:

+* [Create or edit a dynamic group and get status in Azure AD](../enterprise-users/groups-create-rule.md)

+* [Use self-service groups for user-initiated group management](../enterprise-users/groups-self-service-management.md)

+* [Attribute-based application provisioning with scoping filters](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md) or [What is Azure AD entitlement management?](../governance/entitlement-management-overview.md) (for application access)

+* [Compare groups](/microsoft-365/admin/create-groups/compare-groups)

+* [Restrict guest access permissions in Azure Active Directory](../enterprise-users/users-restrict-guest-permissions.md)

+You and your team might feel compelled to change your current employee provisioning to use cloud-only accounts at this stage. The effort is non-trivial but doesn't provide enough business value. We recommend that you plan this transition at a different phase of your transformation.

+Client workstations are traditionally joined to Active Directory and managed via Group Policy objects (GPOs) or device management solutions such as Microsoft Endpoint Configuration Manager. Your teams will establish a new policy and process to prevent newly deployed workstations from being domain joined. Key points include:

+* Mandate [Azure AD join](../devices/concept-azure-ad-join.md) for new Windows client workstations to achieve "no more domain join."

+* Manage workstations from the cloud by using unified endpoint management (UEM) solutions such as [Intune](/mem/intune/fundamentals/what-is-intune).

+[Windows Autopilot](/mem/autopilot/windows-autopilot) can help you establish a streamlined onboarding and device provisioning, which can enforce these directives.

+For more information, see [Learn more about cloud-native endpoints](/mem/cloud-native-endpoints-overview).

+Traditionally, application servers are often joined to an on-premises Active Directory domain so that they can use Windows Integrated Authentication (Kerberos or NTLM), directory queries through LDAP, and server management through GPO or Microsoft Endpoint Configuration Manager.

+The organization has a process to evaluate Azure AD alternatives when it's considering new services, apps, or infrastructure. Directives for a cloud-first approach to applications should be as follows. (New on-premises applications or legacy applications should be a rare exception when no modern alternative exists.)

+* Provide a recommendation to change the procurement policy and application development policy to require modern protocols (OIDC/OAuth2 and SAML) and authenticate by using Azure AD. New apps should also support [Azure AD app provisioning](../app-provisioning/what-is-hr-driven-provisioning.md) and have no dependency on LDAP queries. Exceptions require explicit review and approval.

+ > [!IMPORTANT]

+ > Depending on the anticipated demands of applications that require legacy protocols, you can choose to deploy [Azure Active Directory Domain Services](../../active-directory-domain-services/overview.md) when more current alternatives won't work.

+* Provide a recommendation to create a policy to prioritize use of cloud-native alternatives. The policy should limit deployment of new application servers to the domain. Common cloud-native scenarios to replace Active Directory-joined servers include:

+ * File servers:

+ * SharePoint or OneDrive provides collaboration support across Microsoft 365 solutions and built-in governance, risk, security, and compliance.

+ * [Azure Files](../../storage/files/storage-files-introduction.md) offers fully managed file shares in the cloud that are accessible via the industry-standard SMB or NFS protocol. Customers can use native [Azure AD authentication to Azure Files](../../virtual-desktop/create-profile-container-azure-ad.md) over the internet without line of sight to a domain controller.

+ * Azure AD works with third-party applications in the Microsoft [application gallery](/microsoft-365/enterprise/integrated-apps-and-azure-ads).

+ * Print servers:

+ * If your organization has a mandate to procure [Universal Print](/universal-print/)-compatible printers, see [Partner integrations](/universal-print/fundamentals/universal-print-partner-integrations).

+ * Bridge with the [Universal Print connector](/universal-print/fundamentals/universal-print-connector-overview) for incompatible printers.

+description: Learn how to plan a migration of IAM from Active Directory to Azure AD.

+# Road to the cloud: Introduction

+Some organizations set goals to remove Active Directory and their on-premises IT footprint. Others take advantage of some cloud-based capabilities to reduce the Active Directory footprint, but not to completely remove their on-premises environments.

+This content provides guidance to move:

+* *From* Active Directory and other non-cloud-based services, either on-premises or infrastructure as a service (IaaS), that provide identity management (IDM), identity and access management (IAM), and device management.

+* *To* Azure Active Directory (Azure AD) and other Microsoft cloud-native solutions for IDM, IAM, and device management.

+> In this content, *Active Directory* refers to Windows Server Active Directory Domain Services.

+Transformation must be aligned with and achieve business objectives, including increased productivity, reduced costs and complexity, and improved security posture. To better understand the costs versus value of moving to the cloud, see [Forrester TEI for Microsoft Azure Active Directory](https://www.microsoft.com/security/business/forrester-tei-study) and [Cloud economics](https://azure.microsoft.com/overview/cloud-economics/).

+ Title: Road to the cloud - Move identity and access management from Active Directory to an Azure AD migration workstream

+description: Learn to plan your migration workstream of IAM from Active Directory to Azure AD.

+After you align your organization toward halting growth of the Active Directory footprint, you can focus on moving the existing on-premises workloads to Azure Active Directory (Azure AD). This article describes the various migration workstreams. You can execute the workstreams in this article based on your priorities and resources.

+* **Discover**: Find out what you currently have in your environment.

+* **Pilot**: Deploy new cloud capabilities to a small subset of users, applications, or devices, depending on the workstream.

+* **Scale out**: Expand the pilot to complete the transition of a capability to the cloud.

+* **Cut over (when applicable)**: Stop using the old on-premises workload.

+## Users and groups

+To enable self-service capabilities, choose the appropriate [authentication methods](../authentication/concept-authentication-methods.md) for your organization. After the authentication methods are updated, you can enable user self-service password capability for your Azure AD authentication environment. For deployment guidance, see [Deployment considerations for Azure Active Directory self-service password reset](../authentication/howto-sspr-deployment.md).

+Additional considerations include:

+* Deploy [Azure AD Password Protection](../authentication/howto-password-ban-bad-on-premises-operations.md) in a subset of domain contollers with **Audit** mode to gather information about the impact of modern policies.

+* Gradually enable [combined registration for SSPR and Azure AD Multi-Factor Authentication](../authentication/concept-registration-mfa-sspr-combined.md). For example, roll out by region, subsidiary, or department for all users.

+* Go through a cycle of password change for all users to flush out weak passwords. After the cycle is complete, implement the policy expiration time.

+* Switch the Password Protection configuration in the domain controllers that have the mode set to **Enforced**. For more information, see [Enable on-premises Azure AD Password Protection](../authentication/howto-password-ban-bad-on-premises-operations.md).

+>* We recommend user communications and evangelizing for a smooth deployment. See [Sample SSPR rollout materials](https://www.microsoft.com/download/details.aspx?id=56768).

+>* If you use Azure AD Identity Protection, enable [password reset as a control in Conditional Access policies](../identity-protection/howto-identity-protection-configure-risk-policies.md) for users marked as risky.

+### Move management of groups

+* For security groups, use your existing business logic that assigns users to security groups. Migrate the logic and capability to Azure AD and dynamic groups.

+* For self-managed group capabilities provided by Microsoft Identity Manager, replace the capability with self-service group management.

+* You can [convert distribution lists to Microsoft 365 groups](/microsoft-365/admin/manage/upgrade-distribution-lists) in Outlook. This is a great way to give your organization's distribution lists all the features and functionality of Microsoft 365 groups.

+You can simplify your environment by removing application provisioning flows from on-premises identity management (IDM) systems such as Microsoft Identity Manager. Based on your application discovery, categorize your application based on the following characteristics:

+* Applications in your environment that have a provisioning integration with the [Azure AD application gallery](https://www.microsoft.com/security/business/identity-access-management/integrated-apps-azure-ad).

+* Applications that aren't in the gallery but support the SCIM 2.0 protocol. These applications are natively compatible with the Azure AD cloud provisioning service.

+* On-premises applications that have an ECMA connector available. These applications can be integrated with [Azure AD on-premises application provisioning](../app-provisioning/on-premises-application-provisioning-architecture.md).

+For more information, check [Plan an automatic user-provisioning deployment for Azure Active Directory](../app-provisioning/plan-auto-user-provisioning.md).

+### Move to cloud HR provisioning

+You can reduce your on-premises footprint by moving the HR provisioning workflows from on-premises IDM systems, such as Microsoft Identity Manager, to Azure AD. Two account types are available for Azure AD cloud HR provisioning:

+* For new employees who are exclusively using applications that use Azure AD, you can choose to provision *cloud-only accounts*. This provisioning helps you contain the footprint of Active Directory.

+* For new employees who need access to applications that have dependency on Active Directory, you can provision *hybrid accounts*.

+Azure AD cloud HR provisioning can also manage Active Directory accounts for existing employees. For more information, see [Plan cloud HR application to Azure Active Directory user provisioning](../app-provisioning/plan-cloud-hr-provision.md) and [Plan the deployment project](../app-provisioning/plan-auto-user-provisioning.md).

+If your organization provisions accounts in Active Directory or other on-premises directories for external identities such as vendors, contractors, or consultants, you can simplify your environment by managing those third-party user objects natively in the cloud. Here are some possibilities:

+* For new external users, use [Azure AD External Identities](../external-identities/external-identities-overview.md), which will stop the Active Directory footprint of users.

+* For existing Active Directory accounts that you provision for external identities, you can remove the overhead of managing local credentials (for example, passwords) by configuring them for business-to-business (B2B) collaboration. Follow the steps in [Invite internal users to B2B collaboration](../external-identities/invite-internal-users.md).

+* Use [Azure AD entitlement management](../governance/entitlement-management-overview.md) to grant access to applications and resources. Most companies have dedicated systems and workflows for this purpose that you can now move out of on-premises tools.

+* Use [access reviews](../governance/access-reviews-external-users.md) to remove access rights and/or external identities that are no longer needed.

+### Move non-Windows workstations

+You can integrate non-Windows workstations with Azure AD to enhance the user experience and to benefit from cloud-based security features such as conditional access.

+* For macOS:

+ * Register macOS to Azure AD and [enroll/manage them by using a mobile device management solution](/mem/intune/enrollment/macos-enroll).

+ * Deploy the [Microsoft Enterprise SSO (single sign-on) plug-in for Apple devices](../develop/apple-sso-plugin.md).

+ * Plan to deploy [Platform SSO for macOS 13](https://techcommunity.microsoft.com/t5/microsoft-endpoint-manager-blog/microsoft-simplifies-endpoint-manager-enrollment-for-apple/ba-p/3570319).

+* For Linux, you can [sign in to a Linux virtual machine (VM) by using Azure Active Directory credentials](../../active-directory/devices/howto-vm-sign-in-azure-ad-linux.md).

+### Replace other Windows versions for workstations

+If you have the following operating systems on workstations, consider upgrading to the latest versions to benefit from cloud-native management (Azure AD join and unified endpoint management):

+* Windows Server

+### VDI solution

+This project has two primary initiatives:

+* **New deployments**: Deploy a cloud-managed virtual desktop infrastructure (VDI) solution, such as Windows 365 or Azure Virtual Desktop, that doesn't require on-premises Active Directory.

+* **Existing deployments**: If your existing VDI deployment is dependent on Active Directory, use business objectives and goals to determine whether you maintain the solution or migrate it to Azure AD.

+* [Deploy Azure AD-joined VMs in Azure Virtual Desktop](../../virtual-desktop/deploy-azure-ad-joined-vm.md)

+To help maintain a secure environment, Azure AD supports modern authentication protocols. To transition application authentication from Active Directory to Azure AD, you must:

+* Determine which applications can migrate to Azure AD with no modification.

+* Determine which applications have an upgrade path that enables you to migrate with an upgrade.

+* Determine which applications require replacement or significant code changes to migrate.

+The outcome of your application discovery initiative is to create a prioritized list for migrating your application portfolio. The list contains applications that:

+* Require an upgrade or update to the software, and an upgrade path is available.

+* Require an upgrade or update to the software, but an upgrade path isn't available.

+By using the list, you can further evaluate the applications that don't have an existing upgrade path. Determine whether business value warrants updating the software or if it should be retired. If the software should be retired, decide whether you need a replacement.

+Based on the results, you might redesign aspects of your transformation from Active Directory to Azure AD. There are approaches that you can use to extend on-premises Active Directory to Azure infrastructure as a service (IaaS) (lift and shift) for applications with unsupported authentication protocols. We recommend that you set a policy that requires an exception to use this approach.

+After you've segmented your app portfolio, you can prioritize migration based on business value and business priority. You can use tools to create or refresh your app inventory.

+There are three main ways to categorize your apps:

+* **Modern authentication apps**: These applications use modern authentication protocols (such as OIDC, OAuth2, SAML, or WS-Federation) or that use a federation service such as Active Directory Federation Services (AD FS).

+* **Web access management (WAM) tools**: These applications use headers, cookies, and similar techniques for SSO. These apps typically require a WAM identity provider, such as Symantec SiteMinder.

+* **Legacy apps**: These applications use legacy protocols such as Kerberos, LDAP, Radius, Remote Desktop, and NTLM (not recommended).

+Azure AD can be used with each type of application to provide levels of functionality that will result in different migration strategies, complexity, and trade-offs. Some organizations have an application inventory that can be used as a discovery baseline. (It's common that this inventory isn't complete or updated.)

+* If you're using AD FS, use the [AD FS application activity report](../manage-apps/migrate-adfs-application-activity.md).

+* If you're using a different identity provider, use the logs and configuration.

+The following tools can help you discover applications that use LDAP:

+* [Event1644Reader](/troubleshoot/windows-server/identity/event1644reader-analyze-ldap-query-performance): Sample tool for collecting data on LDAP queries made to domain controllers by using field engineering logs.

+* [Microsoft 365 Defender for Identity](/defender-for-identity/monitored-activities): Security solution that uses a sign-in operations monitoring capability. (Note that it captures binds by using LDAP, not Secure LDAP.)

+* [PSLDAPQueryLogging](https://github.com/RamblingCookieMonster/PSLDAPQueryLogging): GitHub tool for reporting on LDAP queries.

+### Migrate AD FS or other federation services

+When you plan your migration to Azure AD, consider migrating the apps that use modern authentication protocols (such as SAML and OpenID Connect) first. You can reconfigure these apps to authenticate with Azure AD either via a built-in connector from the Azure App Gallery or via registration in Azure AD.

+After you move SaaS applications that were federated to Azure AD, there are a few steps to decommission the on-premises federation system:

+* [Move application authentication to Azure Active Directory](../manage-apps/migrate-adfs-apps-to-azure.md)

+* [Migrate from Azure AD Multi-Factor Authentication Server to Azure AD Multi-Factor Authentication](../authentication/how-to-migrate-mfa-server-to-azure-mfa.md)

+* [Move remote access to internal applications](#move-remote-access-to-internal-applications), if you're using Azure AD Application Proxy

+>If you're using other features, verify that those services are relocated before you decommission Active Directory Federation Services.

+### Move WAM authentication apps

+This project focuses on migrating SSO capability from WAM systems to Azure AD. To learn more, see [Migrate applications from Symantec SiteMinder to Azure AD](https://azure.microsoft.com/resources/migrating-applications-from-symantec-siteminder-to-azure-active-directory/).

+### Define an application server management strategy

+In terms of infrastructure management, on-premises environments often use a combination of Group Policy objects (GPOs) and Microsoft Endpoint Configuration Manager features to segment management duties. For example, duties can be segmented into security policy management, update management, configuration management, and monitoring.

+Active Directory is for on-premises IT environments, and Azure AD is for cloud-based IT environments. One-to-one parity of features isn't present here, so you can manage application servers in several ways.

+For example, Azure Arc helps bring many of the features that exist in Active Directory together into a single view when you use Azure AD for identity and access management (IAM). You can also use Azure Active Directory Domain Services (Azure AD DS) to domain-join servers in Azure AD, especially when you want those servers to use GPOs for specific business or technical reasons.

+Use the following table to determine what Azure-based tools you can use to replace the on-premises environment:

+| Management area | On-premises (Active Directory) feature | Equivalent Azure AD feature |

+| Security policy management| GPO, Microsoft Endpoint Configuration Manager| [Microsoft 365 Defender for Cloud](https://azure.microsoft.com/services/security-center/) |

+| Update management| Microsoft Endpoint Configuration Manager, Windows Server Update Services| [Azure Automation Update Management](../../automation/update-management/overview.md) |

+| Configuration management| GPO, Microsoft Endpoint Configuration Manager| [Azure Automation State Configuration](../../automation/automation-dsc-overview.md) |

+Here's more information that you can use for application server management:

+* [Azure Arc](https://azure.microsoft.com/services/azure-arc/) enables Azure features for non-Azure VMs. For example, you can use it to get Azure features for Windows Server when it's used on-premises or on Amazon Web Services.

+* If you must wait to migrate or perform a partial migration, you can use GPOs with [Azure AD DS](https://azure.microsoft.com/services/active-directory-ds/).

+If you require management of application servers with Microsoft Endpoint Configuration Manager, you can't achieve this by using Azure AD DS. Microsoft Endpoint Configuration Manager isn't supported to run in an Azure AD DS environment. Instead, you'll need to extend your on-premises Active Directory instance to a domain controller running on an Azure VM. Or, you'll need to deploy a new Active Directory instance to an Azure IaaS virtual network.

+### Define the migration strategy for legacy applications

+Legacy applications have dependencies like these to Active Directory:

+* User authentication and authorization: Kerberos, NTLM, LDAP bind, ACLs.

+* Access to directory data: LDAP queries, schema extensions, read/write of directory objects.

+* Server management: As determined by the [server management strategy](#define-an-application-server-management-strategy).

+To reduce or eliminate those dependencies, you have three main approaches.

+#### Approach 1

+In the most preferred approach, you undertake projects to migrate from legacy applications to SaaS alternatives that use modern authentication. Have the SaaS alternatives authenticate to Azure AD directly:

+1. Deploy Azure AD DS into an Azure virtual network.

+2. Lift and shift legacy apps to VMs on the Azure virtual network that are domain-joined to Azure AD DS.

+3. Publish legacy apps to the cloud by using Azure AD Application Proxy or a [secure hybrid access](../manage-apps/secure-hybrid-access.md) partner.

+4. As legacy apps retire through attrition, eventually decommission Azure AD DS running in the Azure virtual network.

+>[!NOTE]

+>* Use Azure AD DS if the dependencies are aligned with [common deployment scenarios for Azure AD DS](../../active-directory-domain-services/scenarios.md).

+>* To validate if Azure AD DS is a good fit, you might use tools like [Service Map in Azure Marketplace](https://azuremarketplace.microsoft.com/marketplace/apps/Microsoft.ServiceMapOMS?tab=Overview) and [automatic dependency mapping with Service Map and Live Maps](https://techcommunity.microsoft.com/t5/system-center-blog/automatic-dependency-mapping-with-service-map-and-live-maps/ba-p/351867).

+>* Validate that your SQL Server instantiations can be [migrated to a different domain](https://social.technet.microsoft.com/wiki/contents/articles/24960.migrating-sql-server-to-new-domain.aspx). If your SQL service is running in virtual machines, [use this guidance](/azure/azure-sql/migration-guides/virtual-machines/sql-server-to-sql-on-azure-vm-individual-databases-guide).

+#### Approach 2

+If the first approach isn't possible and an application has a strong dependency on Active Directory, you can extend on-premises Active Directory to Azure IaaS.

+You can replatform to support modern serverless hosting--for example, use platform as a service (PaaS). Or, you can update the code to support modern authentication. You can also enable the app to integrate with Azure AD directly. [Learn about Microsoft Authentication Library in the Microsoft identity platform](../develop/msal-overview.md).

+1. Connect an Azure virtual network to the on-premises network via virtual private network (VPN) or Azure ExpressRoute.

+2. Deploy new domain controllers for the on-premises Active Directory instance as virtual machines into the Azure virtual network.

+3. Lift and shift legacy apps to VMs on the Azure virtual network that are domain joined.

+4. Publish legacy apps to the cloud by using Azure AD Application Proxy or a [secure hybrid access](../manage-apps/secure-hybrid-access.md) partner.

+5. Eventually, decommission the on-premises Active Directory infrastructure and run Active Directory in the Azure virtual network entirely.

+6. As legacy apps retire through attrition, eventually decommission the Active Directory instance running in the Azure virtual network.

+#### Approach 3

+If the first migration isn't possible and an application has a strong dependency on Active Directory, you can deploy a new Active Directory instance to Azure IaaS. Leave the applications as legacy applications for the foreseeable future, or sunset them when the opportunity arises.

+This approach enables you to decouple the app from the existing Active Directory instance to reduce surface area. We recommend that you consider it only as a last resort.

+1. Deploy a new Active Directory instance as virtual machines in an Azure virtual network.

+2. Lift and shift legacy apps to VMs on the Azure virtual network that are domain-joined to the new Active Directory instance.

+3. Publish legacy apps to the cloud by using Azure AD Application Proxy or a [secure hybrid access](../manage-apps/secure-hybrid-access.md) partner.

+4. As legacy apps retire through attrition, eventually decommission the Active Directory instance running in the Azure virtual network.

+| Strategy | Azure AD DS | Extend Active Directory to IaaS | Independent Active Directory instance in IaaS |

+| Decoupling from on-premises Active Directory| Yes| No| Yes |

+| Allowing schema extensions| No| Yes| Yes |

+| Potential reconfiguration of apps required (for example, ACLs or authorization)| Yes| No| Yes |

+### Move VPN authentication

+This project focuses on moving your VPN authentication to Azure AD. It's important to know that different configurations are available for VPN gateway connections. You need to determine which configuration best fits your needs. For more information on designing a solution, see [VPN gateway design](../../vpn-gateway/design.md).

+Here are key points about usage of Azure AD for VPN authentication:

+ * [Tutorial: Azure Active Directory SSO integration with Cisco AnyConnect](../saas-apps/cisco-anyconnect.md)

+ * [Tutorial: Azure Active Directory SSO integration with Palo Alto Networks GlobalProtect](../saas-apps/palo-alto-networks-globalprotect-tutorial.md)

+* For Windows 10 devices, consider integrating [Azure AD support into the built-in VPN client](/windows-server/remote/remote-access/vpn/ad-ca-vpn-connectivity-windows10).

+* After you evaluate this scenario, you can implement a solution to remove your dependency with on-premises to authenticate to VPN.

+### Move remote access to internal applications

+To simplify your environment, you can use [Azure AD Application Proxy](../app-proxy/application-proxy.md) or [secure hybrid access](../manage-apps/secure-hybrid-access.md) partners to provide remote access. This will allow you to remove the dependency on on-premises reverse proxy solutions.

+It's important to mention that enabling remote access to an application by using the preceding technologies is an interim step. You'll need to do more work to completely decouple the application from Active Directory.

+Azure AD DS allows you to migrate application servers to the cloud IaaS and decouple from Active Directory, while using Azure AD Application Proxy to enable remote access. To learn more about this scenario, check [Deploy Azure AD Application Proxy for Azure Active Directory Domain Services](../../active-directory-domain-services/deploy-azure-app-proxy.md).

+[Implement a cloud-first approach](road-to-the-cloud-implement.md)

+ Title: Road to the cloud - Determine cloud transformation posture when moving identity and access management from Active Directory to Azure AD

+description: Determine your cloud transformation posture when planning your migration of IAM from Active Directory to Azure AD.

+Active Directory, Azure Active Directory (Azure AD), and other Microsoft tools are at the core of identity and access management (IAM). For example, Active Directory Domain Services (AD DS) and Microsoft Endpoint Configuration Manager provide device management in Active Directory. In Azure AD, Intune provides the same capability.

+As part of most modernization, migration, or Zero Trust initiatives, organizations shift IAM activities from using on-premises or infrastructure-as-a-service (IaaS) solutions to using built-for-the-cloud solutions. For an IT environment that uses Microsoft products and services, Active Directory and Azure AD play a role.

+Many companies that migrate from Active Directory to Azure AD start with an environment that's similar to the following diagram. The diagram overlays three pillars:

+* **Applications**: Includes applications, resources, and their underlying domain-joined servers.

+* **Devices**: Focuses on domain-joined client devices.

+* **Users**: Represents the human and non-human identities and attributes that access resources from devices.

+[](media/road-to-cloud-posture/road-to-the-cloud-start.png#lightbox)

+Microsoft has modeled five states of transformation that commonly align with the business goals of customers. As the goals of customers mature, it's typical for them to shift from one state to the next at a pace that suits their resources and culture. This approach closely follows [Active Directory in Transition: Gartner Survey Results and Analysis](https://www.gartner.com/en/documents/4006741).

+The five states have exit criteria to help you determine where your environment resides today. Some projects, such as application migration, span all five states. Other projects span a single state.

+The content then provides more detailed guidance that's organized to help with intentional changes to people, process, and technology. The guidance can help you:

+* Establish an Azure AD footprint.

+* Implement a cloud-first approach.

+* Start to migrate out of your Active Directory environment.

+Guidance is organized by user management, device management, and application management according to the preceding pillars.

+Organizations that are formed in Azure AD rather than in Active Directory don't have the legacy on-premises environment that more established organizations must contend with. For them, or for customers who are completely re-creating their IT environment in the cloud, becoming 100 percent cloud-centric can happen as the new IT environment is established.

+For customers who have an established on-premises IT capability, the transformation process introduces complexity that requires careful planning. Also, because Active Directory and Azure AD are separate products targeted at different IT environments, they don't have like-for-like features. For example, Azure AD doesn't have the notion of Active Directory domain and forest trusts.

+## Five states of transformation

+In enterprise-sized organizations, IAM transformation, or even transformation from Active Directory to Azure AD, is typically a multi-year effort with multiple states. You analyze your environment to determine your current state, and then set a goal for your next state. Your goal might remove the need for Active Directory entirely, or you might decide not to migrate some capability to Azure AD and leave it in place.

+The states logically group initiatives into projects toward completing a transformation. During the state transitions, you put interim solutions in place. The interim solutions enable the IT environment to support IAM operations in both Active Directory and Azure AD. The interim solutions must also enable the two environments to interoperate.

+The following diagram shows the five states:

+[](media/road-to-cloud-posture/road-to-the-cloud-five-states.png#lightbox)

+> The states in this diagram represent a logical progression of cloud transformation. Your ability to move from one state to the next depends on the functionality that you've implemented and the capabilities within that functionality to move to the cloud.

+### State 1: Cloud attached

+In the cloud-attached state, organizations have created an Azure AD tenant to enable user productivity and collaboration tools. The tenant is fully operational.

+Most companies that use Microsoft products and services in their IT environment are already in or beyond this state. In this state, operational costs might be higher because there's an on-premises environment and a cloud environment to maintain and make interactive. People must have expertise in both environments to support their users and the organization.

+In this state:

+* Devices are joined to Active Directory and managed through Group Policy or on-premises device management tools.

+* Users are managed in Active Directory, provisioned via on-premises identity management (IDM) systems, and synchronized to Azure AD through Azure AD Connect.

+* Apps are authenticated to Active Directory and to federation servers like Active Directory Federation Services (AD FS) through a web access management (WAM) tool, Microsoft 365, or other tools such as SiteMinder and Oracle Access Manager.

+### State 2: Hybrid

+In the hybrid state, organizations start to enhance their on-premises environment through cloud capabilities. The solutions can be planned to reduce complexity, increase security posture, and reduce the footprint of the on-premises environment.

+During the transition and while operating in this state, organizations grow the skills and expertise for using Azure AD for IAM solutions. Because user accounts and device attachments are relatively easy and a common part of day-to-day IT operations, this is the approach that most organizations have used.

+In this state:

+* Non-Microsoft platforms based on software as a service (SaaS) start being integrated with Azure AD. Examples are Salesforce and ServiceNow.

+* Legacy apps are authenticating to Azure AD via Application Proxy or partner solutions that offer secure hybrid access.

+* Some legacy apps are authenticated in the cloud through Azure AD DS and Application Proxy.

+### State 3: Cloud first

+In the cloud-first state, the teams across the organization build a track record of success and start planning to move more challenging workloads to Azure AD. Organizations typically spend the most time in this state of transformation. As complexity, the number of workloads, and the use of Active Directory grow over time, an organization needs to increase its effort and its number of initiatives to shift to the cloud.

+In this state:

+* New Windows clients are joined to Azure AD and are managed through Intune.

+* ECMA connectors are used to provision users and groups for on-premises apps.

+* All apps that previously used an AD DS-integrated federated identity provider, such as AD FS, are updated to use Azure AD for authentication. If you were using password-based authentication through that identity provider for Azure AD, it's migrated to password hash synchronization.

+* Azure AD provides a business-to-business (B2B) collaboration capability.

+### State 4: Active Directory minimized

+Azure AD provides most IAM capability, whereas edge cases and exceptions continue to use on-premises Active Directory. A state of minimizing Active Directory is more difficult to achieve, especially for larger organizations that have significant on-premises technical debt.

+Azure AD continues to evolve as your organization's transformation matures, bringing new features and tools that you can use. Organizations are required to deprecate capabilities or build new capabilities to provide replacement.

+In this state:

+* New users provisioned through the HR provisioning capability are created directly in Azure AD.

+* A plan to move apps that depend on Active Directory and are part of the vision for the future-state Azure AD environment is being executed. A plan to replace services that won't move (file, print, or fax services) is in place.

+* On-premises workloads have been replaced with cloud alternatives such as Windows Virtual Desktop, Azure Files, or Google Cloud Print. Azure SQL Managed Instance replaces SQL Server.

+### State 5: 100% cloud

+In the 100%-cloud state, Azure AD and other Azure tools provide all IAM capability. This is the long-term aspiration for many organizations.

+In this state:

+* No on-premises IAM footprint is required.

+* All devices are managed in Azure AD and cloud solutions such as Intune.

+* The user identity lifecycle is managed through Azure AD.

+* Network services that rely on Active Directory are relocated.

+## Transformation analogy

+1. **Establish a new location**: You purchase your destination and establish connectivity between the current location and the new location. These activities enable you to maintain your productivity and ability to operate. For more information, see [Establish an Azure AD footprint](road-to-the-cloud-establish.md). The results transition you to state 2.

+1. **Limit new items in the old location**: You stop investing in the old location and set a policy to stage new items in the new location. For more information, see [Implement a cloud-first approach](road-to-the-cloud-implement.md). These activities set the foundation to migrate at scale and reach state 3.

+1. **Move existing items to the new location**: You move items from the old location to the new location. You assess the business value of the items to determine if you'll move them as is, upgrade them, replace them, or deprecate them. For more information, see [Transition to the cloud](road-to-the-cloud-migrate.md).

+ These activities enable you to complete state 3 and reach states 4 and 5. Based on your business objectives, you decide what end state you want to target.

+Transformation to the cloud isn't only the identity team's responsibility. The organization needs coordination across teams to define policies that include people and process change, along with technology. Using a coordinated approach helps ensure consistent progress and reduces the risk of regressing to on-premises solutions. Involve teams that manage:

+* Devices/endpoints

+* Networks

+### High-level journey

+As organizations start a migration of IAM to Azure AD, they must determine the prioritization of efforts based on their specific needs. Operational staff and support staff must be trained to perform their jobs in the new environment. The following chart shows the high-level journey for migration from Active Directory to Azure AD:

+* **Establish an Azure AD footprint**: Initialize your new Azure AD tenant to support the vision for your end-state deployment. Adopt a [Zero Trust](https://www.microsoft.com/security/blog/2020/04/30/zero-trust-deployment-guide-azure-active-directory/) approach and a security model that [helps protect your tenant from on-premises compromise](../fundamentals/protect-m365-from-on-premises-attacks.md) early in your journey.

+* **Implement a cloud-first approach**: Establish a policy that all new devices, apps, and services should be cloud-first. New applications and services that use legacy protocols (for example, NTLM, Kerberos, or LDAP) should be by exception only.

+* **Transition to the cloud**: Shift the management and integration of users, apps, and devices away from on-premises and over to cloud-first alternatives. Optimize user provisioning by taking advantage of [cloud-first provisioning capabilities](../governance/what-is-provisioning.md) that integrate with Azure AD.

+The transformation changes how users accomplish tasks and how support teams provide user support. The organization should design and implement initiatives or projects in a way that minimizes the impact on user productivity.

+As part of the transformation, the organization introduces self-service IAM capabilities. Some parts of the workforce more easily adapt to the self-service user environment that's prevalent in cloud-based businesses.

+Aging applications might need to be updated or replaced to operate well in cloud-based IT environments. Application updates or replacements can be costly and time-consuming. The planning and other stages must also take the age and capability of the organization's applications into account.

+1. Enter a unique display name and description for the workflow and select **Next**.

+1. On the **configure scope** page select the **Trigger type** and execution conditions to be used for this workflow. For more information on what can be configured, see: [Configure scope](understanding-lifecycle-workflows.md#configure-scope).

+1. Under rules, select the **Property**, **Operator**, and give it a **value**. The following picture gives an example of a rule being set up for a sales department.

+1. To view your rule syntax, select the **View rule syntax** button. You can copy and paste multiple user property rules on this screen. For more detailed information on which properties that can be included see: [User Properties](/graph/aad-advanced-queries?tabs=http#user-properties). When you are finished adding rules, select **Next**.

+1. On the **Review tasks** page you can add a task to the template by selecting **Add task**. To enable an existing task on the list, select **enable**. You're also able to disable a task by selecting **disable**. To remove a task from the template, select **Remove** on the selected task. When you are finished with tasks for your workflow, select **Next**.

+1. On the **Review+create** page you are able to review the workflow's settings. You can also choose whether or not to enable the schedule for the workflow. Select **Create** to create the workflow.

+1. In the search box, enter a domain name to search for the Azure AD directory or domain. You can also add domains that are not in Azure AD. Be sure to enter the entire domain name.

+1. Confirm that the organization name(s) and authentication type(s) are correct. User sign in, prior to being able to access the MyAccess portal, depends on the authentication type for their organization. If the authentication type for a connected organization is Azure AD, all users with an account in any verified domain of that Azure AD directory will sign into their directory, and then can request access to access packages that allow that connected organization. If the authentication type is One-time passcode, this allows users with email addresses from just that domain to visit the MyAccess portal. After they authenticate with the passcode, the user can make a request.

+1. Select **Add** to add the Azure AD directory or domain. **You can add multiple Azure AD directories and domains**.

+1. After you've added the Azure AD directories or domains, select **Select**.

+ The organization(s) appears in the list.

+- [customTaskExtension resource type](/graph/api/resources/identitygovernance-customtaskextension?view=graph-rest-beta)

+- [userProcessingResult resource type](/graph/api/resources/identitygovernance-userprocessingresult?view=graph-rest-beta)

+- [taskReport resource type](/graph/api/resources/identitygovernance-taskreport?view=graph-rest-beta)

+- [run resource type](/graph/api/resources/identitygovernance-run?view=graph-rest-beta)

+- [taskProcessingResult resource type](/graph/api/resources/identitygovernance-taskprocessingresult?view=graph-rest-beta)

+- [workflowTemplate resource type](/graph/api/resources/identitygovernance-workflowtemplate?view=graph-rest-beta)

+- [workflowVersion resource type](/graph/api/resources/identitygovernance-workflowversion?view=graph-rest-beta)

+1. You can reorder the order in which tasks are executed in the workflow by selecting the **Reorder** button. You can also remove a task from a workflow by using the **Remove** button.

+

+ - Global Administrator

+ - Security Administrator

+ - Security Operator

+ - Security Reader

+- **The recipients of this email** - Users in the Global Administrator, Security Administrator, or Security Reader roles are automatically added to this list. We attempt to send emails to the first 20 members of each role. If a user is enrolled in PIM to elevate to one of these roles on demand, then **they will only receive emails if they are elevated at the time the email is sent**.

+Users in the Global Administrator, Security Administrator, or Security Reader roles are automatically added to this list. We attempt to send emails to the first 20 members of each role. If a user is enrolled in PIM to elevate to one of these roles on demand, then **they will only receive emails if they are elevated at the time the email is sent**

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Conditional Access Administrator.

+| Global Administrator | Full access to Identity Protection | |

+| Security Administrator | Full access to Identity Protection | Reset password for a user |

+| Security Operator | View all Identity Protection reports and Overview <br><br> Dismiss user risk, confirm safe sign-in, confirm compromise | Configure or change policies <br><br> Reset password for a user <br><br> Configure alerts |

+| Security Reader | View all Identity Protection reports and Overview | Configure or change policies <br><br> Reset password for a user <br><br> Configure alerts <br><br> Give feedback on detections |

+| Global Reader | Read-only access to Identity Protection | |

+Currently, the Security Operator role can't access the Risky sign-ins report.

+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

+{

+"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": {

+ "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"

+}

+| August | 99.999% | 99.999% |

+Follow the instructions given in the [link](https://support.airtable.com/docs/configuring-sso-with-azure-ad) to configure single sign-on on **Airtable** side.

+> * [Single sign-on](../manage-apps/add-application-portal-setup-oidc-sso.md) to Apple Business Manager (recommended).

+Leave this window open to copy the Tenant URL from Apple Business Manager to Azure AD, which is: `https://federation.apple.com/feeds/business/scim`

+ 

+ > [!NOTE]

+ > The secret token shouldnΓÇÖt be shared with anyone other than the Azure AD administrator.

+* Add Apple Business Manager from the Azure AD application gallery to start managing provisioning to Apple Business Manager. If you have previously setup Apple Business Manager for SSO, you can use the same application. However it is recommended that you create a separate app when testing out the integration initially.

+* To add the Apple Business Manager Azure AD app with Microsoft tenants, the administrator of the tenants must go through the federated authentication setup process, including testing authentication. When authentication has succeeded, the Apple Business Manager Azure AD app is populated in the tenant and the administrator can federate domains and configure Apple Business Manager to use SCIM (System for Cross-domain Identity Management) for directory sync.

+ [Use federated authentication with MS Azure AD in Apple Business Manager](https://support.apple.com/en-ke/guide/apple-business-manager/axmb02f73f18/web)

+

+ 

+ 

+ 

+ 

+5. Under the **Admin Credentials** section, input the **SCIM 2.0 base URL and Access Token** values retrieved from Apple Business Manager in **Tenant URL** and **Secret Token** respectively. Click **Test Connection** to ensure Azure AD can connect to Apple Business Manager. If the connection fails, ensure your Apple Business Manager account has Admin permissions and try again.

+ 

+ 

+ 

+ 

+ 

+> * [Single sign-on](../manage-apps/add-application-portal-setup-oidc-sso.md) to Apple School Manager (recommended).

+Leave this window open to copy the Tenant URL from Apple School Manager to Azure AD, which is: `https://federation.apple.com/feeds/school/scim`

+ 

+ > [!NOTE]

+ > The secret token shouldnΓÇÖt be shared with anyone other than the Azure AD administrator.

+* Add Apple School Manager from the Azure AD application gallery to start managing provisioning to Apple School Manager. If you have previously setup Apple School Manager for SSO, you can use the same application. However it is recommended that you create a separate app when testing out the integration initially.

+* To add the Apple School Manager Azure AD app with Microsoft tenants, the administrator of the tenants must go through the federated authentication setup process, including testing authentication. When authentication has succeeded, the Apple School Manager Azure AD app is populated in the tenant and the administrator can federate domains and configure Apple School Manager to use SCIM (System for Cross-domain Identity Management) for directory sync.

+ [Use federated authentication with MS Azure AD in Apple School Manager](https://support.apple.com/en-ke/guide/apple-school-manager/axmb02f73f18/web)

+

+ 

+ 

+ 

+ 

+5. Under the **Admin Credentials** section, input the **SCIM 2.0 base URL and Access Token** values retrieved from Apple School Manager in **Tenant URL** and **Secret Token** respectively. Click **Test Connection** to ensure Azure AD can connect to Apple School Manager. If the connection fails, ensure your Apple School Manager account has Admin permissions and try again.

+ 

+ 

+ 

+ 

+ 

+ > The value is not real. Update the value with the actual Sign-On URL. See [HRworks Single Sign-On Helpcenter article](https://help.hrworks.de/en/single-sign-on) to get the value. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+|  | [Onfido](https://onfido.com/landing/onfido-microsoft-idv-service/) Start issuing and accepting verifiable credentials in minutes. With verifiable credentials and Onfido you can verify a personΓÇÖs identity while respecting privacy. Digitally validate information on a personΓÇÖs ID or their biometrics.| * |

+|  | [Vu Security](https://landings.vusecurity.com/microsoft-verifiable-credentials) Verifiable credentials with just a selfie and your ID.| * |

+|  | [Jumio](https://www.jumio.com/microsoft-verifiable-credentials/) is helping to support a new form of digital identity by Microsoft based on verifiable credentials and decentralized identifiers standards to let consumers verify once and use everywhere.| * |

+|  | [Idemia](https://na.idemia.com/identity/verifiable-credentials/) Integration with Verified ID enables ΓÇ£Verify once, use everywhereΓÇ¥ functionality.| * |

+|  | [Acuant](https://www.acuant.com/microsoft-acuant-verifiable-credentials-my-digital-id/) - My Digital ID - Create Your Digital Identity Once, Use It Everywhere.| * |

+|  | [Clear](https://ir.clearme.com/news-events/press-releases/detail/25/clear-collaborates-with-microsoft-to-create-more-secure) Collaborates with Microsoft to Create More Secure Digital Experience Through Verification Credential.| * |

+\* - no documentation available yet

+1. Create a website that you can use to distribute the files. If you specified **https://contoso.com** as your domain, the URLs for each of the files would look as shown below:

+- [Learn how to verify Microsoft Entra Verified ID credentials](verifiable-credentials-configure-verifier.md).

+Regardless of which language of the sample you are using, they will pickup the Azure AppService hostname `https://something.azurewebsites.net` and use it as the public endpoint. You don't need to configure something extra to make it work. If you make changes to the code or configuration, you need to redeploy the sample to Azure AppServices. Troubleshooting/debugging will not be as easy as running the sample on your local machine, where traces to the console window shows you errors, but you can achieve almost the same by using the [Log Stream](../../app-service/troubleshoot-diagnostic-logs.md#stream-logs).

+* [Azure CLI][azure-cli-install] or [Azure PowerShell][azure-powershell-install] and the `aks-preview` 0.5.96 or later CLI extension installed.

+[trivy]: https://github.com/aquasecurity/trivy

+Once you've created a server and deployed a tabular model to it, clients can connect and begin exploring data. This article describes connecting to an Azure Analysis Services resource by using the Excel desktop app. Connecting to an Azure Analysis Services resource is not supported in Excel for the Web or Excel for MacOS.

+ Title: Authentication and authorization - Overview

+description: Learn about authentication and authorization features in Azure API Management to secure access to the management, API, and developer features

+# Authentication and authorization in Azure API Management

+This article is an introduction to API Management capabilities that help you secure users' access to API Management features and APIs.

+API Management provides a rich, flexible set of features to support API authentication and authorization in addition to the standard control-plane authentication and role-based access control (RBAC) required when interacting with Azure services.

+API Management also provides a fully customizable, standalone, managed [developer portal](api-management-howto-developer-portal.md), which can be used externally (or internally) to allow developer users to discover and interact with the APIs published through API Management. The developer portal has several options to facilitate secure user sign-up and sign-in.

+The following diagram is a conceptual view of Azure API Management, showing the management plane (Azure control plane), API gateway (data plane), and developer portal (user plane), each with at least one option to secure interaction. For an overview of API Management components, see [What is Azure API Management?](api-management-key-concepts.md)

+## Management plane

+Administrators, operators, developers, and DevOps service principals are examples of the different personas required to manage an Azure API Management instance in a customer environment.

+Azure API Management relies on Azure Active Directory (Azure AD), which includes optional features such as multifactor authentication (MFA), and Azure RBAC to enable fine-grained access to the API Management service and its entities including APIs and policies. For more information, see [How to use role-based access control in Azure API Management](api-management-role-based-access-control.md).

+The management plane can be accessed via an Azure AD login (or token) through the Azure portal, infrastructure-as-code templates (such as Azure Resource Manager or Bicep), the REST API, client SDKs, the Azure CLI, or Azure PowerShell.

+## Gateway (data plane)

+API authentication and authorization in API Management involve the end-to-end communication of client apps *through* the API Management gateway to backend APIs.

+In many customer environments, [OAuth 2.0](https://oauth.net/2/) is the preferred API authorization protocol. API Management supports OAuth 2.0 across the data plane.

+### OAuth concepts

+What happens when a client app calls an API with a request that is secured using TLS and OAuth? The following is an abbreviated example flow:

+* The client (the calling app, or *bearer*) authenticates using credentials to an *identity provider*.

+* The client obtains a time-limited *access token* (a JSON web token, or JWT) from the identity provider's *authorization server*.

+

+ The identity provider (for example, Azure AD) is the *issuer* of the token, and the token includes an *audience claim* that authorizes access to a *resource server* (for example, to a backend API, or to the API Management gateway itself).

+* The client calls the API and presents the access token - for example, in an Authorization header.

+* The *resource server* validates the access token. Validation is a complex process that includes a check that the *issuer* and *audience* claims contain expected values.

+* Based on token validation criteria, access to resources of the [backend] API is then granted.

+Depending on the type of client app and scenarios, different *authentication flows* are needed to request and manage tokens. For example, the authorization code flow and grant type are commonly used in apps that call web APIs. Learn more about [OAuth flows and application scenarios in Azure AD](../active-directory/develop/authentication-flows-app-scenarios.md).

+### OAuth 2.0 authorization scenarios

+#### Audience is the backend

+The most common scenario is when the Azure API Management instance is a "transparent" proxy between the caller and backend API, and the calling application requests access to the API directly. The scope of the access token is between the calling application and backend API.

+In this scenario, the access token sent along with the HTTP request is intended for the backend API, not API Management. However, API Management still allows for a defense in depth approach. For example, configure policies to [validate the token](api-management-access-restriction-policies.md#ValidateJWT), rejecting requests that arrive without a token, or a token that's not valid for the intended backend API. You can also configure API Management to check other claims of interest extracted from the token.

+For an example, see [Protect an API in Azure API Management using OAuth 2.0 authorization with Azure Active Directory](api-management-howto-protect-backend-with-aad.md).

+#### Audience is API Management

+In this scenario, the API Management service acts on behalf of the API, and the calling application requests access to the API Management instance. The scope of the access token is between the calling application and API Management.

+There are different reasons for wanting to do this. For example:

+* The backend is a legacy API that can't be updated to support OAuth.

+ API Management should first be configured to validate the token (checking the issuer and audience claims at a minimum). After validation, use one of several options available to secure onward connections from API Management. See [other options](#other-options), later in this article.

+* The context required by the backend isnΓÇÖt possible to establish from the caller.

+ After API Management has successfully validated the token received from the caller, it then needs to obtain an access token for the backend API using its own context, or context derived from the calling application. This scenario can be accomplished using either:

+ * A custom policy to obtain an onward access token valid for the backend API from a configured identity provider.

+ * The API Management instance's own identity ΓÇô passing the token from the API Management resource's system-assigned or user-assigned [managed identity](api-management-authentication-policies.md#ManagedIdentity) to the backend API.

+### Token management by API Management

+API Management also supports acquisition and secure storage of OAuth 2.0 tokens for certain downstream services using the [authorizations](authorizations-overview.md) (preview) feature, including through use of custom policies and caching.

+With authorizations, API Management manages the tokens for access to OAuth 2.0 backends, simplifying the development of client apps that access APIs.

+### Other options

+Although authorization is preferred and OAuth 2.0 has become the dominant method of enabling strong authorization for APIs, API Management enables other authentication options that can be useful if the backend or calling applications are legacy or don't yet support OAuth. Options include:

+* Mutual TLS (mTLS), also known as client certificate authentication, between the client (app) and API Management. This authentication can be end-to-end, with the call between API Management and the backend API secured in the same way. For more information, see [How to secure APIs using client certificate authentication in API Management](api-management-howto-mutual-certificates-for-clients.md)

+* Basic authentication, using the [authentication-basic](api-management-authentication-policies.md#Basic) policy.

+* Subscription key, also known as an API key. For more information, see [Subscriptions in API Management](api-management-subscriptions.md).

+> [!NOTE]

+> We recommend using a subscription (API) key *in addition to* another method of authentication or authorization. On its own, a subscription key isn't a strong form of authentication, but use of the subscription key might be useful in certain scenarios, for example, tracking individual customers' API usage.

+## Developer portal (user plane)

+The managed developer portal is an optional API Management feature that allows internal or external developers and other interested parties to discover and use APIs that are published through API Management.

+If you elect to customize and publish the developer portal, API Management provides different options to secure it:

+* **External users** - The preferred option when the developer portal is consumed externally is to enable business-to-consumer access control through Azure Active Directory B2C (Azure AD B2C).

+ * Azure AD B2C provides the option of using Azure AD B2C native accounts: users sign up to Azure AD B2C and use that identity to access the developer portal.

+ * Azure AD B2C is also useful if you want users to access the developer portal using existing social media or federated organizational accounts.

+ * Azure AD B2C provides many features to improve the end user sign-up and sign-in experience, including conditional access and MFA.

+

+ For steps to enable Azure AD B2C authentication in the developer portal, see [How to authorize developer accounts by using Azure Active Directory B2C in Azure API Management](api-management-howto-aad-b2c.md).

+* **Internal users** - The preferred option when the developer portal is consumed internally is to leverage your corporate Azure AD. Azure AD provides a seamless single sign-on (SSO) experience for corporate users who need to access and discover APIs through the developer portal.

+ For steps to enable Azure AD authentication in the developer portal, see [How to authorize developer accounts by using Azure Active Directory in Azure API Management](api-management-howto-aad.md).

+

+* **Basic authentication** - A default option is to use the built-in developer portal [username and password](developer-portal-basic-authentication.md) provider, which allows developer users to register directly in API Management and sign in using API Management user accounts. User sign up through this option is protected by a CAPTCHA service.

+### Developer portal test console

+In addition to providing configuration for developer users to sign up for access and sign in, the developer portal includes a test console where the developers can send test requests through API Management to the backend APIs. This test facility also exists for contributing users of API Management who manage the service using the Azure portal.

+In either both cases, if the API exposed through Azure API Management is secured with OAuth 2.0 - that is, a calling application (*bearer*) needs to obtain and pass a valid access token - you can configure API Management to generate a valid token on behalf of an Azure portal or developer portal test console user. For more information, see [How to authorize test console of developer portal by configuring OAuth 2.0 user authorization](api-management-howto-oauth2.md) .

+This OAuth configuration for API testing is independent of the configuration required for user access to the developer portal. However, the identity provider and user could be the same. For example, an intranet application could require user access to the developer portal using SSO with their corporate identity, and that same corporate identity could obtain a token, through the test console, for the backend service being called with the same user context.

+## Scenarios

+Different authentication and authorization options apply to different scenarios. The following sections explore high level configurations for three example scenarios. More steps are required to fully secure and configure APIs exposed through API Management to either internal or external audiences. However, the scenarios intentionally focus on the minimum configurations recommended in each case to provide the required authentication and authorization.

+### Scenario 1 - Intranet API and applications

+* An API Management contributor and backend API developer wants to publish an API that is secured by OAuth 2.0.

+* The API will be consumed by desktop applications whose users sign in using SSO through Azure AD.

+* The desktop application developers also need to discover and test the APIs via the API Management developer portal.

+Key configurations:

+|Configuration |Reference |

+|||

+| Authorize developer users of the API Management developer portal using their corporate identities and Azure AD. | [Authorize developer accounts by using Azure Active Directory in Azure API Management](api-management-howto-aad.md) |

+|Set up the test console in the developer portal to obtain a valid OAuth 2.0 token for the desktop app developers to exercise the backend API. <br/><br/>The same configuration can be used for the test console in the Azure portal, which is accessible to the API Management contributors and backend developers. <br/><br/>The token could be used in combination with an API Management subscription key. | [How to authorize test console of developer portal by configuring OAuth 2.0 user authorization](api-management-howto-oauth2.md)<br/><br/>[Subscriptions in Azure API Management](api-management-subscriptions.md) |

+| Validate the OAuth 2.0 token and claims when an API is called through API Management with an access token. | [Validate JWT policy](api-management-access-restriction-policies.md#ValidateJWT) |

+Go a step further with this scenario by moving API Management into the network perimeter and controlling ingress through a reverse proxy. For a reference architecture, see [Protect APIs with Application Gateway and API Management](/azure/architecture/reference-architectures/apis/protect-apis).

+

+### Scenario 2 - External API, partner application

+* An API Management contributor and backend API developer wants to undertake a rapid proof-of-concept to expose a legacy API through Azure API Management. The API through API Management will be externally (internet) facing.

+* The API uses client certificate authentication and will be consumed by a new public-facing single-page Application (SPA) being developed and delivered offshore by a partner.

+* The SPA uses OAuth 2.0 with Open ID Connect (OIDC).

+* Application developers will access the API in a test environment through the developer portal, using a test backend endpoint to accelerate frontend development.

+Key configurations:

+|Configuration |Reference |

+|||

+| Configure frontend developer access to the developer portal using the default username and password authentication.<br/><br/>Developers can also be invited to the developer portal. | [Configure users of the developer portal to authenticate using usernames and passwords](developer-portal-basic-authentication.md)<br/><br/>[How to manage user accounts in Azure API Management](api-management-howto-create-or-invite-developers.md) |

+| Validate the OAuth 2.0 token and claims when the SPA calls API Management with an access token. In this case, the audience is API Management. | [Validate JWT policy](api-management-access-restriction-policies.md#ValidateJWT) |

+| Set up API Management to use client certificate authentication to the backend. | [Secure backend services using client certificate authentication in Azure API Management](api-management-howto-mutual-certificates.md) |

+Go a step further with this scenario by using the [developer portal with Azure AD authorization](api-management-howto-aad.md) and Azure AD [B2B collaboration](../active-directory/external-identities/what-is-b2b.md) to allow the delivery partners to collaborate more closely. Consider delegating access to API Management through RBAC in a development or test environment and enable SSO into the developer portal using their own corporate credentials.

+### Scenario 3 - External API, SaaS, open to the public

+* An API Management contributor and backend API developer is writing several new APIs that will be available to community developers.

+* The APIs will be publicly available, with full functionality protected behind a paywall and secured using OAuth 2.0. After purchasing a license, the developer will be provided with their own client credentials and subscription key that is valid for production use.

+* External community developers will discover the APIs using the developer portal. Developers will sign up and sign in to the developer portal using their social media accounts.

+* Interested developer portal users with a test subscription key can explore the API functionality in a test context, without needing to purchase a license. The developer portal test console will represent the calling application and generate a default access token to the backend API.

+

+ > [!CAUTION]

+ > Extra care is required when using a client credentials flow with the developer portal test console. See [security considerations](api-management-howto-oauth2.md#security-considerations).

+Key configurations:

+|Configuration |Reference |

+|||

+| Set up products in Azure API Management to represent the combinations of APIs that are exposed to community developers.<br/><br/> Set up subscriptions to enable developers to consume the APIs. | [Tutorial: Create and publish a product](api-management-howto-add-products.md)<br/><br/>[Subscriptions in Azure API Management](api-management-subscriptions.md) |

+| Configure community developer access to the developer portal using Azure AD B2C. Azure AD B2C can then be configured to work with one or more downstream social media identity providers. | [How to authorize developer accounts by using Azure Active Directory B2C in Azure API Management](api-management-howto-aad-b2c.md) |

+| Set up the test console in the developer portal to obtain a valid OAuth 2.0 token to the backend API using the client credentials flow. | [How to authorize test console of developer portal by configuring OAuth 2.0 user authorization](api-management-howto-oauth2.md)<br/><br/>Adjust configuration steps shown in this article to use the [client credentials grant flow](../active-directory/develop/v2-oauth2-client-creds-grant-flow.md) instead of the authorization code grant flow. |

+Go a step further by delegating [user registration or product subscription](api-management-howto-setup-delegation.md) and extend the process with your own logic.

+## Next steps

+* Learn more about [authentication and authorization](../active-directory/develop/authentication-vs-authorization.md) in the Microsoft identity platform.

+* Learn how to [mitigate OWASP API security threats](mitigate-owasp-api-threats.md) using API Management.

+ Title: Azure API Management - API version retirements (September 2023) | Microsoft Docs

+description: Azure API Management is retiring all API versions prior to 2021-08-01. If you use one of these API versions, you must update your tools, scripts, or programs to use the latest versions.

+documentationcenter: ''

+# API version retirements (September 2023)

+Azure API Management uses Azure Resource Manager (ARM) to configure your API Management instances. The API version is embedded in your use of templates that describe your infrastructure, tools that are used to configure the service, and programs that you write to manage your Azure API Management services.

+On 30 September 2023, all API versions prior to **2021-08-01** will be retired and API calls using those API versions will fail. This means you'll no longer be able to create or manage your API Management services using your existing templates, tools, scripts, and programs until they've been updated. Data operations (such as accessing the APIs or Products configured on Azure API Management) will be unaffected by this update, including after 30 September 2023.

+From now through 30 September 2023, you can continue to use the templates, tools, and programs without impact. You can transition to API version 2021-08-01 or later at any point prior to 30 September 2023.

+## Is my service affected by this?

+While your service isn't* affected by this change, any tool, script, or program that uses the Azure Resource Manager (such as the Azure CLI, Azure PowerShell, Azure API Management DevOps Resource Kit, or Terraform) is affected by this change. You'll be unable to run those tools successfully unless you update the tools.

+## What is the deadline for the change?

+The affected API versions will no longer be valid after 30 September 2023.

+After 30 September 2023, if you prefer not to update your tools, scripts, and programs, your services will continue to run but you won't be able to add or remove APIs, change API policy, or otherwise configure your API Management service.

+## Required action

+* **ARM, Bicep, or Terraform templates** - Update the template to use API version 2021-08-01 or later.

+* **Azure CLI** - Run `az version -help` to check your version. If you're running version 2.38.0 or later, no action is required. Use the `az upgrade` command to upgrade the Azure CLI if necessary. For more information, see [How to update the Azure CLI](/cli/azure/update-azure-cli).

+* **Azure PowerShell** - Run `Get-Module -ListAvailable -Name Az` to check your version. If you're running version 8.1.0 or later, no action is required. Use `Update-Module -Name Az -Repository PSGallery` to update the module if necessary. For more information, see [Install the Azure Az PowerShell module](/powershell/azure/install-az-ps).

+* **Other tools** - Use the following versions (or later):

+ * API Management DevOps Resource Kit: 1.0.0

+ * Terraform azurerm provider: 3.0.0

+

+* **Azure SDKs** - Update the Azure API Management SDKs to the latest versions (or later):

+ * .NET: 8.0.0

+ * Go: 1.0.0

+ * Python: 3.0.0

+ * JavaScript: 8.0.1

+## More information

+* [Azure CLI](/cli/azure/update-azure-cli)

+* [Azure PowerShell](/powershell/azure/install-az-ps)

+* [Azure Resource Manager](/azure/azure-resource-manager/management/overview)

+* [Terraform on Azure](/azure/developer/terraform/)

+* [Bicep](/azure/azure-resource-manager/bicep/overview)

+* [Microsoft Q&A](/answers/topics/azure-api-management.html)

+## Next steps

+See all [upcoming breaking changes and feature retirements](overview.md).

+ Title: Azure API Management CAPTCHA endpoint change (September 2025) | Microsoft Docs

+description: Azure API Management is updating the CAPTCHA endpoint. If your service is hosted in an Azure virtual network, you may need to update network settings to continue using the developer portal.

+documentationcenter: ''

+# CAPTCHA endpoint update (September 2025)

+On 30 September, 2025 as part of our continuing work to increase the resiliency of API Management services, we're permanently changing the CAPTCHA endpoint used by the developer portal.

+This change will have no effect on the availability of your API Management service. However, you may have to take steps described below to continue using the developer portal beyond 30 September, 2025.

+## Is my service affected by this change?

+Your service may be impacted by this change if:

+* Your API Management service is running inside an Azure virtual network.

+* You use the Azure API Management developer portal.

+Follow the steps below to confirm if your network restricts connectivity to the new CAPTCHA endpoint.

+1. Navigate to your API Management service in the Azure portal.

+2. Select **Network** from the menu and go to the **Network status tab**.

+3. Check the status for the **Captcha endpoint**. Your service is impacted if the status isn't **Success**.

+## What is the deadline for the change?

+The CAPTCHA endpoint will permanently change on 30 September, 2025. Complete all required networking changes before then.

+After 30 September 2025, if you prefer not to make changes to your network configuration, your services will continue to run but the developer portal sign-up and password reset functionality will no longer work.

+## What do I need to do?

+Update the virtual network configuration to allow connectivity to the new CAPTCHA hostnames.

+| Environment | Endpoint |

+| | |

+| Global Azure cloud | `partner.prod.repmap.microsoft.com` |

+| USGov | `partner.prod.repmap.microsoft.us` |

+The new CAPTCHA endpoints provide the same functionality as the previous endpoints.

+## Help and support

+If you have questions, get answers from community experts in [Microsoft Q&A](https://aka.ms/apim/azureqa/change/captcha-2022). If you have a support plan and you need technical help, create a [support request](https://portal.azure.com/#view/Microsoft_Azure_Support/HelpAndSupportBlade/~/overview).

+1. For **Summary**, type a description of your issue, for example, "stv1 retirement".

+1. Under **Issue type**, select **Technical**.

+1. Under **Subscription**, select your subscription.

+1. Under **Service**, select **My services**, then select **API Management Service**.

+1. Under **Resource**, select the Azure resource that youΓÇÖre creating a support request for.

+1. For **Problem type**, select **General configuration**.

+1. For **Problem subtype**, select **VNET integration**.

+## More information

+* [Virtual Network](../../virtual-network/index.yml)

+* [API Management VNet Reference](../virtual-network-reference.md)

+* [Microsoft Q&A](/answers/topics/azure-api-management.html)

+## Next steps

+See all [upcoming breaking changes and feature retirements](overview.md).

+ Title: Azure API Management identity providers configuration change (September 2025) | Microsoft Docs

+description: Azure API Management is updating the library used for user authentication in the developer portal. If you use Azure AD or Azure AD B2C identity providers, you need to update application settings and identity provider configuration to use the Microsoft Authentication Library (MSAL).

+documentationcenter: ''

+# ADAL-based Azure AD or Azure AD B2C identity provider retirement (September 2025)

+On 30 September, 2025 as part of our continuing work to increase the resiliency of API Management services, we're removing the support for the previous library for user authentication and authorization in the developer portal (AD Authentication Library, or ADAL). You need to migrate your Azure AD or Azure AD B2C applications, change identity provider configuration to use the Microsoft Authentication Library (MSAL), and republish your developer portal.

+This change will have no effect on the availability of your API Management service. However, you have to take steps described below to configure your API Management service if you wish to continue using Azure AD or Azure AD B2C identity providers beyond 30 September, 2025.

+## Is my service affected by this change?

+Your service is impacted by this change if:

+* You've configured an [Azure AD](../api-management-howto-aad.md) or [Azure AD B2C](../api-management-howto-aad-b2c.md) identity provider for user account authentication using the ADAL and use the provided developer portal.

+## What is the deadline for the change?

+On 30 September, 2025, these identity providers will stop functioning. To avoid disruption of your developer portal, you need to update your Azure AD applications and identity provider configuration in Azure API Management by that date. Your developer portal might be at a security risk after Microsoft ADAL support ends in December 2022.

+Developer portal sign-in and sign-up with Azure AD or Azure AD B2C will stop working past 30 September, 2025 if you don't update your ADAL-based Azure AD or Azure AD B2C identity providers. This new authentication method is more secure, as it relies on the OAuth 2.0 authorization code flow with PKCE and uses an up-to-date software library.

+## What do I need to do?

+### Update Azure AD and Azure AD B2C applications for MSAL compatibility

+[Switch redirect URIs to the single-page application type](../../active-directory/develop/migrate-spa-implicit-to-auth-code.md#switch-redirect-uris-to-spa-platform).

+### Update identity provider configuration

+1. Go to the [Azure portal](https://portal.azure.com) and navigate to your Azure API Management service.

+2. Select **Identities** in the menu.

+3. Select **Azure Active Directory** or **Azure Active Directory B2C** from the list.

+4. Select **MSAL** in the **Client library** dropdown.

+5. Select **Update**.

+6. [Republish your developer portal](../api-management-howto-developer-portal-customize.md#publish-from-the-azure-portal).

+## Help and support

+If you have questions, get answers from community experts in [Microsoft Q&A](https://aka.ms/apim/azureqa/change/msal-2022). If you have a support plan and you need technical help, create a [support request](https://portal.azure.com/#view/Microsoft_Azure_Support/HelpAndSupportBlade/~/overview).

+1. For **Summary**, type a description of your issue, for example, "stv1 retirement".

+1. Under **Issue type**, select **Technical**.

+1. Under **Subscription**, select your subscription.

+1. Under **Service**, select **My services**, then select **API Management Service**.

+1. Under **Resource**, select the Azure resource that youΓÇÖre creating a support request for.

+1. For **Problem type**, select **Authentication and Security**.

+1. For **Problem subtype**, select **Azure Active Directory Authentication** or **Azure Active Directory B2C Authentication**.

+## More information

+* [Authenticate users with Azure AD](../api-management-howto-aad.md)

+* [Authenticate users with Azure AD B2C](../api-management-howto-aad-b2c.md)

+* [Microsoft Q&A](/answers/topics/azure-api-management.html)

+## Next steps

+See all [upcoming breaking changes and feature retirements](overview.md).

+| [Resource provider source IP address updates][bc1] | March 31, 2023 |

+| [Resource provider source IP address updates][rp2023] | September 30, 2023 |

+| [API version retirements][api2023] | September 30, 2023 |

+| [Deprecated (legacy) portal retirement][devportal2023] | October 2023 |

+| [Self-hosted gateway v0/v1 retirement][shgwv0v1] | October 1, 2023 |

+| [stv1 platform retirement][stv12024] | August 31, 2024 |

+| [ADAL-based Azure AD or Azure AD B2C identity provider retirement][msal2025] | September 30, 2025 |

+| [CAPTCHA endpoint update][captcha2025] | September 30, 2025 |

+[bc1]: ./rp-source-ip-address-change-mar-2023.md

+[rp2023]: ./rp-source-ip-address-change-sep-2023.md

+[api2023]: ./api-version-retirement-sep-2023.md

+[devportal2023]: ../api-management-customize-styles.md

+[shgwv0v1]: ./self-hosted-gateway-v0-v1-retirement-oct-2023.md

+[stv12024]: ./stv1-platform-retirement-august-2024.md

+[msal2025]: ./identity-provider-adal-retirement-sep-2025.md

+[captcha2025]: ./captcha-endpoint-change-sep-2025.md

+ Title: Azure API Management IP address change (March 2023) | Microsoft Docs

+description: Azure API Management is updating the source IP address of the resource provider in certain regions. If your service is hosted in a Microsoft Azure Virtual Network, you may need to update network settings to continue managing your service.

+documentationcenter: ''

+# Resource Provider source IP address updates (March 2023)

+On 31 March, 2023 as part of our continuing work to increase the resiliency of API Management services, we're making the resource providers for Azure API Management zone redundant in each region. The IP address that the resource provider uses to communicate with your service will change in seven regions:

+| Region | Old IP Address | New IP Address |

+|:-|:--:|:--:|

+| Canada Central | 52.139.20.34 | 20.48.201.76 |

+| Brazil South | 191.233.24.179 | 191.238.73.14 |

+| Germany West Central | 51.116.96.0 | 20.52.94.112 |

+| South Africa North | 102.133.0.79 | 102.37.166.220 |

+| Korea Central | 40.82.157.167 | 20.194.74.240 |

+| Central India | 13.71.49.1 | 20.192.45.112 |

+| South Central US | 20.188.77.119 | 20.97.32.190 |

+This change will have NO effect on the availability of your API Management service. However, you **may** have to take steps described below to configure your API Management service beyond 31 March, 2023.

+## Is my service affected by this change?

+Your service is impacted by this change if:

+* The API Management service is in one of the seven regions listed in the table above.

+* The API Management service is running inside an Azure virtual network.

+* The Network Security Group (NSG) or User-defined Routes (UDRs) for the virtual network are configured with explicit source IP addresses.

+## What is the deadline for the change?

+The source IP addresses for the affected regions will be changed on 31 March, 2023. Complete all required networking changes before then.

+After 31 March 2023, if you prefer not to make changes to your IP addresses, your services will continue to run but you will not be able to add or remove APIs, or change API policy, or otherwise configure your API Management service.

+## Can I avoid this sort of change in the future?

+Yes, you can.

+API Management publishes a _service tag_ that you can use to configure the NSG for your virtual network. The service tag includes information about the source IP addresses that API Management uses to manage your service. For more information on this topic, read [Configure NSG Rules] in the API Management documentation.

+## What do I need to do?

+Update the NSG security rules that allow the API Management resource provider to communicate with your API Management instance. For detailed instructions on how to manage an NSG, review [Create, change, or delete a network security group] in the Azure Virtual Network documentation.

+1. Go to the [Azure portal](https://portal.azure.com) to view your NSGs. Search for and select **Network security groups**.

+2. Select the name of the NSG associated with the virtual network hosting your API Management service.

+3. In the menu bar, choose **Inbound security rules**.

+4. The inbound security rules should already have an entry that mentions a Source address matching the _Old IP Address_ from the table above. If it doesn't, you're not using explicit source IP address filtering, and can skip this update.

+5. Select **Add**.

+6. Fill in the form with the following information:

+

+ 1. Source: **Service Tag**

+ 2. Source Service Tag: **ApiManagement**

+ 3. Source port ranges: __*__

+ 4. Destination: **VirtualNetwork**

+ 5. Destination port ranges: **3443**

+ 6. Protocol: **TCP**

+ 7. Action: **Allow**

+ 8. Priority: Pick a suitable priority to place the new rule next to the existing rule.

+ The Name and Description fields can be set to anything you wish. All other fields should be left blank.

+7. Select **OK**.

+In addition, you may have to adjust the network routing for the virtual network to accommodate the new control plane IP addresses. If you've configured a default route (`0.0.0.0/0`) forcing all traffic from the API Management subnet to flow through a firewall instead of directly to the Internet, then additional configuration is required.

+If you configured user-defined routes (UDRs) for control plane IP addresses, the new IP addresses must be routed the same way. For more details on the changes necessary to handle network routing of management requests, review [Force tunneling traffic] documentation.

+Finally, check for any other systems that may impact the communication from the API Management resource provider to your API Management service subnet. For more information about virtual network configuration, review the [Virtual Network] documentation.

+## More Information

+* [Virtual Network](../../virtual-network/index.yml)

+* [API Management VNET Reference](../virtual-network-reference.md)

+* [Microsoft Q&A](/answers/topics/azure-api-management.html)

+<!-- Links -->

+[Configure NSG Rules]: ../api-management-using-with-internal-vnet.md#configure-nsg-rules

+[Virtual Network]: ../../virtual-network/index.yml

+[Force tunneling traffic]: ../api-management-using-with-internal-vnet.md#force-tunnel-traffic-to-on-premises-firewall-using-expressroute-or-network-virtual-appliance

+[Create, change, or delete a network security group]: ../../virtual-network/manage-network-security-group.md

+ Title: Azure API Management IP address change (September 2023) | Microsoft Docs

+description: Azure API Management is updating the source IP address of the resource provider in Switzerland North. If your service is hosted in a Microsoft Azure virtual network, you may need to update network settings to continue managing your service.

+documentationcenter: ''

+# Resource provider source IP address updates (September 2023)

+On 30 September 2023 as part of our continuing work to increase the resiliency of API Management services, we're making the resource providers for Azure API Management zone redundant in each region. The IP address that the resource provider uses to communicate with your service will change if it's located in Switzerland North:

+* Old IP address: 51.107.0.91

+* New IP address: 51.107.246.176

+This change will have *no* effect on the availability of your API Management service. However, you **may** have to take steps described below to configure your API Management service beyond 30 September 2023.

+## Is my service affected by this change?

+Your service is impacted by this change if:

+* The API Management service is in the Switzerland North region.

+* The API Management service is running inside an Azure virtual network.

+* The network security group (NSG) or user-defined routes (UDRs) for the virtual network are configured with explicit source IP addresses.

+## What is the deadline for the change?

+The source IP addresses for the affected region will be changed on 30 September 2023. Complete all required networking changes before then.

+After 30 September 2023, if you prefer not to make changes to your IP addresses, your services will continue to run but you won't be able to add or remove APIs, or change API policy, or otherwise configure your API Management service.

+## Can I avoid this sort of change in the future?

+Yes, you can.

+API Management publishes a _service tag_ that you can use to configure the NSG for your virtual network. The service tag includes information about the source IP addresses that API Management uses to manage your service. For more information on this article, read [Configure NSG Rules] in the API Management documentation.

+## What do I need to do?

+Update the NSG security rules that allow the API Management resource provider to communicate with your API Management instance. For detailed instructions on how to manage an NSG, review [Create, change, or delete a network security group] in the Azure virtual network documentation.

+1. Go to the [Azure portal](https://portal.azure.com) to view your NSGs. Search for and select **Network security groups**.

+2. Select the name of the NSG associated with the virtual network hosting your API Management service.

+3. In the menu bar, choose **Inbound security rules**.

+4. The inbound security rules should already have an entry that mentions a source address matching the _Old IP address_ from the table above. If it doesn't, you're not using explicit source IP address filtering, and can skip this update.

+5. Select **Add**.

+6. Fill in the form with the following information:

+

+ 1. Source: **Service Tag**

+ 2. Source Service Tag: **ApiManagement**

+ 3. Source port ranges: __*__

+ 4. Destination: **VirtualNetwork**

+ 5. Destination port ranges: **3443**

+ 6. Protocol: **TCP**

+ 7. Action: **Allow**

+ 8. Priority: Pick a suitable priority to place the new rule next to the existing rule.

+ The Name and Description fields can be set to anything you wish. All other fields should be left blank.

+7. Select **OK**.

+In addition, you may have to adjust the network routing for the virtual network to accommodate the new control plane IP addresses. If you've configured a default route (`0.0.0.0/0`) forcing all traffic from the API Management subnet to flow through a firewall instead of directly to the Internet, then more configuration is required.

+If you configured user-defined routes (UDRs) for control plane IP addresses, the new IP addresses must be routed the same way. For more details on the changes necessary to handle network routing of management requests, review [Force tunneling traffic] documentation.

+Finally, check for any other systems that may impact the communication from the API Management resource provider to your API Management service subnet. For more information about virtual network configuration, review the [Virtual Network] documentation.

+## More information

+* [Virtual network](../../virtual-network/index.yml)

+* [API Management VN24 Reference](../virtual-network-reference.md)

+* [Microsoft Q&A](/answers/topics/azure-api-management.html)

+## Next steps

+See all [upcoming breaking changes and feature retirements](overview.md).

+<!-- Links -->

+[Configure NSG Rules]: ../api-management-using-with-internal-vnet.md#configure-nsg-rules

+[Virtual Network]: ../../virtual-network/index.yml

+[Force tunneling traffic]: ../api-management-using-with-internal-vnet.md#force-tunnel-traffic-to-on-premises-firewall-using-expressroute-or-network-virtual-appliance

+[Create, change, or delete a network security group]: ../../virtual-network/manage-network-security-group.md

+ Title: Azure API Management - Self-hosted gateway v0/v1 retirement (October 2023) | Microsoft Docs

+description: Azure API Management is retiring the v0 and v1 versions of the self-hosted gateway container image, effective 1 October 2023. If you've deployed one of these versions, you must migrate to the v2 version of the self-hosted gateway.

+documentationcenter: ''

+# Support ending for Azure API Management self-hosted gateway version 0 and version 1 container images (October 2023)

+The [self-hosted gateway](../self-hosted-gateway-overview.md) is an optional, containerized version of the default managed gateway included in every API Management service. On 1 October 2023 we're removing support for the v0 and v1 versions of the self-hosted gateway container image. If you've deployed the self-hosted gateway using either of these container images, you need to take the steps below to continue using the self-hosted gateway by migrating to the v2 container image and configuration API.

+## Is my service affected by this?

+Your service is affected by this change if:

+* Your service is in the Developer or Premium service tier.

+* You have deployed a self-hosted gateway using the version v0 or v1 of the self-hosted gateway [container image](../self-hosted-gateway-migration-guide.md#using-the-new-configuration-api).

+## What is the deadline for the change?

+**Support for the v1 configuration API and for the v0 and v1 container images of the self-hosted gateway will retire on 1 October 2023.**

+Version 2 of the configuration API and container image is already available, and includes the following improvements:

+* A new configuration API that removes the dependency on Azure Storage, unless you're using request tracing or quotas.

+* New container images, and new container image tags to let you choose the best way to try our gateway and deploy it in production.

+If you are using version 0 or version 1 of the self-hosted gateway, you will need to manually migrate your container images to the newest v2 image and switch to the v2 configuration API.

+## What do I need to do?

+Migrate all your existing deployments of the self-hosted gateway using version 0 or version 1 to the newest v2 container image and v2 configuration API by 1 October 2023.

+Follow the [migration guide](../self-hosted-gateway-migration-guide.md) for a successful migration.

+## Help and support

+If you have questions, get answers from community experts in [Microsoft Q&A](https://aka.ms/apim/retirement/shgwv0v1). If you have a support plan and you need technical help, create a [support request](https://portal.azure.com/#view/Microsoft_Azure_Support/HelpAndSupportBlade/~/overview).

+1. For **Summary**, type a description of your issue, for example, "stv1 retirement".

+1. Under **Issue type**, select **Technical**.

+1. Under **Subscription**, select your subscription.

+1. Under **Service**, select **My services**, then select **API Management Service**.

+1. Under **Resource**, select the Azure resource that youΓÇÖre creating a support request for.

+1. For **Summary**, type a description of your issue, for example, "v1/v0 retirement".

+1. For **Problem type**, select **Self-hosted gateway**.

+1. For **Problem subtype**, select **Administration, Configuration and Deployment**.

+## Next steps

+See all [upcoming breaking changes and feature retirements](overview.md).

+ Title: Azure API Management - stv1 platform retirement (August 2024) | Microsoft Docs

+description: Azure API Management is retiring the stv1 compute platform effective 31 August 2024. If your API Management instance is hosted on the stv1 platform, you must migrate to the stv2 platform.

+documentationcenter: ''

+# stv1 platform retirement (August 2024)

+As a cloud platform-as-a-service (PaaS), Azure API Management abstracts many details of the infrastructure used to host and run your service. **The infrastructure associated with the API Management `stv1` compute platform version will be retired effective 31 August 2024.** A more current compute platform version (`stv2`) is already available, and provides enhanced service capabilities.

+The following table summarizes the compute platforms currently used for instances in the different API Management service tiers.

+| Version | Description | Architecture | Tiers |

+| -| -| -- | - |

+| `stv2` | Single-tenant v2 | Azure-allocated compute infrastructure that supports availability zones, private endpoints | Developer, Basic, Standard, Premium¹ |

+| `stv1` | Single-tenant v1 | Azure-allocated compute infrastructure | Developer, Basic, Standard, Premium |

+| `mtv1` | Multi-tenant v1 | Shared infrastructure that supports native autoscaling and scaling down to zero in times of no traffic | Consumption |

+To take advantage of upcoming features, we're recommending that customers migrate their Azure API Management instances from the `stv1` compute platform to the `stv2` compute platform. The `stv2` compute platform comes with additional features and improvements such as support for Azure Private Link and other networking features.

+New instances created in service tiers other than the Consumption tier are mostly hosted on the `stv2` platform already. Existing instances on the `stv1` compute platform will continue to work normally until the retirement date, but those instances wonΓÇÖt receive the latest features available to the `stv2` platform. Support for `stv1` instances will be retired by 31 August 2024.

+## Is my service affected by this?

+If the value of the `platformVersion` property of your service is `stv1`, it is hosted on the `stv1` platform. See [How do I know which platform hosts my API Management instance?](../compute-infrastructure.md#how-do-i-know-which-platform-hosts-my-api-management-instance)

+## What is the deadline for the change?

+Support for API Management instances hosted on the `stv1` platform will be retired by 31 August 2024.

+After 31 August 2024, any instance hosted on the `stv1` platform won't be supported, and could experience system outages.

+## What do I need to do?

+**Migrate all your existing instances hosted on the `stv1` compute platform to the `stv2` compute platform by 31 August 2024.**

+If you have existing instances hosted on the `stv1` platform, you can follow our [migration guide](../compute-infrastructure.md#how-do-i-migrate-to-the-stv2-platform) which provides all the details to ensure a successful migration.

+## Help and support

+If you have questions, get answers from community experts in [Microsoft Q&A](https://aka.ms/apim/retirement/stv1). If you have a support plan and you need technical help, create a [support request](https://portal.azure.com/#view/Microsoft_Azure_Support/HelpAndSupportBlade/~/overview).

+1. For **Summary**, type a description of your issue, for example, "stv1 retirement".

+1. Under **Issue type**, select **Technical**.

+1. Under **Subscription**, select your subscription.

+1. Under **Service**, select **My services**, then select **API Management Service**.

+1. Under **Resource**, select the Azure resource that youΓÇÖre creating a support request for.

+1. For **Problem type**, select **Administration and Management**.

+1. For **Problem subtype**, select **Upgrade, Scale or SKU Changes**.

+## Next steps

+See all [upcoming breaking changes and feature retirements](overview.md).

+In this quickstart, you'll learn how to create and deploy your first [WordPress](https://www.wordpress.org/) site to [Azure App Service on Linux](overview.md#app-service-on-linux) using the [WordPress Azure Marketplace item by App Service](https://azuremarketplace.microsoft.com/marketplace/apps/WordPress.WordPress?tab=Overview). This quickstart uses the **Basic** tier and [**incurs a cost**](https://azure.microsoft.com/pricing/details/app-service/linux/) for your Azure subscription. The WordPress installation comes with pre-installed plugins for performance improvements, [W3TC](https://wordpress.org/plugins/w3-total-cache/) for caching and [Smush](https://wordpress.org/plugins/wp-smushit/) for image compression.

+> [!IMPORTANT]

+> Azure App Configuration added [geo-replication](./concept-geo-replication.md) support recently. You can enable replicas of your data across multiple locations for enhanced resiliency to regional outages. You can also leverage App Configuration provider libraries in your applications for [automatic failover](./howto-geo-replication.md#use-replicas). The geo-replication feature is currently under preview. It will be the recommended solution for high availability when the feature is generally available.

+## Toggle automatic upgrade on or off when connecting a cluster to Azure Arc

+## Toggle automatic upgrade on or off after connecting a cluster to Azure Arc

+## Check if automatic upgrade is enabled on a cluster

+To check whether a cluster is enabled for automatic upgrade, run the following kubectl command. Note that the automatic upgrade configuration is not available in the public API for Azure Arc-enabled Kubernetes.

+```console

+kubectl -n azure-arc get cm azure-clusterconfig -o jsonpath="{.data['AZURE_ARC_AUTOUPDATE']}"

+```

+## Check agent version

+To list connected clusters and reported agent version, use the following command:

+```azurecli

+az connectedk8s list --query '[].{name:name,rg:resourceGroup,id:id,version:agentVersion}'

+```

+|`guestnotificationservice.azure.com`, `*.guestnotificationservice.azure.com`|Notification service for extension and connectivity scenarios|Always| Public |

+ Title: How to upgrade the Redis version of Azure Cache for Redis

+description: Learn how to upgrade the version of Azure Cache for Redis

+# How to upgrade an existing Redis 4 cache to Redis 6

+Azure Cache for Redis supports upgrading the version of your Azure Cache for Redis from Redis 4 to Redis 6. Upgrading is permanent, and it might cause a brief connection issue similar to regular monthly maintenance. As a precautionary step, we recommend exporting the data from your existing Redis 4 cache and testing your client application with a Redis 6 cache in a lower environment before upgrading.

+For more information, see [here](cache-how-to-import-export-data.md) for details on how to export.

+## Prerequisites

+- Azure subscription - [create one for free](https://azure.microsoft.com/free/)

+### Limitations

+- Upgrading a Basic tier cache results in brief unavailability and data loss.

+- Upgrading on geo-replicated cache isn't supported. You must manually unlink the cache instances before upgrading.

+- Upgrading a cache with a dependency on Cloud Services isn't supported. You should migrate your cache instance to virtual machine scale set before upgrading. For more information, see [Caches with a dependency on Cloud Services (classic)](/azure/azure-cache-for-redis/cache-faq) for details on cloud services hosted caches.

+### Check the version of a cache

+Before you upgrade, check the Redis version of a cache by selecting **Properties** from the Resource menu of the Azure Cache for Redis. We recommend you use Redis 6.

+## Upgrade using the Azure portal

+1. In the Azure portal, select the Azure Cache for Redis instance that you want to upgrade from Redis 4 to Redis 6.

+1. On the left side of the screen, select **Advanced settings**.

+1. If your cache instance is eligible to be upgraded, you should see the following blue banner. If you want to proceed, select the text in the banner.

+ :::image type="content" source="media/cache-how-to-upgrade/blue-banner-upgrade-cache.png" alt-text="Screenshot informing you that you can upgrade your cache to Redis 6 with additional features. Upgrading your cache instance cannot be reversed.":::

+1. A dialog box displays a popup notifying you that upgrading is permanent and might cause a brief connection blip. Select **Yes** if you would like to upgrade your cache instance.

+ :::image type="content" source="media/cache-how-to-upgrade/dialog-version-upgrade.png" alt-text="Screenshot showing a dialog with more information about upgrading your cache with Yes selected.":::

+1. To check on the status of the upgrade, navigate to **Overview**.

+ :::image type="content" source="media/cache-how-to-upgrade/upgrade-status.png" alt-text="Screenshot showing Overview in the Resource menu. Status shows cache is being upgraded.":::

+## Upgrade using Azure CLI

+To upgrade a cache from 4 to 6 using the Azure CLI, use the following command:

+```azurecli-interactive

+az redis update --name cacheName --resource-group resourceGroupName --set redisVersion=6

+```

+## Upgrade using PowerShell

+To upgrade a cache from 4 to 6 using PowerShell, use the following command:

+```powershell-interactive

+Set-AzRedisCache -Name "CacheName" -ResourceGroupName "ResourceGroupName" -RedisVersion "6"

+```

+## Next steps

+- To learn more about Azure Cache for Redis versions, see lin[Set Redis version for Azure Cache for Redis](cache-how-to-version.md)

+- To learn more about Redis 6 features, see [Diving Into Redis 6.0 by Redis](https://redis.com/blog/diving-into-redis-6/)

+- To learn more about Azure Cache for Redis features: [Azure Cache for Redis Premium service tiers](cache-overview.md#service-tiers)

+ Title: Set the Redis version of Azure Cache for Redis

+description: Learn how to configure the version of Azure Cache for Redis

+> At this time, Redis 6 does not support Access Control Lists (ACL) or geo-replication between a Redis 4 cache and Redis 6 cache.

+- Azure subscription - [create one for free](https://azure.microsoft.com/free/)

+## How to create a cache using the Azure portal

+ | **Subscription** | Select your subscription. | The subscription under which to create this new Azure Cache for Redis instance. |

+ | **Resource group** | Select a resource group, or select **Create new** and enter a new resource group name. | Name for the resource group in which to create your cache and other resources. By putting all your app resources in one resource group, you can easily manage or delete them together. |

+ | **DNS name** | Enter a globally unique name. | The cache name must be a string between 1 and 63 characters that contains only numbers, letters, or hyphens. The name must start and end with a number or letter, and can't contain consecutive hyphens. Your cache instance's *host name* will be *\<DNS name>.redis.cache.windows.net*. |

+ It takes a while for the cache to be created. You can monitor progress on the Azure Cache for Redis **Overview** page. When **Status** shows as **Running**, the cache is ready to use.

+To create a cache using PowerShell:

+To create a cache using Azure CLI:

+<!--

+ -->

+## How to check the version of a cache

+You can check the Redis version of a cache by selecting **Properties** from the Resource menu of the Azure Cache for Redis.

+At this time, Redis 6 doesn't support Access Control Lists (ACL). Geo-replication between a Redis 4 cache and a Redis 6 cache is also not supported.

+You can upgrade your existing Redis 4 caches to Redis 6. Upgrading your cache instance is permanent and you can't downgrade your Redis 6 caches to Redis 4 caches.

+For more information, see [How to upgrade an existing Redis 4 cache to Redis 6](cache-how-to-upgrade.md).

+- To learn more about upgrading your cache, see [How to upgrade an existing Redis 4 cache to Redis 6](cache-how-to-upgrade.md)

+> The retry policy support in the runtime for triggers other than Timer, Kafka, and Event Hubs is being removed after this feature becomes generally available (GA). Preview retry policy support for all triggers other than Timer and Event Hubs will be removed in October 2022.

+Several Functions bindings extensions provide built-in support for retries. In addition, the runtime lets you define retry policies for Timer, Kafka, and Event Hubs triggered functions. To learn more, see [Retries](#retries). For triggers that don't provide retry behaviors, you may want to implement your own retry scheme.

+|Kafka | [Retry policies](#retry-policies) | Function-level |

+Starting with version 3.x of the Azure Functions runtime, you can define a retry policies for Timer, Kafka, and Event Hubs triggers that are enforced by the Functions runtime. The retry policy tells the runtime to rerun a failed execution until either successful completion occurs or the maximum number of retries is reached.

+A retry policy is evaluated when a Timer, Kafka, or Event Hubs triggered function raises an uncaught exception. As a best practice, you should catch all exceptions in your code and rethrow any errors that you want to result in a retry. Event Hubs checkpoints won't be written until the retry policy for the execution has completed. Because of this behavior, progress on the specific partition is paused until the current batch has completed.

+[In-process](functions-dotnet-class-library.md) C# library uses [TimerTriggerAttribute](https://github.com/Azure/azure-webjobs-sdk-extensions/blob/master/src/WebJobs.Extensions/Extensions/Timers/TimerTriggerAttribute.cs) from [Microsoft.Azure.WebJobs.Extensions](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions) whereas [Isolated process](dotnet-isolated-process-guide.md) C# library uses [TimerTriggerAttribute](https://github.com/Azure/azure-functions-dotnet-worker/blob/main/extensions/Worker.Extensions.Timer/src/TimerTriggerAttribute.cs) from [Microsoft.Azure.Functions.Worker.Extensions.Timer](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Timer) to define the function.

+| [Cognitive

+| [Container Instances](../../container-instances/index.yml) | &#x2705; | &#x2705; |

+| [Dynamics 365 Chat (Omnichannel Engagement Hub)](/dynamics365/omnichannel/introduction-omnichannel) | &#x2705; | &#x2705; |

+| [Form Recognizer](../../applied-ai-services/form-recognizer/index.yml) | &#x2705; | &#x2705; |

+| [Logic Apps](../../logic-apps/index.yml) | &#x2705; | &#x2705; |

+| [Metrics Advisor](../../applied-ai-services/metrics-advisor/index.yml) | &#x2705; | &#x2705; |

+| **Service** | **FedRAMP High** | **DoD IL2** |

+| **Service** | **FedRAMP High** | **DoD IL2** |

+| **Service** | **FedRAMP High** | **DoD IL2** |

+| **Service** | **FedRAMP High** | **DoD IL2** |

+|Harborgrid Inc.|

+ - For **resourceTagValues**, match the existing tag values specified for the existing Container insights extension DCR of the cluster and the name of the data collection rule, which will be MSCI-\<clusterName\>-\<clusterRegion\> and this resource created in AKS clusters Resource Group. If this first-time onboarding, you can set the arbitrary tag values.

+Starting with chart version 1.0.0, the agent data collection settings are controlled from the ConfigMap. Refer to documentation about agent data collection settings [here](container-insights-agent-config.md).

+With monitoring enabled to collect health and resource utilization of your hybrid Kubernetes cluster and workloads running on them, learn [how to use](container-insights-analyze.md) Container insights.

+Container insights uses a containerized version of the Log Analytics agent for Linux. When a new version of the agent is released, the agent is automatically upgraded on your managed Kubernetes clusters hosted on Azure Kubernetes Service (AKS). For a [hybrid Kubernetes cluster](container-insights-hybrid-setup.md), the agent is not managed, and you need to manually upgrade the agent.

+If the agent upgrade fails for a cluster hosted on AKS, this article also describes the process to manually upgrade the agent. To follow the versions released, see [agent release announcements](https://github.com/microsoft/docker-provider/tree/ci_feature_prod).

+Run the following command to apply the change to Kubernetes clusters: `kubectl apply -f <path to yaml file>`.

+>The minimum agent version supported for scraping Prometheus metrics is ciprod07092019. The agent version supported for writing configuration and agent errors in the `KubeMonAgentEvents` table is ciprod10112019. For Red Hat OpenShift v4, the agent version is ciprod04162020 or later.

+- Red Hat OpenShift version 4.x through cluster connect to Azure Arc.

+* Red Hat OpenShift version 4.x

+- Red Hat OpenShift version 4.x

+Errors prevent omsagent from parsing the file, causing it to restart and use the default configuration. After you correct the errors in ConfigMap on clusters, save the YAML file and apply the updated ConfigMaps by running the command `kubectl apply -f <configmap_yaml_file.yaml`.

+ :::image type="content" source="./media/container-insights-update-metrics/portal-banner-enable-01.png" alt-text="Screenshot of the Azure portal that shows the banner for upgrading an AKS cluster." lightbox="media/container-insights-update-metrics/portal-banner-enable-01.png":::

+The following diagram gives a high-level view of Azure Monitor.

+- At the center of the diagram are the data stores for metrics and logs and changes, which are the fundamental types of data used by Azure Monitor.

+- On the left are the [sources of monitoring data](data-sources.md) that populate these [data stores](data-platform.md).

+- On the right are the different functions that Azure Monitor performs with this collected data. This includes such actions as analysis, alerting, and integration such as streaming to external systems.

+The following video uses an earlier version of the preceding diagram, but its explanations are still relevant.

+## Observability and the Azure Monitor data platform

+Metrics, logs, and distributed traces are commonly referred to as the three pillars of observability. Observability can be achieved by aggregating and correlating these different types of data across the entire system being monitored.

+Natively, Azure Monitor stores data as metrics, logs, or changes. Traces are stored in the Logs store. Each storage platform is optimized for particular monitoring scenarios, and each supports different features in Azure Monitor. Features such as data analysis, visualizations, or alerting require you to understand the differences so that you can implement your required scenario in the most efficient and cost effective manner.

+| Pillar | Description |

+|:|:|

+| Metrics | Metrics are numerical values that describe some aspect of a system at a particular point in time. They are collected at regular intervals and are identified with a timestamp, a name, a value, and one or more defining labels. Metrics can be aggregated using various algorithms, compared to other metrics, and analyzed for trends over time.<br><br>Metrics in Azure Monitor are stored in a time-series database, which is optimized for analyzing time-stamped data. For more information, see [Azure Monitor Metrics](essentials/data-platform-metrics.md). |

+| Logs | [Logs](logs/data-platform-logs.md) are events that occurred within the system. They can contain different kinds of data and may be structured or free form text with a timestamp. They may be created sporadically as events in the environment generate log entries, and a system under heavy load will typically generate more log volume.<br><br>Azure Monitor stores logs the Azure Monitor Logs store. The store allows you to segregate logs into separate "Log Analytics workspaces". There you can analyze them using the Log Analytics tool. Log Analytics workspaces are based on [Azure Data Explorer](/azure/data-explorer/), which provides a powerful analysis engine and the [Kusto rich query language](/azure/kusto/query/). For more information, see [Azure Monitor Logs](logs/data-platform-logs.md). |

+| Distributed traces | Traces are series of related events that follow a user request through a distributed system. They can be used to determine behavior of application code and the performance of different transactions. While logs will often be created by individual components of a distributed system, a trace measures the operation and performance of your application across the entire set of components.<br><br>Distributed tracing in Azure Monitor is enabled with the [Application Insights SDK](app/distributed-tracing.md). Trace data is stored with other application log data collected by Application Insights and stored in Azure Monitor Logs. For more information, see [What is Distributed Tracing?](app/distributed-tracing.md). |

+| Changes | Changes are tracked using [Change Analysis](change/change-analysis.md). Changes are a series of events that occur in your Azure application and resources. Change Analysis is a subscription-level observability tool that's built on the power of Azure Resource Graph. <br><br> Once Change Analysis is enabled, the `Microsoft.ChangeAnalysis` resource provider is registered with an Azure Resource Manager subscription. Change Analysis' integrations with Monitoring and Diagnostics tools provide data to help users understand what changes might have caused the issues. Read more about Change Analysis in [Use Change Analysis in Azure Monitor](./change/change-analysis.md). |

+Azure Monitor aggregates and correlates data across multiple Azure subscriptions and tenants, in addition to hosting data for other services. Because this data is stored together, it can be correlated and analyzed using a common set of tools.

+> [!NOTE]

+> It's important to distinguish between Azure Monitor Logs and sources of log data in Azure. For example, subscription level events in Azure are written to an [activity log](essentials/platform-logs-overview.md) that you can view from the Azure Monitor menu. Most resources will write operational information to a [resource log](essentials/platform-logs-overview.md) that you can forward to different locations. Azure Monitor Logs is a log data platform that collects activity logs and resource logs along with other monitoring data to provide deep analysis across your entire set of resources.

+Log data collected by Azure Monitor can be analyzed with [queries](logs/log-query-overview.md) to quickly retrieve, consolidate, and analyze collected data. You can create and test queries by using the [Log Analytics](./logs/log-query-overview.md) user interface in the Azure portal. You can then either directly analyze the data by using different tools or save queries for use with [visualizations](best-practices-analysis.md) or [alert rules](alerts/alerts-overview.md).

+Azure Monitor Logs uses a version of the [Kusto Query Language](/azure/kusto/query/) that's suitable for simple log queries but also includes advanced functionality such as aggregations, joins, and smart analytics. You can quickly learn the query language by using [multiple lessons](logs/get-started-queries.md). Particular guidance is provided to users who are already familiar with [SQL](/azure/data-explorer/kusto/query/sqlcheatsheet) and [Splunk](/azure/data-explorer/kusto/query/splunk-cheat-sheet).

+- **Application** - Data about the performance and functionality of the code you've written, regardless of its platform.

+- **Guest operating system** - Data about the operating system on which your application is running. The system could be running in Azure, another cloud, or on-premises.

+- **Azure resource** - Data about the operation of an Azure resource. For a complete list of the resources that have metrics or logs, see [What can you monitor with Azure Monitor?](monitor-reference.md#azure-supported-services).

+- **Azure subscription** - Data about the operation and management of an Azure subscription, and data about the health and operation of Azure itself.

+- **Azure tenant** - Data about the operation of tenant-level Azure services, such as Azure Active Directory.

+- **Azure resource changes** - Data about changes within your Azure resources and how to address and triage incidents and issues.

+For more information, see [List of insights and curated visualizations using Azure Monitor](monitor-reference.md#insights-and-curated-visualizations). Some of the larger insights are described here.

+For different options to enable the Change Tracking solution on your virtual machines, see [Enable Change Tracking and Inventory](../../automation/change-tracking/overview.md#enable-change-tracking-and-inventory). This solution includes methods to configure virtual machines at scale. You'll have to [create an Azure Automation account](/azure/automation/quickstarts/create-azure-automation-account-portal) to support the solution.

+* [Learn about alerts using metrics and logs in Azure Monitor](../alerts/alerts-overview.md)

+* South India

+When you export a dashboard from the Azure portal, the `id` field is not included. If you import this JSON file to create a new dashboard in the Azure portal, a new ID value will be assigned to each new dashboard.

+# Na

+You'll get an error if you attempt to use this function in any other part of the Bicep file. You'll also get an error if you use this function with string interpolation, even when used in the params section.

+| Microsoft.DocumentDB/databaseAccounts | [listConnectionStrings](/rest/api/cosmos-db-resource-provider/2022-05-15/database-accounts/list-connection-strings) |

+| Microsoft.DocumentDB/databaseAccounts | [listKeys](/rest/api/cosmos-db-resource-provider/2022-05-15/database-accounts/list-keys) |

+| Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces | [listConnectionInfo](/rest/api/cosmos-db-resource-provider/2022-05-15/notebook-workspaces/list-connection-info) |

+| Microsoft.DocumentDB/databaseAccounts | [listConnectionStrings](/rest/api/cosmos-db-resource-provider/2022-05-15/database-accounts/list-connection-strings) |

+| Microsoft.DocumentDB/databaseAccounts | [listKeys](/rest/api/cosmos-db-resource-provider/2022-05-15/database-accounts/list-keys) |

+| Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces | [listConnectionInfo](/rest/api/cosmos-db-resource-provider/2022-05-15/notebook-workspaces/list-connection-info) |

+* Accessibility: Whether you want to make your content available for people with disabilities or if you want your content to be distributed to different regions using different languages, you can use the transcription and translation provided by Azure Video Indexer in multiple languages.

+The following list shows the insights you can retrieve from your video/audio files using Azure Video Indexer video and audio AI features (models).

+* **Audio transcription**: Converts speech to text over 50 languages and allows extensions. For more information, see [Azure Video Indexer language support](language-support.md).

+* **Automatic language detection**: Identifies the dominant spoken language. For more information, see [Azure Video Indexer language support](language-support.md). If the language can't be identified with confidence, Azure Video Indexer assumes the spoken language is English. For more information, see [Language identification model](language-identification-model.md).

+* **Translation**: Creates translations of the audio transcript to many different languages. For more information, see [Azure Video Indexer language support](language-support.md).

+### Supported file formats

+See the [input container/file formats](/azure/media-services/latest/encode-media-encoder-standard-formats-reference) article for a list of file formats that you can use with Azure Video Indexer.

+For the latest updates, see [Azure Video Indexer release notes](release-notes.md).

+When visiting the [Azure Video Indexer](https://www.videoindexer.ai/) website for the first time, a trial account is automatically created for you. With the trial account, you get a certain number of free indexing minutes. You can later add a paid account. With the paid option, you pay for indexed minutes. For details about available accounts (trial and paid options), see [Azure Video Indexer account types](accounts-overview.md).

+## Prerequisite

+Before you start, see the [Recommendations](#recommendations) section (that follows later in this article).

+## Recommendations

+This section lists some recommendations when using Azure Video Indexer API.

+- If you're planning to upload a video, it's recommended to place the file in some public network location (for example, an Azure Blob Storage account). Get the link to the video and provide the URL as the upload file param.

+ The URL provided to Azure Video Indexer must point to a media (audio or video) file. An easy verification for the URL (or SAS URL) is to paste it into a browser, if the file starts playing/downloading, it's likely a good URL. If the browser is rendering some visualization, it's likely not a link to a file but to an HTML page.

+- When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. [See details about the returned JSON in this topic](video-indexer-output-json-v2.md).

+- The JSON output produced by the API contains `Insights` and `SummarizedInsights` elements. We highly recommend using `Insights` and not using `SummarizedInsights` (which is present for backward compatibility).

+- We do not recommend that you use data directly from the artifacts folder for production purposes. Artifacts are intermediate outputs of the indexing process. They are essentially raw outputs of the various AI engines that analyze the videos; the artifacts schema may change over time.

+ It is recommended that you use the [Get Video Index](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Video-Index) API, as described in [Get insights and artifacts produced by the API](video-indexer-output-json-v2.md#get-insights-produced-by-the-api) and **not** [Get-Video-Artifact-Download-Url](https://api-portal.videoindexer.ai/api-details#api=Operations&operation=Get-Video-Artifact-Download-Url).

+ If you arenΓÇÖt using firewall/NVA in your setup, then the backup stream is transferred over the Azure network to the Recovery Services vault / Azure Storage. Also, you can set up [Virtual Network Service Endpoint](../virtual-network/virtual-network-service-endpoints-overview.md) or [Private Endpoint](../private-link/private-endpoint-overview.md) to allow SAP HANA to send backup traffic directly to Recovery Services Vault / Azure Storage, skipping NVA/Azure Firewall. Additionally, when you use firewall/NVA, the traffic to Azure Active Directory and Azure Backup Service will pass through the firewall/NVA and it doesnΓÇÖt affect the overall backup performance.

+Your capabilities on the VM when connecting via native client are dependent on what is enabled on the native client. Controlling access to features such as file transfer via Bastion isn't supported.

+After you deploy this feature, there are two different sets of connection instructions.

+* [Connect to a VM from the native client on a Windows local computer](#connect). This lets you do the following:

+* [Connect to a VM using the **az network bastion tunnel** command](#connect-tunnel). This lets you do the following:

+## <a name="configure"></a>Configure the native client support feature

+You can configure this feature by either modifying an existing Bastion deployment, or you can deploy Bastion with the feature configuration already specified.

+### To modify an existing Bastion deployment

+If you've already deployed Bastion to your VNet, modify the following configuration settings:

+1. Navigate to the **Configuration** page for your Bastion resource. Verify that the SKU Tier is **Standard**. If it isn't, select **Standard**.

+1. Select the box for **Native Client Support**, then apply your changes.

+ :::image type="content" source="./media/connect-native-client-windows/update-host.png" alt-text="Screenshot that shows settings for updating an existing host with Native Client Support box selected." lightbox="./media/connect-native-client-windows/update-host.png":::

+### To deploy Bastion with the native client feature

+If you haven't already deployed Bastion to your VNet, you can deploy with the native client feature specified by deploying Bastion using manual settings. For steps, see [Tutorial - Deploy Bastion with manual settings](tutorial-create-host-portal.md#createhost). When you deploy Bastion, specify the following settings:

+1. On the **Basics** tab, for **Instance Details -> Tier** select **Standard**. Native client support requires the Standard SKU.

+1. Before you create the bastion host, go to the **Advanced** tab and check the box for **Native Client Support**, along with the checkboxes for any other additional features that you want to deploy.

+ :::image type="content" source="./media/connect-native-client-windows/new-host.png" alt-text="Screenshot that shows settings for a new bastion host with Native Client Support box selected." lightbox="./media/connect-native-client-windows/new-host.png":::

+1. Click **Review + create** to validate, then click **Create** to deploy your Bastion host.

+Verify that the following roles and ports are configured in order to connect to the VM.

+### Required roles

+## <a name="connect"></a>Connect to VM - Windows native client

+## <a name="connect-tunnel"></a>Connect to VM - other native clients

+In this quickstart, you'll learn how to deploy Azure Bastion with default settings to your virtual network using the Azure portal. After Bastion is deployed, you can connect (SSH/RDP) to virtual machines in the virtual network via Bastion using the private IP address of the VM. When you connect to a VM, it doesn't need a public IP address, client software, agent, or a special configuration. Azure Bastion is a PaaS service that's maintained for you, not a bastion host that you install on one of your VMs and maintain yourself. For more information about Azure Bastion, see [What is Azure Bastion?](bastion-overview.md)

+The following steps walk you through how to deploy Bastion from your VM resource using the Azure portal. When you deploy using default settings, the settings are based on the virtual network to which Bastion will be deployed. After deploying Bastion, you'll then connect to your VM using RDP/SSH connectivity and the VM's private IP address. If your VM has a public IP address that you don't need for anything else, you can remove it. While the steps in this quickstart help you deploy Bastion from your VM resource, you can deploy Bastion from a virtual network resource instead. The steps are similar, except you start from the virtual network resource instead of the VM resource.

+When you deploy from VM settings, Bastion is automatically configured with default values from the VNet

+1. On the **Bastion** page, you can view some of the values that will be used when creating the bastion host for your virtual network. Select **Deploy Bastion** to deploy bastion using default settings.

+ :::image type="content" source="./media/quickstart-host-portal/deploy.png" alt-text="Screenshot of Deploy Bastion." lightbox="./media/quickstart-host-portal/deploy.png":::

+> [!div class="nextstepaction"]

+> [Azure Bastion configuration settings and features](configuration-settings.md)

+> [!IMPORTANT]

+> You can't use the [Application Packages](batch-application-packages.md) feature with Azure Storage accounts configured with [firewall rules](../storage/common/storage-network-security.md), or with **Hierarchical namespace** set to **Enabled**.

+- Public: Central US EUAP, East US 2 EUAP, West Central US, North Central US, South Central US, East US, East US 2, West US 2, West US, Central US, West US 3, East Asia, South East Asia, Australia East, Australia Southeast, Brazil Southeast, Brazil South, Canada Central, Canada East, North Europe, West Europe, Central India, South India, Japan East, Japan West, Korea Central, Korea South, Sweden Central, Sweden South, Switzerland North, Switzerland West, UK West, UK South, UAE North, France Central, Germany West Central, Norway East, South Africa North.

+ > In order for the certificate to be automatically rotated to the latest version when a newer version of the certificate is available in your Key Vault, please set the certificate/secret version to 'Latest'. If a specific version is selected, you have to re-select the new version manually for certificate rotation. It takes up to 72 hours for the new version of the certificate/secret to be deployed.

+| `EnableMiscue` | Enables miscue calculation when the pronounced words are compared to the reference text. If this value is `True`, the `ErrorType` result value can be set to `Omission` or `Insertion` based on the comparison. Accepted values are `False` and `True`. Default: `False`. |

+| `ScenarioId` | A GUID indicating a customized point system. |

+setx ENVIRONMENT_VARIABLE_KEY "value"

+ Title: How to find immutable Azure resource ID

+description: how to find the immutable Azure Resource ID.

+# How to get your Azure Resource ID

+In order to get your Resource ID allowlisted, send your Immutable Azure Resource ID to the Call Recording Team. For reference, see the image below.

+

+## See Also

+For more information, see the following articles:

+- Check out our [web calling sample](../../samples/web-calling-sample.md)

+- Learn about [Calling SDK capabilities](./getting-started-with-calling.md?pivots=platform-web)

+- Learn more about [how calling works](../../concepts/voice-video-calling/about-call-types.md)

+ Title: Get server Call ID

+description: This section describes how to get the serverCallid from a JavaScript server app

+# Get serverCallId as a requirement for call recording server APIs from JavaScript application

+In a peer to peer calling scenario using the [Calling client SDK](get-started-with-video-calling.md), in order to use Call Recording from Azure Communications you'll have to get the `serverCallId`.

+The following example shows you how to get the `serverCallId` from a JavaScript server application.

+Call recording is an extended feature of the core Call API. You first need to import calling Features from the Calling SDK.

+```JavaScript

+import { Features} from "@azure/communication-calling";

+```

+Then you can get the recording feature API object from the call instance:

+```JavaScript

+const callRecordingApi = call.feature(Features.Recording);

+```

+Subscribe to recording changes:

+```JavaScript

+const recordingStateChanged = () => {

+ let recordings = callRecordingApi.recordings;

+ let state = SDK.RecordingState.None;

+ if (recordings.length > 0) {

+ state = recordings.some(r => r.state == SDK.RecordingState.Started)

+ ? SDK.RecordingState.Started

+ : SDK.RecordingState.Paused;

+ }

+

+ console.log(`RecordingState: ${state}`);

+}

+const recordingsChangedHandler = (args: { added: SDK.RecordingInfo[], removed: SDK.RecordingInfo[]}) => {

+ args.added?.forEach(a => {

+ a.on('recordingStateChanged', recordingStateChanged);

+ });

+ args.removed?.forEach(r => {

+ r.off('recordingStateChanged', recordingStateChanged);

+ });

+ recordingStateChanged();

+};

+callRecordingApi.on('recordingsUpdated', recordingsChangedHandler);

+```

+Get `servercallId`, which can be used to start/stop/pause/resume recording sessions.

+Once the call is connected, use the `getServerCallId` method to get the server call ID.

+```JavaScript

+callAgent.on('callsUpdated', (e: { added: Call[]; removed: Call[] }): void => {

+ e.added.forEach((addedCall) => {

+ addedCall.on('stateChanged', (): void => {

+ if (addedCall.state === 'Connected') {

+ addedCall.info.getServerCallId().then(result => {

+ dispatch(setServerCallId(result));

+ }).catch(err => {

+ console.log(err);

+ });

+ }

+ });

+ });

+});

+```

+## See also

+For more information, see the following articles:

+- Learn about [Calling SDK capabilities]()

+- Learn more about [how calling works](../../concepts/voice-video-calling/about-call-types.md)

+The API for MongoDB exposes a built-in role-based access control (RBAC) system that lets you authorize your data requests with a fine-grained, role-based permission model. Users and roles reside within a database and are managed using the Azure CLI, Azure PowerShell, or ARM for this preview feature.

+- Now that you're familiar with using built-in views, read about [Saving and sharing customized views](save-share-views.md).

+- Learn about how to [Customize views in cost analysis](customize-cost-analysis-views.md)

+ Title: Customize views in cost analysis

+description: This article helps you customize views in cost analysis to understand how you're being charged and to investigate unexpected changes.

+# Customize views in cost analysis

+This article helps you customize views in cost analysis to understand how you're being charged and to investigate unexpected changes.

+## Prerequisites

+To customize views, you must have at least the Cost Management Reader (or Contributor) role.

+You should be familiar with the information at [Quickstart: Explore and analyze costs with cost analysis](quick-acm-cost-analysis.md).

+## Get started with customizing views

+Customizing views in cost analysis includes anything from tweaking display settings to changing what data gets included or how it's summarized. You customize views when trying to understand what you're spending and where the costs originated. For example, you can drill into data, apply specific filters or groupings, or change display settings, like whether to view a chart or table. The following sections cover each of these customization options.

+## Group costs

+Use the **Group by** option to group common properties so that you get a break down of costs and to identify top contributors. It should be your first change when drilling into data because it helps you identify the largest changes. To group by resource tags, for example, select the tag key you want to group by. Costs are broken down by each tag value, with an extra segment for resources that don't have that tag applied.

+Most Azure resources support tagging. However, some tags aren't available in Cost Management and billing. Additionally, resource group tags aren't supported. Support for tags applies to usage reported _after_ the tag was applied to the resource. Tags aren't applied retroactively for cost rollups.

+Here's a view of Azure service costs for the current month, grouped by Service name.

+The following image shows resource group names. You can group by tag to view total costs per tag or group by **Resource group name**.

+When you're grouping costs by a specific attribute, the top 10 cost contributors are shown from highest to lowest. If there are more than 10, the top nine cost contributors are shown with an **Others** group that represents all remaining groups combined. When you're grouping by tags, an **Untagged** group appears for costs that don't have the tag key applied. **Untagged** is always last, even if untagged costs are higher than tagged costs. Untagged costs will be part of **Others**, if 10 or more tag values exist. To view what's grouped into **Others** , either select that segment to apply a filter or switch to the table view and change granularity to **None** to see all values ranked from highest to lowest cost.

+Classic virtual machines, networking, and storage resources don't share detailed billing data. They're merged as **Classic services** when grouping costs.

+Cost analysis doesn't support grouping by multiple attributes. To work around it, you can apply a filter for a desired attribute and group by the more detailed attribute. For instance, filter down to a specific resource group, then group by resource.

+Pivot charts under the main chart show different groupings, which give you a broader picture of your overall costs for the selected time period and filters. Select a property or tag to view aggregated costs by any dimension.

+## Select a date range

+There are many cases where you need deeper analysis. Customization starts at the top of the page, with the date selection.

+Cost analysis shows data for the current month by default. Use the date selector to switch to common date ranges quickly. Examples include the last seven days, the last month, the current year, or a custom date range. Pay-as-you-go subscriptions also include date ranges based on your billing period, which isn't bound to the calendar month, like the current billing period or last invoice.

+## Filter charges

+Add filters to narrow down or drill into your specific charges. It's especially helpful when trying to understand an unexpected change. Start by selecting the **Add filter** pill, then select the desired attribute, and lastly select the options you want to filter down to. Your view will automatically update once you've applied the filter.

+You can add multiple filters. As you add filters, you'll notice that the available values for each filter include the previously selected filters. For instance, if you apply a resource group filter, then add a resource filter, the resource filter options will only show resources in the selected resource group.

+When you view charts, you can also select a chart segment to apply a filter. After selecting a chart segment, you should consider changing the group by attribute to see other details about the attribute you selected.

+## Switch between actual and amortized cost

+By default, cost analysis shows all usage and purchase costs as they're accrued and will show on your invoice, also known as **Actual cost**. Viewing actual cost is ideal for reconciling your invoice. However, purchase spikes in cost can be alarming when you're keeping an eye out for spending anomalies and other changes in cost. To flatten out spikes caused by reservation purchase costs, switch to **Amortized cost**.

+Amortized cost breaks down reservation purchases into daily chunks and spreads them over the duration of the reservation term. Most reservation terms are one or three years. Let's look at a one-year reservation example. Instead of seeing a $365 purchase on January 1, you'll see a $1.00 purchase every day from January 1 to December 31. In addition to basic amortization, these costs are also reallocated and associated by using the specific resources that used the reservation. For example, if that $1.00 daily charge was split between two virtual machines, you'd see two $0.50 charges for the day. If part of the reservation isn't utilized for the day, you'd see one $0.50 charge associated with the applicable virtual machine and another $0.50 charge with a charge type of UnusedReservation. Unused reservation costs can be seen only when you view amortized cost.

+If you buy a one-year reservation on May 26 with an upfront payment, the amortized cost is divided by 365 (assuming it's not a leap year) and spread from May 26 through May 25 of the next year. If you pay monthly, the monthly fee is divided by the number of days in that month. The free is spread evenly across May 26 through June 25, with the next month's fee spread across June 26 through July 25.

+Because of the change in how costs are represented, it's important to note that actual cost and amortized cost views will show different total numbers. In general, the total cost of months with a reservation purchase will decrease when you view amortized costs, and months following a reservation purchase will increase. Amortization is available only for reservation purchases and doesn't apply to Azure Marketplace purchases at this time.

+## Select a currency

+Costs are shown in your billing currency by default. If you have charges in multiple currencies, costs will automatically be converted to USD. If you have any non-USD charges, you can switch between currencies in the total KPI menu. You may see options like **GBP only** to view only the charges in that one currency or **All costs in USD** to view the normalized costs in USD. You can't view costs normalized to other currencies today.

+## Select a budget

+When you view a chart, it can be helpful to visualize your charges against a budget. It's especially helpful when showing accumulated daily costs with a forecast trending towards your budget. If your costs go over your budget, you'll see a red critical icon next to your budget. If your forecast goes over your budget, you'll see a yellow warning icon.

+When you view daily or monthly costs, your budget may be estimated for the period. For instance, a monthly budget of $31 will be shown as `$1/day (est)`. Note your budget won't be shown as red when it exceeds this estimated amount on a specific day or month.

+Budgets that have filters aren't currently supported in cost analysis. You won't see them in the list. Budgets on lower-level scopes are also not shown in cost analysis today. To view a budget for a specific scope, change scope using the scope picker.

+## Change granularity

+Use **Granularity** to indicate how you want to view cost over time. The lowest level you can view is Daily costs. You can view daily costs for up to 3 months or 92 consecutive days. If you select more than 92 days, cost analysis switches to **Monthly** granularity. It updates your date range to include the start and end of the selected months to provide the most accurate picture of your monthly costs. You can view up to 12 months of monthly costs.

+If you'd like to view a running total of charges on either a daily or monthly basis, select **Accumulated**. Accumulated is especially helpful when you view your forecast as it helps you see the trend over time.

+If you'd like to view the total for the entire period (no granularity), select **None**. Selecting no granularity is helpful when grouping costs by a specific attribute in either a chart or table.

+## Visualize costs in a chart

+Cost analysis supports the following chart types:

+- Area charts are ideal for showing a running total with forecast trending towards a budget.

+- Line charts are ideal for reviewing relative changes. Line charts aren't stacked, which helps spot changes easily.

+- Column (stacked) charts are ideal for reviewing your daily or monthly run rate. It shows a breakdown by some attribute to easily spot which group has the most charges. Groups are sorted from largest to smallest from left-to-right, bottom-to-top.

+- Column (grouped) charts are helpful when you view grouped costs with no granularity.

+## View costs in table format

+You can view the full dataset for any view. Whichever selections or filters that you apply affect the data presented. To see the full dataset, select the **chart type** list and then select **Table** view.

+## Next steps

+- Learn about [Saving and sharing customized views](save-share-views.md).

+Use the [amortized cost view](customize-cost-analysis-views.md#switch-between-actual-and-amortized-cost) in billing scopes to view reserved instance amortized costs across a reservation term.

+1. The billing profile configuration is shown. Policies are shown as Enabled or Disabled. If you want to change a policy, select **Edit** under a policy.

+In this quickstart, you use cost analysis to explore and analyze your organizational costs. You can view aggregated costs or break them down to understand where costs occur over time and identify spending trends. You can view accumulated costs over time to estimate monthly, quarterly, or even yearly cost trends against a budget. You can use budgets to get notified as cost exceeds specific thresholds.

+**Currently selected view**: Represents the predefined cost analysis view configuration. Each view includes date range, granularity, group by, and filter settings. The default view shows a running total of your costs for the current billing period with the Accumulated costs view, but you can select other built-in views from the menu. The view menu is between the scope pill and the date selector. For details about saved views, see [Save and share customized views](save-share-views.md).

+**Filters**: Allow you to limit the results to a subset of your total charges. Filters apply to all summarized totals and charts.

+**Cost**: Shows the total usage and purchase costs for the selected period, as they're accrued and will show on your bill. Costs are shown in your billing currency by default. If you have charges in multiple currencies, cost will automatically be converted to USD.

+**Forecast**: Shows the total forecasted costs the selected period.

+**Budget (if selected)**: Shows the current budget amount for the selected scope, if already defined.

+**Granularity**: Indicates how to show data over time. Select **Daily** or **Monthly** to view costs broken down by day or month. Select **Accumulated** to view the running total for the period. Select **None** to view the total cost for the period, with no breakdown.

+Cost analysis has many built-in views, optimized for the most common goals:

+Resources (preview) | Which resources cost the most so far this month? Are there any subscription cost anomalies?

+Resource groups (preview) | Which resource groups cost the most so far this month?

+Subscriptions (preview) | Which subscriptions the most so far this month?

+Services (preview) | Which services cost the most so far this month?

+Reservations (preview) | How much are reservations being used? Which resources are utilizing reservations?

+The Cost by resource and Resources views are only available for subscriptions and resource groups.

+For more information about views, see:

+- [Use built-in views in Cost analysis](cost-analysis-built-in-views.md)

+- [Save and share customized views](save-share-views.md)

+- [Customize views in cost analysis](customize-cost-analysis-views.md)

+When the forecast is disabled, you won't see projected spending for future dates. Also, when you look at costs for past time periods, cost forecast doesn't show costs.

+Generally, you can expect to see data or notifications for consumed resources within 24 to 48 hours.

+| Maximum columns | The default value is 20480. Customize this value when the column number is over 20480 | no | Integer | maxColumns |

+ validateSchema: false,

+ ignoreNoFilesFound: false,

+ multiLineRow: true,

+ wildcardPaths:['*.csv']) ~> CSVSource

+> [!NOTE]

+> Custom DNS is not supported in managed virtual network.

+ Title: FAQ about using Azure Database Migration Service for Azure Database MySQL Single Server to Flexible Server migrations

+description: Frequently asked questions about using Azure Database Migration Service to perform database migrations from Azure Database MySQL Single Server to Flexible Server.

+# Frequently Asked Questions (FAQs)

+- **When using Azure Database Migration Service, whatΓÇÖs the difference between an offline and an online migration?**

+Azure Database Migration Service supports both offline and online migrations. With an offline migration, application downtime starts when the migration starts. With an online migration, downtime is limited to the time required to cut over at the end of migration. We suggest that you test an offline migration to determine whether the downtime is acceptable; if not, then perform an online migration.

+Online and Offline migrations are compared in the following table:

+ | Area | Online migration | Offline migration |

+ | - |:-:|:-:|

+ | **Database availability for reads during migration** | Available | Available |

+ | **Database availability for writes during migration** | Available | Generally, not recommended. Any ΓÇÿwritesΓÇÖ initiated after the migration is not captured or migrated |

+ | **Application Suitability** | Applications that need maximum uptime | Applications that can afford a planned downtime window |

+ | **Environment Suitability** | Production environment | Usually Development, Testing environment and some production that can afford downtime |

+ | **Suitability for Write-heavy workloads** | Suitable but expected to reduce the workload during migration | Not Applicable. Writes at source after migration begins are not replicated to target |

+ | **Manual Cutover** | Required | Not required |

+ | **Downtime required** | Less | More |

+ | **Migration time** | Depends on Database size and the write activity until cutover | Depends on Database size |

+- **IΓÇÖm setting up a migration project in DMS and IΓÇÖm having difficulty connecting to my source database. What should I do?**

+If you have trouble connecting to your source database system while working on migration, create a virtual machine in the same subnet of the virtual network with which you set up your DMS instance. In the virtual machine, you should be able to run a connect test. If the connection test succeeds, you shouldn't have an issue with connecting to your source database. If the connection test doesn't succeed, contact your network administrator.

+- **Why is my Azure Database Migration Service unavailable or stopped?**

+If the user explicitly stops Azure Database Migration Service (DMS) or if the service is inactive for a period of 24 hours, the service will be in a stopped or auto paused state. In each case, the service will be unavailable and in a stopped status. To resume active migrations, restart the service.

+- **Are there any recommendations for optimizing the performance of Azure Database Migration Service?**

+There are a couple of things to you can try to speed up your database migration using DMS:

+ - Use the multi CPU General Purpose Pricing Tier when you create your service instance to allow the service to take advantage of multiple vCPUs for parallelization and faster data transfer.

+ - Temporarily scale up your Azure MySQL Database target instance to the Premium tier SKU during the data migration operation to minimize Azure MySQL Database throttling that may impact data transfer activities when using lower-level SKUs.

+- **Which data, schema, and metadata components are migrated as part of the migration?**

+Azure Database Migration Service migrates schema, data, and metadata from the source to the destination. All of the following data, schema, and metadata components are migrated as part of the database migration:

+ - Data Migration - All tables from all databases/schemas.

+ - Schema Migration - Naming, Primary key, Data type, Ordinal position, Default value, Nullability, Auto-increment attributes, Secondary indexes

+ - Metadata Migration, Stored Procedures, Functions, Triggers, Views, Foreign key constraints

+- **Is there an option to rollback a Single Server to Flexible Server migration?**

+You can perform any number of test migrations, and after gaining confidence through testing, perform the final migration. A test migration doesnΓÇÖt affect the source single server, which remains operational and continues replicating until you perform the actual migration. If there are any errors during the test migration, you can choose to postpone the final migration and keep your source server running. You can then reattempt the final migration after you resolve the errors. Note that after you have performed a final migration to Flexible Server and the source single server has been shut down, you cannot perform a rollback from Flexible Server to Single Server.

+- **The size of my database is greater than 1 TB, so how should I proceed with migration?**

+To support migrations of databases that are 1 TB+, raise a support ticket with Azure Database Migration Service to scale-up the migration agent to support your 1 TB+ database migrations.

+- **Is cross-region migration supported?**

+Azure Database Migration Service supports cross-region migrations, so you can migrate your single server to a flexible server that is deployed in a different region using DMS.

+- **Is cross-subscription migration supported?**

+Azure Database Migration Service supports cross-subscription migrations, so you can migrate your single server to a flexible server that deployed on a different subscription using DMS.

+- **Is cross-resource group subscription supported?**

+Azure Database Migration Service supports cross-resource group migrations, so you can migrate your single server to a flexible server that is deployed in a different resource group using DMS.

+- **Is there cross-version support?**

+Yes, migration from lower version MySQL servers (v5.6 and above) to higher versions is supported.

+> For online migrations, you can use the Enable Transactional Consistency feature supported by DMS together with [Data-in replication](./../mysql/single-server/concepts-data-in-replication.md) or [replicate changes](https://techcommunity.microsoft.com/t5/microsoft-data-migration-blog/azure-dms-mysql-replicate-changes-now-in-preview/ba-p/3601564). Additionally, you can use the online migration scenario to migrate by following the tutorial [here](./tutorial-mysql-azure-single-to-flex-offline-portal.md).

+ * Configure the replicas on the target server to match those on the source server.

+8. After configuring for schema migration, select **Review and start migration**.

+> [!NOTE]

+> This article contains references to the term *slave*, a term that Microsoft no longer uses. When the term is removed from the software, we'll remove it from this article.

+ * Configure the replicas on the target server to match those on the source server.

+ :::image type="content" source="media/tutorial-azure-mysql-single-to-flex-online/select-source-online.png" alt-text="Screenshot of an Add source details screen.":::

+ :::image type="content" source="media/tutorial-azure-mysql-single-to-flex-online/select-target-online.png" alt-text="Screenshot of a Select target.":::

+ If the selected source table doesn't exist on the target server, the online migration process will ensure that the table schema and data is migrated to the target server.

+7. After configuring for schema migration, select **Review and start migration**.

+ :::image type="content" source="media/tutorial-azure-mysql-single-to-flex-online/running-online-migration.png" alt-text="Screenshot of a Running status.":::

+1. Once the **Initial Load** activity is completed, navigate to the **Initial Load** tab to view the completion status and the number of tables completed.

+ :::image type="content" source="media/tutorial-azure-mysql-single-to-flex-online/completed-initial-load-online.png" alt-text="Screenshot of a completed initial load migration.":::

+2. Once the **Initial Load** activity is completed, you are navigated to the **Replicate Data Changes** tab automatically. You can monitor the migration progress as the screen is auto-refreshed every 30 seconds. Select **Refresh** to update the display and view the seconds behind source as and when needed.

+ :::image type="content" source="media/tutorial-azure-mysql-single-to-flex-online/running-replicate-data-changes.png" alt-text="Screenshot of a Monitoring migration.":::

+3. Monitor the **Seconds behind source** and as soon as it nears 0, proceed to start cutover by clicking on the **Start Cutover** menu tab at the top of the migration activity screen. Follow the steps in the cutover window before you are ready to perform a cutover. Once all steps are completed, click on **Confirm** and next click on **Apply**.

+> - Make sure that you are a member of one of these roles: **Owner**, **Contributor**, or **Schema Registry Contributor**. For details about role-based access control, see [Schema Registry overview](schema-registry-overview.md#azure-role-based-access-control).

+ > In order for the certificate to be automatically rotated to the latest version when a newer version of the certificate is available in your Key Vault, please set the secret version to 'Latest'. If a specific version is selected, you have to re-select the new version manually for certificate rotation. It takes up to 72 hours for the new version of the certificate/secret to be deployed.

+In order for the certificate to automatically be rotated to the latest version when a newer version of the certificate is available in your key vault, set the secret version to 'Latest'. If a specific version is selected, you have to reselect the new version manually for certificate rotation. It takes up to 72 hours for the new version of the certificate/secret to be automatically deployed.

+| Apache Spark | 2.4.4, 3.1 |

+| Apache Kafka | 2.1.1, 2.4.1 |

+* Customers can't create new Kafka 2.1.0 clusters but existing 2.1.0 clusters won't be impacted and will get basic support until September 30, 2022.

+- and finally use the production line certificate, to generate a unique device (end-entity) certificate for each device manufactured on the line.

+#### Why are intermediate certs useful?

+### Mutual TLS support

+When DPS enrollments are configured for X.509 attestation, mutual TLS (mTLS) is supported by DPS.

+### DPS device chain requirements

+### DPS order of operations with certificates

+Current TLS protocol versions supported by DPS are:

+### Legacy cipher suites

+## Mutual TLS support

+When DPS enrollments are configured for X.509 authentication, mutual TLS (mTLS) is supported by DPS.

+> [!NOTE]

+> This information relates to a preview feature that's available for early testing and use in a production environment. This feature is fully supported but it's still in active development and may receive substantial changes until it becomes generally available.

+> [!NOTE]

+> This information relates to a preview feature that's available for early testing and use in a production environment. This feature is fully supported but it's still in active development and may receive substantial changes until it becomes generally available.

+> [!NOTE]

+> This information relates to a preview feature that's available for early testing and use in a production environment. This feature is fully supported but it's still in active development and may receive substantial changes until it becomes generally available.

+> [!NOTE]

+> This information relates to a preview feature that's available for early testing and use in a production environment. This feature is fully supported but it's still in active development and may receive substantial changes until it becomes generally available.

+> [!NOTE]

+> This information relates to a preview feature that's available for early testing and use in a production environment. This feature is fully supported but it's still in active development and may receive substantial changes until it becomes generally available.

+installers. For instance, the `SWUpdate` update handler, `Apt` update handler, and `Script` update handler.

+If you choose to implement with your own downloader in place of Delivery Optimization, be sure to review the [requirements for large file downloads](device-update-limits.md).

+## Support for managed identities

+Managed identities provide Azure services with an automatically managed identity in Azure AD in a secure manner. This eliminates the needs for developers having to manage credentials by providing an identity. Device Update for IoT Hub supports system-assigned managed identities.

+### System-assigned managed identity

+To add and remove a system-assigned managed identity in Azure portal:

+1. Sign in to the Azure portal and navigate to your desired Device Update for IoT Hub account.

+2. Navigate to Identity in your Device Update for IoT Hub portal

+3. Navigate to Identity in your IoT Hub portal

+4. Under System-assigned tab, select On and click Save.

+To remove system-assigned managed identity from an Device Update for IoT hub account, select Off and click Save.

+## Next Steps

+* [Create device update resources and configure access control roles](./create-device-update-account.md)

+### Requirements for large-file downloads

+If you plan to deploy large-file packages, with file size larger than 100 MB, it is recommended to utilize byte range requests for a reliable download performance.

+The Device Update for IoT Hub service utilizes Content Delivery Networks (CDNs) that work optimally with range requests of 1 MB in size. Range requests larger than 100 MB are not supported.

+## Update the IoT hub

+You can change the settings of an existing IoT hub after it's created from the IoT Hub pane. Here are some properties you can set for an IoT hub:

+**Pricing and scale**: Migrate to a different tier or set the number of IoT Hub units.

+**Properties**: A list of properties that you can copy and use elsewhere, such as the resource ID, resource group, location, and so on.

+For a complete list of options to update an IoT hub, see the [**az iot hub update** commands](/cli/azure/iot/hub#az-iot-hub-update) reference page.

+To delete an IoT hub, open your IoT hub in the Azure portal, then choose **Delete**.

+- [Azure IoT Tools](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-tools) installed for Visual Studio Code

+- An Azure resource group: [create a resource group](/azure/azure-resource-manager/management/manage-resource-groups-portal#create-resource-groups) in the Azure portal

+> [!TIP]

+> To delete a device from your IoT hub, use the `Azure IoT Hub: Delete Device` option from the Command Palette. There is no option to delete your IoT hub in Visual Studio Code, however you can [delete your hub in the Azure portal](iot-hub-create-through-portal.md#delete-the-iot-hub).

+When you create an IoT hub, you must create it in a resource group. Either use an existing resource group, or run the following [command to create a resource group](/cli/azure/resource):

+## Create an IoT Hub

+Use the Azure CLI to create a resource group and then add an IoT hub.

+Run the following [command to create an IoT hub](/cli/azure/iot/hub#az-iot-hub-create) in your resource group, using a globally unique name for your IoT hub:

+For more information on Azure IoT Hub commands, see the [`az iot hub`](/cli/azure/iot/hub) reference article.

+## Update the IoT hub

+You can change the settings of an existing IoT hub after it's created. Here are some properties you can set for an IoT hub:

+**Pricing and scale**: Migrate to a different tier or set the number of IoT Hub units.

+**IP Filter**: Specify a range of IP addresses that will be accepted or rejected by the IoT hub.

+**Properties**: A list of properties that you can copy and use elsewhere, such as the resource ID, resource group, location, and so on.

+For a complete list of options to update an IoT hub, see the [**az iot hub update** commands](/cli/azure/iot/hub#az-iot-hub-update) reference page.

+## Register a new device in the IoT hub

+In this section, you create a device identity in the identity registry in your IoT hub. A device can't connect to a hub unless it has an entry in the identity registry. For more information, see [Understand the identity registry in your IoT hub](iot-hub-devguide-identity-registry.md). This device identity is [IoT Edge](/azure/iot-edge) enabled.

+Run the following command to create a device identity. Use your IoT hub name and create a new device ID name in place of `{iothub_name}` and `{device_id}`. This command creates a device identity with default authorization (shared private key).

+az iot hub device-identity create -n {iothub_name} -d {device_id} --ee

+The result is a JSON printout which includes your keys and other information.

+Alternatively, there are several options to register a device using different kinds of authorization. To explore the options, see [Examples](/device-identity?view=azure-cli-latest#az-iot-hub-device-identity-create-examples&preserve-view=true) on the **az iot hub device-identity** reference page.

+## Remove an IoT Hub

+There are various commands to [delete an individual resource](/cli/azure/resource), such as an IoT hub.

+To [delete an IoT hub](/cli/azure/iot/hub#az-iot-hub-delete), run the following command:

+az iot hub delete --name {your iot hub name} -\

+ -resource-group {your resource group name}

+## Prerequisites

+To create a new resource group for your IoT hub, use the [New-AzResourceGroup](/powershell/module/az.Resources/New-azResourceGroup) command. This example creates a resource group called **MyIoTRG1** in the **East US** region:

+## Connect to your Azure subscription

+If you're using Cloud Shell, you're already logged in to your subscription, so you can skip this section. If you're running PowerShell locally instead, enter the following command to sign in to your Azure subscription:

+```powershell

+# Log into Azure account.

+Login-AzAccount

+```

+Create an IoT hub using your resource group. Use the [New-AzIotHub](/powershell/module/az.IotHub/New-azIotHub) command. This example creates an **S1** hub called **MyTestIoTHub** in the **East US** region:

+## Update the IoT hub

+You can change the settings of an existing IoT hub after it's created. Here are some properties you can set for an IoT hub:

+**Pricing and scale**: Migrate to a different tier or set the number of IoT Hub units.

+**IP Filter**: Specify a range of IP addresses that will be accepted or rejected by the IoT hub.

+**Properties**: A list of properties that you can copy and use elsewhere, such as the resource ID, resource group, location, and so on.

+Explore the [**Set-AzIotHub** commands](/powershell/module/az.iothub/set-aziothub) for a complete list of update options.

+## Turn on data protection for your vault

+Turn on purge protection to guard against malicious or accidental deletion of the secrets and key vault even after soft-delete is turned on.

+For more information, see [Azure Key Vault soft-delete overview](soft-delete-overview.md)

+## Backup

+Purge protection prevents malicious and accidental deletion of vault objects for up to 90 days. In scenarios when purge protection is not a possible option, we recommend backup vault objects, which can't be recreated from other sources like encryption keys generated within the vault.

+For more information about backup, see [Azure Key Vault backup and restore](backup.md)

+## Frequently Asked Questions:

+### Can I use Key Vault role-based access control (RBAC) permission model object-scope assignments to provide isolation for application teams within Key Vault?

+No. RBAC permission model allows to assign access to individual objects in Key Vault to user or application, but any administrative operations like network access control, monitoring, and objects management require vault level permissions which will then expose secure information to operators across application teams.

+Turn on [purge protection](../general/soft-delete-overview.md#purge-protection) to guard against malicious or accidental deletion of the secrets.

+In scenarios when purge protection is not a possible option, we recommend [backup](../general/backup.md) secrets, which can't be recreated from other sources.

+5. Add a second IP configuration to each of the VMs. Follow the instructions in [Assign multiple IP addresses to virtual machines](../virtual-network/ip-services/virtual-network-multiple-ip-addresses-powershell.md#add-secondary-private-and-public-ip-address) article. Use the following configuration settings:

+- Azure CLI version 2.2.0 or later (if you're using CI/CD). Run `az --version` to find the version that's installed on your computer. If you need to install or upgrade the Azure CLI, see [How to install the Azure CLI](/cli/azure/install-azure-cli).

+To test private endpoints, you need an existing Azure virtual network. Your virtual network should have at least one subnet, and allow access for traffic coming from the Azure Load Testing service.

+When you deploy Azure Load Testing in your virtual network, it's recommended to use separate subnets for Azure Load Testing and for the application endpoint. This approach enables you to configure network traffic access policies specifically for each purpose. Learn more about how to [add a subnet to a virtual network](/azure/virtual-network/virtual-network-manage-subnet#add-a-subnet).

+Azure Load Testing requires both inbound and outbound access for the injected VMs in your virtual network. If you plan to restrict traffic access to your virtual network, or if you're already using a network security group, configure the network security group for the subnet in which you deploy the load test.

+1. Go to the [Azure portal](https://portal.azure.com).

+1. If you don't have an NSG yet, follow these steps to [create a network security group](/azure/virtual-network/manage-network-security-group#create-a-network-security-group).

+ Create the NSG in the same region as your virtual network, and then associate it with your subnet.

+1. Search for and select your network security group.

+ <!-- TODO: add screenshot of portal -->

+## Configure your load test

+To include privately hosted endpoints in your load test, you need to configure the virtual network settings for the load test. You can configure the VNET settings in the Azure portal, or specify them in the [YAML test configuration file](./reference-test-config-yaml.md) for CI/CD pipelines.

+> [!IMPORTANT]

+> When you deploy Azure Load Testing in a virtual network, you'll incur additional charges. Azure Load Testing deploys an [Azure Load Balancer](https://azure.microsoft.com/pricing/details/load-balancer/) and a [Public IP address](https://azure.microsoft.com/pricing/details/ip-addresses/) in your subscription and there might be a cost for generated traffic. For more information, see the [Virtual Network pricing information](https://azure.microsoft.com/pricing/details/virtual-network).

+### Configure the VNET in the Azure portal

+You can specify the VNET configuration settings in the load test creation/update wizard.

+1. Go to your Azure Load Testing resource, and select **Tests** from the left pane.

+1. Open the load test creation/update wizard in either of two ways:

+ - Select **+ Create > Upload a JMeter script**, if you want to create a new test.

+ :::image type="content" source="media/how-to-test-private-endpoint/create-new-test.png" alt-text="Screenshot that shows the Tests page, highlighting the button for creating a new test.":::

+

+ - Select an existing test from the list, and then select **Edit**.

+ :::image type="content" source="media/how-to-test-private-endpoint/edit-test.png" alt-text="Screenshot that shows the Tests page, highlighting the button for editing a test.":::

+

+1. Review or fill the load test information. Follow these steps to [create or manage a test](./how-to-create-manage-test.md).

+ If you have multiple subnets in your virtual network, make sure to select the subnet that will host the injected test engine VMs.

+ :::image type="content" source="media/how-to-test-private-endpoint/create-new-test-load-vnet.png" alt-text="Screenshot that shows the Load tab for creating or updating a load test.":::

+1. Select **Review + create** and then **Create** (or **Apply**, when updating an existing test).

+ When the load test starts, Azure Load Testing injects the test engine VMs in your virtual network and subnet. The test script can now access the privately hosted application endpoint in your VNET.

+### Configure the VNET for CI/CD pipelines

+To configure the load test with your virtual network settings, update the [YAML test configuration file](./reference-test-config-yaml.md).

+1. Open a terminal, and use the Azure CLI to sign in to your Azure subscription:

+ ```azurecli

+ az login

+ az account set --subscription <your-Azure-Subscription-ID>

+ ```

+1. Retrieve the subnet ID and copy the resulting value:

+ ```azurecli

+ az network vnet subnet show -g <your-resource-group> --vnet-name <your-vnet-name> --name <your-subnet-name> --query id

+ ```

+1. Open your YAML test configuration file in your favorite editor.

+1. Add the `subnetId` property to the configuration file and provide the subnet ID you copied earlier:

+ ```yml

+ version: v0.1

+ testName: SampleTest

+ testPlan: SampleTest.jmx

+ description: 'Load test the website home page'

+ engineInstances: 1

+ subnetId: <your-subnet-id>

+ ```

+ For more information about the YAML configuration, see [test configuration YAML reference](./reference-test-config-yaml.md).

+1. Save the YAML configuration file, and commit your changes to the source code repository.

+1. After the CI/CD workflow triggers, your load test starts, and can now access the privately hosted application endpoint in your VNET.

+| `subnetId` | string | | Resource ID of the subnet for testing privately hosted endpoints (VNET injection). This subnet will host the injected test engine VMs. For more information, see [how to load test privately hosted endpoints](./how-to-test-private-endpoint.md). |

+subnetId: /subscriptions/abcdef01-2345-6789-0abc-def012345678/resourceGroups/sample-rg/providers/Microsoft.Network/virtualNetworks/load-testing-vnet/subnets/load-testing

+* A Consumption logic app workflow with a request trigger to export.

+ > [!NOTE]

+ >

+ > The Export capability is available only for Consumption logic app workflows in multi-tenant Azure Logic Apps.

+### [Azure CLI](#tab/cli)

+### [Azure CLI](#tab/cli)

+### [Azure CLI](#tab/cli)

+### [Azure CLI](#tab/cli)

+### [Azure CLI](#tab/cli)

+### [Azure CLI](#tab/cli)

+### [Python SDK](#tab/python)

+> [!div class="op_single_selector" title1="Select the version of Azure Machine Learning you are using:"]

+# [Azure CLI](#tab/cli)

+ [!INCLUDE [cli v2](../../includes/machine-learning-cli-v2.md)]

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+Based on the task type, you can create AutoML image jobs using task specific `automl` functions.

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+In general, deep learning model performance can often improve with more data. Data augmentation is a practical technique to amplify the data size and variability of a dataset which helps to prevent overfitting and improve the modelΓÇÖs generalization ability on unseen data. Automated ML applies different data augmentation techniques based on the computer vision task, before feeding input images to the model. Currently, there's no exposed hyperparameter to control data augmentations.

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+Once you've built a baseline model, you might want to optimize model performance in order to sweep over the model algorithm and hyperparameter space. You can use the following sample config to sweep over the hyperparameters for each algorithm, choosing from a range of values for learning_rate, optimizer, lr_scheduler, etc., to generate a model with the optimal primary metric. If hyperparameter values aren't specified, then default values are used for the specified algorithm.

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+For definitions and examples of the performance charts and metrics provided for each run, see [Evaluate automated machine learning experiment results](how-to-understand-automated-ml.md#metrics-for-image-models-preview).

+Once the run completes, you can register the model that was created from the best run (configuration that resulted in the best primary metric). You can either register the model after downloading or by specifying the azureml path with corresponding jobid. Note: If you want to change the inference settings that are described below you need to download the model and change settings.json and register using the updated model folder.

+### Get the best run

+# [Azure CLI](#tab/cli)

+```yaml

+

+```

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=best_run)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=create_local_dir)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=download_model)]

+### register the model

+Register the model either using the azureml path or your locally downloaded path.

+# [Azure CLI](#tab/cli)

+```azurecli

+ az ml model create --name od-fridge-items-mlflow-model --version 1 --path azureml://jobs/$best_run/outputs/artifacts/outputs/mlflow-model/ --type mlflow_model --workspace-name [YOUR_AZURE_WORKSPACE] --resource-group [YOUR_AZURE_RESOURCE_GROUP] --subscription [YOUR_AZURE_SUBSCRIPTION]

+```

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=register_model)]

+After you register the model you want to use, you can deploy it using the managed online endpoint [deploy-managed-online-endpoint](how-to-deploy-managed-online-endpoint-sdk-v2.md)

+### Configure online endpoint

+# [Azure CLI](#tab/cli)

+```yaml

+$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json

+name: od-fridge-items-endpoint

+auth_mode: key

+```

+

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=endpoint)]

+### Create the endpoint

+Using the `MLClient` created earlier, we'll now create the Endpoint in the workspace. This command will start the endpoint creation and return a confirmation response while the endpoint creation continues.

+# [Azure CLI](#tab/cli)

+```azurecli

+az ml online-endpoint create --file .\create_endpoint.yml --workspace-name [YOUR_AZURE_WORKSPACE] --resource-group [YOUR_AZURE_RESOURCE_GROUP] --subscription [YOUR_AZURE_SUBSCRIPTION]

+```

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=create_endpoint)]

+### Configure online deployment

+A deployment is a set of resources required for hosting the model that does the actual inferencing. We'll create a deployment for our endpoint using the `ManagedOnlineDeployment` class. You can use either GPU or CPU VM SKUs for your deployment cluster.

+# [Azure CLI](#tab/cli)

+```yaml

+name: od-fridge-items-mlflow-deploy

+endpoint_name: od-fridge-items-endpoint

+model: azureml:od-fridge-items-mlflow-model@latest

+instance_type: Standard_DS3_v2

+instance_count: 1

+liveness_probe:

+ failure_threshold: 30

+ success_threshold: 1

+ timeout: 2

+ period: 10

+ initial_delay: 2000

+readiness_probe:

+ failure_threshold: 10

+ success_threshold: 1

+ timeout: 10

+ period: 10

+ initial_delay: 2000

+```

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=deploy)]

+### Create the deployment

+Using the `MLClient` created earlier, we'll now create the deployment in the workspace. This command will start the deployment creation and return a confirmation response while the deployment creation continues.

+# [Azure CLI](#tab/cli)

+```azurecli

+az ml online-deployment create --file .\create_deployment.yml --workspace-name [YOUR_AZURE_WORKSPACE] --resource-group [YOUR_AZURE_RESOURCE_GROUP] --subscription [YOUR_AZURE_SUBSCRIPTION]

+```

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=create_deploy)]

+### update traffic:

+By default the current deployment is set to receive 0% traffic. you can set the traffic percentage current deployment should receive. Sum of traffic percentages of all the deployments with one end point shouldn't exceed 100%.

+# [Azure CLI](#tab/cli)

+```azurecli

+az ml online-endpoint update --name 'od-fridge-items-endpoint' --traffic 'od-fridge-items-mlflow-deploy=100' --workspace-name [YOUR_AZURE_WORKSPACE] --resource-group [YOUR_AZURE_RESOURCE_GROUP] --subscription [YOUR_AZURE_SUBSCRIPTION]

+```

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=update_traffic)]

+Alternatively You can deploy the model from the [Azure Machine Learning studio UI](https://ml.azure.com/).

+Navigate to the model you wish to deploy in the **Models** tab of the automated ML run and select on **Deploy** and select **Deploy to real-time endpoint** .

+.

+this is how your review page looks like. we can select instance type, instance count and set traffic percentage for the current deployment.

+.

+.

+### Update inference settings

+In the previous step, we downloaded a file `mlflow-model/artifacts/settings.json` from the best model. which can be used to update the inference settings before registering the model. Although its's recommended to use the same parameters as training for best performance.

+Each of the tasks (and some models) has a set of parameters. By default, we use the same values for the parameters that were used during the training and validation. Depending on the behavior that we need when using the model for inference, we can change these parameters. Below you can find a list of parameters for each task type and model.

+| Task | Parameter name | Default |

+| |- | |

+|Image classification (multi-class and multi-label) | `valid_resize_size`<br>`valid_crop_size` | 256<br>224 |

+|Object detection | `min_size`<br>`max_size`<br>`box_score_thresh`<br>`nms_iou_thresh`<br>`box_detections_per_img` | 600<br>1333<br>0.3<br>0.5<br>100 |

+|Object detection using `yolov5`| `img_size`<br>`model_size`<br>`box_score_thresh`<br>`nms_iou_thresh` | 640<br>medium<br>0.1<br>0.5 |

+|Instance segmentation| `min_size`<br>`max_size`<br>`box_score_thresh`<br>`nms_iou_thresh`<br>`box_detections_per_img`<br>`mask_pixel_score_threshold`<br>`max_number_of_polygon_points`<br>`export_as_image`<br>`image_type` | 600<br>1333<br>0.3<br>0.5<br>100<br>0.5<br>100<br>False<br>JPG|

+For a detailed description on task specific hyperparameters, please refer to [Hyperparameters for computer vision tasks in automated machine learning](./reference-automl-images-hyperparameters.md).

+

+If you want to use tiling, and want to control tiling behavior, the following parameters are available: `tile_grid_size`, `tile_overlap_ratio` and `tile_predictions_nms_thresh`. For more details on these parameters please check [Train a small object detection model using AutoML](./how-to-use-automl-small-object-detect.md).

+## Example notebooks

+Review detailed code examples and use cases in the [GitHub notebook repository for automated machine learning samples](https://github.com/Azure/azureml-examples/tree/main/sdk/jobs/automl-standalone-jobs). Please check the folders with 'automl-image-' prefix for samples specific to building computer vision models.

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+ [!INCLUDE [cli v2](../../includes/machine-learning-cli-v2.md)]

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Studio](#tab/azure-studio)

+# [Studio](#tab/azure-studio)

+# [Studio](#tab/azure-studio)

+# [Studio](#tab/azure-studio)

+# [Studio](#tab/azure-studio)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/Python-SDK)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/Python-SDK)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/Python-SDK)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+description: Learn how your machine learning model makes predictions during training and inferencing by using the Azure Machine Learning CLI and Python SDK.

+> With the release of the Responsible AI dashboard, which includes model interpretability, we recommend that you migrate to the new experience, because the older SDK v1 preview model interpretability dashboard will no longer be actively maintained.

+## Why model interpretability is important to model debugging

+When you're using machine learning models in ways that affect peopleΓÇÖs lives, it's critically important to understand what influences the behavior of models. Interpretability helps answer questions in scenarios such as:

+* Model debugging: Why did my model make this mistake? How can I improve my model?

+* Human-AI collaboration: How can I understand and trust the modelΓÇÖs decisions?

+* Regulatory compliance: Does my model satisfy legal requirements?

+The interpretability component of the [Responsible AI dashboard](concept-responsible-ai-dashboard.md) contributes to the ΓÇ£diagnoseΓÇ¥ stage of the model lifecycle workflow by generating human-understandable descriptions of the predictions of a machine learning model. It provides multiple views into a modelΓÇÖs behavior:

+* Global explanations: For example, what features affect the overall behavior of a loan allocation model?

+* Local explanations: For example, why was a customerΓÇÖs loan application approved or rejected?

+You can also observe model explanations for a selected cohort as a subgroup of data points. This approach is valuable when, for example, you're assessing fairness in model predictions for individuals in a particular demographic group. The **Local explanation** tab of this component also represents a full data visualization, which is great for general eyeballing of the data and looking at differences between correct and incorrect predictions of each cohort.

+The capabilities of this component are founded by the [InterpretML](https://interpret.ml/) package, which generates model explanations.

+Use interpretability when you need to:

+* Determine how trustworthy your AI systemΓÇÖs predictions are by understanding what features are most important for the predictions.

+* Approach the debugging of your model by understanding it first and identifying whether the model is using healthy features or merely false correlations.

+* Uncover potential sources of unfairness by understanding whether the model is basing predictions on sensitive features or on features that are highly correlated with them.

+* Build user trust in your modelΓÇÖs decisions by generating local explanations to illustrate their outcomes.

+* Complete a regulatory audit of an AI system to validate models and monitor the impact of model decisions on humans.

+## How to interpret your model

+In machine learning, *features* are the data fields you use to predict a target data point. For example, to predict credit risk, you might use data fields for age, account size, and account age. Here, age, account size, and account age are features. Feature importance tells you how each data field affects the model's predictions. For example, although you might use age heavily in the prediction, account size and account age might not affect the prediction values significantly. Through this process, data scientists can explain resulting predictions in ways that give stakeholders visibility into the model's most important features.

+By using the classes and methods in the Responsible AI dashboard and by using SDK v2 and CLI v2, you can:

+* Explain model prediction by generating feature-importance values for the entire model (global explanation) or individual data points (local explanation).

+* Achieve model interpretability on real-world datasets at scale.

+* Use an interactive visualization dashboard to discover patterns in your data and its explanations at training time.

+By using the classes and methods in the SDK v1, you can:

+* Explain model prediction by generating feature-importance values for the entire model or individual data points.

+* Achieve model interpretability on real-world datasets at scale during training and inference.

+* Use an interactive visualization dashboard to discover patterns in your data and its explanations at training time.

+Model interpretability classes are made available through the SDK&nbsp;v1 package. For more information, see [Install SDK packages for Azure Machine Learning](/python/api/overview/azure/ml/install) and [azureml.interpret](/python/api/azureml-interpret/azureml.interpret).

+The Responsible AI dashboard and `azureml-interpret` use the interpretability techniques that were developed in [Interpret-Community](https://github.com/interpretml/interpret-community/), an open-source Python package for training interpretable models and helping to explain opaque-box AI systems. Opaque-box models are those for which we have no information about their internal workings.

+Interpret-Community serves as the host for the following supported explainers, and currently supports the interpretability techniques presented in the next sections.

+|Interpretability technique|Description|Type|

+|--|--|--|

+|Mimic Explainer (Global Surrogate) + SHAP tree|Mimic Explainer is based on the idea of training global surrogate models to mimic opaque-box models. A global surrogate model is an intrinsically interpretable model that's trained to approximate the predictions of any opaque-box model as accurately as possible.<br><br> Data scientists can interpret the surrogate model to draw conclusions about the opaque-box model. The Responsible AI dashboard uses LightGBM (LGBMExplainableModel), paired with the SHAP (SHapley Additive exPlanations) Tree Explainer, which is a specific explainer to trees and ensembles of trees. The combination of LightGBM and SHAP tree provides model-agnostic global and local explanations of your machine learning models.|Model-agnostic|

+|Interpretability technique|Description|Type|

+|--|--|--|

+|SHAP Tree Explainer| The [SHAP](https://github.com/slundberg/shap) Tree Explainer, which focuses on a polynomial, time-fast, SHAP value-estimation algorithm that's specific to *trees and ensembles of trees*.|Model-specific|

+|SHAP Deep Explainer| Based on the explanation from SHAP, Deep Explainer is a "high-speed approximation algorithm for SHAP values in deep learning models that builds on a connection with DeepLIFT described in the [SHAP NIPS paper](https://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions). *TensorFlow* models and *Keras* models using the TensorFlow back end are supported (there's also preliminary support for PyTorch)."|Model-specific|

+|SHAP Linear Explainer| The SHAP Linear Explainer computes SHAP values for a *linear model*, optionally accounting for inter-feature correlations.|Model-specific|

+|SHAP Kernel Explainer| The SHAP Kernel Explainer uses a specially weighted local linear regression to estimate SHAP values for *any model*.|Model-agnostic|

+|Mimic Explainer (Global Surrogate)| Mimic Explainer is based on the idea of training [global surrogate models](https://christophm.github.io/interpretable-ml-book/global.html) to mimic opaque-box models. A global surrogate model is an intrinsically interpretable model that's trained to approximate the predictions of *any opaque-box model* as accurately as possible. Data scientists can interpret the surrogate model to draw conclusions about the opaque-box model. You can use one of the following interpretable models as your surrogate model: LightGBM (LGBMExplainableModel), Linear Regression (LinearExplainableModel), Stochastic Gradient Descent explainable model (SGDExplainableModel), or Decision Tree (DecisionTreeExplainableModel).|Model-agnostic|

+|Permutation Feature Importance Explainer| Permutation Feature Importance (PFI) is a technique used to explain classification and regression models that's inspired by [Breiman's Random Forests paper](https://www.stat.berkeley.edu/~breiman/randomforest2001.pdf) (see section 10). At a high level, the way it works is by randomly shuffling data one feature at a time for the entire dataset and calculating how much the performance metric of interest changes. The larger the change, the more important that feature is. PFI can explain the overall behavior of *any underlying model* but doesn't explain individual predictions. |Model-agnostic|

+Besides the interpretability techniques described above, we support another SHAP-based explainer, called Tabular Explainer. Depending on the model, Tabular Explainer uses one of the supported SHAP explainers:

+* Tree Explainer for all tree-based models

+* Deep Explainer for deep neural network (DNN) models

+* Linear Explainer for linear models

+* Kernel Explainer for all other models

+Tabular Explainer has also made significant feature and performance enhancements over the direct SHAP explainers:

+* **Summarization of the initialization dataset**: When speed of explanation is most important, we summarize the initialization dataset and generate a small set of representative samples. This approach speeds up the generation of overall and individual feature importance values.

+* **Sampling the evaluation data set**: If you pass in a large set of evaluation samples but don't actually need all of them to be evaluated, you can set the sampling parameter to `true` to speed up the calculation of overall model explanations.

+The following diagram shows the current structure of supported explainers:

+The `azureml.interpret` package of the SDK supports models that are trained with the following dataset formats:

+* `numpy.array`

+* `pandas.DataFrame`

+* `iml.datatypes.DenseData`

+* `scipy.sparse.csr_matrix`

+The explanation functions accept both models and pipelines as input. If a model is provided, it must implement the prediction function `predict` or `predict_proba` that conforms to the Scikit convention. If your model doesn't support this, you can wrap it in a function that generates the same outcome as `predict` or `predict_proba` in Scikit and use that wrapper function with the selected explainer.

+If you provide a pipeline, the explanation function assumes that the running pipeline script returns a prediction. When you use this wrapping technique, `azureml.interpret` can support models that are trained via PyTorch, TensorFlow, and Keras deep learning frameworks as well as classic machine learning models.

+The `azureml.interpret` package is designed to work with both local and remote compute targets. If you run the package locally, the SDK functions won't contact any Azure services.

+You can run the explanation remotely on Azure Machine Learning Compute and log the explanation info into the Azure Machine Learning Run History Service. After this information is logged, reports and visualizations from the explanation are readily available on Azure Machine Learning studio for analysis.

+* Learn how to generate the Responsible AI dashboard via [CLI v2 and SDK v2](how-to-responsible-ai-dashboard-sdk-cli.md) or the [Azure Machine Learning studio UI](how-to-responsible-ai-dashboard-ui.md).

+* Explore the [supported interpretability visualizations](how-to-responsible-ai-dashboard.md#feature-importances-model-explanations) of the Responsible AI dashboard.

+* Learn how to generate a [Responsible AI scorecard](how-to-responsible-ai-scorecard.md) based on the insights observed in the Responsible AI dashboard.

+* Learn how to enable [interpretability for automated machine learning models](how-to-machine-learning-interpretability-automl.md).

+> [!div class="op_single_selector" title1="Select the version of Azure Machine Learning you are using:"]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ Title: Generate a Responsible AI dashboard with YAML and Python (preview)

+description: Learn how to generate a Responsible AI dashboard with Python and YAML in Azure Machine Learning.

+# Generate a Responsible AI dashboard with YAML and Python (preview)

+You can generate a Responsible AI dashboard via a pipeline job by using Responsible AI components. There are six core components for creating Responsible AI dashboards, along with a couple of helper components. Here's a sample experiment graph:

+## Get started

+- An Azure Machine Learning workspace

+- A Git installation

+### Installation steps

+1. Clone the repository:

+2. Sign in to Azure:

+3. From the repository root, run the following PowerShell setup script:

+ Running the script:

+ - Creates a new conda environment with a name you specify.

+ - Installs all the required Python packages.

+ - Registers all the Responsible AI components in your Azure Machine Learning workspace.

+ - Registers some sample datasets in your workspace.

+ - Sets the defaults for the Azure CLI to point to your workspace.

+ Running the script prompts for the desired conda environment name and Azure Machine Learning workspace details.

+ Alternatively, you can use the following Bash script:

+ This script echoes the supplied parameters, and it pauses briefly before continuing.

+The core components for constructing the Responsible AI dashboard in Azure Machine Learning are:

+- RAI Insights dashboard constructor

+ - Add Explanation to RAI Insights dashboard

+ - Add Causal to RAI Insights dashboard

+ - Add Counterfactuals to RAI Insights dashboard

+ - Add Error Analysis to RAI Insights dashboard

+ - Gather RAI Insights dashboard

+The RAI Insights dashboard constructor and Gather RAI Insights dashboard components are always required, plus at least one of the tool components. However, it isn't necessary to use all the tools in every Responsible AI dashboard.

+In the following sections are specifications of the Responsible AI components and examples of code snippets in YAML and Python. To view the full code, see [sample YAML and Python notebook](https://aka.ms/RAIsamplesProgrammer).

+- All models must be registered in Azure Machine Learning in MLflow format with a sklearn (scikit-learn) flavor.

+- The models must be supplied to the Responsible AI components by using the *fetch registered model* component, which we provide.

+- The dataset inputs must be in pandas.DataFrame.to_parquet format.

+- A model must be supplied even if only a causal analysis of the data is performed. You can use the DummyClassifier and DummyRegressor estimators from scikit-learn for this purpose.

+### RAI Insights dashboard constructor

+To generate model-debugging insights with components such as error analysis and Model explanations, use the training and test dataset that you used when you trained your model. For components like causal analysis, which doesn't require a model, you use the training dataset to train the causal model to generate the causal insights. You use the test dataset to populate your Responsible AI dashboard visualizations.

+The easiest way to supply the model is to use the fetch registered model component, which we discuss later in this article.

+> Currently, only models in MLflow format and with a sklearn flavor are supported.

+The two datasets should be file datasets (of type `uri_file`) in Parquet format. Tabular datasets aren't supported, but we provide a TabularDataset to Parquet file component to help with conversions. The training and test datasets provided don't have to be the same datasets that are used in training the model, but they can be the same. By default, for performance reasons, the test dataset is restricted to 5,000 rows of the visualization UI.

+| Parameter name | Description | Type |

+||||

+| `title` | Brief description of the dashboard. | String |

+| `task_type` | Specifies whether the model is for classification or regression. | String, `classification` or `regression` |

+| `target_column_name` | The name of the column in the input datasets, which the model is trying to predict. | String |

+| `maximum_rows_for_test_dataset` | The maximum number of rows allowed in the test dataset, for performance reasons. | Integer, defaults to 5,000 |

+| `categorical_column_names` | The columns in the datasets, which represent categorical data. | Optional list of strings¹ |

+| `classes` | The full list of class labels in the training dataset. | Optional list of strings¹ |

+¹ The lists should be supplied as a single JSON-encoded string for `categorical_column_names` and `classes` inputs.

+The constructor component has a single output named `rai_insights_dashboard`. This is an empty dashboard, which the individual tool components operate on. All the results are assembled by the Gather RAI Insights dashboard component at the end.

+#Then inside the pipeline:

+### Export pre-built cohorts for scorecard generation

+You can export pre-built cohorts for use in scorecard generation. For example, here are building cohorts in a Jupyter Notebook: [responsibleaidashboard-diabetes-decision-making.ipynb](https://github.com/microsoft/responsible-ai-toolbox/blob/main/notebooks/responsibleaidashboard/responsibleaidashboard-diabetes-decision-making.ipynb). After you've defined a cohort, you can export it to a JSON file, as shown here:

+A sample generated JSON string is shown here:

+### Add Causal to RAI Insights dashboard

+This component performs a causal analysis on the supplied datasets. It has a single input port, which accepts the output of the RAI Insights dashboard constructor. It also accepts the following parameters:

+| Parameter name | Description | Type&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |

+||||

+| `treatment_features` | A list of feature names in the datasets, which are potentially "treatable" to obtain different outcomes. | List of strings². |

+| `heterogeneity_features` | A list of feature names in the datasets, which might affect how the "treatable" features behave. By default, all features will be considered. | Optional list of strings².|

+| `nuisance_model` | The model used to estimate the outcome of changing the treatment features. | Optional string. Must be `linear` or `AutoML`, defaulting to `linear`. |

+| `heterogeneity_model` | The model used to estimate the effect of the heterogeneity features on the outcome. | Optional string. Must be `linear` or `forest`, defaulting to `linear`. |

+| `alpha` | Confidence level of confidence intervals. | Optional floating point number, defaults to 0.05. |

+| `upper_bound_on_cat_expansion` | The maximum expansion of categorical features. | Optional integer, defaults to 50. |

+| `treatment_cost` | The cost of the treatments. If 0, all treatments will have zero cost. If a list is passed, each element is applied to one of the `treatment_features`.<br><br>Each element can be a scalar value to indicate a constant cost of applying that treatment or an array indicating the cost for each sample. If the treatment is a discrete treatment, the array for that feature should be two dimensional, with the first dimension representing samples and the second representing the difference in cost between the non-default values and the default value. | Optional integer or list².|

+| `min_tree_leaf_samples` | The minimum number of samples per leaf in the policy tree. | Optional integer, defaults to 2. |

+| `max_tree_depth` | The maximum depth of the policy tree. | Optional integer, defaults to 2. |

+| `skip_cat_limit_checks` | By default, categorical features need to have several instances of each category in order for a model to be fit robustly. Setting this to `True` will skip these checks. |Optional Boolean, defaults to `False`. |

+| `categories` | The categories to use for the categorical columns. If `auto`, the categories will be inferred for all categorical columns. Otherwise, this argument should have as many entries as there are categorical columns.<br><br>Each entry should be either `auto` to infer the values for that column or the list of values for the column. If explicit values are provided, the first value is treated as the "control" value for that column against which other values are compared. | Optional, `auto` or list². |

+| `n_jobs` | The degree of parallelism to use. | Optional integer, defaults to 1. |

+| `verbose` | Expresses whether to provide detailed output during the computation. | Optional integer, defaults to 1. |

+| `random_state` | Seed for the pseudorandom number generator (PRNG). | Optional integer. |

+² For the `list` parameters: Several of the parameters accept lists of other types (strings, numbers, even other lists). To pass these into the component, they must first be JSON-encoded into a single string.

+This component has a single output port, which can be connected to one of the `insight_[n]` input ports of the Gather RAI Insights dashboard component.

+### Add Counterfactuals to RAI Insights dashboard

+This component generates counterfactual points for the supplied test dataset. It has a single input port, which accepts the output of the RAI Insights dashboard constructor. It also accepts the following parameters:

+| Parameter name | Description | Type |

+||||

+| `total_CFs` | The number of counterfactual points to generate for each row in the test dataset. | Optional integer, defaults to 10. |

+| `method` | The `dice-ml` explainer to use. | Optional string. Either `random`, `genetic`, or `kdtree`. Defaults to `random`. |

+| `desired_class` | Index identifying the desired counterfactual class. For binary classification, this should be set to `opposite`. | Optional string or integer. Defaults to 0. |

+| `desired_range` | For regression problems, identify the desired range of outcomes. | Optional list of two numbers³. |

+| `permitted_range` | Dictionary with feature names as keys and the permitted range in a list as values. Defaults to the range inferred from training data. | Optional string or list³.|

+| `features_to_vary` | Either a string `all` or a list of feature names to vary. | Optional string or list³.|

+| `feature_importance` | Flag to enable computation of feature importances by using `dice-ml`. |Optional Boolean. Defaults to `True`. |

+³ For the non-scalar parameters: Parameters that are lists or dictionaries should be passed as single JSON-encoded strings.

+This component has a single output port, which can be connected to one of the `insight_[n]` input ports of the Gather RAI Insights dashboard component.

+### Add Error Analysis to RAI Insights dashboard

+This component generates an error analysis for the model. It has a single input port, which accepts the output of the RAI Insights dashboard constructor. It also accepts the following parameters:

+| Parameter name | Description | Type |

+||||

+| `max_depth` | The maximum depth of the error analysis tree. | Optional integer. Defaults to 3. |

+| `num_leaves` | The maximum number of leaves in the error tree. | Optional integer. Defaults to 31. |

+| `min_child_samples` | The minimum number of datapoints required to produce a leaf. | Optional integer. Defaults to 20. |

+| `filter_features` | A list of one or two features to use for the matrix filter. | Optional list, to be passed as a single JSON-encoded string. |

+This component has a single output port, which can be connected to one of the `insight_[n]` input ports of the Gather RAI Insights dashboard component.

+### Add Explanation to RAI Insights dashboard

+This component generates an explanation for the model. It has a single input port, which accepts the output of the RAI Insights dashboard constructor. It accepts a single, optional comment string as a parameter.

+This component has a single output port, which can be connected to one of the `insight_[n]` input ports of the Gather RAI Insights dashboard component.

+### Gather RAI Insights dashboard

+- The `constructor` port that must be connected to the RAI Insights dashboard constructor component.

+There are two output ports:

+- The `dashboard` port contains the completed `RAIInsights` object.

+- The `ux_json` port contains the data required to display a minimal dashboard.

+This component produces information about a registered model, which can be consumed by the `model_info_path` input port of the RAI Insights dashboard constructor component. It has a single input parameter: the Azure Machine Learning ID (`<NAME>:<VERSION>`) of the desired model.

+This component converts the tabular dataset named in its sole input parameter into a Parquet file, which can be consumed by the `train_dataset` and `test_dataset` input ports of the RAI Insights dashboard constructor component. Its single input parameter is the name of the desired dataset.

+The model must be in the MLflow directory with a sklearn flavor available. Additionally, the model needs to be loadable in the environment that's used by the Responsible AI components.

+The supplied datasets should be file datasets (of type `uri_file`) in Parquet format. We provide the `TabularDataset to Parquet File` component to help convert the data into the required format.

+- After you've generated your Responsible AI dashboard, [view how to access and use it in Azure Machine Learning studio](how-to-responsible-ai-dashboard.md).

+- Learn more about the [concepts and techniques behind the Responsible AI dashboard](concept-responsible-ai-dashboard.md).

+- Learn more about how to [collect data responsibly](concept-sourcing-human-data.md).

+- View [sample YAML and Python notebooks](https://aka.ms/RAIsamples) to generate the Responsible AI dashboard with YAML or Python.

+- Learn more about how to use the Responsible AI dashboard and scorecard to debug data and models and inform better decision-making in this [tech community blog post](https://www.microsoft.com/ai/ai-lab-responsible-ai-dashboard).

+- Learn about how the Responsible AI dashboard and scorecard were used by the UK National Health Service (NHS) in a [real life customer story](https://aka.ms/NHSCustomerStory).

+- Explore the features of the Responsible AI dashboard through this [interactive AI lab web demo](https://www.microsoft.com/ai/ai-lab-responsible-ai-dashboard).

+ Title: Generate a Responsible AI dashboard (preview) in the studio UI

+description: Learn how to generate a Responsible AI dashboard with no-code experience in the Azure Machine Learning studio UI.

+# Generate a Responsible AI dashboard (preview) in the studio UI

+In this article, you create a Responsible AI dashboard with a no-code experience in the [Azure Machine Learning studio UI](https://ml.azure.com/). To access the dashboard generation wizard, do the following:

+1. [Register your model](how-to-manage-models.md) in Azure Machine Learning so that you can access the no-code experience.

+1. On the left pane of Azure Machine Learning studio, select the **Models** tab.

+1. Select the registered model that you want to create Responsible AI insights for, and then select the **Details** tab.

+1. Select **Create Responsible AI dashboard (preview)**.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard-ui/model-page.png" alt-text="Screenshot of the wizard details pane with 'Create Responsible AI dashboard (preview)' tab highlighted." lightbox ="./media/how-to-responsible-ai-dashboard-ui/model-page.png":::

+To learn more, see the Responsible AI dashboard [supported model types and limitations](concept-responsible-ai-dashboard.md#supported-scenarios-and-limitations).

+The wizard provides an interface for entering all the necessary parameters to create your Responsible AI dashboard without having to touch code. The experience takes place entirely in the Azure Machine Learning studio UI. The studio presents a guided flow and instructional text to help contextualize the variety of choices about which Responsible AI components youΓÇÖd like to populate your dashboard with.

+The wizard is divided into five sections:

+1. Modeling task

+1. Dashboard components

+1. Component parameters

+1. Experiment configuration

+In the first section, you select the train and test datasets that you used when you trained your model to generate model-debugging insights. For components like causal analysis, which doesn't require a model, you use the train dataset to train the causal model to generate the causal insights.

+1. **Select a dataset for training**: In the dropdown list of registered datasets in the Azure Machine Learning workspace, select the dataset you want to use to generate Responsible AI insights for components, such as model explanations and error analysis.

+1. **Select a dataset for testing**: In the dropdown list, select the dataset you want to use to populate your Responsible AI dashboard visualizations.

+1. If the train or test dataset you want to use isn't listed, select **New dataset** to upload it.

+After you've picked your datasets, select your modeling task type, as shown in the following image:

+> The wizard supports only models in MLflow format and with a sklearn (scikit-learn) flavor.

+The Responsible AI dashboard offers two profiles for recommended sets of tools that you can generate:

+- **Model debugging**: Understand and debug erroneous data cohorts in your machine learning model by using error analysis, counterfactual what-if examples, and model explainability.

+- **Real-life interventions**: Understand and debug erroneous data cohorts in your machine learning model by using causal analysis.

+ > [!NOTE]

+ > Multi-class classification doesn't support the real-life interventions analysis profile.

+1. Select the profile you want to use.

+1. Select **Next**.

+After youΓÇÖve selected a profile, the **Component parameters for model debugging** configuration pane for the corresponding components appears.

+1. **Target feature (required)**: Specify the feature that your model was trained to predict.

+1. **Categorical features**: Indicate which features are categorical to properly render them as categorical values in the dashboard UI. This field is pre-loaded for you based on your dataset metadata.

+1. **Generate error tree and heat map**: Toggle on and off to generate an error analysis component for your Responsible AI dashboard.

+1. **Features for error heat map**: Select up to two features that you want to pre-generate an error heatmap for.

+1. **Advanced configuration**: Specify additional parameters, such as **Maximum depth of error tree**, **Number of leaves in error tree**, and **Minimum number of samples in each leaf node**.

+1. **Generate counterfactual what-if examples**: Toggle on and off to generate a counterfactual what-if component for your Responsible AI dashboard.

+1. **Number of counterfactuals (required)**: Specify the number of counterfactual examples that you want generated per data point. A minimum of 10 should be generated to enable a bar chart view of the features that were most perturbed, on average, to achieve the desired prediction.

+1. **Range of value predictions (required)**: Specify for regression scenarios the range that you want counterfactual examples to have prediction values in. For binary classification scenarios, the range will automatically be set to generate counterfactuals for the opposite class of each data point. For multi-classification scenarios, use the dropdown list to specify which class you want each data point to be predicted as.

+1. **Specify which features to perturb**: By default, all features will be perturbed. However, if you want only specific features to be perturbed, select **Specify which features to perturb for generating counterfactual explanations** to display a pane with a list of features to select.

+ When you select **Specify which features to perturb**, you can specify the range you want to allow perturbations in. For example: for the feature YOE (Years of experience), specify that counterfactuals should have feature values ranging from only 10 to 21 instead of the default values of 5 to 21.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard-ui/model-debug-counterfactuals.png" alt-text="Screenshot of the wizard, showing a pane of features you can specify to perturb." lightbox = "./media/how-to-responsible-ai-dashboard-ui/model-debug-counterfactuals.png":::

+1. **Generate explanations**: Toggle on and off to generate a model explanation component for your Responsible AI dashboard. No configuration is necessary, because a default opaque box mimic explainer will be used to generate feature importances.

+Alternatively, if you select the **Real-life interventions** profile, youΓÇÖll see the following screen generate a causal analysis. This will help you understand the causal effects of features you want to ΓÇ£treatΓÇ¥ on a certain outcome you want to optimize.

+Component parameters for real-life interventions use causal analysis. Do the following:

+1. **Treatment features (required)**: Choose one or more features that youΓÇÖre interested in changing (ΓÇ£treatingΓÇ¥) to optimize the target outcome.

+1. **Categorical features**: Indicate which features are categorical to properly render them as categorical values in the dashboard UI. This field is pre-loaded for you based on your dataset metadata.

+1. **Advanced settings**: Specify additional parameters for your causal analysis, such as heterogenous features (that is, additional features to understand causal segmentation in your analysis, in addition to your treatment features) and which causal model you want to be used.

+## Configure your experiment

+On the **Training job or experiment configuration** pane, do the following:

+1. **Experiment name**: Select an existing experiment to run the job in, or create a new experiment.

+1. **Existing experiment**: In the dropdown list, select an existing experiment.

+1. **Select compute type**: Specify which compute type you want to use to execute your job.

+1. **Select compute**: In the dropdown list, select the compute you want to use. If there are no existing compute resources, select the plus sign (**+**), create a new compute resource, and then refresh the list.

+1. **Description**: Add a longer description of your Responsible AI dashboard.

+1. **Tags**: Add any tags to this Responsible AI dashboard.

+After youΓÇÖve finished configuring your experiment, select **Create** to start generating your Responsible AI dashboard. You'll be redirected to the experiment page to track the progress of your job.

+In the "Next steps" section, you can learn how to view and use your Responsible AI dashboard.

+- After you've generated your Responsible AI dashboard, [view how to access and use it in Azure Machine Learning studio](how-to-responsible-ai-dashboard.md).

+- Learn more about how to [collect data responsibly](concept-sourcing-human-data.md).

+- Learn more about how to use the Responsible AI dashboard and scorecard to debug data and models and inform better decision-making in this [tech community blog post](https://www.microsoft.com/ai/ai-lab-responsible-ai-dashboard).

+- Learn about how the Responsible AI dashboard and scorecard were used by the UK National Health Service (NHS) in a [real life customer story](https://aka.ms/NHSCustomerStory).

+- Explore the features of the Responsible AI dashboard through this [interactive AI Lab web demo](https://www.microsoft.com/ai/ai-lab-responsible-ai-dashboard).

+ Title: Use the Responsible AI dashboard in Azure Machine Learning studio (preview)

+description: Learn how to use the various tools and visualization charts in the Responsible AI dashboard in Azure Machine Learning.

+# Use the Responsible AI dashboard (preview) in Azure Machine Learning studio

+Responsible AI dashboards are linked to your registered models. To view your Responsible AI dashboard, go into your model registry and select the registered model you've generated a Responsible AI dashboard for. Then, select the **Responsible AI (preview)** tab to view a list of generated dashboards.

+You can configure multiple dashboards and attach them to your registered model. Various combinations of components (interpretability, error analysis, causal analysis, and so on) can be attached to each Responsible AI dashboard. The following image displays a dashboard's customization and the components that were generated within it. In each dashboard, you can view or hide various components within the dashboard UI itself.

+Select the name of the dashboard to open it into a full view in your browser. To return to your list of dashboards, you can select **Back to models details** at any time.

+Some features of the Responsible AI dashboard require dynamic, on-the-fly, and real-time computation (for example, what-if analysis). Unless you connect a compute resource to the dashboard, you might find some functionality missing. When you connect to a compute resource, you enable full functionality of your Responsible AI dashboard for the following components:

+ - Dynamically updating the heat map for up to two features is supported.

+ - Generating a new what-if counterfactual data point to understand the minimum change required for a desired outcome is supported.

+ - Selecting any individual data point, perturbing its treatment features, and seeing the expected causal outcome of causal what-if is supported (only for regression machine learning scenarios).

+You can also find this information on the Responsible AI dashboard page by selecting the **Information** icon, as shown in the following image:

+### Enable full functionality of the Responsible AI dashboard

+1. Select a running compute instance in the **Compute** dropdown list at the top of the dashboard. If you donΓÇÖt have a running compute, create a new compute instance by selecting the plus sign (**+**) next to the dropdown. Or you can select the **Start compute** button to start a stopped compute instance. Creating or starting a compute instance might take few minutes.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/select-compute.png" alt-text="Screenshot of the 'Compute' dropdown box for selecting a running compute instance." lightbox = "./media/how-to-responsible-ai-dashboard/select-compute.png":::

+2. When a compute is in a *Running* state, your Responsible AI dashboard starts to connect to the compute instance. To achieve this, a terminal process is created on the selected compute instance, and a Responsible AI endpoint is started on the terminal. Select **View terminal outputs** to view the current terminal process.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/compute-connect-terminal.png" alt-text="Screenshot showing that the responsible AI dashboard is connecting to a compute resource." lightbox = "./media/how-to-responsible-ai-dashboard/compute-connect-terminal.png":::

+4. If the process takes a while and your Responsible AI dashboard is still not connected to the compute instance, or a red error message bar is displayed, it means there are issues with starting your Responsible AI endpoint. Select **View terminal outputs** and scroll down to the bottom to view the error message.

+ If you're having difficulty figuring out how to resolve the "failed to connect to compute instance" issue, select the **Smile** icon at the upper right. Submit feedback to us about any error or issue you encounter. You can include a screenshot and your email address in the feedback form.

+The Responsible AI dashboard includes a robust, rich set of visualizations and functionality to help you analyze your machine learning model or make data-driven business decisions:

+- [Feature importance (model explanations)](#feature-importances-model-explanations)

+At the top of the dashboard, you can create cohorts (subgroups of data points that share specified characteristics) to focus your analysis of each component. The name of the cohort that's currently applied to the dashboard is always shown at the top left of your dashboard. The default view in your dashboard is your whole dataset, titled **All data (default)**.

+1. **Cohort settings**: Allows you to view and modify the details of each cohort in a side panel.

+2. **Dashboard configuration**: Allows you to view and modify the layout of the overall dashboard in a side panel.

+3. **Switch cohort**: Allows you to select a different cohort and view its statistics in a pop-up window.

+4. **New cohort**: Allows you to create and add a new cohort to your dashboard.

+Select **Cohort settings** to open a panel with a list of your cohorts, where you can create, edit, duplicate, or delete them.

+Select **New cohort** at the top of the dashboard or in the Cohort settings to open a new panel with options to filter on the following:

+1. **Index**: Filters by the position of the data point in the full dataset.

+2. **Dataset**: Filters by the value of a particular feature in the dataset.

+3. **Predicted Y**: Filters by the prediction made by the model.

+4. **True Y**: Filters by the actual value of the target feature.

+5. **Error (regression)**: Filters by error (or **Classification Outcome (classification)**: Filters by type and accuracy of classification).

+6. **Categorical Values**: Filter by a list of values that should be included.

+7. **Numerical Values**: Filter by a Boolean operation over the values (for example, select data points where age < 64).

+You can name your new dataset cohort, select **Add filter** to add each filter you want to use, and then do either of the following:

+* Select **Save** to save the new cohort to your cohort list.

+* Select **Save and switch** to save and immediately switch the global cohort of the dashboard to the newly created cohort.

+Select **Dashboard configuration** to open a panel with a list of the components youΓÇÖve configured on your dashboard. You can hide components on your dashboard by selecting the **Trash** icon, as shown in the following image:

+You can add components back to your dashboard via the blue circular plus sign (**+**) icon in the divider between each component, as shown in the following image:

+The next sections cover how to interpret and use error tree maps and heat maps.

+The first pane of the error analysis component is a tree map, which illustrates how model failure is distributed across various cohorts with a tree visualization. Select any node to see the prediction path on your features where an error was found.

+1. **Heat map view**: Switches to heat map visualization of error distribution.

+2. **Feature list:** Allows you to modify the features used in the heat map using a side panel.

+3. **Error coverage**: Displays the percentage of all error in the dataset concentrated in the selected node.

+4. **Error (regression) or Error rate (classification)**: Displays the error or percentage of failures of all the data points in the selected node.

+5. **Node**: Represents a cohort of the dataset, potentially with filters applied, and the number of errors out of the total number of data points in the cohort.

+6. **Fill line**: Visualizes the distribution of data points into child cohorts based on filters, with the number of data points represented through line thickness.

+7. **Selection information**: Contains information about the selected node in a side panel.

+8. **Save as a new cohort:** Creates a new cohort with the specified filters.

+9. **Instances in the base cohort**: Displays the total number of points in the entire dataset and the number of correctly and incorrectly predicted points.

+10. **Instances in the selected cohort**: Displays the total number of points in the selected node and the number of correctly and incorrectly predicted points.

+11. **Prediction path (filters)**: Lists the filters placed over the full dataset to create this smaller cohort.

+Select the **Feature list** button to open a side panel, from which you can retrain the error tree on specific features.

+1. **Search features**: Allows you to find specific features in the dataset.

+2. **Features**: Lists the name of the feature in the dataset.

+3. **Importances**: A guideline for how related the feature might be to the error. Calculated via mutual information score between the feature and the error on the labels. You can use this score to help you decide which features to choose in the error analysis.

+4. **Check mark**: Allows you to add or remove the feature from the tree map.

+7. **Minimum number of samples in one leaf**: The minimum amount of data required to create one leaf.

+Select the **Heat map** tab to switch to a different view of the error in the dataset. You can select one or many heat map cells and create new cohorts. You can choose up to two features to create a heat map.

+1. **Cells**: Displays the number of cells selected.

+2. **Error coverage**: Displays the percentage of all errors concentrated in the selected cell(s).

+3. **Error rate**: Displays the percentage of failures of all data points in the selected cell(s).

+4. **Axis features**: Selects the intersection of features to display in the heat map.

+5. **Cells**: Represents a cohort of the dataset, with filters applied, and the percentage of errors out of the total number of data points in the cohort. A blue outline indicates selected cells, and the darkness of red represents the concentration of failures.

+6. **Prediction path (filters)**: Lists the filters placed over the full dataset for each selected cohort.

+The model overview component provides a comprehensive set of performance and fairness metrics for evaluating your model, along with key performance disparity metrics along specified features and dataset cohorts.

+On the **Dataset cohorts** pane, you can investigate your model by comparing the model performance of various user-specified dataset cohorts (accessible via the **Cohort settings** icon at the top right of the dashboard).

+1. **Help me choose metrics**: Select this icon to open a panel with more information about what model performance metrics are available to be shown in the table. Easily adjust which metrics to view by using the multi-select dropdown list to select and deselect performance metrics.

+2. **Show heat map**: Toggle on and off to show or hide heat map visualization in the table. The gradient of the heat map corresponds to the range normalized between the lowest value and the highest value in each column.

+3. **Table of metrics for each dataset cohort**: View columns of dataset cohorts, the sample size of each cohort, and the selected model performance metrics for each cohort.

+4. **Bar chart visualizing individual metric**: View mean absolute error across the cohorts for easy comparison.

+5. **Choose metric (x-axis)**: Select this button to choose which metrics to view in the bar chart.

+6. **Choose cohorts (y-axis)**: Select this button to choose which cohorts to view in the bar chart. **Feature cohort** selection might be disabled unless you first specify the features you want on the **Feature cohort tab** of the component.

+Select **Help me choose metrics** to open a panel with a list of model performance metrics and their definitions, which can help you select the right metrics to view.

+| Machine learning scenario | Metrics |

+|||

+| Regression | Mean absolute error, Mean squared error, R-squared, Mean prediction. |

+| Classification | Accuracy, Precision, Recall, F1 score, False positive rate, False negative rate, Selection rate. |

+Classification scenarios support accuracy scores, precision scores, recall, false positive rate, false negative rate, and selection rate (the percentage of predictions with label 1):

+Regression scenarios support mean absolute error, mean squared error, and mean prediction:

+On the **Feature cohorts** pane, you can investigate your model by comparing model performance across user-specified sensitive and non-sensitive features (for example, performance across various gender, race, and income level cohorts).

+1. **Help me choose metrics**: Select this icon to open a panel with more information about what metrics are available to be shown in the table. Easily adjust which metrics to view by using the multi-select dropdown to select and deselect performance metrics.

+2. **Help me choose features**: Select this icon to open a panel with more information about what features are available to be shown in the table, with descriptors of each feature and their binning capability (see below). Easily adjust which features to view by using the multi-select dropdown to select and deselect them.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/model-overview-choose-features.png" alt-text="Screenshot of the dashboard 'Model overview' pane, showing how to choose features." lightbox= "./media/how-to-responsible-ai-dashboard/model-overview-choose-features.png":::

+3. **Show heat map**: Toggle on and off to see a heat map visualization. The gradient of the heat map corresponds to the range that's normalized between the lowest value and the highest value in each column.

+4. **Table of metrics for each feature cohort**: A table with columns for feature cohorts (sub-cohort of your selected feature), sample size of each cohort, and the selected model performance metrics for each feature cohort.

+5. **Fairness metrics/disparity metrics**: A table that corresponds to the metrics table and shows the maximum difference or maximum ratio in performance scores between any two feature cohorts.

+6. **Bar chart visualizing individual metric**: View mean absolute error across the cohorts for easy comparison.

+7. **Choose cohorts (y-axis)**: Select this button to choose which cohorts to view in the bar chart.

+ Selecting **Choose cohorts** opens a panel with an option to either show a comparison of selected dataset cohorts or feature cohorts, depending on what you select in the multi-select dropdown list below it. Select **Confirm** to save the changes to the bar chart view.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/model-overview-choose-cohorts.png" alt-text="Screenshot of the dashboard 'Model overview' pane, showing how to choose cohorts." lightbox= "./media/how-to-responsible-ai-dashboard/model-overview-choose-cohorts.png":::

+8. **Choose metric (x-axis)**: Select this button to choose which metric to view in the bar chart.

+With the data explorer component, you can analyze data statistics along the x-axis and y-axis by using filters such as predicted outcome, dataset features, and error groups. This component helps you understand overrepresentation and underrepresentation in your dataset.

+2. **X-axis**: Displays the type of value being plotted horizontally. Modify the values by selecting the button to open a side panel.

+3. **Y-axis**: Displays the type of value being plotted vertically. Modify the values by selecting the button to open a side panel.

+4. **Chart type**: Specifies the chart type. Choose between aggregate plots (bar charts) or individual data points (scatter plot).

+ By selecting the **Individual data points** option under **Chart type**, you can shift to a disaggregated view of the data with the availability of a color axis.

+By using the model explanation component, you can see which features were most important in your modelΓÇÖs predictions. You can view what features affected your modelΓÇÖs prediction overall on the **Aggregate feature importance** pane or view feature importances for individual data points on the **Individual feature importance** pane.

+1. **Top k features**: Lists the most important global features for a prediction and allows you to change it by using a slider bar.

+2. **Aggregate feature importance**: Visualizes the weight of each feature in influencing model decisions across all predictions.

+3. **Sort by**: Allows you to select which cohort's importances to sort the aggregate feature importance graph by.

+4. **Chart type**: Allows you to select between a bar plot view of average importances for each feature and a box plot of importances for all data.

+ When you select one of the features in the bar plot, the dependence plot is populated, as shown in the following image. The dependence plot shows the relationship of the values of a feature to its corresponding feature importance values, which affect the model prediction.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/aggregate-feature-importance-2.png" alt-text="Screenshot of the dashboard, showing a populated dependence plot on the 'Aggregate feature importances' pane." lightbox="./media/how-to-responsible-ai-dashboard/aggregate-feature-importance-2.png":::

+5. **Feature importance of [feature] (regression) or Feature importance of [feature] on [predicted class] (classification)**: Plots the importance of a particular feature across the predictions. For regression scenarios, the importance values are in terms of the output, so positive feature importance means it contributed positively toward the output. The opposite applies to negative feature importance. For classification scenarios, positive feature importances mean that feature value is contributing toward the predicted class denoted in the y-axis title. Negative feature importance means it's contributing against the predicted class.

+6. **View dependence plot for**: Selects the feature whose importances you want to plot.

+7. **Select a dataset cohort**: Selects the cohort whose importances you want to plot.

+The following image illustrates how features influence the predictions that are made on specific data points. You can choose up to five data points to compare feature importances for.

+**Point selection table**: View your data points and select up to five points to display in the feature importance plot or the ICE plot below the table.

+**Feature importance plot**: A bar plot of the importance of each feature for the model's prediction on the selected data points.

+1. **Top k features**: Allows you to specify the number of features to show importances for by using a slider.

+2. **Sort by**: Allows you to select the point (of those checked above) whose feature importances are displayed in descending order on the feature importance plot.

+3. **View absolute values**: Toggle on to sort the bar plot by the absolute values. This allows you to see the most impactful features regardless of their positive or negative direction.

+4. **Bar plot**: Displays the importance of each feature in the dataset for the model prediction of the selected data points.

+**Individual conditional expectation (ICE) plot**: Switches to the ICE plot, which shows model predictions across a range of values of a particular feature.

+- **Min (numerical features)**: Specifies the lower bound of the range of predictions in the ICE plot.

+- **Max (numerical features)**: Specifies the upper bound of the range of predictions in the ICE plot.

+- **Steps (numerical features)**: Specifies the number of points to show predictions for within the interval.

+- **Feature values (categorical features)**: Specifies which categorical feature values to show predictions for.

+- **Feature**: Specifies the feature to make predictions for.

+Counterfactual analysis provides a diverse set of *what-if* examples generated by changing the values of features minimally to produce the desired prediction class (classification) or range (regression).

+1. **Point selection**: Selects the point to create a counterfactual for and display in the top-ranking features plot below it.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/counterfactuals-top-ranked-features.png" alt-text="Screenshot of the dashboard, showing a top ranked features plot." lightbox="./media/how-to-responsible-ai-dashboard/counterfactuals-top-ranked-features.png":::

+ **Top ranked features plot**: Displays, in descending order of average frequency, the features to perturb to create a diverse set of counterfactuals of the desired class. You must generate at least 10 diverse counterfactuals per data point to enable this chart, because there's a lack of accuracy with a lesser number of counterfactuals.

+2. **Selected data point**: Performs the same action as the point selection in the table, except in a dropdown menu.

+3. **Desired class for counterfactual(s)**: Specifies the class or range to generate counterfactuals for.

+4. **Create what-if counterfactual**: Opens a panel for counterfactual what-if data point creation.

+ Select the **Create what-if counterfactual** button to open a full window panel.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/counterfactuals-examples.png" alt-text="Screenshot of the dashboard, showing what-if counterfactuals." lightbox="./media/how-to-responsible-ai-dashboard/counterfactuals-examples.png":::

+5. **Search features**: Finds features to observe and change values.

+6. **Sort counterfactual by ranked features**: Sorts counterfactual examples in order of perturbation effect. (Also see **Top ranked features plot**, discussed earlier.)

+7. **Counterfactual examples**: Lists feature values of example counterfactuals with the desired class or range. The first row is the original reference data point. Select **Set value** to set all the values of your own counterfactual data point in the bottom row with the values of the pre-generated counterfactual example.

+8. **Predicted value or class**: Lists the model prediction of a counterfactual's class given those changed features.

+9. **Create your own counterfactual**: Allows you to perturb your own features to modify the counterfactual. Features that have been changed from the original feature value are denoted by the title being bolded (for example, Employer and Programming language). Select **See prediction delta** to view the difference in the new prediction value from the original data point.

+10. **What-if counterfactual name**: Allows you to name the counterfactual uniquely.

+11. **Save as new data point**: Saves the counterfactual you've created.

+Select the **Aggregate causal effects** tab of the causal analysis component to display the average causal effects for pre-defined treatment features (the features that you want to treat to optimize your outcome).

+1. **Direct aggregate causal effect table**: Displays the causal effect of each feature aggregated on the entire dataset and associated confidence statistics.

+ * **Continuous treatments**: On average in this sample, increasing this feature by one unit will cause the probability of class to increase by X units, where X is the causal effect.

+ * **Binary treatments**: On average in this sample, turning on this feature will cause the probability of class to increase by X units, where X is the causal effect.

+1. **Direct aggregate causal effect whisker plot**: Visualizes the causal effects and confidence intervals of the points in the table.

+To get a granular view of causal effects on an individual data point, switch to the **Individual causal what-if** tab.

+1. **X-axis**: Selects the feature to plot on the x-axis.

+2. **Y-axis**: Selects the feature to plot on the y-axis.

+3. **Individual causal scatter plot**: Visualizes points in the table as a scatter plot to select data points for analyzing causal what-if and viewing the individual causal effects below it.

+4. **Set new treatment value**:

+ * **(numerical)**: Shows a slider to change the value of the numerical feature as a real-world intervention.

+ * **(categorical)**: Shows a dropdown list to select the value of the categorical feature.

+Select the **Treatment policy** tab to switch to a view to help determine real-world interventions and show treatments to apply to achieve a particular outcome.

+1. **Set treatment feature**: Selects a feature to change as a real-world intervention.

+2. **Recommended global treatment policy**: Displays recommended interventions for data cohorts to improve the target feature value. The table can be read from left to right, where the segmentation of the dataset is first in rows and then in columns. For example, for 658 individuals whose employer isn't Snapchat and whose programming language isn't JavaScript, the recommended treatment policy is to increase the number of GitHub repos contributed to.

+ **Average gains of alternative policies over always applying treatment**: Plots the target feature value in a bar chart of the average gain in your outcome for the above recommended treatment policy versus always applying treatment.

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/causal-treatment-policy-2.png" alt-text="Screenshot of the dashboard showing a bar chart of the average gains of alternative policies over always applying treatment on the treatment policy tab." lightbox= "./media/how-to-responsible-ai-dashboard/causal-treatment-policy-2.png":::

+ **Recommended individual treatment policy**:

+ :::image type="content" source="./media/how-to-responsible-ai-dashboard/causal-treatment-policy-3.png" alt-text="Screenshot of the dashboard showing a recommended individual treatment policy table on the treatment policy tab." lightbox= "./media/how-to-responsible-ai-dashboard/causal-treatment-policy-3.png":::

+3. **Show top k data point samples ordered by causal effects for recommended treatment feature**: Selects the number of data points to show in the table.

+4. **Recommended individual treatment policy table**: Lists, in descending order of causal effect, the data points whose target features would be most improved by an intervention.

+- Learn more about the [concepts and techniques behind the Responsible AI dashboard](concept-responsible-ai-dashboard.md).

+- Explore the features of the Responsible AI dashboard through this [interactive AI lab web demo](https://www.microsoft.com/ai/ai-lab-responsible-ai-dashboard).

+- Learn more about how you can use the Responsible AI dashboard and scorecard to debug data and models and inform better decision-making in this [tech community blog post](https://www.microsoft.com/ai/ai-lab-responsible-ai-dashboard).

+- Learn about how the Responsible AI dashboard and scorecard were used by the UK National Health Service (NHS) in a [real-life customer story](https://aka.ms/NHSCustomerStory).

+ Title: Share insights with a Responsible AI scorecard (preview)

+# Share insights with a Responsible AI scorecard (preview)

+An Azure Machine Learning Responsible AI scorecard is a PDF report that's generated based on Responsible AI dashboard insights and customizations to accompany your machine learning models. You can easily configure, download, and share your PDF scorecard with your technical and non-technical stakeholders to educate them about your data and model health and compliance, and to help build trust. You can also use the scorecard in audit reviews to inform the stakeholders about the characteristics of your model.

+## Why a Responsible AI scorecard?

+The Responsible AI dashboard is designed for machine learning professionals and data scientists to explore and evaluate model insights and inform their data-driven decisions. Though the dashboard can help you implement Responsible AI practically in your machine learning lifecycle, there are some needs left unaddressed:

+- There often exists a gap between the technical Responsible AI tools (designed for machine learning professionals) and the ethical, regulatory, and business requirements that define the production environment.

+- Although an end-to-end machine learning lifecycle keeps both technical and non-technical stakeholders in the loop, there's very little support to enable an effective multi-stakeholder alignment where technical experts get timely feedback and direction from the non-technical stakeholders.

+One of the biggest benefits of using the Azure Machine Learning ecosystem is related to the ability to archive, for quick future reference, model and data insights in the Azure Machine Learning run history. As a part of that infrastructure and to accompany machine learning models and their corresponding Responsible AI dashboards, we're introducing the Responsible AI scorecard to empower machine learning professionals to generate and share their data and model health records easily.

+* If you're a data scientist or machine learning professional:

+

+ After training your model and generating its corresponding Responsible AI dashboards for assessment and decision-making purposes, you can extract those learnings via our PDF scorecard and share the report easily with your technical and non-technical stakeholders. Doing so helps build trust and gain their approval for deployment.

+* If you're a product manager, a business leader, or an accountable stakeholder on an AI product:

+ You can pass your desired model performance and fairness target values, such as target accuracy or target error rate, to your data science team. The team can generate a scorecard with respect to your identified target values, assess whether your model meets them, and then advise as to whether the model should be deployed or further improved.

+## Generate a Responsible AI scorecard

+As with other Responsible AI dashboard components [configured in the YAML pipeline](how-to-responsible-ai-dashboard-sdk-cli.md?tabs=yaml#responsible-ai-components), you can add a component to generate the scorecard in the YAML pipeline.

+In the following code, the *pdf_gen.json* file is the JSON configuration file for scorecard generation, and *cohorts.json* is the JSON definition file for pre-built cohorts.

+Here's a sample JSON file for cohorts definition and scorecard-generation configuration:

+Here's a scorecard-generation configuration file as a regression example:

+ "ModelName": "GPT-2 Access",

+ "ModelSummary": "This is a regression model to analyze how likely a programmer is given access to GPT-2"

+Here's a scorecard-generation configuration file as a classification example:

+ "ModelSummary": "This model is a classifier that predicts whether the house will sell for more than the median price."

+### Definition of inputs for the Responsible AI scorecard component

+This section lists and defines the parameters that are required to configure the Responsible AI scorecard component.

+| ModelName | Name of model |

+|||

+| `ModelType` | Values in ['classification', 'regression']. |

+| `ModelSummary` | Enter text that summarizes what the model is for. |

+> For multi-class classification, you should first use the One-vs-Rest strategy to choose your reference class, and then split your multi-class classification model into a binary classification problem for your selected reference class versus the rest of the classes.

+| Performance metric | Definition | Model type |

+||||

+| `accuracy_score` | The fraction of data points that are classified correctly. | Classification |

+| `precision_score` | The fraction of data points that are classified correctly among those classified as 1. | Classification |

+| `recall_score` | The fraction of data points that are classified correctly among those whose true label is 1. Alternative names: true positive rate, sensitivity. | Classification |

+| `f1_score` | The F1 score is the harmonic mean of precision and recall. | Classification |

+| `error_rate` | The proportion of instances that are misclassified over the whole set of instances. | Classification |

+| `mean_absolute_error` | The average of absolute values of errors. More robust to outliers than `mean_squared_error`. | Regression |

+| `mean_squared_error` | The average of squared errors. | Regression |

+| `median_absolute_error` | The median of squared errors. | Regression |

+| `r2_score` | The fraction of variance in the labels explained by the model. | Regression |

+Threshold: The desired threshold for the selected metric. Allowed mathematical tokens are >, <, >=, and <=m, followed by a real number. For example, >= 0.75 means that the target for the selected metric is greater than or equal to 0.75.

+top_n: The number of features to show, with a maximum of 10. Positive integers up to 10 are allowed.

+| `metric` | The primary metric for evaluation fairness. |

+| `sensitive_features` | A list of feature names from the input dataset to be designated as sensitive features for the fairness report. |

+| `fairness_evaluation_kind` | Values in ['difference', 'ratio']. |

+| `threshold` | The *desired target values* of the fairness evaluation. Allowed mathematical tokens are >, <, >=, and <=, followed by a real number.<br>For example, metric="accuracy", fairness_evaluation_kind="difference".<br><= 0.05 means that the target for the difference in accuracy is less than or equal to 0.05. |

+> Your choice of `fairness_evaluation_kind` (selecting 'difference' versus 'ratio') affects the scale of your target value. In your selection, be sure to choose a meaningful target value.

+You can select from the following metrics, paired with `fairness_evaluation_kind`, to configure your fairness assessment component of the scorecard:

+| Metric | fairness_evaluation_kind | Definition | Model type |

+| `accuracy_score` | difference | The maximum difference in accuracy score between any two groups. | Classification |

+| `accuracy_score` | ratio | The minimum ratio in accuracy score between any two groups. | Classification |

+| `precision_score` | difference | The maximum difference in precision score between any two groups. | Classification |

+| `precision_score` | ratio | The maximum ratio in precision score between any two groups. | Classification |

+| `recall_score` | difference | The maximum difference in recall score between any two groups. | Classification |

+| `recall_score` | ratio | The maximum ratio in recall score between any two groups. | Classification |

+| `f1_score` | difference | The maximum difference in f1 score between any two groups. | Classification |

+| `f1_score` | ratio | The maximum ratio in f1 score between any two groups. | Classification |

+| `error_rate` | difference | The maximum difference in error rate between any two groups. | Classification |

+| `error_rate` | ratio | The maximum ratio in error rate between any two groups.|Classification|

+| `Selection_rate` | difference | The maximum difference in selection rate between any two groups. | Classification |

+| `Selection_rate` | ratio | The maximum ratio in selection rate between any two groups. | Classification |

+| `mean_absolute_error` | difference | The maximum difference in mean absolute error between any two groups. | Regression |

+| `mean_absolute_error` | ratio | The maximum ratio in mean absolute error between any two groups. | Regression |

+| `mean_squared_error` | difference | The maximum difference in mean squared error between any two groups. | Regression |

+| `mean_squared_error` | ratio | The maximum ratio in mean squared error between any two groups. | Regression |

+| `median_absolute_error` | difference | The maximum difference in median absolute error between any two groups. | Regression |

+| `median_absolute_error` | ratio | The maximum ratio in median absolute error between any two groups. | Regression |

+| `r2_score` | difference | The maximum difference in R² score between any two groups. | Regression |

+| `r2_Score` | ratio | The maximum ratio in R² score between any two groups. | Regression |

+## View your Responsible AI scorecard

+The Responsible AI scorecard is linked to a Responsible AI dashboard. To view your Responsible AI scorecard, go into your model registry and select the registered model that you've generated a Responsible AI dashboard for. After you've selected your model, select the **Responsible AI (preview)** tab to view a list of generated dashboards. Select which dashboard you want to export a Responsible AI scorecard PDF for by selecting **Responsible AI scorecard (preview)**.

+1. Select **Responsible AI scorecard (preview)** to display a list of all Responsible AI scorecards that are generated for this dashboard.

+ :::image type="content" source="./media/how-to-responsible-ai-scorecard/scorecard-studio-dropdown.png" alt-text="Screenshot of Responsible AI scorecard dropdown." lightbox ="./media/how-to-responsible-ai-scorecard/scorecard-studio-dropdown.png":::

+1. In the list, select the scorecard you want to download, and then select **Download** to download the PDF to your machine.

+ :::image type="content" source="./media/how-to-responsible-ai-scorecard/studio-select-scorecard.png" alt-text="Screenshot of the 'Responsible AI scorecards' pane for selecting a scorecard to download." lightbox= "./media/how-to-responsible-ai-scorecard/studio-select-scorecard.png":::

+## Read your Responsible AI scorecard

+The Responsible AI scorecard is a PDF summary of key insights from your Responsible AI dashboard. The first summary segment of the scorecard gives you an overview of the machine learning model and the key target values you've set to help your stakeholders determine whether the model is ready to be deployed:

+The data explorer segment shows you characteristics of your data, because any model story is incomplete without a correct understanding of your data:

+The model performance segment displays your model's most important metrics and characteristics of your predictions and how well they satisfy your desired target values:

+Next, you can also view the top performing and worst performing data cohorts and subgroups that are automatically extracted for you to see the blind spots of your model:

+You can see the top important factors that affect your model predictions, which is a requirement to build trust with how your model is performing its task:

+You can further see your model fairness insights summarized and inspect how well your model is satisfying the fairness target values you've set for your desired sensitive groups:

+Finally, you can see your dataset's causal insights summarized, which can help you determine whether your identified factors or treatments have any causal effect on the real-world outcome:

+- See the how-to guide for generating a Responsible AI dashboard via [CLI&nbsp;v2 and SDK&nbsp;v2](how-to-responsible-ai-dashboard-sdk-cli.md) or the [Azure Machine Learning studio UI](how-to-responsible-ai-dashboard-ui.md).

+- Learn more about how you can use the Responsible AI dashboard and scorecard to debug data and models and inform better decision-making in this [tech community blog post](https://www.microsoft.com/ai/ai-lab-responsible-ai-dashboard).

+- Learn about how the Responsible AI dashboard and scorecard were used by the UK National Health Service (NHS) in a [real-life customer story](https://aka.ms/NHSCustomerStory).

+- Explore the features of the Responsible AI dashboard through this [interactive AI lab web demo](https://www.microsoft.com/ai/ai-lab-responsible-ai-dashboard).

+* An Azure subscription. If you don't have an Azure subscription, create a free account before you begin. Try the [free or paid version of Azure Machine Learning](https://azure.microsoft.com/free/machine-learning/search/) today.

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ # [Azure CLI](#tab/cli)

+ # [Python SDK](#tab/python)

+ # [Azure CLI](#tab/cli)

+ # [Python SDK](#tab/python)

+1. Go to the Azure portal, select a new subscription or an existing one.

+1. Select the Events entry from the left navigation area, and then select **+ Event subscription**.

+> [!IMPORTANT]

+> This example relies on a feature (data drift) that is only available when using Azure Machine Learning SDK v1 or Azure CLI extension v1 for Azure Machine Learning. For more information, see [What is Azure ML CLI & SDK v2](concept-v2.md).

+# [Studio](#tab/azure-studio)

+> [!div class="op_single_selector" title1="Select the version of Azure Machine Learning you are using:"]

+# [Azure CLI](#tab/cli)

+ [!INCLUDE [cli v2](../../includes/machine-learning-cli-v2.md)]

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+# [Azure CLI](#tab/cli)

+# [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+## Register and deploy model

+Once the run completes, you can register the model that was created from the best run (configuration that resulted in the best primary metric). You can either register the model after downloading or by specifying the azureml path with corresponding jobid.

+### Get the best run

+# [Azure CLI](#tab/cli)

+```yaml

+ to be supported

+```

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=best_run)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=create_local_dir)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=download_model)]

+### Register the model

+Register the model either using the azureml path or your locally downloaded path.

+# [Azure CLI](#tab/cli)

+```azurecli

+ az ml model create --name od-fridge-items-mlflow-model --version 1 --path azureml://jobs/$best_run/outputs/artifacts/outputs/mlflow-model/ --type mlflow_model --workspace-name [YOUR_AZURE_WORKSPACE] --resource-group [YOUR_AZURE_RESOURCE_GROUP] --subscription [YOUR_AZURE_SUBSCRIPTION]

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=register_model)]

+After you register the model you want to use, you can deploy it using the managed online endpoint [deploy-managed-online-endpoint](how-to-deploy-managed-online-endpoint-sdk-v2.md)

+### Configure online endpoint

+# [Azure CLI](#tab/cli)

+```yaml

+$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json

+name: od-fridge-items-endpoint

+auth_mode: key

+

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=endpoint)]

+### Create the endpoint

+Using the `MLClient` created earlier, we'll now create the Endpoint in the workspace. This command will start the endpoint creation and return a confirmation response while the endpoint creation continues.

+# [Azure CLI](#tab/cli)

+```azurecli

+az ml online-endpoint create --file .\create_endpoint.yml --workspace-name [YOUR_AZURE_WORKSPACE] --resource-group [YOUR_AZURE_RESOURCE_GROUP] --subscription [YOUR_AZURE_SUBSCRIPTION]

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=create_endpoint)]

+### Configure online deployment

+A deployment is a set of resources required for hosting the model that does the actual inferencing. We'll create a deployment for our endpoint using the `ManagedOnlineDeployment` class. You can use either GPU or CPU VM SKUs for your deployment cluster.

+# [Azure CLI](#tab/cli)

+```yaml

+name: od-fridge-items-mlflow-deploy

+endpoint_name: od-fridge-items-endpoint

+model: azureml:od-fridge-items-mlflow-model@latest

+instance_type: Standard_DS3_v2

+instance_count: 1

+liveness_probe:

+ failure_threshold: 30

+ success_threshold: 1

+ timeout: 2

+ period: 10

+ initial_delay: 2000

+readiness_probe:

+ failure_threshold: 10

+ success_threshold: 1

+ timeout: 10

+ period: 10

+ initial_delay: 2000

+```

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=deploy)]

+### Create the deployment

+Using the `MLClient` created earlier, we'll now create the deployment in the workspace. This command will start the deployment creation and return a confirmation response while the deployment creation continues.

+# [Azure CLI](#tab/cli)

+```azurecli

+az ml online-deployment create --file .\create_deployment.yml --workspace-name [YOUR_AZURE_WORKSPACE] --resource-group [YOUR_AZURE_RESOURCE_GROUP] --subscription [YOUR_AZURE_SUBSCRIPTION]

+```

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=create_deploy)]

+### Update traffic:

+By default the current deployment is set to receive 0% traffic. you can set the traffic percentage current deployment should receive. Sum of traffic percentages of all the deployments with one end point should not exceed 100%.

+# [Azure CLI](#tab/cli)

+```azurecli

+az ml online-endpoint update --name 'od-fridge-items-endpoint' --traffic 'od-fridge-items-mlflow-deploy=100' --workspace-name [YOUR_AZURE_WORKSPACE] --resource-group [YOUR_AZURE_RESOURCE_GROUP] --subscription [YOUR_AZURE_SUBSCRIPTION]

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=update_traffic)]

+## Test the deployment

+# [Azure CLI](#tab/cli)

+```yaml

+

+```

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=create_inference_request)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=dump_inference_request)]

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=invoke_inference)]

+## Visualize detections

+Now that you have scored a test image, you can visualize the bounding boxes for this image. To do so, be sure you have matplotlib installed.

+# [Azure CLI](#tab/cli)

+```yaml

+

+```

+# [Python SDK](#tab/python)

+[!Notebook-python[] (~/azureml-examples-main/sdk/jobs/automl-standalone-jobs/automl-image-object-detection-task-fridge-items/automl-image-object-detection-task-fridge-items.ipynb?name=visualize_detections)]

+ # [Azure CLI](#tab/cli)

+ [!INCLUDE [cli v2](../../includes/machine-learning-cli-v2.md)]

+

+ * Review detailed code examples and use cases in the [azureml-examples repository for automated machine learning samples](https://github.com/Azure/azureml-examples/tree/sdk-preview/cli/jobs/automl-standalone-jobs). Please check the folders with 'cli-automl-image-' prefix for samples specific to building computer vision models.

+

+ # [Python SDK](#tab/python)

+ [!INCLUDE [sdk v2](../../includes/machine-learning-sdk-v2.md)]

+ * Review detailed code examples and use cases in the [GitHub notebook repository for automated machine learning samples](https://github.com/Azure/azureml-examples/tree/sdk-preview/sdk/jobs/automl-standalone-jobs). Please check the folders with 'automl-image-' prefix for samples specific to building computer vision models.

+

+

+# [Studio](#tab/azure-studio)

+> [!div class="op_single_selector" title1="Select the version of Azure Machine Learning you are using:"]

+* [Deploy a trained model](../v1/how-to-deploy-and-where.md)

+# [Studio](#tab/azure-studio)

+> [!div class="op_single_selector" title1="Select the version of Azure Machine Learning SDK you are using:"]

+An Azure Managed Grafana instance in the Standard tier is hosted on a dedicated set of virtual machines (VMs). By default, two VMs are deployed to provide redundancy. Each VM runs a Grafana server. A network load balancer distributes browser requests amongst the Grafana servers. On the backend, the Grafana servers are connected to a common database that stores the configuration and other persistent data for an entire Managed Grafana instance.

+Normally the network load balancer, VMs and database that underpin a Managed Grafana instance are located in a region based on system resource availability, and could end up being in a same Azure datacenter.

+When the zone redundancy option is enabled, VMs are spread across [availability zones](../availability-zones/az-overview.md#availability-zones). Other resources such as network load balancer and database are also configured for availability zones.

+Zone redundancy is disabled in the Managed Grafana Standard tier by default. In this scenario, virtual machines are created as single-region resources and should not be expected to survive zone-downs scenarios as they can go down at same time.

+## Supported regions

+Zone redundancy support is enabled in the following regions:

+| Americas | Europe | Africa | Asia Pacific |

+||-|-|-|

+| East US | West Europe | | Australia East |

+| South Central US | | | |

+For a complete list of regions where Managed Grafana is available, see [Products available by region - Azure Managed Grafana](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/?products=managed-grafana&regions=all)

+ :::image type="content" source="media/authentication/create-form-permission.png" alt-text="Screenshot of the Azure portal. Create workspace form. Permission.":::

+ Title: Azure Managed Grafana limitations

+description: List of known limitations in Azure Managed Grafana

+# Limitations of Azure Managed Grafana

+Azure Managed Grafana delivers the native Grafana functionality in the highest possible fidelity. There are some differences between what it provides and what you can get by self-hosting Grafana. As a general rule, Azure Managed Grafana disables features and settings that may affect the security or reliability of the service and individual Grafana instances it manages.

+## Current limitations

+Managed Grafana has the following known limitations:

+* All users must have accounts in an Azure Active Directory. Microsoft (also known as MSA) and 3rd-party accounts aren't supported. As a workaround, use the default tenant of your Azure subscription with your Grafana instance and add other users as guests.

+* Installing, uninstalling and upgrading plugins from the Grafana Catalog aren't allowed.

+* Data source query results are capped at 80 MB. To mitigate this constraint, reduce the size of the query, for example, by shortening the time duration.

+* Querying Azure Data Explorer may take a long time or return 50x errors. To resolve these issues, use a table format instead of a time series, shorten the time duration, or avoid having many panels querying the same data cluster that can trigger throttling.

+* API key usage isn't included in the audit log.

+## Next steps

+> [!div class="nextstepaction"]

+> [Troubleshooting](./troubleshoot-managed-grafana.md)

+- [Android](https://developer.android.com/develop/ui/views/notifications)

+7. Go to the summary page, and select **Create** to create the account private endpoint.

+8. Repeat steps 2 through 7 to create the portal private endpoint. Make sure you select **portal** for **Target sub-resource**.

+ 1. A manual or automatic scan is initiated from the Microsoft Purview Data Map through the Azure integration runtime.

+ 4. Metadata is sent to the Microsoft Purview Data Map.

+- Scanning on-premises and VM-based data sources always requires using a self-hosted integration runtime. The Azure integration runtime isn't supported for these data sources. The following steps show the communication flow at a high level when you're using a self-hosted integration runtime to scan a data source. The first diagram shows a scenario where resources are within Azure or on a VM in Azure. The second diagram shows a scenario with on-premises resources. The steps between the two are the same from Microsoft Purview's perspective:

+ :::image type="content" source="media/concept-best-practices/security-self-hosted-runtime-on-premises.png" alt-text="Screenshot that shows the connection flow between Microsoft Purview, an on-premises self-hosted runtime, and data sources in on-premises network."lightbox="media/concept-best-practices/security-self-hosted-runtime-on-premises.png":::

+ 2. The scan is initiated from the Microsoft Purview Data Map through a self-hosted integration runtime.

+ 3. The self-hosted integration runtime service from the VM or on-premises machine connects to the data source to extract metadata.

+ 4. Metadata is processed in the machine's memory for the self-hosted integration runtime. Metadata is queued in Microsoft Purview managed storage and then stored in Azure Blob Storage. Actual data never leaves the boundary of your network.

+ 5. Metadata is sent to the Microsoft Purview Data Map.

+ If the data source is Azure Blob Storage, you can use a Microsoft Purview managed identity, or a service principal in Azure Active Directory added as a Blob Storage Data Reader role on the Azure storage account. Or use the storage account's key.

+### Other considerations

+Similar to other PaaS solutions, Microsoft Purview doesn't support deploying directly into a virtual network. So you can't use certain networking features with the offering's resources, such as network security groups, route tables, or other network-dependent appliances such as Azure Firewall. Instead, you can use private endpoints that can be enabled on your virtual network. You can then disable public internet access to securely connect to Microsoft Purview.

+- Scanning multiple Azure sources by using the entire subscription or resource group through ingestion private endpoints and a self-hosted integration runtime isn't supported when you're using private endpoints for ingestion. Instead, you can register and scan data sources individually.

+You can optionally deploy another self-hosted integration runtime in the spoke virtual networks.

+It's recommended to follow these recommendations, if your organization needs to deploy and maintain multiple Microsoft Purview accounts using private endpoints:

+This scenario also applies if multiple Microsoft Purview accounts are deployed across multiple subscriptions and multiple VNets that are connected through VNet peering. _Portal_ private endpoint mainly renders static assets related to the Microsoft Purview governance portal, thus, it's independent of Microsoft Purview account, therefore, only one _portal_ private endpoint is needed to visit all Microsoft Purview accounts in the Azure environment if VNets are connected.

+- The Self-hosted integration runtime service can communicate with Microsoft Purview through public or private network over port 443. For more information, see, [self-hosted integration runtime networking requirements](manage-integration-runtimes.md#networking-requirements).

+- One self-hosted integration runtime VM can be used to scan one or multiple data sources in Microsoft Purview, however, self-hosted integration runtime must be only registered for Microsoft Purview and can't be used for Azure Data Factory or Azure Synapse at the same time.

+- You can register and use one or multiple self-hosted integration runtimes in one Microsoft Purview account. It's recommended to place at least one self-hosted integration runtime VM in each region or on-premises network where your data sources reside.

+- It's recommended to define a baseline for required capacity for each self-hosted integration runtime VM and scale the VM capacity based on demand.

+- It's recommended to set up network connection between self-hosted integration runtime VMs and Microsoft Purview and its managed resources through private network, when possible.

+- The self-hosted integration runtime service doesn't require outbound internet connectivity, if self-hosted integration runtime VMs are deployed in an Azure VNet or in the on-premises network that is connected to Azure through an ExpressRoute or Site to Site VPN connection. In this case, the scan and metadata ingestion process can be done through private network.

+1. [Create an application registration](/azure/active-directory/develop/howto-create-service-principal-portal#register-an-application-with-azure-ad-and-create-a-service-principal) that will act as the login identity once Profisee is installed. It needs to be a part of the Azure Active Directory that will be used to sign in to Profisee. Save the **Application (client) ID** for use later.

+1. [Create a service principal](/azure/active-directory/develop/howto-create-service-principal-portal#register-an-application-with-azure-ad-and-create-a-service-principal) that Microsoft Purview will use to take some actions on itself during this Profisee deployment. To create a service principal, create an application like you did in the previous step, then [create an application secret](/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret). Save the **Object ID** for the application, and the **Value** of the secret you created for later use.

+ 1. For the Application Registration Client ID, provide the [**application (client) ID**](/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in) for the [application registration you created earlier](#microsoft-purviewprofisee-integration-deployment-on-azure-kubernetes-service-aks).

+> | [Template Spec Contributor](#template-spec-contributor) | Allows full access to Template Spec operations at the assigned scope. | 1c9b6475-caf0-4164-b5a1-2142a7116f4b |

+> | [Template Spec Reader](#template-spec-reader) | Allows read access to Template Specs at the assigned scope. | 392ae280-861d-42bd-9ea5-08ee6d83b80e |

+> | [Microsoft.Insights](resource-provider-operations.md#microsoftinsights)/autoscalesettings/* | |

+ "Microsoft.Web/hostingEnvironments/Join/Action",

+ "Microsoft.Insights/autoscalesettings/*"

+> | [Microsoft.Resources](resource-provider-operations.md#microsoftresources)/templateSpecs/*/read | Get or list template specs and template spec versions |

+> | *none* | |

+ "dataActions": [],

+> | *none* | |

+ "dataActions": [],

+### Template Spec Contributor

+Allows full access to Template Spec operations at the assigned scope.

+> [!div class="mx-tableFixed"]

+> | Actions | Description |

+> | | |

+> | [Microsoft.Resources](resource-provider-operations.md#microsoftresources)/templateSpecs/* | Create and manage template specs and template spec versions |

+> | [Microsoft.Authorization](resource-provider-operations.md#microsoftauthorization)/*/read | Read roles and role assignments |

+> | [Microsoft.Resources](resource-provider-operations.md#microsoftresources)/deployments/* | Create and manage a deployment |

+> | [Microsoft.Resources](resource-provider-operations.md#microsoftresources)/subscriptions/resourceGroups/read | Gets or lists resource groups. |

+> | **NotActions** | |

+> | *none* | |

+> | **DataActions** | |

+> | *none* | |

+> | **NotDataActions** | |

+> | *none* | |

+```json

+{

+ "assignableScopes": [

+ "/"

+ ],

+ "description": "Allows full access to Template Spec operations at the assigned scope.",

+ "id": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/1c9b6475-caf0-4164-b5a1-2142a7116f4b",

+ "name": "1c9b6475-caf0-4164-b5a1-2142a7116f4b",

+ "permissions": [

+ {

+ "actions": [

+ "Microsoft.Resources/templateSpecs/*",

+ "Microsoft.Authorization/*/read",

+ "Microsoft.Resources/deployments/*",

+ "Microsoft.Resources/subscriptions/resourceGroups/read"

+ ],

+ "notActions": [],

+ "dataActions": [],

+ "notDataActions": []

+ }

+ ],

+ "roleName": "Template Spec Contributor",

+ "roleType": "BuiltInRole",

+ "type": "Microsoft.Authorization/roleDefinitions"

+}

+```

+### Template Spec Reader

+Allows read access to Template Specs at the assigned scope.

+> [!div class="mx-tableFixed"]

+> | Actions | Description |

+> | | |

+> | [Microsoft.Resources](resource-provider-operations.md#microsoftresources)/templateSpecs/*/read | Get or list template specs and template spec versions |

+> | **NotActions** | |

+> | *none* | |

+> | **DataActions** | |

+> | *none* | |

+> | **NotDataActions** | |

+> | *none* | |

+```json

+{

+ "assignableScopes": [

+ "/"

+ ],

+ "description": "Allows read access to Template Specs at the assigned scope.",

+ "id": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/392ae280-861d-42bd-9ea5-08ee6d83b80e",

+ "name": "392ae280-861d-42bd-9ea5-08ee6d83b80e",

+ "permissions": [

+ {

+ "actions": [

+ "Microsoft.Resources/templateSpecs/*/read"

+ ],

+ "notActions": [],

+ "dataActions": [],

+ "notDataActions": []

+ }

+ ],

+ "roleName": "Template Spec Reader",

+ "roleType": "BuiltInRole",

+ "type": "Microsoft.Authorization/roleDefinitions"

+}

+```

+> | [Microsoft.DigitalTwins](resource-provider-operations.md#microsoftdigitaltwins)/eventroutes/* | Read, delete, create, or update any Event Route |

+> | [Microsoft.DigitalTwins](resource-provider-operations.md#microsoftdigitaltwins)/jobs/* | |

+ "Microsoft.DigitalTwins/eventroutes/*",

+ "Microsoft.DigitalTwins/jobs/*",

+> | [Microsoft.DigitalTwins](resource-provider-operations.md#microsoftdigitaltwins)/jobs/import/read | Read any Bulk Import Job |

+ "Microsoft.DigitalTwins/jobs/import/read",

+> | Microsoft.Marketplace/privateStores/queryUserRules/action | Fetch the approved rules for the user under the user subscriptions |

+> | Microsoft.Marketplace/privateStores/queryInternalOfferIds/action | List of all internal offers under given azure application and plans |

+> | Microsoft.NetApp/netAppAccounts/capacityPools/volumes/PopulateAvailabilityZone/action | Populates logical availability zone for a volume in a zone aware region and storage. |

+> | Microsoft.CertificateRegistration/certificateOrders/retrieveContactInfo/Action | Retrieve certificate order contact information |

+> | Microsoft.DomainRegistration/domains/retrieveContactInfo/Action | Retrieve contact info for existing domain |

+> | Microsoft.Web/hostingEnvironments/testUpgradeAvailableNotification/Action | Send test upgrade notification for an App Service Environment |

+> | microsoft.web/sites/deployWorkflowArtifacts/action | Create the artifacts in a Logic App. |

+> | microsoft.web/sites/slots/deployWorkflowArtifacts/action | Create the artifacts in a deployment slot in a Logic App. |

+> | microsoft.web/sites/slots/workflows/read | List the workflows in a deployment slot in a Logic App. |

+> | microsoft.web/sites/slots/workflowsconfiguration/read | Get workflow app's configuration information by its ID in a deployment slot in a Logic App. |

+> | microsoft.web/sites/workflows/read | List the workflows in a Logic App. |

+> | microsoft.web/sites/workflowsconfiguration/read | Get workflow app's configuration information by its ID in a Logic App. |

+> | Microsoft.ContainerInstance/containerGroups/refreshDelegatedResourceIdentity/action | Refresh delegated resource identity for a specific container group. |

+> | Microsoft.ContainerRegistry/registries/deleted/read | Gets the deleted artifacts in a container registry |

+> | Microsoft.ContainerRegistry/registries/deleted/restore/action | Restores deleted artifacts in a container registry |

+> | Microsoft.DBforMySQL/flexibleServers/checkHaReplica/action | |

+> | Microsoft.DBforPostgreSQL/assessForMigration/action | Performs a migration assessment with the specified parameters |

+> | Microsoft.SqlVirtualMachine/sqlVirtualMachines/startAssessment/action | |

+> | Microsoft.CognitiveServices/accounts/encryptionScopes/read | Reads deployments. |

+> | Microsoft.CognitiveServices/accounts/encryptionScopes/write | Writes deployments. |

+> | Microsoft.CognitiveServices/accounts/encryptionScopes/delete | Deletes deployments. |

+> | Microsoft.CognitiveServices/accounts/AudioContentCreation/Synthesis/PredictSsmlTagsRealtime/action | Realtime API for predict ssml tag. |

+> | Microsoft.CognitiveServices/accounts/Face/detectlivenesswithverify/singlemodal/action | Detects liveness of a target face in a sequence of images of the same stream type (e.g. color) and then compares with VerifyImage to return confidence score for identity scenarios. |

+> | Microsoft.CognitiveServices/accounts/Knowledge/entitymatch/action | Entity Match |

+> | Microsoft.CognitiveServices/accounts/Knowledge/entitymatchwithattributes/action | Entity Match with Attributes |

+> | Microsoft.CognitiveServices/accounts/Knowledge/annotation/dataverse/action | Dataverse search annotation |

+> | Microsoft.MachineLearningServices/workspaces/computes/reimage/action | Reimages compute resource in Machine Learning Services Workspace |

+> | Microsoft.IoTSecurity/locations/alertSuppressionRules/read | Gets alert suppression rule |

+> | Microsoft.IoTSecurity/locations/alertSuppressionRules/write | Creates alert suppression rule |

+> | Microsoft.IoTSecurity/locations/alertSuppressionRules/delete | Deletes alert suppression rule |

+> | Microsoft.Security/assessments/subAssessments/read | Get security sub assessments on your subscription |

+> | Microsoft.Security/assessments/subAssessments/write | Create or update security sub assessments on your subscription |

+> | Microsoft.SecurityInsights/ContentPackages/read | Read available Content Packages. |

+> | Microsoft.SecurityInsights/ContentPackages/write | Install or uninstall Content Packages. |

+> | Microsoft.SecurityInsights/ContentTemplates/read | Read installed Content Templates. |

+> | Microsoft.OperationalInsights/workspaces/query/ANFFileAccess/read | Read data from the ANFFileAccess table |

+> | Microsoft.OperationalInsights/workspaces/query/AppServiceServerlessSecurityPluginData/read | Read data from the AppServiceServerlessSecurityPluginData table |

+> | Microsoft.OperationalInsights/workspaces/query/DefenderIoTRawEvent/read | Read data from the DefenderIoTRawEvent table |

+> | Microsoft.OperationalInsights/workspaces/query/GCPAuditLogs/read | Read data from the GCPAuditLogs table |

+> | microsoft.operationalinsights/workspaces/restoreLogs/write | Restore data from a table. |

+> | microsoft.operationalinsights/workspaces/searchJobs/write | Run a search job. |

+> | Microsoft.RecoveryServices/Locations/backupCrossRegionRestore/action | Trigger Cross region restore. |

+> | Microsoft.RecoveryServices/Locations/backupCrrJob/action | Get Cross Region Restore Job Details in the secondary region for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Locations/backupCrrJobs/action | List Cross Region Restore Jobs in the secondary region for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Locations/backupPreValidateProtection/action | |

+> | Microsoft.RecoveryServices/Locations/backupStatus/action | Check Backup Status for Recovery Services Vaults |

+> | Microsoft.RecoveryServices/Locations/backupValidateFeatures/action | Validate Features |

+> | Microsoft.RecoveryServices/Locations/backupAadProperties/read | Get AAD Properties for authentication in the third region for Cross Region Restore. |

+> | Microsoft.RecoveryServices/Locations/backupCrrOperationResults/read | Returns CRR Operation Result for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Locations/backupCrrOperationsStatus/read | Returns CRR Operation Status for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Locations/backupProtectedItem/write | Create a backup Protected Item |

+> | Microsoft.RecoveryServices/Locations/backupProtectedItems/read | Returns the list of all Protected Items. |

+> | Microsoft.RecoveryServices/Vaults/backupJobsExport/action | Export Jobs |

+> | Microsoft.RecoveryServices/Vaults/backupSecurityPIN/action | Returns Security PIN Information for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Vaults/backupTriggerValidateOperation/action | Validate Operation on Protected Item |

+> | Microsoft.RecoveryServices/Vaults/backupValidateOperation/action | Validate Operation on Protected Item |

+> | Microsoft.RecoveryServices/Vaults/backupconfig/read | Returns Configuration for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Vaults/backupconfig/write | Updates Configuration for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Vaults/backupEncryptionConfigs/read | Gets Backup Resource Encryption Configuration. |

+> | Microsoft.RecoveryServices/Vaults/backupEncryptionConfigs/write | Updates Backup Resource Encryption Configuration |

+> | Microsoft.RecoveryServices/Vaults/backupEngines/read | Returns all the backup management servers registered with vault. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/refreshContainers/action | Refreshes the container list |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/backupProtectionIntent/delete | Delete a backup Protection Intent |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/backupProtectionIntent/read | Get a backup Protection Intent |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/backupProtectionIntent/write | Create a backup Protection Intent |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/operationResults/read | Returns status of the operation |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/operationsStatus/read | Returns status of the operation |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectableContainers/read | Get all protectable containers |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/delete | Deletes the registered Container |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/inquire/action | Do inquiry for workloads within a container |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/read | Returns all registered containers |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/write | Creates a registered container |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/items/read | Get all items in a container |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/operationResults/read | Gets result of Operation performed on Protection Container. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/operationsStatus/read | Gets status of Operation performed on Protection Container. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/backup/action | Performs Backup for Protected Item. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/delete | Deletes Protected Item |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/read | Returns object details of the Protected Item |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/recoveryPointsRecommendedForMove/action | Get Recovery points recommended for move to another tier |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/write | Create a backup Protected Item |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/operationResults/read | Gets Result of Operation Performed on Protected Items. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/operationsStatus/read | Returns the status of Operation performed on Protected Items. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints/accessToken/action | Get AccessToken for Cross Region Restore. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints/move/action | Move Recovery point to another tier |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints/provisionInstantItemRecovery/action | Provision Instant Item Recovery for Protected Item |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints/read | Get Recovery Points for Protected Items. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints/restore/action | Restore Recovery Points for Protected Items. |

+> | Microsoft.RecoveryServices/Vaults/backupFabrics/protectionContainers/protectedItems/recoveryPoints/revokeInstantItemRecovery/action | Revoke Instant Item Recovery for Protected Item |

+> | Microsoft.RecoveryServices/Vaults/backupJobs/cancel/action | Cancel the Job |

+> | Microsoft.RecoveryServices/Vaults/backupJobs/read | Returns all Job Objects |

+> | Microsoft.RecoveryServices/Vaults/backupJobs/operationResults/read | Returns the Result of Job Operation. |

+> | Microsoft.RecoveryServices/Vaults/backupJobs/operationsStatus/read | Returns the status of Job Operation. |

+> | Microsoft.RecoveryServices/Vaults/backupOperationResults/read | Returns Backup Operation Result for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Vaults/backupOperations/read | Returns Backup Operation Status for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Vaults/backupPolicies/delete | Delete a Protection Policy |

+> | Microsoft.RecoveryServices/Vaults/backupPolicies/read | Returns all Protection Policies |

+> | Microsoft.RecoveryServices/Vaults/backupPolicies/write | Creates Protection Policy |

+> | Microsoft.RecoveryServices/Vaults/backupPolicies/operationResults/read | Get Results of Policy Operation. |

+> | Microsoft.RecoveryServices/Vaults/backupPolicies/operations/read | Get Status of Policy Operation. |

+> | Microsoft.RecoveryServices/Vaults/backupProtectableItems/read | Returns list of all Protectable Items. |

+> | Microsoft.RecoveryServices/Vaults/backupProtectedItems/read | Returns the list of all Protected Items. |

+> | Microsoft.RecoveryServices/Vaults/backupProtectionContainers/read | Returns all containers belonging to the subscription |

+> | Microsoft.RecoveryServices/Vaults/backupProtectionIntents/read | List all backup Protection Intents |

+> | Microsoft.RecoveryServices/Vaults/backupResourceGuardProxies/delete | The Delete ResourceGuard proxy operation deletes the specified Azure resource of type 'ResourceGuard proxy' |

+> | Microsoft.RecoveryServices/Vaults/backupResourceGuardProxies/read | Get the list of ResourceGuard proxies for a resource |

+> | Microsoft.RecoveryServices/Vaults/backupResourceGuardProxies/read | Get ResourceGuard proxy operation gets an object representing the Azure resource of type 'ResourceGuard proxy' |

+> | Microsoft.RecoveryServices/Vaults/backupResourceGuardProxies/unlockDelete/action | Unlock delete ResourceGuard proxy operation unlocks the next delete critical operation |

+> | Microsoft.RecoveryServices/Vaults/backupResourceGuardProxies/write | Create ResourceGuard proxy operation creates an Azure resource of type 'ResourceGuard Proxy' |

+> | Microsoft.RecoveryServices/Vaults/backupstorageconfig/read | Returns Storage Configuration for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Vaults/backupstorageconfig/write | Updates Storage Configuration for Recovery Services Vault. |

+> | Microsoft.RecoveryServices/Vaults/backupUsageSummaries/read | Returns summaries for Protected Items and Protected Servers for a Recovery Services . |

+> | Microsoft.RecoveryServices/Vaults/backupValidateOperationResults/read | Validate Operation on Protected Item |

+> | Microsoft.RecoveryServices/Vaults/backupValidateOperationsStatuses/read | Validate Operation on Protected Item |

+> | Microsoft.RecoveryServices/Vaults/privateEndpointConnectionProxies/delete | Wait for a few minutes and then try the operation again. If the issue persists, please contact Microsoft support. |

+> | Microsoft.RecoveryServices/Vaults/privateEndpointConnectionProxies/read | Get all protectable containers |

+> | Microsoft.RecoveryServices/Vaults/privateEndpointConnectionProxies/validate/action | Get all protectable containers |

+> | Microsoft.RecoveryServices/Vaults/privateEndpointConnectionProxies/write | Get all protectable containers |

+> | Microsoft.RecoveryServices/Vaults/privateEndpointConnectionProxies/operationsStatus/read | Get all protectable containers |

+> | Microsoft.RecoveryServices/Vaults/privateEndpointConnections/delete | Delete Private Endpoint requests. This call is made by Backup Admin. |

+> | Microsoft.RecoveryServices/Vaults/privateEndpointConnections/write | Approve or Reject Private Endpoint requests. This call is made by Backup Admin. |

+> | Microsoft.RecoveryServices/Vaults/privateEndpointConnections/operationsStatus/read | Returns the operation status for a private endpoint connection. |

+> | Microsoft.RecoveryServices/Vaults/usages/read | Returns usage details for a Recovery Services Vault. |

+> | Microsoft.DigitalTwins/jobs/import/read | Read any Bulk Import Job |

+> | Microsoft.DigitalTwins/jobs/import/write | Create any Bulk Import Job |

+> | Microsoft.DigitalTwins/jobs/import/delete | Delete any Bulk Import Job |

+Start by getting the endpoint and key for your search service. Then create a new project with npm as outlined below.

+Calls to the service require a URL endpoint and an access key on every request. As a first step, find the API key and URL to add to your project. You'll specify both values when creating the client in a later step.

+2. In **Settings** > **Keys**, get an admin key for full rights on the service, required if you're creating or deleting objects. There are two interchangeable primary and secondary keys. You can use either one.

+### Create a new npm project

+2. Initialize an empty project with npm by running the following command. To fully initialize the project, press Enter multiple times to accept the default values, except for the License, which you should set to "MIT".

+

+3. Install `@azure/search-documents`, the [JavaScript/TypeScript SDK for Azure Cognitive Search](/javascript/api/overview/azure/search-documents-readme).

+4. Install `dotenv`, which is used to import the environment variables such as your search service name and API key.

+ "@azure/search-documents": "^11.3.0",

+ "dotenv": "^16.0.2"

+Add the following content to **hotels_quickstart_index.json** or [download the file](https://github.com/Azure-Samples/azure-search-javascript-samples/blob/master/quickstart/v11/hotels_quickstart_index.json).

+Next, we want to delete the index if it already exists. This operation is a common practice for test/demo code.

+Open the **Overview** of your search service in the Azure portal. Select the **Indexes** tab. You should see something like the following example:

+Queries are sent using the `search()` method of `searchClient`. The first parameter is the search text and the second parameter specifies search options.

+The remaining queries outlined below should also be added to the `sendQueries()` function. They're separated here for readability.

+Next, the search is limited to a single searchable field using the `searchFields` parameter. This approach is a great option to make your query more efficient if you know you're only interested in matches in certain fields.

+If you're using a free service, remember the limit of three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit.

+> Support for native blob soft delete is in preview under [Supplemental Terms of Use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). The [REST API version 2020-06-30-Preview](./search-api-preview.md) provides this feature. There is currently no .NET SDK support.

+1. In Cognitive Search, set a native blob soft deletion detection policy on the data source. You can do this either from the Azure portal or by using preview REST API (`api-version=2020-06-30-Preview`).

+### [**Azure portal**](#tab/portal)

+1. [Sign in to Azure portal](https://portal.azure.com).

+1. On the Cognitive Search service Overview page, go to **New Data Source**, a visual editor for specifying a data source definition.

+ The following screenshot shows where you can find this feature in the portal.

+ :::image type="content" source="media/search-indexing-changed-deleted-blobs/new-data-source.png" alt-text="Screenshot of portal data source." border="true":::

+1. On the **New Data Source** form, fill out the required fields, select the **Track deletions** checkbox and choose **Native blob soft delete**. Then hit **Save** to enable the feature on Data Source creation.

+ :::image type="content" source="media/search-indexing-changed-deleted-blobs/native-soft-delete.png" alt-text="Screenshot of portal data source native soft delete." border="true":::

+### [**REST**](#tab/rest-api)

+An example of using REST API to set soft deletion detection policy on the data source is shown below.

+```http

+PUT https://[service name].search.windows.net/datasources/blob-datasource?api-version=2020-06-30-Preview

+Content-Type: application/json

+api-key: [admin key]

+{

+ "name" : "blob-datasource",

+ "type" : "azureblob",

+ "credentials" : { "connectionString" : "<your storage connection string>" },

+ "container" : { "name" : "my-container", "query" : null },

+ "dataDeletionDetectionPolicy" : {

+ "@odata.type" :"#Microsoft.Azure.Search.NativeBlobSoftDeleteDeletionDetectionPolicy"

+ }

+}

+```

+Even if you enable deletion detection policy, deleting complex (`Edm.ComplexType`) fields from the index is not supported. This policy requires that the 'active' column in the Gremlin database to be of type integer, string or boolean.

+During this section youΓÇÖll be asked to sign in with your organization credentials that have access to the SharePoint site. If possible, we recommend creating a new organizational user account and giving that new user the exact permissions that you want the indexer to have.

+ }

+ ]

+ "dataToExtract": "contentAndMetadata",

+ "indexedFileNameExtensions" : ".pdf, .docx",

+ "excludedFileNameExtensions" : ".png, .jpg"

+ }

+ ]

+| [Reader](../role-based-access-control/built-in-roles.md#reader) | (Generally available) Limited access to partial service information. In the portal, the Reader role can access information in the service Overview page, in the Essentials section and under the Monitoring tab. All other tabs and pages are off limits. </br></br>This role has access to service information: service name, resource group, service status, location, subscription name and ID, tags, URL, pricing tier, replicas, partitions, and search units. This role also has access to service metrics: search latency, percentage of throttled requests, average queries per second. </br></br>This role doesn't allow access to API keys, role assignments, content (indexes or synonym maps), or content metrics (storage consumed, number of objects). </br></br> (Preview) When you enable the RBAC preview for the data plane, the Reader role has read access across the entire service. This allows you to read search metrics, content metrics (storage consumed, number of objects), and the definitions of data plane resources (indexes, indexers, etc.). The Reader role still won't have access to read API keys or read content within indexes. |

+SNCSYSACL_FULL = <True/False> (Preview)

+USRACL_FULL = <True/False> (Preview)

+| SNCSYSACL (PREVIEW)| SNC Access Control List (ACL): Systems | SAP_SNCSYSACL |

+| USRACL (PREVIEW)| SNC Access Control List (ACL): User | SAP_USRACL |

+|<ul><li>Is the server hosting this virtual machine up and running?</li><li>Is the virtual machine container provisioned and powered up?</li><li>Is there network connectivity between the host and the storage account?</li><li>Is there ongoing planned maintenance?</li><li>Is there heartbeats between Guest and host agent *(if Guest extension is installed)*?</li></ul>|

+ Title: Java memory management

+description: Introduces concepts for Java memory management to help you understand Java applications in Azure Spring Apps.

+# Java memory management

+> [!NOTE]

+> Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

+**This article applies to:** ✔️ Basic/Standard tier ✔️ Enterprise tier

+This article describes various concepts related to Java memory management to help you understand the behavior of Java applications hosted in Azure Spring Apps.

+## Java memory model

+A Java application's memory has several parts, and there are different ways to divide the parts. This article discusses Java memory as divided into heap memory, non-heap memory, and direct memory.

+### Heap memory

+Heap memory stores all class instances and arrays. Each Java virtual machine (JVM) has only one heap area, which is shared among threads.

+Spring Boot Actuator can observe the value of heap memory. Spring Boot Actuator takes the heap value as part of `jvm.memory.used/committed/max`. For more information, see the [jvm.memory.used/committed/max](tools-to-troubleshoot-memory-issues.md#jvmmemoryusedcommittedmax) section in [Tools to troubleshoot memory issues](tools-to-troubleshoot-memory-issues.md).

+Heap memory is divided into *young generation* and *old generation*. These terms are described in the following list, along with related terms.

+- *Young generation*: all new objects are allocated and aged in young generation.

+ - *Eden space*: new objects are allocated in Eden space.

+ - *Survivor space*: objects will be moved from Eden to survivor space after surviving one garbage collection cycle. Survivor space can be divided to two parts: s1 and s2.

+- *Old generation*: also called *tenured space*. Objects that have remained in the survivor spaces for a long time will be moved to old generation.

+Before Java 8, another section called *permanent generation* was also part of the heap. Starting with Java 8, permanent generation was replaced by metaspace in non-heap memory.

+### Non-heap memory

+Non-heap memory is divided into the following parts:

+- The part of non-heap memory that replaced the permanent generation (or *permGen*) starting with Java 8. Spring Boot Actuator observes this section and takes it as part of `jvm.memory.used/committed/max`. In other words, `jvm.memory.used/committed/max` is the sum of heap memory and the former permGen part of non-heap memory. The former permanent generation is composed of the following parts:

+ - *Metaspace*, which stores the class definitions loaded by class loaders.

+ - *Compressed class space*, which is for compressed class pointers.

+ - *Code cache*, which stores native code compiled by JIT.

+- Other memory such as the thread stack, which isn't observed by Spring Boot Actuator.

+### Direct memory

+Direct memory is native memory allocated by `java.nio.DirectByteBuffer`, which is used in third party libraries like nio and gzip.

+Spring Boot Actuator doesn't observe the value of direct memory.

+The following diagram summarizes the Java memory model described in the previous section.

+## Java garbage collection

+There are three terms regarding of Java Garbage Collection (GC): "Minor GC", "Major GC", and "Full GC". These terms aren't clearly defined in the JVM specification. Here, we consider "Major GC" and "Full GC" to be equivalent.

+Minor GC performs when Eden space is full. It removes all dead objects in young generation and moves live objects to from Eden space to s1 of survivor space, or from s1 to s2.

+Full GC or major GC does garbage collection in the entire heap. Full GC can also collect parts like metaspace and direct memory, which can be cleaned only by full GC.

+The maximum heap size influences the frequency of minor GC and full GC. The maximum metaspace and maximum direct memory size influence full GC.

+When you set the maximum heap size to a lower value, garbage collections occur more frequently, which slow the app a little, but better limits the memory usage. When you set the maximum heap size to a higher value, garbage collections occur less frequently, which may create more out-of-memory (OOM) risk. For more information, see the [Types of out-of-memory issues](how-to-fix-app-restart-issues-caused-by-out-of-memory.md#types-of-out-of-memory-issues) section of [App restart issues caused by out-of-memory issues](how-to-fix-app-restart-issues-caused-by-out-of-memory.md).

+Metaspace and direct memory can be collected only by full GC. When metaspace or direct memory is full, full GC will occur.

+## Java memory configurations

+The following sections describe important aspects of Java memory configuration.

+### Java containerization

+Applications in Azure Spring Apps run in container environments. For more information, see [Containerize your Java applications](/azure/developer/java/containers/overview?toc=/azure/spring-cloud/toc.json&bc=/azure/spring-cloud/breadcrumb/toc.json).

+### Important JVM options

+You can configure the maximum size of each part of memory by using JVM options. You can set JVM options by using Azure CLI commands or through the Azure portal. For more information, see the [Modify configurations to fix problems](tools-to-troubleshoot-memory-issues.md#modify-configurations-to-fix-problems) section of [Tools to troubleshoot memory issues](tools-to-troubleshoot-memory-issues.md).

+The following list describes the JVM options:

+- Heap size configuration

+ - `-Xms` sets the initial heap size by absolute value.

+ - `-Xmx` sets the maximum heap size by absolute value.

+ - `-XX:InitialRAMPercentage` sets the initial heap size by the percentage of heap size / app memory size.

+ - `-XX:MaxRAMPercentage` sets the maximum heap size by the percentage of heap size / app memory size.

+- Direct memory size configuration

+ - `-XX:MaxDirectMemorySize` sets the maximum direct memory size by absolute value. For more information, see [MaxDirectMemorySize](https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-3B1CE181-CD30-4178-9602-230B800D4FAE__GUID-2E02B495-5C36-4C93-8597-0020EFDC9A9C) in the Oracle documentation.

+- Metaspace size configuration

+ - `-XX:MaxMetaspaceSize` sets the maximum metaspace size by absolute value.

+### Default maximum memory size

+The following sections describe how default maximum memory sizes are set.

+#### Default maximum heap size

+Azure Spring Apps sets the default maximum heap memory size to about 50%-80% of app memory for Java apps. Specifically, Azure Spring Apps uses the following settings:

+- If the app memory < 1 GB, the default maximum heap size will be 50% of app memory.

+- If 1 GB <= the app memory < 2 GB, the default maximum heap size will be 60% of app memory.

+- If 2 GB <= the app memory < 3 GB, the default maximum heap size will be 70% of app memory.

+- If 3 GB <= the app memory, the default maximum heap size will be 80% of app memory.

+#### Default maximum direct memory size

+When the maximum direct memory size isn't set using JVM options, the JVM automatically sets the maximum direct memory size to the value returned by [Runtime.getRuntime.maxMemory()](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#maxMemory--). This value is approximately equal to the maximum heap memory size. For more information, see the [JDK 8 VM.java file](http://hg.openjdk.java.net/jdk8u/jdk8u/jdk/file/a71d26266469/src/share/classes/sun/misc/VM.java#l282&gt;%20jdk8).

+### Memory usage layout

+Heap size is influenced by your throughput. Basically, when configuring, you can keep the default maximum heap size, which leaves reasonable memory for other parts.

+The metaspace size depends on the complexity of your code, such as the number of classes.

+The direct memory size depends on your throughput and your use of third party libraries like nio and gzip.

+The following list describes a typical memory layout sample for 2-GB apps. You can refer to this list to configure your memory size settings.

+- Total Memory (2048M)

+- Heap memory: Xmx is 1433.6M (70% of total memory). The reference value of daily memory usage is 1200M.

+ - Young generation

+ - Survivor space (S0, S1)

+ - Eden space

+ - Old generation

+- Non-heap memory

+ - Observed part (observed by Spring Boot Actuator)

+ - Metaspace: the daily usage reference value is 50M-256M

+ - Code cache

+ - Compressed class space

+ - Not observed part (not observed by Spring Boot Actuator): the daily usage reference value is 150M-250M.

+ - Thread stack

+ - GC, internal symbol and other

+- Direct memory: the daily usage reference value is 10M-200M.

+The following diagram shows the same information. Numbers in grey are the reference values of daily memory usage.

+Overall, when configuring maximum memory sizes, you should consider the usage of each part in memory, and the sum of all maximum sizes shouldn't exceed total available memory.

+## Java OOM

+OOM means the application is out of memory. There are two different concepts: container OOM and JVM OOM. For more information, see [App restart issues caused by out-of-memory issues](how-to-fix-app-restart-issues-caused-by-out-of-memory.md).

+## See also

+- [App restart issues caused by out-of-memory issues](how-to-fix-app-restart-issues-caused-by-out-of-memory.md)

+- [Tools to troubleshoot memory issues](tools-to-troubleshoot-memory-issues.md)

+## Prerequisites

+* A deployed Azure Spring Apps instance.

+* An Azure Cache for Redis service instance.

+* The Azure Spring Apps extension for the Azure CLI.

+If you don't have a deployed Azure Spring Apps instance, follow the steps in the [Quickstart: Deploy your first application to Azure Spring Apps](./quickstart.md).

+ <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>

+ <version>4.3.0</version>

+ <groupId>com.azure.spring</groupId>

+ <artifactId>spring-cloud-azure-starter-storage-blob</artifactId>

+ <version>4.3.0</version>

+ spring.cloud.azure.cosmos.endpoint=https://<some account>.documents.azure.com:443

+ spring.cloud.azure.cosmos.key=abc******

+ spring.cloud.azure.cosmos.database=testdb

+The following Terraform script shows how to set up an Azure Spring Apps app with an Azure Cosmos DB account.

+ kind = "GlobalDocumentDB"

+resource "azurerm_cosmosdb_sql_database" "cosmosdb" {

+ quota {

+ cpu = "2"

+ memory = "4Gi"

+ }

+ "spring.cloud.azure.cosmos.endpoint" : azurerm_cosmosdb_account.cosmosdb.endpoint

+ "spring.cloud.azure.cosmos.key" : azurerm_cosmosdb_account.cosmosdb.primary_key

+ "spring.cloud.azure.cosmos.database" : azurerm_cosmosdb_sql_database.cosmosdb.name

+If you don't have a deployed Azure Spring Apps instance, follow the instructions in [Quickstart: Deploy your first application to Azure Spring Apps](./quickstart.md) to deploy your first Spring app.

+ quota {

+ cpu = "2"

+ memory = "4Gi"

+ }

+If you don't have a deployed Azure Spring Apps instance, follow the steps in the [Quickstart: Deploy your first application to Azure Spring Apps](./quickstart.md).

+ quota {

+ cpu = "2"

+ memory = "4Gi"

+ }

+ Title: App restart issues caused by out-of-memory issues

+description: Explains how to understand out-of-memory (OOM) issues for Java applications in Azure Spring Apps.

+# App restart issues caused by out-of-memory issues

+> [!NOTE]

+> Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

+**This article applies to:** ✔️ Basic/Standard tier ✔️ Enterprise tier

+This article describes out-of-memory (OOM) issues for Java applications in Azure Spring Apps.

+## Types of out-of-memory issues

+There are two types of out-of-memory issues: container OOM and JVM OOM.

+- Container OOM, also called *system OOM*, occurs when the available app memory has run out. Container OOM issue causes app restart events, which are reported in the **Resource Health** section of the Azure portal. Normally, container OOM is caused by incorrect memory size configurations.

+- JVM OOM occurs when the amount of used memory has reached the maximum size set in JVM options. JVM OOM won't cause an app to restart. Normally, JVM OOM is a result of bad code, which you can find by looking for `java.lang.OutOfMemoryError` exceptions in the application log. JVM OOM has a negative effect on application and Java Profiling tools, such as Java Flight Recorder.

+This article focuses on how to fix container OOM issues. To fix JVM OOM issues, check tools such as heap dump, thread dump, and Java Flight Recorder. For more information, see [Capture heap dump and thread dump manually and use Java Flight Recorder in Azure Spring Apps](how-to-capture-dumps.md).

+## Fix app restart issues due to OOM

+The following sections describe the tools, metrics, and JVM options that you can use to diagnose and fix container OOM issues.

+### View alerts on the Resource health page

+The **Resource health** page on the Azure portal shows app restart events due to container OOM, as shown in the following screenshot:

+### Configure memory size

+The metrics *App memory Usage*, `jvm.memory.used`, and `jvm.memory.committed` provide a view of memory usage. For more information, see the [Metrics](tools-to-troubleshoot-memory-issues.md#metrics) section of [Tools to troubleshoot memory issues](tools-to-troubleshoot-memory-issues.md). Configure the maximum memory sizes in JVM options to ensure that memory is under the limit.

+The sum of the maximum memory sizes of all the parts in the [Java memory model](concepts-for-java-memory-management.md#java-memory-model) should be less than the real available app memory. To set your maximum memory sizes, see the typical memory layout described in the [Memory usage layout](concepts-for-java-memory-management.md#memory-usage-layout) section of [Java memory management](concepts-for-java-memory-management.md).

+Find a balance when you set the maximum memory size. When you set the maximum memory size too high, there's a risk of container OOM. When you set the maximum memory size too low, there's a risk of JVM OOM, and garbage collection will be of and will slow down the app.

+#### Control heap memory

+You can set the maximum heap size by using the `-Xms`, `-Xmx`, `-XX:InitialRAMPercentage`, and `-XX:MaxRAMPercentage` JVM options.

+You may need to adjust the maximum heap size settings when the value of `jvm.memory.used` is too high in the metrics. For more information, see the [jvm.memory.used/committed/max](tools-to-troubleshoot-memory-issues.md#jvmmemoryusedcommittedmax) section of [Tools to troubleshoot memory issues](tools-to-troubleshoot-memory-issues.md).

+#### Control direct memory

+It's important to set the `-XX:MaxDirectMemorySize` JVM option for the following reasons:

+- You may not notice when frameworks such as nio and gzip use direct memory.

+- Garbage collection of direct memory is only handled during full garbage collection, and full garbage collection occurs only when the heap is near full.

+Normally, you can set `MaxDirectMemorySize` to a value less than the app memory size minus the heap memory minus the non-heap memory.

+#### Control metaspace

+You can set the maximum metaspace size by setting the `-XX:MaxMetaspaceSize` JVM option. The `-XX:MetaspaceSize` option sets the threshold value to trigger full garbage collection.

+Metaspace memory is usually stable.

+## See also

+- [Java memory management](concepts-for-java-memory-management.md)

+- [Tools to troubleshoot memory issues](tools-to-troubleshoot-memory-issues.md)

+ Title: Tools to troubleshoot memory issues

+description: Provides a list of tools for troubleshooting Java memory issues.

+# Tools to troubleshoot memory issues

+> [!NOTE]

+> Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

+**This article applies to:** ✔️ Basic/Standard tier ✔️ Enterprise tier

+This article describes various tools that are useful for troubleshooting Java memory issues. You can use these tools in many scenarios not limited to memory issues, but this article focuses only on the topic of memory.

+## Alerts and diagnostics

+The following sections describe resource health alerts and diagnostics available through the Azure portal.

+### Resource health

+You can monitor app lifecycle events and set up alerts with Azure Activity log and Azure Service Health. For more information, see [Monitor app lifecycle events using Azure Activity log and Azure Service Health](monitor-app-lifecycle-events.md).

+Resource health sends alerts about app restart events due to container out-of-memory (OOM) issues. For more information, see [App restart issues caused by out-of-memory issues](how-to-fix-app-restart-issues-caused-by-out-of-memory.md).

+The following screenshot shows an app resource health alert indicating an OOM issue.

+### Diagnose and solve problems

+Azure Spring Apps diagnostics is an interactive experience to troubleshoot your app without configuration. For more information, see [Self-diagnose and solve problems in Azure Spring Apps](how-to-self-diagnose-solve.md).

+In the Azure portal, you can find **Memory Usage** under **Diagnose and solve problems**, as shown in the following screenshot.

+**Memory Usage** provides a simple diagnosis for app memory usage, as shown in the following screenshot.

+### Metrics

+The following sections describe metrics that cover issues including high memory usage, heap memory that's too large, and abnormal garbage collection abnormal (too frequent or not frequent enough). For more information, see [Quickstart: Monitoring Azure Spring Apps apps with logs, metrics, and tracing](quickstart-logs-metrics-tracing.md?tabs=Azure-CLI&pivots=programming-language-java).

+#### App memory usage

+App memory usage is a percentage equal to the app memory used divided by the app memory limit. This value shows the whole app memory.

+#### jvm.memory.used/committed/max

+For JVM memory, there are three metrics: `jvm.memory.used`, `jvm.memory.committed`, and `jvm.memory.max`, which are described in the following list.

+"JVM memory" isn't a clearly defined concept. Here, `jvm.memory` is the sum of [heap memory](concepts-for-java-memory-management.md#heap-memory) and former permGen part of [non-heap memory](concepts-for-java-memory-management.md#non-heap-memory). JVM memory doesn't include direct memory or other memory like the thread stack. These three metrics are gathered by Spring Boot Actuator, and the scope of `jvm.memory` is also determined by Spring Boot Actuator.

+- `jvm.memory.used` is the amount of used JVM memory, including used heap memory and used former permGen in non-heap memory.

+ `jvm.memory.used` is a major reflection of the change of heap memory, because the former permGen part is usually stable.

+ If you find `jvm.memory.used` too large, consider setting a smaller maximum heap memory size.

+- `jvm.memory.committed` is the amount of memory committed for the JVM to use. The size of `jvm.memory.committed` is basically the limit of usable JVM memory.

+- `jvm.memory.max` is the maximum amount of JVM memory, not to be confused with the real available amount.

+ The value of `jvm.memory.max` can sometimes be confusing because it can be much higher than the available app memory. To clarify, `jvm.memory.max` is the sum of all maximum sizes of heap memory and the former permGen part of [non-heap memory](concepts-for-java-memory-management.md#non-heap-memory), regardless of the real available memory. For example, if an app is set with 1 GB memory in the Azure Spring Apps portal, then the default heap memory size will be 0.5 GB. For more information, see the [Default maximum heap size](concepts-for-java-memory-management.md#default-maximum-heap-size) section of [Java memory management](concepts-for-java-memory-management.md).

+ If the default *compressed class space* size is 1 GB, then the value of `jvm.memory.max` will be larger than 1.5 GB regardless of whether the app memory size 1 GB. For more information, see [Java Platform, Standard Edition HotSpot Virtual Machine Garbage Collection Tuning Guide: Other Considerations](https://docs.oracle.com/javase/9/gctuning/other-considerations.htm) in the Oracle documentation.

+#### jvm.gc.memory.allocated/promoted

+These two metrics are for observing Java garbage collection (GC). For more information, see the [Java garbage collection](concepts-for-java-memory-management.md#java-garbage-collection) section of [Java memory management](concepts-for-java-memory-management.md). The maximum heap size influences the frequency of minor GC and full GC. The maximum metaspace and maximum direct memory size influence full GC. If you want to adjust the frequency of garbage collection, consider modifying the following maximum memory sizes.

+- `jvm.gc.memory.allocated` is the amount of increase in the size of the young generation memory pool after one GC and before the next. This value reflects minor GC.

+- `jvm.gc.memory.promoted` is the amount of increase in the size of the old generation memory pool after GC. This value reflects full GC.

+You can find this feature on the Azure portal, as shown in the following screenshot. You can choose specific metrics and add filters for a specific app, deployment, or instance. You can also apply splitting.

+## Further debugging

+For further debugging, you can manually capture heap dumps and thread dumps, and use Java Flight Recorder (JFR). For more information, see [Capture heap dump and thread dump manually and use Java Flight Recorder in Azure Spring Apps](how-to-capture-dumps.md).

+Heap dump records the state of the Java heap memory. Thread dump records the stacks of all live threads. These tools are available through the Azure CLI and on the app page of the Azure portal, as shown in the following screenshot.

+You can also use third party tools like [Memory Analyzer](https://www.eclipse.org/mat/) to analyze heap dumps.

+## Modify configurations to fix problems

+Some issues you might identify include [container OOM](how-to-fix-app-restart-issues-caused-by-out-of-memory.md#fix-app-restart-issues-due-to-oom), heap memory that's too large, and abnormal garbage collection. If you identify any of these issues, you may need to configure the maximum memory size in the JVM options. For more information, see the [Important JVM options](concepts-for-java-memory-management.md#important-jvm-options) section of [Java memory management](concepts-for-java-memory-management.md#important-jvm-options).

+This feature is available on Azure CLI and on the Azure portal, as shown in the following screenshot:

+## See also

+- [Java memory management](concepts-for-java-memory-management.md)

+- [App restart issues caused by out-of-memory issues](how-to-fix-app-restart-issues-caused-by-out-of-memory.md)

+ Title: Troubleshoot common exit code issues in Azure Spring Apps

+description: Describes how to troubleshoot common exit codes in Azure Spring Apps

+# Troubleshoot common exit code issues in Azure Spring Apps

+> [!NOTE]

+> Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

+**This article applies to:** ✔️ Basic/Standard tier ✔️ Enterprise tier

+This article describes troubleshooting actions you can take when your application in Azure Spring Apps exits with an error code. You may receive an error code if your application deployment is unsuccessful, or if the application exits when it's running.

+## Exit codes

+The exit code indicates the reason the application terminated. The following list describes some common exit codes:

+- **0** - The application exited because it ran to completion. Update your server application so that it runs continuously.

+

+ Deployed Azure apps in Azure Spring Apps should offer services continuously. An exit code of *0* indicates that the application isn't running continuously. Check your logs and source code.

+- **1** - If the application exits with a non-zero exit code, debug the code and related services, and then deploy the application again.

+

+ Consider the following possible causes of a non-zero exit code:

+ - There's something wrong with your Spring Boot configuration.

+ For example, you need a *spring.db.url* parameter to connect to the database, but it's not found in your configuration file.

+ - You're disconnected from a third-party service.

+

+ For example, you need to connect to a Redis service, but the service isn't working or available.

+

+ - You don't have sufficient access to a third-party service.

+ For example, you need to connect to Azure Key Vault to import certificates in your application, but your application doesn't have the necessary permissions to access it.

+- **137** - The application exited because of an out-of-memory error. The application requested resources that the hosting platform failed to provide. Update your application's Java Virtual Machine (JVM) parameters to restrict resource usage or scale up application resources.

+

+ If the application is a Java application, check the JVM parameter values. They may exceed the memory limit of your application.

+ For example, suppose you set the *Xmx* JVM parameter to 10 GB, but the application is using up to 5 GB of memory. Decrease the *Xmx* value or increase the application memory to make sure that the value of the *Xmx* parameter is lower or equal to the memory limit of the application.

+

+- **143** - The application exited because it failed to respond to a health check due to an out-of-memory error or some other error.

+ This error code is most often generated by an out-of-memory error. For more information, see [App restart issues caused by out-of-memory issues](./how-to-fix-app-restart-issues-caused-by-out-of-memory.md).

+ You can also find more information from the application log by using the Azure CLI [az spring app logs](/cli/azure/spring/app#az-spring-app-logs) command.

+## Next steps

+- [Troubleshoot common Azure Spring Apps issues](./troubleshoot.md)

+* [Troubleshoot common exit code issues in Azure Spring Apps](./troubleshoot-exit-code.md)

+az group create --location <location> --name <resource-group-name>

+> Each Key Vault must have a unique name. Replace *\<key-vault-name>* with the name of your Key Vault in the following examples.

+az keyvault create --resource-group <resource-group-name> --name <key-vault-name>

+Make a note of the returned `vaultUri`, which will be in the format `https://<key-vault-name>.vault.azure.net`. It will be used in the following step.

+ --vault-name <key-vault-name> \

+ --name <mysql-password> \

+ --value <mysql-password>

+ --resource-group <resource-group-name> \

+ --server-name <mysql-instance-name>

+az spring create --name <Azure-Spring-Apps-instance-name> --resource-group <resource-group-name>

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name>

+export SERVICE_IDENTITY=$(az spring app show --name springapp -s <Azure-Spring-Apps-instance-name> -g <resource-group-name> | jq -r '.identity.principalId')

+Make a note of the returned `url`, which will be in the format `https://<app-name>.azuremicroservices.io`. It will be used in the following step.

+ --name <key-vault-name> \

+> Use `az keyvault delete-policy --name <key-vault-name> --object-id ${SERVICE_IDENTITY}` to remove the access for your app after system-assigned managed identity is disabled.

+ ```azurecli

+ git clone https://github.com/Azure-Samples/Azure-Spring-Cloud-Samples.git

+ ```

+ ```properties

+ spring.datasource.url=jdbc:mysql://<mysql-instance-name>.mysql.database.azure.com:3306/demo?serverTimezone=UTC

+ spring.datasource.username=<mysql-username>@<mysql-instance-name>

+ spring.cloud.azure.keyvault.secret.endpoint=https://<keyvault-instance-name>.vault.azure.net/

+ ```

+ ```azurecli

+ mvn clean package

+ ```

+ ```azurecli

+ az spring app deploy \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ ```

+ ```bash

+ # Create an entry in table

+ curl --header "Content-Type: application/json" \

+ --request POST \

+ --data '{"description":"configuration","details":"congratulations, you have set up JDBC correctly!","done": "true"}' \

+ https://myspringcloud-springapp.azuremicroservices.io

+ # List entires in table

+ curl https://myspringcloud-springapp.azuremicroservices.io

+ ```

+| Destination Endpoint | Port | Use | Note |

+|-||-|--|

+| \*:1194 *or* [ServiceTag](../virtual-network/service-tags-overview.md#available-service-tags) - AzureCloud:1194 | UDP:1194 | Underlying Kubernetes Cluster management. | |

+| \*:443 *or* [ServiceTag](../virtual-network/service-tags-overview.md#available-service-tags) - AzureCloud:443 | TCP:443 | Azure Spring Apps Service Management. | Information of service instance "requiredTraffics" could be known in resource payload, under "networkProfile" section. |

+| \*:123 *or* ntp.ubuntu.com:123 | UDP:123 | NTP time synchronization on Linux nodes. | |

+| \*.azure.io:443 *or* [ServiceTag](../virtual-network/service-tags-overview.md#available-service-tags) - AzureContainerRegistry:443 | TCP:443 | Azure Container Registry. | Can be replaced by enabling *Azure Container Registry* [service endpoint in virtual network](../virtual-network/virtual-network-service-endpoints-overview.md). |

+| \*.core.windows.net:443 and \*.core.windows.net:445 *or* [ServiceTag](../virtual-network/service-tags-overview.md#available-service-tags) - Storage:443 and Storage:445 | TCP:443, TCP:445 | Azure Files | Can be replaced by enabling *Azure Storage* [service endpoint in virtual network](../virtual-network/virtual-network-service-endpoints-overview.md). |

+| \*.servicebus.windows.net:443 *or* [ServiceTag](../virtual-network/service-tags-overview.md#available-service-tags) - EventHub:443 | TCP:443 | Azure Event Hubs. | Can be replaced by enabling *Azure Event Hubs* [service endpoint in virtual network](../virtual-network/virtual-network-service-endpoints-overview.md). |

+| Destination FQDN | Port | Use |

+|--|--||

+| <i>*.azmk8s.io</i> | HTTPS:443 | Underlying Kubernetes Cluster management. |

+| <i>mcr.microsoft.com</i> | HTTPS:443 | Microsoft Container Registry (MCR). |

+| <i>*.cdn.mscr.io</i> | HTTPS:443 | MCR storage backed by the Azure CDN. |

+| <i>*.data.mcr.microsoft.com</i> | HTTPS:443 | MCR storage backed by the Azure CDN. |

+| <i>management.azure.com</i> | HTTPS:443 | Underlying Kubernetes Cluster management. |

+| <i>*login.microsoftonline.com</i> | HTTPS:443 | Azure Active Directory authentication. |

+| <i>*login.microsoft.com</i> | HTTPS:443 | Azure Active Directory authentication. |

+| <i>packages.microsoft.com</i> | HTTPS:443 | Microsoft packages repository. |

+| *mscrl.microsoft.com*¹ | HTTPS:80 | Required Microsoft Certificate Chain Paths. |

+| *crl.microsoft.com*¹ | HTTPS:80 | Required Microsoft Certificate Chain Paths. |

+| *crl3.digicert.com*¹ | HTTPS:80 | Third-Party TLS/SSL Certificate Chain Paths. |

+| Destination FQDN | Port | Use |

+||||

+| <i>*.live.dynatrace.com</i> | TCP:443 | Required network of Dynatrace APM agents. |

+| <i>*.live.ruxit.com</i> | TCP:443 | Required network of Dynatrace APM agents. |

+| <i>*.saas.appdynamics.com</i> | TCP:443/80 | Required network of AppDynamics APM agents, also see [SaaS Domains and IP Ranges](https://docs.appdynamics.com/display/PAA/SaaS+Domains+and+IP+Ranges). |

+* [Create the project and configure dependencies](#setting-up)

+* [Authenticate to Azure](#authenticate-the-app-to-azure)

+* [Create a container](#create-a-container)

+* [Upload a blob to a container](#upload-a-blob-to-a-container)

+* [List blobs in a container](#list-blobs-in-a-container)

+* [Download a blob](#download-a-blob)

+* [Delete a container](#delete-a-container)

+- [Samples](/azure/storage/common/storage-samples-dotnet?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json#blob-samples)

+- Azure storage account - [create a storage account](/azure/storage/common/storage-account-create)

+For the steps ahead, you'll need to create a .NET console app using either the .NET CLI or Visual Studio 2022.

+### [Visual Studio 2022](#tab/visual-studio)

+1. At the top of Visual Studio, navigate to **File** > **New** > **Project..**.

+1. In the dialog window, enter *console app* into the project template search box and select the first result. Choose **Next** at the bottom of the dialog.

+ :::image type="content" source="media/storage-quickstart-blobs-dotnet/visual-studio-new-console-app.png" alt-text="A screenshot showing how to create a new project using Visual Studio.":::

+1. For the **Project Name**, enter *BlobQuickstartV12*. Leave the default values for the rest of the fields and select **Next**.

+1. For the **Framework**, ensure .NET 6.0 is selected. Then choose **Create**. The new project will open inside the Visual Studio environment.

+### [.NET CLI](#tab/net-cli)

+ ```dotnetcli

+1. Open the project in your desired code editor. To open the project in:

+ * Visual Studio, locate and double-click the `BlobQuickStartV12.csproj` file.

+ * Visual Studio Code, run the following command:

+ ```bash

+ code .

+To interact with Azure Blob Storage, install the Azure Blob Storage client library for .NET.

+### [Visual Studio 2022](#tab/visual-studio)

+1. In **Solution Explorer**, right-click the **Dependencies** node of your project. Select **Manage NuGet Packages**.

+1. In the resulting window, search for *Azure.Storage.Blobs*. Select the appropriate result, and select **Install**.

+ :::image type="content" source="media/storage-quickstart-blobs-dotnet/visual-studio-add-package.png" alt-text="A screenshot showing how to add a new package using Visual Studio.":::

+### [.NET CLI](#tab/net-cli)

+```dotnetcli

+### Set up the app code

+Replace the starting code in the `Program.cs` file so that it matches the following example, which includes the necessary `using` statements for this exercise.

+```csharp

+using Azure.Storage.Blobs;

+using Azure.Storage.Blobs.Models;

+using System;

+using System.IO;

+// See https://aka.ms/new-console-template for more information

+Console.WriteLine("Hello, World!");

+```

+

+The sample code snippets in the following sections demonstrate how to perform basic data operations with the Azure Blob Storage client library for .NET.

+> [!IMPORTANT]

+> Make sure you have installed the correct NuGet packages and added the necessary using statements in order for the code samples to work, as described in the [setting up](#setting-up) section.

+* **Azure.Identity** (if you are using the passwordless approach)

+* **Azure.Storage.Blobs**

+You can call the [CreateBlobContainerAsync](/dotnet/api/azure.storage.blobs.blobserviceclient.createblobcontainerasync) method on the `blobServiceClient` to create a container in your storage account.

+Add this code to the end of the `Program.cs` class:

+```csharp

+// TODO: Replace <storage-account-name> with your actual storage account name

+var blobServiceClient = new BlobServiceClient(

+ new Uri("https://<storage-account-name>.blob.core.windows.net"),

+ new DefaultAzureCredential());

+//Create a unique name for the container

+string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

+// Create the container and return a container client object

+BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

+```

+Add the following code to the end of the `Program.cs` class:

+```csharp

+// Create a local file in the ./data/ directory for uploading and downloading

+string localPath = "data";

+Directory.CreateDirectory(localPath);

+string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";

+string localFilePath = Path.Combine(localPath, fileName);

+// Write text to the file

+await File.WriteAllTextAsync(localFilePath, "Hello, World!");

+// Get a reference to a blob

+BlobClient blobClient = containerClient.GetBlobClient(fileName);

+Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

+// Upload data from the local file

+await blobClient.UploadAsync(localFilePath, true);

+```

+The code snippet completes the following steps:

+Add the following code to the end of the `Program.cs` class:

+```csharp

+Console.WriteLine("Listing blobs...");

+// List all blobs in the container

+await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())

+{

+ Console.WriteLine("\t" + blobItem.Name);

+}

+```

+Add the following code to the end of the `Program.cs` class:

+```csharp

+// Download the blob to a local file

+// Append the string "DOWNLOADED" before the .txt extension

+// so you can compare the files in the data directory

+string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

+Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

+// Download the blob's contents and save it to a file

+await blobClient.DownloadToAsync(downloadFilePath);

+```

+Add the following code to the end of the `Program.cs` class:

+```csharp

+// Clean up

+Console.Write("Press any key to begin clean up");

+Console.ReadLine();

+Console.WriteLine("Deleting blob container...");

+await containerClient.DeleteAsync();

+Console.WriteLine("Deleting the local source and downloaded files...");

+File.Delete(localFilePath);

+File.Delete(downloadFilePath);

+Console.WriteLine("Done");

+```

+## The completed code

+After completing these steps the code in your `Program.cs` file should now resemble the following:

+## [Passwordless (Recommended)](#tab/managed-identity)

+```csharp

+using Azure.Storage.Blobs;

+using Azure.Storage.Blobs.Models;

+using Azure.Identity;

+// TODO: Replace <storage-account-name> with your actual storage account name

+var blobServiceClient = new BlobServiceClient(

+ new Uri("https://<storage-account-name>.blob.core.windows.net"),

+ new DefaultAzureCredential());

+//Create a unique name for the container

+string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

+// Create the container and return a container client object

+BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

+// Create a local file in the ./data/ directory for uploading and downloading

+string localPath = "data";

+Directory.CreateDirectory(localPath);

+string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";

+string localFilePath = Path.Combine(localPath, fileName);

+// Write text to the file

+await File.WriteAllTextAsync(localFilePath, "Hello, World!");

+// Get a reference to a blob

+BlobClient blobClient = containerClient.GetBlobClient(fileName);

+Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

+// Upload data from the local file

+await blobClient.UploadAsync(localFilePath, true);

+Console.WriteLine("Listing blobs...");

+// List all blobs in the container

+await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())

+{

+ Console.WriteLine("\t" + blobItem.Name);

+}

+// Download the blob to a local file

+// Append the string "DOWNLOADED" before the .txt extension

+// so you can compare the files in the data directory

+string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

+Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

+// Download the blob's contents and save it to a file

+await blobClient.DownloadToAsync(downloadFilePath);

+// Clean up

+Console.Write("Press any key to begin clean up");

+Console.ReadLine();

+Console.WriteLine("Deleting blob container...");

+await containerClient.DeleteAsync();

+Console.WriteLine("Deleting the local source and downloaded files...");

+File.Delete(localFilePath);

+File.Delete(downloadFilePath);

+Console.WriteLine("Done");

+```

+## [Connection String](#tab/connection-string)

+```csharp

+using Azure.Storage.Blobs;

+using Azure.Storage.Blobs.Models;

+// TODO: Replace <storage-account-name> with your actual storage account name

+var blobServiceClient = new BlobServiceClient("<storage-account-connection-string>");

+//Create a unique name for the container

+string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

+// Create the container and return a container client object

+BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

+// Create a local file in the ./data/ directory for uploading and downloading

+string localPath = "data";

+Directory.CreateDirectory(localPath);

+string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";

+string localFilePath = Path.Combine(localPath, fileName);

+// Write text to the file

+await File.WriteAllTextAsync(localFilePath, "Hello, World!");

+// Get a reference to a blob

+BlobClient blobClient = containerClient.GetBlobClient(fileName);

+Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

+// Upload data from the local file

+await blobClient.UploadAsync(localFilePath, true);

+Console.WriteLine("Listing blobs...");

+// List all blobs in the container

+await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())

+{

+ Console.WriteLine("\t" + blobItem.Name);

+}

+// Download the blob to a local file

+// Append the string "DOWNLOADED" before the .txt extension

+// so you can compare the files in the data directory

+string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

+Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

+// Download the blob's contents and save it to a file

+await blobClient.DownloadToAsync(downloadFilePath);

+// Clean up

+Console.Write("Press any key to begin clean up");

+Console.ReadLine();

+Console.WriteLine("Deleting blob container...");

+await containerClient.DeleteAsync();

+Console.WriteLine("Deleting the local source and downloaded files...");

+File.Delete(localFilePath);

+File.Delete(downloadFilePath);

+Console.WriteLine("Done");

+```

+If you're using Visual Studio, press F5 to build and run the code and interact with the console app. If you're using the .NET CLI, navigate to your application directory, then build and run the application.

+ Title: Migrate applications to use passwordless authentication with Azure Storage

+description: Learn to migrate existing applications away from Shared Key authorization with the account key to instead use Azure AD and Azure RBAC for enhanced security.

+# Migrate an application to use passwordless connections with Azure services

+Application requests to Azure Storage must be authenticated using either account access keys or passwordless connections. However, you should prioritize passwordless connections in your applications when possible. This tutorial explores how to migrate from traditional authentication methods to more secure, passwordless connections.

+## Security risks associated with Shared Key authorization

+The following code example demonstrates how to connect to Azure Storage using a storage account key. When you create a storage account, Azure generates access keys for that account. Many developers gravitate towards this solution because it feels familiar to options they have worked with in the past. For example, connection strings for storage accounts also use access keys as part of the string. If your application currently uses access keys, consider migrating to passwordless connections using the steps described later in this document.

+```csharp

+var blobServiceClient = new BlobServiceClient(

+ new Uri("https://<storage-account-name>.blob.core.windows.net"),

+ new StorageSharedKeyCredential("<storage-account-name>", "<your-access-key>"));

+```

+Storage account keys should be used with caution. Developers must be diligent to never expose the keys in an unsecure location. Anyone who gains access to the key is able to authenticate. For example, if an account key is accidentally checked into source control, sent through an unsecure email, pasted into the wrong chat, or viewed by someone who shouldn't have permission, there's risk of a malicious user accessing the application. Instead, consider updating your application to use passwordless connections.

+## Migrating to passwordless connections

+Many Azure services support passwordless connections through Azure AD and Role Based Access control (RBAC). These techniques provide robust security features and can be implemented using `DefaultAzureCredential` from the Azure Identity client libraries.

+> [!IMPORTANT]

+> Some languages must implement `DefaultAzureCredential` explicitly in their code, while others utilize `DefaultAzureCredential` internally through underlying plugins or drivers.

+ `DefaultAzureCredential` supports multiple authentication methods and automatically determines which should be used at runtime. This approach enables your app to use different authentication methods in different environments (local dev vs. production) without implementing environment-specific code.

+The order and locations in which `DefaultAzureCredential` searches for credentials can be found in the [Azure Identity library overview](/dotnet/api/overview/azure/Identity-readme#defaultazurecredential) and varies between languages. For example, when working locally with .NET, `DefaultAzureCredential` will generally authenticate using the account the developer used to sign-in to Visual Studio. When the app is deployed to Azure, `DefaultAzureCredential` will automatically switch to use a [managed identity](/azure/active-directory/managed-identities-azure-resources/overview). No code changes are required for this transition.

+> [!NOTE]

+> A managed identity provides a security identity to represent an app or service. The identity is managed by the Azure platform and does not require you to provision or rotate any secrets. You can read more about managed identities in the [overview](/azure/active-directory/managed-identities-azure-resources/overview) documentation.

+The following code example demonstrates how to connect to an Azure Storage account using passwordless connections. The next section describes how to migrate to this setup in more detail.

+A .NET Core application can pass an instance of `DefaultAzureCredential` into the constructor of a service client class. `DefaultAzureCredential` will automatically discover the credentials that are available in that environment.

+```csharp

+var blobServiceClient = new BlobServiceClient(

+ new Uri("https://<your-storage-account>.blob.core.windows.net"),

+ new DefaultAzureCredential());

+```

+## Steps to migrate an app to use passwordless authentication

+The following steps explain how to migrate an existing application to use passwordless connections instead of a key-based solution. These same migration steps should apply whether you are using access keys directly, or through connection strings.

+### Configure roles and users for local development authentication

+### Sign-in and migrate the app code to use passwordless connections

+For local development, make sure you're authenticated with the same Azure AD account you assigned the role to on your Blob Storage account. You can authenticate via the Azure CLI, Visual Studio, Azure PowerShell, or other tools such as IntelliJ.

+Next you will need to update your code to use passwordless connections.

+1. To use `DefaultAzureCredential` in a .NET application, add the **Azure.Identity** NuGet package to your application.

+ ```dotnetcli

+ dotnet add package Azure.Identity

+ ```

+1. At the top of your `Program.cs` file, add the following `using` statement:

+ ```csharp

+ using Azure.Identity;

+ ```

+1. Identify the locations in your code that currently create a `BlobServiceClient` to connect to Azure Storage. This task is often handled in `Program.cs`, potentially as part of your service registration with the .NET dependency injection container. Update your code to match the following example:

+ ```csharp

+ // TODO: Update <storage-account-name> placeholder to your account name

+ var blobServiceClient = new BlobServiceClient(

+ new Uri("https://<storage-account-name>.blob.core.windows.net"),

+ new DefaultAzureCredential());

+ ```

+1. Make sure to update the storage account name in the URI of your `BlobServiceClient`. The storage account name can be found on the overview page of the Azure portal.

+ :::image type="content" source="../blobs/media/storage-quickstart-blobs-dotnet/storage-account-name.png" alt-text="A screenshot showing how to find the storage account name.":::

+#### Run the app locally

+After making these code changes, run your application locally. The new configuration should pick up your local credentials, such as the Azure CLI, Visual Studio, or IntelliJ. The roles you assigned to your local dev user in Azure will allow your app to connect to the Azure service locally.

+### Configure the Azure hosting environment

+Once your application is configured to use passwordless connections and runs locally, the same code can authenticate to Azure services after it is deployed to Azure. For example, an application deployed to an Azure App Service instance that has a managed identity enabled can connect to Azure Storage.

+#### Create the managed identity using the Azure portal

+The following steps demonstrate how to create a system-assigned managed identity for various web hosting services. The managed identity can securely connect to other Azure Services using the app configurations you setup previously.

+### [Service Connector](#tab/service-connector)

+Some app hosting environments support Service Connector, which helps you connect Azure compute services to other backing services. Service Connector automatically configures network settings and connection information. You can learn more about Service Connector and which scenarios are supported on the [overview page](/azure/service-connector/overview).

+The following compute services are currently supported:

+* Azure App Service

+* Azure Spring Cloud

+* Azure Container Apps (preview)

+For this migration guide you will use App Service, but the steps are similar on Azure Spring Apps and Azure Container Apps.

+> [!NOTE]

+> Azure Spring Apps currently only supports Service Connector using connection strings.

+1. On the main overview page of your App Service, select **Service Connector** from the left navigation.

+1. Select **+ Create** from the top menu and the **Create connection** panel will open. Enter the following values:

+ * **Service type**: Choose **Storage blob**.

+ * **Subscription**: Select the subscription you would like to use.

+ * **Connection Name**: Enter a name for your connection, such as *connector_appservice_blob*.

+ * **Client type**: Leave the default value selected or choose the specific client you'd like to use.

+

+ Select **Next: Authentication**.

+ :::image type="content" source="media/migration-create-identity-small.png" alt-text="A screenshot showing how to create a system assigned managed identity." lightbox="media/migration-create-identity.png":::

+1. Make sure **System assigned managed identity (Recommended)** is selected, and then choose **Next: Networking**.

+1. Leave the default values selected, and then choose **Next: Review + Create**.

+1. After Azure validates your settings, click **Create**.

+The Service Connector will automatically create a system-assigned managed identity for the app service. The connector will also assign the managed identity a **Storage Blob Data Contributor** role for the storage account you selected.

+### [App Service](#tab/app-service)

+1. On the main overview page of your App Service, select **Identity** from the left navigation.

+1. Under the **System assigned** tab, make sure to set the **Status** field to **on**. A system assigned identity is managed by Azure internally and handles administrative tasks for you. The details and IDs of the identity are never exposed in your code.

+ :::image type="content" source="media/migration-create-identity-small.png" alt-text="A screenshot showing how to create a system assigned managed identity." lightbox="media/migration-create-identity.png":::

+### [Spring Apps](#tab/spring-apps)

+1. On the main overview page of your Azure Spring App, select **Identity** from the left navigation.

+1. Under the **System assigned** tab, make sure to set the **Status** field to **on**. A system assigned identity is managed by Azure internally and handles administrative tasks for you. The details and IDs of the identity are never exposed in your code.

+ :::image type="content" source="media/storage-migrate-credentials/spring-apps-identity.png" alt-text="A screenshot showing how to enable managed identity for spring apps.":::

+### [Container Apps](#tab/container-apps)

+1. On the main overview page of your Azure Container App, select **Identity** from the left navigation.

+1. Under the **System assigned** tab, make sure to set the **Status** field to **on**. A system assigned identity is managed by Azure internally and handles administrative tasks for you. The details and IDs of the identity are never exposed in your code.

+ :::image type="content" source="media/storage-migrate-credentials/container-apps-identity.png" alt-text="A screenshot showing how to enable managed identity for container apps.":::

+### [Virtual Machines](#tab/virtual-machines)

+1. On the main overview page of your Azure Spring App, select **Identity** from the left navigation.

+1. Under the **System assigned** tab, make sure to set the **Status** field to **on**. A system assigned identity is managed by Azure internally and handles administrative tasks for you. The details and IDs of the identity are never exposed in your code.

+ :::image type="content" source="media/storage-migrate-credentials/virtual-machine-identity.png" alt-text="A screenshot showing how to enable managed identity for virtual machines.":::

+You can also enable managed identity on an Azure hosting environment using the Azure CLI.

+### [Service Connector](#tab/service-connector-identity)

+You can create a Service Connection between an Azure compute hosting environment and a target service using the Azure CLI. The CLI automatically handles creating a managed identity and assigns the proper role, as explained in the [portal instructions](#create-the-managed-identity-using-the-azure-portal).

+If you are using an Azure App Service, use the `az webapp connection` command:

+```azurecli

+az webapp connection create storage-blob --resource-group <resource-group-name> --name <app-service-name> --target-resource-group <target-resource-group-name> --account <target-storage-account-name> --system-identity

+```

+If you are using Azure Spring Apps, use `the az spring-cloud connection` command:

+```azurecli

+az spring-cloud connection create storage-blob --resource-group <resource-group-name> --service <spring-cloud-service-name> --app <spring-app-name> --deployment <deployment-name> --target-resource-group <target-resource-group> --account <target-storage-account-name> --system-identity

+```

+If you are using Azure Container Apps, use the `az containerapp connection` command:

+```azurecli

+az containerapp connection create storage-blob --resource-group <resource-group-name> --name <containerapp-name> --target-resource-group <target-resource-group-name> --account <target-storage-account-name> --system-identity

+```

+### [App Service](#tab/app-service-identity)

+You can assign a managed identity to an Azure App Service with the [az webapp identity assign](/cli/azure/webapp/identity) command.

+```azurecli

+az webapp identity assign --resource-group <resource-group-name> --name <app-service-name>

+```

+### [Spring Apps](#tab/spring-apps-identity)

+You can assign a managed identity to an Azure Spring App with the [az spring app identity assign](/cli/azure/spring/app/identity) command.

+```azurecli

+az spring app identity assign --resource-group <resource-group-name> --name <app-service-name> --service <service-name>

+```

+### [Container Apps](#tab/container-apps-identity)

+You can assign a managed identity to an Azure Container App with the [az containerapp identity assign](/cli/azure/containerapp/identity) command.

+```azurecli

+az containerapp identity assign --resource-group <resource-group-name> --name <app-service-name>

+```

+### [Virtual Machines](#tab/virtual-machines-identity)

+You can assign a managed identity to a Virtual Machine with the [az vm identity assign](/cli/azure/vm/identity) command.

+```azurecli

+az vm identity assign --resource-group <resource-group-name> --name <app-service-name>

+```

+### [AKS](#tab/aks-identity)

+You can assign a managed identity to an Azure Kubernetes Service with the [az aks update](/cli/azure/aks) command.

+```azurecli

+az vm identity assign --resource-group <resource-group-name> --name <app-service-name>

+```

+#### Assign roles to the managed identity

+Next, you need to grant permissions to the managed identity you created to access your storage account. You can do this by assigning a role to the managed identity, just like you did with your local development user.

+### [Service Connector](#tab/assign-role-service-connector)

+If you connected your services using the Service Connector you do not need to complete this step. The necessary configurations were handled for you:

+* If you selected a managed identity while creating the connection, a system-assigned managed identity was created for your app and assigned the **Storage Blob Data Contributor** role on the storage account.

+* If you selected connection string, the connection string was added as an app environment variable.

+### [Azure portal](#tab/assign-role-azure-portal)

+1. Navigate to your storage account overview page and select **Access Control (IAM)** from the left navigation.

+1. Choose **Add role assignment**

+ :::image type="content" source="media/migration-add-role-small.png" alt-text="A screenshot showing how to add a role to a managed identity." lightbox="media/migration-add-role.png":::

+1. In the **Role** search box, search for *Storage Blob Data Contributor*, which is a common role used to manage data operations for blobs. You can assign whatever role is appropriate for your use case. Select the *Storage Blob Data Contributor* from the list and choose **Next**.

+1. On the **Add role assignment** screen, for the **Assign access to** option, select **Managed identity**. Then choose **+Select members**.

+1. In the flyout, search for the managed identity you created by entering the name of your app service. Select the system assigned identity, and then choose **Select** to close the flyout menu.

+ :::image type="content" source="media/migration-select-identity-small.png" alt-text="A screenshot showing how to select the assigned managed identity." lightbox="media/migration-select-identity.png":::

+1. Select **Next** a couple times until you're able to select **Review + assign** to finish the role assignment.

+### [Azure CLI](#tab/assign-role-azure-cli)

+To assign a role at the resource level using the Azure CLI, you first must retrieve the resource ID using the az storage account show command. You can filter the output properties using the --query parameter.

+```azurecli

+az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

+```

+Copy the output ID from the preceding command. You can then assign roles using the az role command of the Azure CLI.

+```azurecli

+az role assignment create --assignee "<your-username>" \

+ --role "Storage Blob Data Contributor" \

+ --scope "<your-resource-id>"

+```

+#### Test the app

+After making these code changes, browse to your hosted application in the browser. Your app should be able to connect to the storage account successfully. Keep in mind that it may take several minutes for the role assignments to propagate through your Azure environment. Your application is now configured to run both locally and in a production environment without the developers having to manage secrets in the application itself.

+## Next steps

+In this tutorial, you learned how to migrate an application to passwordless connections.

+You can read the following resources to explore the concepts discussed in this article in more depth:

+- For more information on authorizing access with managed identity, visit [Authorize access to blob data with managed identities for Azure resources](/azure/storage/blobs/authorize-managed-identity).

+-[Authorize with Azure roles](/azure/storage/blobs/authorize-access-azure-active-directory)

+- To learn more about .NET Core, see [Get started with .NET in 10 minutes](https://dotnet.microsoft.com/learn/dotnet/hello-world-tutorial/intro).

+- To learn more about authorizing from a web application, visit [Authorize from a native or web application](/azure/storage/common/storage-auth-aad-app)

+ Title: Configure passwordless connections between multiple services

+description: Learn to work with user-assigned managed identities to configure passwordless connections between multiple Azure services.

+# Configure passwordless connections between multiple Azure apps and services

+Applications often require secure connections between multiple Azure services simultaneously. For example, an enterprise Azure App Service instance might connect to several different storage accounts, an Azure SQL database instance, a service bus, and more.

+[Managed identities](/azure/active-directory/managed-identities-azure-resources/overview) are the recommended authentication option for secure, passwordless connections between Azure resources. Developers do not have to manually track and manage many different secrets for managed identities, since most of these tasks are handled internally by Azure. This tutorial explores how to manage connections between multiple services using managed identities and the Azure Identity client library.

+## Compare the types of managed identities

+Azure provides the following types of managed identities:

+* **System-assigned managed identities** are directly tied to a single Azure resource. When you enable a system-assigned managed identity on a service, Azure will create a linked identity and handle administrative tasks for that identity internally. When the Azure resource is deleted, the identity is also deleted.

+* **User-assigned managed identities** are independent identities that are created by an administrator and can be associated with one or more Azure resources. The lifecycle of the identity is independent of those resources.

+You can read more about best practices and when to use system-assigned identities versus user-assigned identities in the [identities best practice recommendations](/azure/active-directory/managed-identities-azure-resources/managed-identity-best-practice-recommendations).

+## Explore DefaultAzureCredential

+Managed identities are generally implemented in your application code through a class called `DefaultAzureCredential` from the `Azure.Identity` client library. `DefaultAzureCredential` supports multiple authentication methods and automatically determines which should be used at runtime. You can read more about this approach in the [DefaultAzureCredential overview](/dotnet/api/overview/azure/Identity-readme#defaultazurecredential).

+## Connect an Azure hosted app to multiple Azure services

+You have been tasked with connecting an existing app to multiple Azure services and databases using passwordless connections. The application is an ASP.NET Core Web API hosted on Azure App Service, though the steps below apply to other Azure hosting environments as well, such as Azure Spring Apps, Virtual Machines, Container Apps and AKS.

+This tutorial applies to the following architectures, though it can be adapted to many other scenarios as well through minimal configuration changes.

+The following steps demonstrate how to configure an app to use a system-assigned managed identity and your local development account to connect to multiple Azure Services.

+### Create a system-assigned managed identity

+1) In the Azure portal, navigate to the hosted application that you would like to connect to other services.

+2) On the service overview page, select **Identity**.

+3) Toggle the **Status** setting to **On** to enable a system assigned managed identity for the service.

+ :::image type="content" source="media/enable-system-assigned-identity.png" alt-text="A screenshot showing how to assign a system assigned managed identity." :::

+### Assign roles to the managed identity for each connected service

+

+1) Navigate to the overview page of the storage account you would like to grant access your identity access to.

+3) Select **Access Control (IAM)** from the storage account navigation.

+4) Choose **+ Add** and then **Add role assignment**.

+ :::image type="content" source="media/assign-role-system-identity.png" alt-text="A screenshot showing how to assign a system-assigned identity." :::

+5) In the **Role** search box, search for *Storage Blob Data Contributor*, which grants permissions to perform read and write operations on blob data. You can assign whatever role is appropriate for your use case. Select the *Storage Blob Data Contributor* from the list and choose **Next**.

+6) On the **Add role assignment** screen, for the **Assign access to** option, select **Managed identity**. Then choose **+Select members**.

+7) In the flyout, search for the managed identity you created by entering the name of your app service. Select the system assigned identity, and then choose **Select** to close the flyout menu.

+ :::image type="content" source="media/migration-select-identity.png" alt-text="A screenshot showing how to select a system-assigned identity." :::

+8) Select **Next** a couple times until you're able to select **Review + assign** to finish the role assignment.

+9) Repeat this process for the other services you would like to connect to.

+#### Local development considerations

+You can also enable access to Azure resources for local development by assigning roles to a user account the same way you assigned roles to your managed identity.

+1) After assigning the **Storage Blob Data Contributor** role to your managed identity, under **Assign access to**, this time select **User, group or service principal**. Choose **+ Select members** to open the flyout menu again.

+2) Search for the *user@domain* account or Azure AD security group you would like to grant access to by email address or name, and then select it. This should be the same account you use to sign-in to your local development tooling with, such as Visual Studio or the Azure CLI.

+> [!NOTE]

+> You can also assign these roles to an Azure Active Directory security group if you are working on a team with multiple developers. You can then place any developer inside that group who needs access to develop the app locally.

+### Implement the application code

+Inside of your project, add a reference to the `Azure.Identity` NuGet package. This library contains all of the necessary entities to implement `DefaultAzureCredential`. You can also add any other Azure libraries that are relevant to your app. For this example, the `Azure.Storage.Blobs` and `Azure.KeyVault.Keys` packages are added in order to connect to Blob Storage and Key Vault.

+```dotnetcli

+dotnet add package Azure.Identity

+dotnet add package Azure.Storage.Blobs

+dotnet add package Azure.KeyVault.Keys

+```

+At the top of your `Program.cs` file, add the following using statements:

+```csharp

+using Azure.Identity;

+using Azure.Storage.Blobs;

+using Azure.Security.KeyVault.Keys;

+```

+In the `Program.cs` file of your project code, create instances of the necessary services your app will connect to. The following examples connect to Blob Storage and service bus using the corresponding SDK classes.

+```csharp

+var blobServiceClient = new BlobServiceClient(

+ new Uri("https://<your-storage-account>.blob.core.windows.net"),

+ new DefaultAzureCredential(credOptions));

+var serviceBusClient = new ServiceBusClient("<your-namespace>", new DefaultAzureCredential());

+var sender = serviceBusClient.CreateSender("producttracking");

+```

+When this application code runs locally, `DefaultAzureCredential` will search down a credential chain for the first available credentials. If the `Managed_Identity_Client_ID` is null locally, it will automatically use the credentials from your local Azure CLI or Visual Studio sign-in. You can read more about this process in the [Azure Identity library overview](/dotnet/api/overview/azure/Identity-readme#defaultazurecredential).

+When the application is deployed to Azure, `DefaultAzureCredential` will automatically retrieve the `Managed_Identity_Client_ID` variable from the app service environment. That value becomes available when a managed identity is associated with your app.

+This overall process ensures that your app can run securely locally and in Azure without the need for any code changes.

+## Connect multiple apps using multiple managed identities

+Although the apps in the previous example all shared the same service access requirements, real environments are often more nuanced. Consider a scenario where multiple apps all connect to the same storage accounts, but two of the apps also access different services or databases.

+To configure this setup in your code, make sure your application registers separate services to connect to each storage account or database. Make sure to pull in the correct managed identity client IDs for each service when configuring `DefaultAzureCredential`. The following code example configures the following service connections:

+* Two connections to separate storage accounts using a shared user-assigned managed identity

+* A connection to Azure Cosmos DB and Azure SQL services using a second shared user-assigned managed identity

+```csharp

+// Get the first user-assigned managed identity ID to connect to shared storage

+var clientIDstorage = Environment.GetEnvironmentVariable("Managed_Identity_Client_ID_Storage");

+// First blob storage client that using a managed identity

+BlobServiceClient blobServiceClient = new BlobServiceClient(

+ new Uri("https://<receipt-storage-account>.blob.core.windows.net"),

+ new DefaultAzureCredential()

+ {

+ ManagedIdentityClientId = clientIDstorage

+ });

+// Second blob storage client that using a managed identity

+BlobServiceClient blobServiceClient2 = new BlobServiceClient(

+ new Uri("https://<contract-storage-account>.blob.core.windows.net"),

+ new DefaultAzureCredential()

+{

+ ManagedIdentityClientId = clientIDstorage

+ });

+// Get the second user-assigned managed identity ID to connect to shared databases

+var clientIDdatabases = Environment.GetEnvironmentVariable("Managed_Identity_Client_ID_Databases");

+// Create a Cosmos DB client

+CosmosClient client = new CosmosClient(

+ accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT", EnvironmentVariableTarget.Process),

+ new DefaultAzureCredential()

+ {

+ ManagedIdentityClientId = clientIDdatabases

+ });

+// Open a connection to Azure SQL using a managed identity

+string ConnectionString1 = @"Server=<azure-sql-hostname>.database.windows.net; User Id=ObjectIdOfManagedIdentity; Authentication=Active Directory Default; Database=<database-name>";

+using (SqlConnection conn = new SqlConnection(ConnectionString1))

+{

+ conn.Open();

+}

+```

+You can also associate a user-assigned managed identity as well as a system-assigned managed identity to a resource simultaneously. This can be useful in scenarios where all of the apps require access to the same shared services, but one of the apps also has a very specific dependency on an additional service. Using a system-assigned identity also ensures that the identity tied to that specific app is deleted when the app is deleted, which can help keep your environment clean.

+These types of scenarios are explored in more depth in the [identities best practice recommendations](/azure/active-directory/managed-identities-azure-resources/managed-identity-best-practice-recommendations).

+## Next steps

+In this tutorial, you learned how to migrate an application to passwordless connections. You can read the following resources to explore the concepts discussed in this article in more depth:

+- For more information on authorizing access with managed identity, visit [Authorize access to blob data with managed identities for Azure resources](/azure/storage/blobs/authorize-managed-identity).

+-[Authorize with Azure roles](/azure/storage/blobs/authorize-access-azure-active-directory)

+- To learn more about .NET Core, see [Get started with .NET in 10 minutes](https://dotnet.microsoft.com/learn/dotnet/hello-world-tutorial/intro).

+- To learn more about authorizing from a web application, visit [Authorize from a native or web application](/azure/storage/common/storage-auth-aad-app)