+ Title: Find help and open a support ticket for Azure Active Directory B2C

+description: Learn how to find technical, pre-sales, billing, and subscription help and open a support ticket for Azure Active Directory B2C

+# Find help and open a support ticket for Azure Active Directory B2C

+Microsoft provides global technical, pre-sales, billing, and subscription support for Azure Active Directory B2C (Azure AD B2C). Support is available both online and by phone for Microsoft Azure paid and trial subscriptions. Phone support and online billing support are available in additional languages.

+## Find help without opening a support ticket

+Before creating a support ticket, check out the following resources for answers and information.

+* For content such as how-to information or code samples for IT professionals and developers, see the [technical documentation for Azure AD B2C at docs.microsoft.com](../active-directory-b2c/index.yml).

+* The [Microsoft Technical Community](https://techcommunity.microsoft.com/) is the place for our IT pro partners and customers to collaborate, share, and learn. The [Microsoft Technical Community Info Center](https://techcommunity.microsoft.com/t5/Community-Info-Center/ct-p/Community-Info-Center) is used for announcements, blog posts, ask-me-anything (AMA) interactions with experts, and more. You can also [join the community to submit your ideas](https://techcommunity.microsoft.com/t5/Communities/ct-p/communities).

+## Open a support ticket

+If you're unable to find answers by using self-help resources, you can open an online support ticket. You should open each support ticket for only a single problem to enable us to connect you to the support engineers who are subject matter experts for your problem. Also, Azure AD B2C engineering teams prioritize their work based on incidents that are generated, so you're often contributing to service improvements.

+### How to open a support ticket for Azure AD B2C in the Azure portal

+> [!NOTE]

+> For billing or subscription issues, use the [Microsoft 365 admin center](https://admin.microsoft.com).

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

+1. Make sure you're using the Azure Active Directory (Azure AD) tenant that contains your Azure subscription:

+ 1. In the Azure portal toolbar, select the **Directories + subscriptions** (:::image type="icon" source="./../active-directory/develop/media/common/portal-directory-subscription-filter.png" border="false":::) icon.

+

+ 1. On the **Portal settings | Directories + subscriptions** page, find your Azure AD directory in the **Directory name** list, and then select **Switch** button next to it.

+

+1. In the Azure portal, search for and select **Azure Active Directory**.

+1. In the left menu, under **Troubleshooting + Support**, select **New support request**.

+

+1. On the **1. Problem description** tab:

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

+ 1. For **Subscription**, select your Azure subscription.

+ 1. For **Service type**, select **Azure Active Directory Business to Consumer (B2C)**. This action shows **Summary** and **Problem type** fields.

+

+ 1. For **Summary**, write a descriptive summary for your request. The summary needs to be under 140 characters.

+

+ 1. For **Problem type**, and then select a category for that type.

+1. Select **Next**.

+1. Under the **2. Recommended solution** tab, you're offered self-help solution and documentation. If none of the solutions recommended resolves your problem, select **Next**.

+1. Under **3. Additional details** tab, fill out the required details accurately. For example:

+ 1. Your tenant ID or domain name. See how to find your [tenant ID](tenant-management.md#get-your-tenant-id) or [tenant name](tenant-management.md#get-your-tenant-name).

+ 1. The time and date when the problem occurred.

+

+ 1. Additional details to describe the problem.

+

+ 1. Under **Advanced diagnostic information**, select **Yes (Recommended)** to allow Microsoft support to access your Azure resources for faster problem resolution.

+

+ 1. Select a **[Severity](https://azure.microsoft.com/support/plans/response)**, and your preferred contact method.

+

+ :::image type="content" source="media/find-help-and-submit-support-ticket/find-help-and-submit-support-ticket-1.png" alt-text="Screenshot of how to find help and submit support ticket part 1.":::

+ :::image type="content" source="media/find-help-and-submit-support-ticket/find-help-and-submit-support-ticket-2.png" alt-text="Screenshot of how to find help and submit support ticket part 2.":::

+

+1. Select **Next**. Under **4. Review + create**, you'll see a summary of your support ticket.

+1. If the details of your support ticket are accurate, select **Create** to submit the support ticket. Otherwise, select **Previous** to make corrections.

+ :::image type="content" source="media/find-help-and-submit-support-ticket/review-and-create.png" alt-text="Screenshot of how to find help and submit support ticket Review and create tab.":::

+## Next steps

+* [Microsoft Tech Community](https://techcommunity.microsoft.com/)

+* [Technical documentation for Azure AD B2C at docs.microsoft.com](../active-directory-b2c/index.yml)

+- If you build an SDK and want to write your own token cache serializer for confidential client applications, inherit from [Microsoft.Identity.Web.MsalAbstractTokenCacheProvider](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.TokenCache/MsalAbstractTokenCacheProvider.cs) and override the `WriteCacheBytesAsync` and `ReadCacheBytesAsync` methods.

+If you want to write your own token cache serializer for confidential client applications, we recommend that you inherit from [Microsoft.Identity.Web.MsalAbstractTokenCacheProvider](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.TokenCache/MsalAbstractTokenCacheProvider.cs) and override the `WriteCacheBytesAsync` and `ReadCacheBytesAsync` methods.

+ Title: Create simpler and faster rules for dynamic groups - Azure AD | Microsoft Docs

+description: How to optimize your membership rules to automatically populate groups.

+documentationcenter: ''

+# Create simpler, more efficient rules for dynamic groups in Azure Active Directory

+The team for Azure Active Directory (Azure AD) sees numerous incidents related to dynamic groups and the processing time for their membership rules. This article contains the methods by which our engineering team helps customers to simplify their membership rules. Simpler and more efficient rules result in better dynamic group processing times. When writing membership rules for dynamic groups, these are steps you can take to ensure the rules are as efficient as possible.

+## Minimize use of MATCH

+Minimize the usage of the 'match' operator in rules as much as possible. Instead, explore if it's possible to use the `contains`, `startswith`, or `-eq` operators. Considering using other properties that allow you to write rules to select the users you want to be in the group without using the `-match` operator. For example, if you want a rule for the group for all users whose city is Lagos, then instead of using rules like:

+- `user.city -match "ago"`

+- `user.city -match ".*?ago.*"`

+It's better to use rules like:

+- `user.city -contains "ago,"`

+- `user.city -startswith "Lag,"`

+Or, best of all:

+- `user.city -eq "Lagos"`

+## Use fewer OR operators

+In your rule, identify when it uses various values for the same property linked together with `-or` operators. Instead, use the `-in` operator to group them into a single criterion to make the rule easier to evaluate. For example, instead of having a rule like this:

+```

+(user.department -eq "Accounts" -and user.city -eq "Lagos") -or

+(user.department -eq "Accounts" -and user.city -eq "Ibadan") -or

+(user.department -eq "Accounts" -and user.city -eq "Kaduna") -or

+(user.department -eq "Accounts" -and user.city -eq "Abuja") -or

+(user.department -eq "Accounts" -and user.city -eq "Port Harcourt")

+```

+It's better to have a rule like this:

+- `user.department -eq "Accounts" -and user.city -in ["Lagos", "Ibadan", "Kaduna", "Abuja", "Port Harcourt"]`

+Conversely, identify similar sub criteria with the same property not equal to various values, that are linked with `-and` operators. Then use the `-notin` operator to group them into a single criterion to make the rule easier to understand and evaluate. For example, instead of using a rule like this:

+- `(user.city -ne "Lagos") -and (user.city -ne "Ibadan") -and (user.city -ne "Kaduna") -and (user.city -ne "Abuja") -and (user.city -ne "Port Harcourt")`

+It's better to use a rule like this:

+- `user.city -notin ["Lagos", "Ibadan", "Kaduna", "Abuja", "Port Harcourt"]`

+## Avoid redundant criteria

+Ensure that you aren't using redundant criteria in your rule. For example, instead of using a rule like this:

+- `user.city -eq "Lagos" or user.city -startswith "Lag"`

+It's better to use a rule like this:

+- `user.city -startswith "Lag"`

+## Next steps

+- [Create a dynamic group](groups-dynamic-membership.md)

+>This information last updated on April 13th, 2022.<br/>You can also download a CSV version of this table [here](https://download.microsoft.com/download/e/3/e/e3e9faf2-f28b-490a-9ada-c6089a1fc5b0/Product%20names%20and%20service%20plan%20identifiers%20for%20licensing.csv).

+| Microsoft Defender for Endpoint P1 | DEFENDER_ENDPOINT_P1 | 16a55f2f-ff35-4cd5-9146-fb784e3761a5 | Intune_Defender (1689aade-3d6a-4bfc-b017-46d2672df5ad)<br/>MDE_LITE (292cc034-7b7c-4950-aaf5-943befd3f1d4) | MDE_SecurityManagement (1689aade-3d6a-4bfc-b017-46d2672df5ad)<br/>Microsoft Defender for Endpoint Plan 1 (292cc034-7b7c-4950-aaf5-943befd3f1d4) |

+| Microsoft Teams Rooms Standard without Audio Conferencing | MEETING_ROOM_NOAUDIOCONF | 61bec411-e46a-4dab-8f46-8b58ec845ffe | MCOEV (4828c8ec-dc2e-4779-b502-87ac9ce28ab7)<br/>TEAMS1 (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>MCOSTANDARD (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>WHITEBOARD_PLAN3 (4a51bca5-1eff-43f5-878c-177680f191af)<br/>INTUNE_A (c1ec4a95-1f05-45b3-a911-aa3fa01094f5) | Microsoft 365 Phone System (4828c8ec-dc2e-4779-b502-87ac9ce28ab7)<br/>Microsoft Teams (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>Skype for Business Online (Plan 2) (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Whiteboard (Plan 3) (4a51bca5-1eff-43f5-878c-177680f191af)<br/>Microsoft Intune (c1ec4a95-1f05-45b3-a911-aa3fa01094f5) |

+ Title: Customer data storage for Japan customers - Azure AD

+description: Learn about where Azure Active Directory stores customer-related data for its Japan customers.

+# Customer data storage for Japan customers in Azure Active Directory

+Azure Active Directory (Azure AD) stores its Customer Data in a geographical location based on the country you provided when you signed up for a Microsoft Online service. Microsoft Online services include Microsoft 365 and Azure.

+For information about where Azure AD and other Microsoft services' data is located, see the [Where your data is located](https://www.microsoft.com/trust-center/privacy/data-location) section of the Microsoft Trust Center.

+From April 15, 2022, Microsoft began storing Azure ADΓÇÖs Customer Data for new tenants with a Japan billing address within the Japanese datacenters. From April 15, 2022 to June 30, 2022 a backup copy of the Azure ADΓÇÖs Customer Data for these new tenants will be stored in Asia to ensure a smooth transition to the Japanese datacenters. This copy will be destroyed on June 30, 2022.

+Additionally, certain Azure AD features do not yet support storage of Customer Data in Japan. Please go to the [Azure AD data map](https://msit.powerbi.com/view?r=eyJrIjoiYzEyZTc5OTgtNTdlZS00ZTVkLWExN2ItOTM0OWU4NjljOGVjIiwidCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsImMiOjV9), for specific feature information. For example, Microsoft Azure AD Multi-Factor Authentication stores Customer Data in the US and processes it globally. See [Data residency and customer data for Azure AD Multi-Factor Authentication](../authentication/concept-mfa-data-residency.md).

+> [!NOTE]

+> Microsoft products, services, and third-party applications that integrate with Azure AD have access to Customer Data. Evaluate each product, service, and application you use to determine how Customer Data is processed by that specific product, service, and application, and whether they meet your company's data storage requirements. For more information about Microsoft services' data residency, see the [Where your data is located](https://www.microsoft.com/trust-center/privacy/data-location) section of the Microsoft Trust Center.

+## Azure role-based access control (Azure RBAC)

+Role definitions, role assignments, and deny assignments are stored globally to ensure that you have access to your resources regardless of the region you created the resource. For more information, see [What is Azure role-based access control (Azure RBAC)?](../../role-based-access-control/overview.md#where-is-azure-rbac-data-stored).

+# Request to Publish your application in the Azure Active Directory application gallery

+- Support for single sign-on (SSO). To learn more about the supported options, see [Plan a single sign-on deployment](plan-sso-deployment.md).

+ - For password SSO, make sure that your application supports form authentication so that password vaulting can be used.

+ - For federated applications (OpenID and SAML/WS-Fed), the application must support the [software-as-a-service (SaaS) model](https://azure.microsoft.com/overview/what-is-saas/) to be listed in the gallery. The enterprise gallery applications must support multiple user configurations and not any specific user.

+ - For Open ID Connect, the application must be multitenanted and the [Azure AD consent framework](../develop/consent-framework.md) must be properly implemented for the application.

+- Supporting provisioning is optional, but highly recommended. To learn more about the Azure AD SCIM implementation, see [build a SCIM endpoint and configure user provisioning with Azure AD](../app-provisioning/use-scim-to-provision-users-and-groups.md).

+| [Get a token using Azure.Identity](#get-a-token-using-the-azure-identity-client-library) | Get a token using Azure.Identity library |

+description: Get guidance on meeting authorization requirements outlined in US government OMB memorandum 22-09.

+# Meet authorization requirements of memorandum 22-09

+This series of articles offers guidance for employing Azure Active Directory (Azure AD) as a centralized identity management system for implementing Zero Trust principles, as described in the US federal government's Office of Management and Budget (OMB) [memorandum 22-09](https://www.whitehouse.gov/wp-content/uploads/2022/01/M-22-09.pdf).

+The memo requires specific types of enforcement within your multifactor authentication (MFA) policies. Specifically, you must account for device-based controls, role-based controls, attribute-based controls, and privileged access management.

+Memorandum 22-09 specifically requires the use of at least one device-based signal when you're making an authorization decision to access a system or application. You can enforce this requirement by using conditional access. Several device signals can be applied during the authorization. The following table describes the signal and the requirements to retrieve the signal:

+| Device must be managed| Integration with Intune or another mobile device management (MDM) solution that supports this integration is required.

+Hybrid Azure AD joined| The device is managed by Active Directory and qualifies.

+| Device must be compliant| Integration with Intune or another MDM solution that supports this integration is required. For more information, see [Use device compliance policies to set rules for devices you manage with Intune](/mem/intune/protect/device-compliance-get-started). |

+| Threat signals| Microsoft Defender for Endpoint and other endpoint detection and response (EDR) tools have integrations with Azure AD and Intune to send threat signals that can be used to deny access. Threat signals are part of the compliant status signal. |

+| Cross-tenant access policies (public preview)| These policies permit an organization to trust device signals from devices that belong to other organizations. |

+## Role-based controls

+Role-based access control (RBAC) is an important way to enforce basic authorizations through assignments of users to a role in a particular scope. Azure AD has tools that make RBAC assignment and lifecycle management easier. For example, you can assign access by using [entitlement management](../governance/entitlement-management-overview.md) features, including [access packages](../governance/entitlement-management-access-package-create.md) and [access reviews](../governance/access-reviews-overview.md).

+These features ease the burden of managing authorizations by providing self-service requests and automated functions to manage the lifecycle. For example, you can automatically end access based on specific criteria.

+Attribute-based access control (ABAC) relies on metadata assigned to a user or resource as a mechanism to permit or deny access during authentication. There are several ways to create authorizations by using ABAC enforcements for data and resources through authentication.

+You can use attributes assigned to users and stored in Azure AD to create authorizations for users. Users can be automatically assigned to [dynamic groups](../enterprise-users/groups-create-rule.md) based on a particular ruleset that you define during group creation. Rules are configured to add or remove a user from the group based on the evaluation of the rule against the user and one or more of their attributes. This feature has greater value when your attributes are maintained and not statically set on users from the day of creation.

+Azure AD allows integration of an authorization directly to the data. You can integrate authorization in multiple ways.

+You can configure [authentication context](../conditional-access/concept-conditional-access-cloud-apps.md) within conditional access policies. This allows you to, for example, restrict which actions a user can take within an application or on specific data. These authentication contexts are then mapped within the data source itself.

+Data sources can be Microsoft Office files like Word and Excel, or SharePoint sites that are mapped to your authentication context. For an example of this integration, see [Manage site access based on sensitivity label](/sharepoint/authentication-context-example).

+You can also use authentication context assigned to data directly in your applications. This approach requires integration with the application code and [developers](../develop/developer-guide-conditional-access-authentication-context.md) to adopt this capability. You can use authentication context integration with Microsoft Defender for Cloud Apps to control [actions taken on data through session controls](/defender-cloud-apps/session-policy-aad).

+If you combine dynamic groups with authentication context, you can control user access mappings between the data and the user attributes.

+Azure includes [ABAC for Storage](../../role-based-access-control/conditions-overview.md), which allows the assignment of metadata tags on data stored in an Azure Blob Storage account. You can then assign this metadata to users by using role assignments to grant access.

+## Privileged access management

+The memo specifically calls out the use of privileged access management tools that use single-factor ephemeral credentials for accessing systems as insufficient. These technologies often include password vault products that accept MFA sign-in for an admin and produce a generated password for an alternate account that's used to access the system. The system is still accessed with a single factor.

+Microsoft has tools for implementing [Privileged Identity Management](../privileged-identity-management/pim-configure.md) (PIM) for privileged systems with the central identity management system of Azure AD. You can enforce MFA for most privileged systems directly, whether these systems are applications, infrastructure elements, or devices.

+Azure also features PIM capabilities to step up into a specific privileged role. This requires implementation of PIM with Azure AD identities, along with identifying systems that are privileged and require additional protections to prevent lateral movement. For configuration guidance, see [Plan a Privileged Identity Management deployment](../privileged-identity-management/pim-deployment-plan.md).

+The following articles are part of this documentation set:

+[Meet identity requirements of memorandum 22-09](memo-22-09-meet-identity-requirements.md)

+[Multifactor authentication](memo-22-09-multi-factor-authentication.md)

+For more information about Zero Trust, see:

+ Title: Memo 22-09 enterprise-wide identity management system

+description: Get guidance on meeting enterprise-wide identity management system requirements outlined in US government OMB memorandum 22-09.

+Memorandum 22-09 requires agencies to develop a plan to consolidate their identity platforms to as few agency-managed identity systems as possible within 60 days of the publication date (March 28, 2022). There are several advantages to consolidating your identity platform:

+* Centralized management of identity lifecycle, policy enforcement, and auditable controls

+* Uniform capability and parity of enforcement

+* Reduced need to train resources across multiple systems

+* Enabling users to sign in once and then directly access applications and services in the IT environment

+* Integration with as many agency applications as possible

+* Use of shared authentication services and trust relationships to facilitate integration among agencies

+Azure Active Directory (Azure AD) provides the capabilities necessary to implement the recommendations from memorandum 22-09. It also provides broad identity controls that support Zero Trust initiatives. If your agency uses Microsoft Office 365, you already have an Azure AD back end to which you can consolidate.

+The memo requires that users sign in once and then directly access applications. Microsoft's robust single sign-on (SSO) capabilities enable users to sign in once and then access cloud and other applications. For more information, see [Azure Active Directory single sign-on](../hybrid/how-to-connect-sso.md).

+## Integration across agencies

+[Azure AD B2B collaboration](../external-identities/what-is-b2b.md) helps you meet the requirement to facilitate integration among agencies. It does this by:

+- Limiting what other Microsoft tenants your users can access.

+- Enabling you to allow access to users whom you don't have to manage in your own tenant, but whom you can subject to your multifactor authentication (MFA) and other access requirements.

+## Connecting applications

+To consolidate your enterprise to using Azure AD as the enterprise-wide identity system, you must first understand the assets that will be in scope.

+You must inventory the applications and services that users will access. An identity management system can protect only what it knows.

+Classify assets in terms of:

+- The sensitivity of data that they contain.

+- Laws and regulations that establish specific requirements for confidentiality, integrity, or availability of data/information in each major system and that apply to the system's information protection requirements.

+As a part of your application inventory, you need to determine if your current applications use cloud-ready protocols or [legacy authentication protocols](../fundamentals/auth-sync-overview.md):

+* Cloud-ready applications support modern protocols for authentication, such as SAML, WS-Federation/Trust, OpenID Connect (OIDC), and OAuth 2.0.

+* Legacy authentication applications rely on older or proprietary methods of authentication, such as Kerberos/NTLM (Windows authentication), header-based authentication, LDAP, and Basic authentication.

+Microsoft offers the following tools to help with your discovery of applications:

+| [Usage Analytics for Active Directory Federation Services (AD FS)](../hybrid/how-to-connect-health-adfs.md)| Analyzes the authentication traffic of your federated servers. |

+| [Microsoft Defender for Cloud Apps](/defender-cloud-apps/what-is-defender-for-cloud-apps)| Scans firewall logs to detect cloud apps, infrastructure as a service (IaaS) services, and platform as a service (PaaS) services that your organization uses. It was previously called Microsoft Cloud App Security. Integrating Defender for Cloud Apps with Defender for Endpoint allows discovery to happen from data analyzed from Windows client devices. |

+| [Application Discovery worksheet](https://download.microsoft.com/download/2/8/3/283F995C-5169-43A0-B81D-B0ED539FB3DD/Application%20Discovery%20worksheet.xlsx)| Helps you document the current states of your applications. |

+We recognize that your apps might be in systems other than Microsoft's, and that Microsoft tools might not discover those apps. Ensure that you do a complete inventory. All providers should have mechanisms for discovering applications that use their services.

+#### Prioritizing applications for connection

+After you discover all applications in your environment, you need to prioritize them for migration. Consider business criticality, user profiles, usage, and lifespan.

+First, connect your cloud-ready apps in priority order. Then look at apps that use [legacy authentication protocols](../fundamentals/auth-sync-overview.md).

+For apps that use legacy authentication protocols, consider the following:

+* For apps with modern authentication that aren't yet using Azure AD, reconfigure them to use Azure AD.

+ * Modernize the application code to use modern protocols by integrating the [Microsoft Authentication Library (MSAL)](../develop/v2-overview.md).

+ * [Use Azure AD Application Proxy or secure hybrid partner access](../manage-apps/secure-hybrid-access.md) to provide secure access.

+* Decommission access to apps that are no longer needed or that aren't supported (for example, apps that shadow IT processes added).

+## Connecting devices

+Part of centralizing your identity management system will include enabling users to sign in to physical and virtual devices.

+You can connect Windows and Linux devices in your centralized Azure AD system. That eliminates the need to have multiple, separate identity systems.

+During your inventory and scope phase, consider identifying your devices and infrastructure so they can be integrated with Azure AD. This integration will centralize your authentication and management. It will also take advantage of conditional access policies and MFA that can be enforced through Azure AD.

+You can use [Azure Automation accounts](../../automation/change-tracking/manage-inventory-vms.md) to identify devices through inventory collection connected to Azure Monitor.

+[Microsoft Defender for Endpoint](/microsoft-365/security/defender-endpoint/machines-view-overview) also features device inventory capabilities and discovery. This feature discovers which devices have Defender for Endpoint configured and which devices don't. Device inventory can also come from on-premises systems such as [System Center Configuration Manager](/mem/configmgr/core/clients/manage/inventory/introduction-to-hardware-inventory) or other systems that manage devices and clients.

+### Integration of devices with Azure AD

+Devices integrated with Azure AD can be either [hybrid joined devices](../devices/concept-azure-ad-join-hybrid.md) or [Azure AD joined devices](../devices/concept-azure-ad-join.md). Agencies should separate device onboarding by client and user devices, and by physical and virtual machines that operate as infrastructure. For more information about choosing and implementing your deployment strategy for user devices, see [Plan your Azure AD device deployment](../devices/plan-device-deployment.md). For servers and infrastructure, consider the following examples for connecting:

+* [Azure Windows virtual machines](../devices/howto-vm-sign-in-azure-ad-windows.md)

+* [Azure Linux virtual machines](../devices/howto-vm-sign-in-azure-ad-linux.md)

+* [Virtual desktop infrastructure](../devices/howto-device-identity-virtual-desktop-infrastructure.md)

+The following articles are part of this documentation set:

+[Meet identity requirements of memorandum 22-09](memo-22-09-meet-identity-requirements.md)

+[Multifactor authentication](memo-22-09-multi-factor-authentication.md)

+For more information about Zero Trust, see:

+description: Get guidance on meeting requirements outlined in US government OMB memorandum 22-09.

+# Meet identity requirements of memorandum 22-09 with Azure Active Directory

+US executive order [14028, Improving the Nation's Cyber Security](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity), directs federal agencies on advancing security measures that dramatically reduce the risk of successful cyberattacks against the federal government's digital infrastructure. On January 26, 2022, the [Office of Management and Budget (OMB)](https://www.whitehouse.gov/omb/) released the federal Zero Trust strategy in [memorandum 22-09](https://www.whitehouse.gov/wp-content/uploads/2022/01/M-22-09.pdf), in support of EO 14028.

+This series of articles offers guidance for employing Azure Active Directory (Azure AD) as a centralized identity management system for implementing Zero Trust principles, as described in memorandum 22-09.

+The release of memorandum 22-09 is designed to support Zero Trust initiatives within federal agencies. It also provides regulatory guidance in supporting federal cybersecurity and data privacy paws. The memo cites the [Department of Defense (DoD) Zero Trust Reference Architecture](https://dodcio.defense.gov/Portals/0/Documents/Library/(U)ZT_RA_v1.1(U)_Mar21.pdf):

+>"The foundational tenet of the Zero Trust Model is that no actor, system, network, or service operating outside or within the security perimeter is trusted. Instead, we must verify anything and everything attempting to establish access. It is a dramatic paradigm shift in philosophy of how we secure our infrastructure, networks, and data, from verify once at the perimeter to continual verification of each user, device, application, and transaction."

+The memo identifies five core goals that federal agencies must reach. These goals are organized through the Cybersecurity Information Systems Architecture (CISA) Maturity Model. CISA's Zero Trust model describes five complementary areas of effort, or pillars: identity, devices, networks, applications and workloads, and data. These themes cut across these areas: visibility and analytics, automation and orchestration, and governance.

+This series of articles provides practical guidance for administrators and decision makers to adapt a plan to meet memo requirements. It assumes that you're using Microsoft 365 products and therefore have an Azure AD tenant available. If this is inaccurate, see [Create a new tenant in Azure Active Directory](../fundamentals/active-directory-access-create-new-tenant.md).

+The article series features guidance that encompasses existing agency investments in Microsoft technologies that align with the identity-related actions outlined in the memo:

+* Agencies must employ centralized identity management systems for agency users that can be integrated into applications and common platforms.

+* Agencies must use strong multifactor authentication (MFA) throughout their enterprise:

+ * MFA must be enforced at the application layer instead of the network layer.

+ * For agency staff, contractors, and partners, phishing-resistant MFA is required. For public users, phishing-resistant MFA must be an option.

+* When agencies are authorizing users to access resources, they must consider at least one device-level signal alongside identity information about the authenticated user.

+The following articles are part of this documentation set:

+[Multifactor authentication](memo-22-09-multi-factor-authentication.md)

+For more information about Zero Trust, see:

+ Title: Memo 22-09 multifactor authentication requirements overview

+description: Get guidance on meeting multifactor authentication requirements outlined in US government OMB memorandum 22-09.

+# Meet multifactor authentication requirements of memorandum 22-09

+This series of articles offers guidance for using Azure Active Directory (Azure AD) as a centralized identity management system for implementing Zero Trust principles, as described in the US federal government's Office of Management and Budget (OMB) [memorandum 22-09](https://www.whitehouse.gov/wp-content/uploads/2022/01/M-22-09.pdf).

+The memo requires that all employees use enterprise-managed identities to access applications, and that phishing-resistant multifactor authentication (MFA) protect those personnel from sophisticated online attacks. Phishing is the attempt to obtain and compromise credentials, such as by sending a spoofed email that leads to an inauthentic site.

+Adoption of MFA is critical for preventing unauthorized access to accounts and data. The memo requires MFA usage with phishing-resistant methods, defined as "authentication processes designed to detect and prevent disclosure of authentication secrets and outputs to a website or application masquerading as a legitimate system." The first step is to establish what MFA methods qualify as phishing resistant.

+## Phishing-resistant methods

+* Active Directory Federation Services (AD FS) as a federated identity provider that's configured with certificate-based authentication.

+* Azure AD certificate-based authentication.

+* FIDO2 security keys.

+* Windows Hello for Business.

+* Microsoft Authenticator and conditional access policies that enforce managed or compliant devices to access the application or service. Microsoft Authenticator native phishing resistance is in development.

+Your current device capabilities, user personas, and other requirements might dictate specific multifactor methods. For example, if you're adopting FIDO2 security keys that have only USB-C support, they can be used only from devices with USB-C ports.

+Consider the following approaches to evaluating phishing-resistant MFA methods:

+* Device types and capabilities that you want to support. Examples include kiosks, laptops, mobile phones, biometric readers, USB, Bluetooth, and near-field communication devices.

+* User personas within your organization. Examples include front-line workers, remote workers with and without company-owned hardware, administrators with privileged access workstations, and business-to-business guest users.

+* Logistics of distributing, configuring, and registering MFA methods such as FIDO2 security keys, smart cards, government-furnished equipment, or Windows devices with TPM chips.

+* Need for FIPS 140 validation at a specific [authenticator assurance level](nist-about-authenticator-assurance-levels.md). For example, some FIDO security keys are FIPS 140 validated at levels required for [AAL3](nist-authenticator-assurance-level-3.md), as set by [NIST SP 800-63B](https://pages.nist.gov/800-63-3/sp800-63b.html).

+## Implementation considerations for phishing-resistant MFA

+The following sections describe support for implementing phishing-resistant methods for both application and virtual device sign-in scenarios.

+### Application sign-in scenarios from various clients

+The following table details the availability of phishing-resistant MFA scenarios, based on the device type that's used to sign in to the applications:

+| Device | AD FS as a federated identity provider configured with certificate-based authentication| Azure AD certificate-based authentication| FIDO2 security keys| Windows Hello for Business| Microsoft authenticator + certificate authority for managed devices |

+| iOS mobile device| | | Not applicable| Not applicable|  |

+| Android mobile device| | | Not applicable| Not applicable|  |

+| MacOS device| | | Edge/Chrome | Not applicable|  |

+To learn more, see [Browser support for FIDO2 passwordless authentication](../authentication/fido2-compatibility.md).

+### Virtual device sign-in scenarios that require integration

+To enforce the use of phishing-resistant MFA methods, integration might be necessary based on your requirements. MFA should be enforced when users access applications and devices.

+| Target system| Integration actions |

+| Azure Linux virtual machine (VM)| Enable the [Linux VM for Azure AD sign-in](../devices/howto-vm-sign-in-azure-ad-linux.md). |

+| Azure Windows VM| Enable the [Windows VM for Azure AD sign-in](../devices/howto-vm-sign-in-azure-ad-windows.md). |

+| Azure Virtual Desktop| Enable [Azure Virtual Desktop for Azure AD sign-in](/azure/architecture/example-scenario/wvd/azure-virtual-desktop-azure-active-directory-join). |

+| VMs hosted on-premises or in other clouds| Enable [Azure Arc](../../azure-arc/overview.md) on the VM and then enable Azure AD sign-in. (Currently in private preview for Linux. Support for Windows VMs hosted in these environments is on our roadmap.) |

+| Non-Microsoft virtual desktop solution| Integrate the virtual desktop solution as an app in Azure AD. |

+Conditional access enables you to enforce MFA for users in your tenant. With the addition of [cross-tenant access policies](../external-identities/cross-tenant-access-overview.md), you can enforce it on external users.

+[Azure AD B2B collaboration](../external-identities/what-is-b2b.md) helps you meet the requirement to facilitate integration among agencies. It does this by:

+- Limiting what other Microsoft tenants your users can access.

+- Enabling you to allow access to users whom you don't have to manage in your own tenant, but whom you can subject to your MFA and other access requirements.

+You must enforce MFA for partners and external users who access your organization's resources. This is common in many inter-agency collaboration scenarios. Azure AD provides cross-tenant access policies to help you configure MFA for external users who access your applications and resources.

+By using trust settings in cross-tenant access policies, you can trust the MFA method that the guest user's tenant is using instead of having them register an MFA method directly with your tenant. These policies can be configured on a per-organization basis. This ability requires you to understand the available MFA methods in the user's home tenant and determine if they meet the requirement for phishing resistance.

+The memo requires organizations to change password policies that are proven ineffective, such as complex passwords that are rotated often. This includes the removal of the requirement for special characters and numbers, along with time-based password rotation policies. Instead, consider doing the following:

+* Use [password protection](..//authentication/concept-password-ban-bad.md) to enforce a common list of weak passwords that Microsoft maintains. You can also add custom banned passwords.

+* Use [self-service password protection](..//authentication/tutorial-enable-sspr.md) to enable users to reset passwords as needed, such as after an account recovery.

+Although the memo isn't specific on which policies to use with passwords, consider the standard from [NIST 800-63B](https://pages.nist.gov/800-63-3/sp800-63b.html).

+The following articles are part of this documentation set:

+[Meet identity requirements of memorandum 22-09](memo-22-09-meet-identity-requirements.md)

+[Enterprise-wide identity management system](memo-22-09-enterprise-wide-identity-management-system.md)

+For more information about Zero Trust, see:

+description: Get guidance on understanding other Zero Trust requirements outlined in US government OMB memorandum 22-09.

+# Other areas of Zero Trust addressed in memorandum 22-09

+The other articles in this guidance set address the identity pillar of Zero Trust principles, as described in the US federal government's Office of Management and Budget (OMB) [memorandum 22-09](https://www.whitehouse.gov/wp-content/uploads/2022/01/M-22-09.pdf). This article covers areas of the Zero Trust maturity model that are beyond the identity pillar.

+It's important to monitor your Azure Active Directory (Azure AD) tenant. You must adopt an "assume breach" mindset and meet compliance standards in memorandum 22-09 and [memorandum 21-31](https://www.whitehouse.gov/wp-content/uploads/2021/08/M-21-31-Improving-the-Federal-Governments-Investigative-and-Remediation-Capabilities-Related-to-Cybersecurity-Incidents.pdf). Three primary log types are used for security analysis and ingestion:

+* [Azure audit logs](../reports-monitoring/concept-audit-logs.md). Used for monitoring operational activities of the directory itself, such as creating, deleting, updating objects like users or groups. Also used for making changes to configurations of Azure AD, like modifications to a conditional access policy.

+* [Azure AD sign-in logs](../reports-monitoring/concept-all-sign-ins.md). Used for monitoring all sign-in activities associated with users, applications, and service principals. The sign-in logs contain specific categories of sign-ins for easy differentiation:

+ * Interactive sign-ins: Shows user successful and failed sign-ins for failures, the policies that might have been applied, and other relevant metadata.

+ * Non-interactive user sign-ins: Shows sign-ins where a user did not perform an interaction during sign-in. These sign-ins are typically clients signing in on behalf of the user, such as mobile applications or email clients.

+ * Service principal sign-ins: Shows sign-ins by service principals or applications. Typically, these are headless and done by services or applications that are accessing other services, applications, or the Azure AD directory itself through the REST API.

+ * Managed identities for Azure resource sign-ins: Shows sign-ins from resources with Azure managed identities. Typically, these are Azure resources or applications that are accessing other Azure resources, such as a web application service authenticating to an Azure SQL back end.

+* [Provisioning logs](../reports-monitoring/concept-provisioning-logs.md). Shows information about objects synchronized from Azure AD to applications like Service Now by using Microsoft Identity Manager.

+Log entries are stored for 7 days in Azure AD free tenants. Tenants with an Azure AD premium license retain log entries for 30 days.

+It's important to ensure that your logs are ingested by a security information and event management (SIEM) tool. Using a SIEM tool allows sign-in and audit events to be correlated with application, infrastructure, data, device, and network logs for a holistic view of your systems.

+We recommend that you integrate your Azure AD logs with [Microsoft Sentinel](../../sentinel/overview.md) by configuring a connector to ingest your Azure AD tenant logs. For more information, see [Connect Azure Active Directory to Microsoft Sentinel](../../sentinel/connect-azure-active-directory.md).

+You can also configure the [diagnostic settings](../reports-monitoring/overview-monitoring.md) on your Azure AD tenant to send the data to an Azure Storage account, Azure Event Hubs, or a Log Analytics workspace. These storage options allow you to integrate other SIEM tools to collect the data. For more information, see [Plan an Azure Active Directory reporting and monitoring deployment](../reports-monitoring/plan-monitoring-and-reporting.md).

+You can use analytics in the following tools to aggregate information from Azure AD and show trends in your security posture in comparison to your baseline. You can also use analytics to assess and look for patterns or threats across Azure AD.

+* [Azure AD Identity Protection](../identity-protection/overview-identity-protection.md) actively analyzes sign-ins and other telemetry sources for risky behavior. Identity Protection assigns a risk score to a sign-in event. You can prevent sign-ins, or force a step-up authentication, to access a resource or application based on risk score.

+* [Microsoft Sentinel](../../sentinel/get-visibility.md) offers the following ways to analyze information from Azure AD:

+ * Microsoft Sentinel has [User and Entity Behavior Analytics (UEBA)](../../sentinel/identify-threats-with-entity-behavior-analytics.md). UEBA delivers high-fidelity, actionable intelligence on potential threats that involve user, host, IP address, and application entities. This intelligence enhances events across the enterprise to help detect anomalous behavior in users and systems.

+ * You can use specific analytics rule templates that hunt for threats and alerts found in your Azure AD logs. Your security or operation analyst can then triage and remediate threats.

+ * Microsoft Sentinel has [workbooks](../../sentinel/top-workbooks.md) that help you visualize multiple Azure AD data sources. These workbooks can show aggregate sign-ins by country, or applications that have the most sign-ins. You can also create or modify existing workbooks to view information or threats in a dashboard to gain insights.

+* [Azure AD usage and insights reports](../reports-monitoring/concept-usage-insights-report.md) show information similar to Azure Sentinel workbooks, including which applications have the highest usage or sign-in trends over a time period. The reports are useful for understanding aggregate trends in your enterprise that might indicate an attack or other events.

+Automation is an important aspect of Zero Trust, particularly in remediation of alerts that occur because of threats or security changes in your environment. In Azure AD, automation integrations are possible to help remediate alerts or perform actions that can improve your security posture. Automations are based on information received from monitoring and analytics.

+[Microsoft Graph API](../develop/microsoft-graph-intro.md) REST calls are the most common way to programmatically access Azure AD. This API-based access requires an Azure AD identity with the necessary authorizations and scope. With the Graph API, you can integrate Microsoft's and other tools. Follow the principles outlined in this article when you're performing the integration.

+We recommend that you set up an Azure function or an Azure logic app to use a [system-assigned managed identity](../managed-identities-azure-resources/overview.md). Your logic app or function contains the steps or code necessary to automate the desired actions. You assign permissions to the managed identity to grant the service principal the necessary directory permissions to perform the required actions. Grant managed identities only the minimum rights necessary.

+Another automation integration point is [Azure AD PowerShell](/powershell/azure/active-directory/overview) modules. PowerShell is a useful automation tool for administrators and IT integrators who are performing common tasks or configurations in Azure AD. PowerShell can also be incorporated into Azure functions or Azure Automation runbooks.

+It's important that you understand and document clear processes for how you intend to operate your Azure AD environment. Azure AD has features that allow for governance-like functionality to be applied to scopes within Azure AD. Consider the following guidance to help with governance via Azure AD:

+* [Azure Active Directory security operations guide](../fundamentals/security-operations-introduction.md). It can help you secure your operations and understand how security and governance overlap.

+After you understand operational governance, you can use [governance features](../governance/identity-governance-overview.md) to implement portions of your governance controls. These include features mentioned in [Meet authorization requirements of memorandum 22-09](memo-22-09-authorization.md).

+The following articles are part of this documentation set:

+[Meet identity requirements of memorandum 22-09](memo-22-09-meet-identity-requirements.md)

+[Multifactor authentication](memo-22-09-multi-factor-authentication.md)

+For more information about Zero Trust, see:

+ Title: Enable Cloud Controller Manager

+# Enable Cloud Controller Manager

+Previously, Cloud provider integration with Kubernetes was "in-tree", where any changes to Cloud specific features would follow the standard Kubernetes release cycle. When issues were fixed or enhancements were rolled out, they would need to be within the Kubernetes community's release cycle.

+The Kubernetes community is now adopting an "out-of-tree" model where the Cloud providers will control their releases independently of the core Kubernetes release schedule through the [cloud-provider-azure][cloud-provider-azure] component. As part of this cloud-provider-azure component, we are also introducing a cloud-node-manager component, which is a component of the Kubernetes node lifecycle controller. This component is deployed by a DaemonSet in the *kube-system* namespace. To view this component, use

+```azurecli-interactive

+kubectl get po -n kube-system | grep cloud-node-manager

+```

+We recently rolled out the Cloud Storage Interface (CSI) drivers to be the default in Kubernetes version 1.21 and above.

+> [!Note]

+> When enabling Cloud Controller Manager on your AKS cluster, this will also enable the out of tree CSI drivers.

+The Cloud Controller Manager is the default controller from Kubernetes 1.22, supported by AKS. If running < v1.22, follow instructions below.

+## Prerequisites

+* The `aks-preview` extension version 0.5.5 or later

+## Create a new AKS cluster with Cloud Controller Manager with version <1.22

+## Upgrade an AKS cluster to Cloud Controller Manager on an existing cluster with version <1.22

+**Normalization rules for `operationId`**

+- Convert to lower case.

+- Replace each sequence of non-alphanumeric characters with a single dash.

+ - For example, `GET-/foo/{bar}?buzz={quix}` will be transformed into `get-foo-bar-buzz-quix-`.

+- Trim dashes on both sides.

+ - For example, `get-foo-bar-buzz-quix-` will become `get-foo-bar-buzz-quix`

+- Truncate to fit 76 characters, four characters less than maximum limit for a resource name.

+- Use remaining four characters for a de-duplication suffix, if necessary, in the form of `-1, -2, ..., -999`.

+### Export API as OpenAPI

+For each operation, its:

+* Azure resource name will be exported as an `operationId`.

+* Display name will be exported as a `summary`.

+Note that normalization of the `operationId` is done on import, not on export.

+App Service on Linux supports a number of language specific built-in images. Just deploy your code. Supported languages include: Node.js, Java (JRE 8 & JRE 11), PHP, Python, .NET Core, and Ruby. Run [`az webapp list-runtimes --os linux`](/cli/azure/webapp#az-webapp-list-runtimes) to view the latest languages and supported versions. If the runtime your application requires is not supported in the built-in images, you can deploy it with a custom container.

+| `DOCKER_ENABLE_CI` | Set to `true` to enable the continuous deployment for custom containers. The default is `false` for custom containers. ||

+## RBAC permissions required to access Kudo

+To access Kudu in the browser with Azure Active Directory authentication, you need to be a member of a built-in or custom role.

+- If using a built-in role, you must be a member of Website Contributor, Contributor, or Owner.

+- If using a custom role, you need the resource provider operation: `Microsoft.Web/sites/publish/Action`.

+Azure App Service uses the Docker container technology to host both built-in images and custom images. To see a list of built-in images, run the Azure CLI command, ['az webapp list-runtimes --os linux'](/cli/azure/webapp#az-webapp-list-runtimes). If those images don't satisfy your needs, you can build and deploy a custom image.

+* The runtime specifies what version of .NET your app is running. This example uses .NET 6.0 LTS. To list all available runtimes, use the command `az webapp list-runtimes --os linux --output table` for Linux and `az webapp list-runtimes --os windows --output table` for Windows.

+While using multi-site listeners, to ensure that the client traffic is routed to the accurate backend, it's important to have the request routing rules be present in the correct order.

+The priority field only impacts the order of evaluation of a request routing rule, this wont change the order of evaluation of path based rules within a `PathBasedRouting` request routing rule.

+* [SSL termination and End-to-End SSL](ssl-overview.md) requires you to configure the protocol as HTTPS and upload a certificate to be used in the listener configuration. If it's a multi-site listener, you can input the host name as well, usually this is the CN of the SSL certificate. When you are specifying multiple host names in the listener or use wildcard characters, you must consider the following:

+ * If it's a wildcard hostname like *.contoso.com, you must upload a wildcard certificate with CN like *.contoso.com

+ When configuring redirects with a multi-site target listener, it is required that all the host names (with or without wildcard characters) defined as part of the source listener are also part of the destination listener. This ensures that no traffic is dropped due to missing host names on the destination listener while setting up HTTP to HTTPS redirection.

+The Form Recognizer v3.0 preview includes the new Read API. Read extracts printed and handwritten from documents. The read model can detect lines, words, locations, and languages and is the core of all the other Form Recognizer models. Layout, general document, custom, and prebuilt models all use the read model as a foundation for extracting texts from documents.

+|**Read model**| <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-rest-api)</li><li>[**C# SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-csharp)</li><li>[**Python SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-python)</li><li>[**Java SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-java)</li><li>[**JavaScript**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-javascript)</li></ul>|**prebuilt-read**|

+Read API extracts text from documents and images with multiple text angles and colors. It accepts photos of documents, faxes, printed and/or handwritten (English only) text, and mixed modes. Text is extracted from data provided in lines, words, bounding boxes, confidence scores, and style.

+Complete a Form Recognizer quickstart:

+> [!div class="checklist"]

+>

+> * [**REST API**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-rest-api)

+> * [**C# SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-csharp)

+> * [**Python SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-python)

+> * [**Java SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-java)

+> * [**JavaScript**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-javascript)</li></ul>

+Explore our REST API:

+> [!div class="nextstepaction"]

+> [Form Recognizer API v3.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-2/operations/AnalyzeDocument)

+Once you've put together the set of forms or documents for training, you'll need to upload it to an Azure blob storage container. If you don't know how to create an Azure storage account with a container, following the [Azure Storage quickstart for Azure portal](../../../storage/blobs/storage-quickstart-blobs-portal.md). You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

+The Form Recognizer Studio provides and orchestrates all the API calls required to complete your dataset and train your model.

+1. Start by navigating to the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio). The first time you use the Studio, you'll need to [initialize your subscription, resource group, and resource](../quickstarts/try-v3-form-recognizer-studio.md). Follow the [additional prerequisite for custom projects](../quickstarts/try-v3-form-recognizer-studio.md#additional-prerequisites-for-custom-projects) to configure the Studio to access your training dataset.

+1. In the Studio, select the **Custom models** tile, on the custom models page and select the **Create a project** button.

+1. Next select the storage account where you uploaded your custom model training dataset. The **Folder path** should be empty if your training documents are in the root of the container. If your documents are in a subfolder, enter the relative path from the container root in the **Folder path** field. Once your storage account is configured, select continue.

+1. To assign a value to the field, choose a word or words in the document and select the field in either the dropdown or the field list on the right navigation bar. You'll see the labeled value below the field name in the list of fields.

+1. Repeat the process for all the fields you wish to label for your dataset.

+1. Label the remaining documents in your dataset by selecting each document and selecting the text to be labeled.

+You now have all the documents in your dataset labeled. If you look at the storage account, you'll find a *.labels.json* and *.ocr.json* files that correspond to each document in your training dataset and a new fields.json file. This training dataset will be submitted to train the model.

+> [Learn about accuracy and confidence with custom models](../concept-accuracy-confidence.md)

+ Title: "Use SDKs and REST API for read Model"

+description: Learn how to use read model using SDKs and REST API.

+zone_pivot_groups: programming-languages-set-formre

+recommendations: false

+# Use the Read Model

+ In this how-to guide, you'll learn to use Azure Form Recognizer's [read model](../concept-read.md) to extract printed and handwritten text from documents. The read model can detect lines, words, locations, and languages. You can use a programming language of your choice or the REST API. We recommend that you use the free service when you're learning the technology. Remember that the number of free pages is limited to 500 per month.

+ The read model is the core of all the other Form Recognizer models. Layout, general document, custom, and prebuilt models all use the read model as a foundation for extracting texts from documents.

+>[!NOTE]

+> Form Recognizer v3.0 is currently in public preview. Some features may not be supported or have limited capabilities.

+The current API version is ```2022-01-30-preview```.

+|[🆕 **Read**](concept-read.md)|Extract text lines, words, detected languages, and handwritten style if detected.|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/read)</li><li>[**REST API**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-rest-api)</li><li>[**C# SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-csharp)</li><li>[**Python SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-python)</li><li>[**Java SDK**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-java)</li><li>[**JavaScript**](how-to-guides/use-prebuilt-read.md?pivots=programming-language-javascript)</li></ul> |

+description: This article provides information about deploying the extension-based User Hybrid Runbook Worker to run runbooks on Windows or Linux machines in your on-premises datacenter or other cloud environment.

+# Deploy an extension-based Windows or Linux User Hybrid Runbook Worker in Azure Automation (Preview)

+The extension-based onboarding is only for **User** Hybrid Runbook Workers. This article describes how to: deploy a user Hybrid Runbook Worker on a Windows or Linux machine, remove the worker, and remove a Hybrid Runbook Worker group.

+For **System** Hybrid Runbook Worker onboarding, see [Deploy an agent-based Windows Hybrid Runbook Worker in Automation](./automation-windows-hrw-install.md) or [Deploy an agent-based Linux Hybrid Runbook Worker in Automation](./automation-linux-hrw-install.md).

+You can use the user Hybrid Runbook Worker feature of Azure Automation to run runbooks directly on an Azure or non-Azure machine, including servers registered with [Azure Arc-enabled servers](../azure-arc/servers/overview.md). From the machine or server that's hosting the role, you can run runbooks directly against it and against resources in the environment to manage those local resources.

+Azure Automation stores and manages runbooks and then delivers them to one or more chosen machines. After you successfully deploy a runbook worker, review [Run runbooks on a Hybrid Runbook Worker](automation-hrw-run-runbooks.md) to learn how to configure your runbooks to automate processes in your on-premises datacenter or other cloud environment.

+1. Open an Azure App Configuration store and from the **Operations** menu, select **Feature Manager** > **+Add**.

+1. Check the box **Enable feature flag** to make the new feature flag active as soon as the flag has been created.

+1. Enter a **Feature flag name**. The feature flag name is the unique ID of the flag, and the name that should be used when referencing the flag in code.

+1. You can edit the key for your feature flag. The default value for this key is the name of your feature flag. You can change the key to add a prefix, which can be used to find specific feature flags when loading the feature flags in your application. For example, using the application's name as prefix such as **appname:featureflagname**.

+1. Optionally select an existing label or create a new one, and enter a description for the new feature flag.

+1. Leave the **Use feature filter** box unchecked and select **Apply** to create the feature flag. To learn more about feature filters, visit [Use feature filters to enable conditional feature flags](howto-feature-filters-aspnet-core.md) and [Enable staged rollout of features for targeted audiences](howto-targetingfilter-aspnet-core.md).

+## Update feature flags

+To update a feature flag:

+1. From the **Operations** menu, select **Feature Manager**.

+1. Move to the right end of the feature flag you want to modify, select the **More actions** ellipsis (**...**). From this menu, you can edit the flag, create a label, lock or delete the feature flag.

+1. Select **Edit** and update the feature flag.

+In the **Feature manager**, you can also change the state of a feature flag by checking or unchecking the **Enable Feature flag** checkbox.

+## Access feature flags

+In the **Operations** menu, select **Feature manager**. You can select **Edits Columns** to add or remove columns, and change the column order.

+create a label, lock or delete the feature flag.

+Feature flags created with the Feature Manager are stored and retrieved as regular key-values. They're kept under a special namespace prefix `.appconfig.featureflag`.

+To view the underlying key-values:

+1. In the **Operations** menu, open the **Configuration explorer**.

+1. Select **Manage view** > **Settings**.

+1. Select **Include feature flags in the configuration explorer** and **Apply**.

+Your application can retrieve these values by using the App Configuration configuration providers, SDKs, command-line extensions, and REST APIs.

+## Next steps

+> [!div class="nextstepaction"]

+> [Enable staged rollout of features for targeted audiences](./howto-targetingfilter-aspnet-core.md)

+## Change maintenance window options

+The update command can be used to change any of the options. In this example, I will update the start time.

+[Enable automatic upgrades of a SQL Managed Instance](upgrade-sql-managed-instance-auto.md)

+Azure Arc-enabled Kubernetes allows you to attach and configure Kubernetes clusters running anywhere. You can connect your clusters running on other public cloud providers (such as GCP or AWS) or clusters running on your on-premise data center (such as VMware vSphere or Azure Stack HCI) to Azure Arc.

+When you connect a Kubernetes cluster to Azure Arc, it will:

+* Be represented in Azure Resource Manager by a unique ID

+* Be placed in an Azure subscription and resource group

+* Receive tags just like any other Azure resource

+Azure Arc-enabled Kubernetes supports industry-standard SSL to secure data in transit. For the connected clusters, data at rest is stored encrypted in an Azure Cosmos DB database to ensure confidentiality.

+Azure Arc-enabled Kubernetes supports the following scenarios for connected clusters:

+* Create [custom locations](./custom-locations.md) as target locations for deploying Azure Arc-enabled Data Services (SQL Managed Instances, PostgreSQL Hyperscale.), [App Services on Azure Arc](../../app-service/overview-arc-integration.md) (including web, function, and logic apps), and [Event Grid on Kubernetes](../../event-grid/kubernetes/overview.md).

+> Azure Cache for Redis Enterprise requires standard network Load Balancers that are charged separately from cache instances themselves. For more information, see [Load Balancer pricing](https://azure.microsoft.com/pricing/details/load-balancer/).

+> If an Enterprise cache is configured for multiple Availability Zones, data transfer is billed at the [standard network bandwidth rates](https://azure.microsoft.com/pricing/details/bandwidth/)

+> starting from July 1, 2022.

+> In addition, data persistence adds Managed Disks. The use of these resources is free during the public preview of Enterprise data persistence. This might change when the feature becomes generally available.

+### Availability by region

+Azure Cache for Redis is continually expanding into new regions. To check the availability by region, see [Products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=redis-cache&regions=all).

+### Availability by region

+Azure Cache for Redis is continually expanding into new regions. To check the availability by region for all tiers, see [Products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=redis-cache&regions=all).

+CIS and SELinux hardening support is planned for [Azure Monitoring Agent](./azure-monitor-agent-overview.md). Further hardening and customization methods are not supported nor planned for OMS Agent. For instance, OS images like GitHub Enterprise Server which include customizations such as limitations to user account privileges are not supported.

+| **Text logs** | Yes | Yes |

+| **IIS logs** | Yes | Yes |

+| **Text logs** | Yes | Yes |

+Here's an **introductory video** explaining all about this new agent, including a quick demo of how to set things up using the Azure portal: [ITOps Talk: Azure Monitor Agent](https://www.youtube.com/watch?v=f8bIrFU8tCs)

+ Not all Log Analytics solutions are supported yet. [View supported features and services](#supported-services-and-features).

+| Text logs | Log Analytics workspace - custom table | Events sent to log file on agent machine. |

+| Text logs and Windows IIS logs | Public preview | [Collect text logs with Azure Monitor agent (preview)](data-collection-text-log.md) |

+| [Change Tracking](../../automation/change-tracking/overview.md) | Supported as File Integrity Monitoring in the Microsoft Defender for Cloud Private Preview. | [Sign-up link](https://aka.ms/AMAgent) |

+| [Update Management](../../automation/update-management/overview.md) | Use Update Management v2 (Private Preview) that doesn't require an agent. | [Sign-up link](https://www.yammer.com/azureadvisors/threads/1064001355087872) |

+The Azure Monitor agent supports Azure service tags (both *AzureMonitor* and *AzureResourceManager* tags are required). It supports connecting via **direct proxies, Log Analytics gateway, and private links** as described below.

+If using private links on the agent, you must also add the [DCE endpoints](../essentials/data-collection-endpoint-overview.md#components-of-a-data-collection-endpoint)

+2. After the values for the *settings* and *protectedSettings* parameters are determined, **provide these additional parameters** when you deploy the Azure Monitor agent by using PowerShell commands. Refer to the following examples.

+2. Add the **configuration endpoint URL** to fetch data collection rules to the allowlist for the gateway

+3. Add the **data ingestion endpoint URL** to the allowlist for the gateway

+ Title: Set up the Azure Monitor agent on Windows client devices (Preview)

+description: This article describes the instructions to install the agent on Windows 10, 11 client OS devices, configure data collection, manage and troubleshoot the agent.

+# Azure Monitor agent on Windows client devices (Preview)

+This article provides instructions and guidance for using the client installer for Azure Monitor Agent. It also explains how to leverage Data Collection Rules on Windows client devices.

+With the new client installer available in this preview, you can now collect telemetry data from your Windows client devices in addition to servers and virtual machines.

+Both the [generally available extension](./azure-monitor-agent-manage.md#virtual-machine-extension-details) and this installer use Data Collection rules to configure the **same underlying agent**.

+## Supported device types

+| Device type | Supported? | Installation method | Additional information |

+|:|:|:|:|

+| Windows 10, 11 desktops, workstations | Yes | Client installer (preview) | Installs the agent using a Windows MSI installer |

+| Windows 10, 11 laptops | Yes | Client installer (preview) | Installs the agent using a Windows MSI installer. The installs works on laptops but the agent is **not optimized yet** for battery, network consumption |

+| Virtual machines, scale sets | No | [Virtual machine extension](./azure-monitor-agent-manage.md#virtual-machine-extension-details) | Installs the agent using Azure extension framework |

+| On-premise servers | No | [Virtual machine extension](./azure-monitor-agent-manage.md#virtual-machine-extension-details) (with Azure Arc agent) | Installs the agent using Azure extension framework, provided for on-premise by installing Arc agent |

+## Prerequisites

+1. The machine must be running Windows client OS version 10 RS4 or higher.

+2. To download the installer, the machine should have [C++ Redistributable version 2015)](/cpp/windows/latest-supported-vc-redist?view=msvc-170&preserve-view=true) or higher

+3. The machine must be domain joined to an Azure AD tenant (AADj or Hybrid AADj machines), which enables the agent to fetch Azure AD device tokens used to authenticate and fetch data collection rules from Azure.

+4. You may need tenant admin permissions on the Azure AD tenant.

+5. The device must have access to the following HTTPS endpoints:

+ - global.handler.control.monitor.azure.com

+ - `<virtual-machine-region-name>`.handler.control.monitor.azure.com (example: westus.handler.control.azure.com)

+ - `<log-analytics-workspace-id>`.ods.opinsights.azure.com (example: 12345a01-b1cd-1234-e1f2-1234567g8h99.ods.opsinsights.azure.com)

+ (If using private links on the agent, you must also add the [data collection endpoints](../essentials/data-collection-endpoint-overview.md#components-of-a-data-collection-endpoint))

+6. Existing data collection rule(s) you wish to associate with the devices. If it doesn't exist already, [follow the guidance here to create data collection rule(s)](./data-collection-rule-azure-monitor-agent.md#create-rule-and-associationusingrestapi). **Do not associate the rule to any resources yet**.

+

+## Install the agent

+1. Download the Windows MSI installer for the agent using [this link](https://go.microsoft.com/fwlink/?linkid=2192409). You can also download it from **Monitor** > **Data Collection Rules** > **Create** experience on Azure portal (shown below):

+ [](media/azure-monitor-agent-windows-client/azure-monitor-agent-client-installer-portal-focus.png#lightbox)

+2. Open an elevated admin command prompt window and update path to the location where you downloaded the installer.

+3. To install with **default settings**, run the following command:

+ ```cli

+ msiexec /i AzureMonitorAgentClientSetup.msi /qn

+ ```

+4. To install with custom file paths or [network proxy settings](./azure-monitor-agent-overview.md#proxy-configuration), use the command below with the values from the following table:

+ ```cli

+ msiexec /i AzureMonitorAgentClientSetup.msi /qn DATASTOREDIR="C:\example\folder"

+ ```

+ | Parameter | Description |

+ |:|:|

+ | INSTALLDIR | Directory path where the agent binaries are installed |

+ | DATASTOREDIR | Directory path where the agent stores its operational logs and data |

+ | PROXYUSE | Must be set to "true" to use proxy |

+ | PROXYADDRESS | Set to Proxy Address. PROXYUSE must be set to "true" to be correctly applied |

+ | PROXYUSEAUTH | Set to "true" if proxy requires authentication |

+ | PROXYUSERNAME | Set to Proxy username. PROXYUSE and PROXYUSEAUTH must be set to "true" |

+ | PROXYPASSWORD | Set to Proxy password. PROXYUSE and PROXYUSEAUTH must be set to "true" |

+5. Verify successful installation:

+ - Open **Control Panel** -> **Programs and Features** OR **Settings** -> **Apps** -> **Apps & Features** and ensure you see ΓÇÿAzure Monitor AgentΓÇÖ listed

+ - Open **Services** and confirm ΓÇÿAzure Monitor AgentΓÇÖ is listed and shows as **Running**.

+6. Proceed to create the monitored object that you'll associate data collection rules to, for the agent to actually start operating.

+> [!NOTE]

+> The agent installed with the client installer currently doesn't support updating configuration once it is installed. Uninstall and reinstall AMA to update its configuration.

+## Create and associate a 'Monitored Object'

+You need to create a 'Monitored Object' (MO) that creates a representation for the Azure AD tenant within Azure Resource Manager (ARM). This ARM entity is what Data Collection Rules are then associated with.

+Currently this association is only **limited** to the Azure AD tenant scope, which means configuration applied to the tenant will be applied to all devices that are part of the tenant and running the agent.

+The image below demonstrates how this works:

+

+Then, proceed with the instructions below to create and associate them to a Monitored Object, using REST APIs or PowerShell commands.

+### Using REST APIs

+#### 1. Assign ΓÇÿMonitored Object ContributorΓÇÖ role to the operator

+This step grants the ability to create and link a monitored object to a user.

+**Permissions required:** Since MO is a tenant level resource, the scope of the permission would be higher than a subscription scope. Therefore, an Azure tenant admin may be needed to perform this step. [Follow these steps to elevate Azure AD Tenant Admin as Azure Tenant Admin](/azure/role-based-access-control/elevate-access-global-admin). It will give the Azure AD admin 'owner' permissions at the root scope.

+**Request URI**

+```HTTP

+PUT https://management.azure.com/providers/microsoft.insights/providers/microsoft.authorization/roleassignments/{roleAssignmentGUID}?api-version=2021-04-01-preview

+```

+**URI Parameters**

+| Name | In | Type | Description |

+|:|:|:|:|:|

+| `roleAssignmentGUID` | path | string | Provide any valid guid (you can generate one using https://guidgenerator.com/) |

+**Headers**

+- Authorization: ARM Bearer Token (using ΓÇÿGet-AzAccessTokenΓÇÖ or other method)

+- Content-Type: Application/json

+**Request Body**

+```JSON

+{

+ "properties":

+ {

+ "roleDefinitionId":"/providers/Microsoft.Authorization/roleDefinitions/56be40e24db14ccf93c37e44c597135b",

+ "principalId":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"

+ }

+}

+```

+**Body parameters**

+| Name | Description |

+|:|:|

+| roleDefinitionId | Fixed value: Role definition ID of the 'Monitored Objects Contributor' role: `/providers/Microsoft.Authorization/roleDefinitions/56be40e24db14ccf93c37e44c597135b` |

+| principalId | Provide the `Object Id` of the identity of the user to which the role needs to be assigned. It may be the user who elevated at the beginning of step 1, or another user who will perform later steps. |

+After this step is complete, **reauthenticate** your session and **reacquire** your ARM bearer token.

+#### 2. Create Monitored Object

+This step creates the Monitored Object for the Azure AD Tenant scope. It will be used to represent client devices that are signed with that Azure AD Tenant identity.

+**Permissions required**: Anyone who has 'Monitored Object Contributor' at an appropriate scope can perform this operation, as assigned in step 1.

+**Request URI**

+```HTTP

+PUT https://management.azure.com/providers/Microsoft.Insights/monitoredObjects/{AADTenantId}?api-version=2021-09-01-preview

+```

+**URI Parameters**

+| Name | In | Type | Description |

+|:|:|:|:|:|

+| `AADTenantId` | path | string | ID of the Azure AD tenant that the device(s) belong to. The MO will be created with the same ID |

+**Headers**

+- Authorization: ARM Bearer Token

+- Content-Type: Application/json

+**Request Body**

+```JSON

+{

+ "properties":

+ {

+ "location":"eastus"

+ }

+}

+```

+**Body parameters**

+| Name | Description |

+|:|:|

+| `location` | The Azure region where the MO object would be stored. It should be the **same region** where you created the Data Collection Rule. This is the location of the region from where agent communications would happen. |

+#### 3. Associate DCR to Monitored Object

+Now we associate the Data Collection Rules (DCR) to the Monitored Object by creating a Data Collection Rule Associations. If you haven't already, [follow instructions here](./data-collection-rule-azure-monitor-agent.md#create-rule-and-associationusingrestapi) to create data collection rule(s) first.

+**Permissions required**: Anyone who has ΓÇÿMonitored Object ContributorΓÇÖ at an appropriate scope can perform this operation, as assigned in step 1.

+**Request URI**

+```HTTP

+PUT https://management.azure.com/{MOResourceId}/providers/microsoft.insights/datacollectionruleassociations/assoc?api-version=2021-04-01

+```

+**Sample Request URI**

+```HTTP

+PUT https://management.azure.com/providers/Microsoft.Insights/monitoredObjects/{AADTenantId}/providers/microsoft.insights/datacollectionruleassociations/assoc?api-version=2021-04-01

+```

+**URI Parameters**

+| Name | In | Type | Description |

+|:|:|:|:|:|

+| ``MOResourceId` | path | string | Full resource ID of the MO created in step 2. Example: 'providers/Microsoft.Insights/monitoredObjects/{AADTenantId}' |

+**Headers**

+- Authorization: ARM Bearer Token

+- Content-Type: Application/json

+**Request Body**

+```JSON

+{

+ "properties":

+ {

+ "dataCollectionRuleId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Insights/dataCollectionRules/{DCRName}"

+ }

+}

+```

+**Body parameters**

+| Name | Description |

+|:|:|

+| `dataCollectionRuleID` | The resource ID of an existing Data Collection Rule that you created in the **same region** as the Monitored Object. |

+### Using PowerShell

+```PowerShell

+$TenantID = "xxxxxxxxx-xxxx-xxx" #Your Tenant ID

+$SubscriptionID = "xxxxxx-xxxx-xxxxx" #Your Subscription ID

+$ResourceGroup = "rg-yourResourseGroup" #Your resroucegroup

+$DCRName = "CollectWindowsOSlogs" #Your Data collection rule name

+Connect-AzAccount -Tenant $TenantID

+#Select the subscription

+Select-AzSubscription -SubscriptionId $SubscriptionID

+#Grant Access to User at root scope "/"

+$user = Get-AzADUser -UserPrincipalName (Get-AzContext).Account

+New-AzRoleAssignment -Scope '/' -RoleDefinitionName 'Owner' -ObjectId $user.Id

+#Create Auth Token

+$auth = Get-AzAccessToken

+$AuthenticationHeader = @{

+ "Content-Type" = "application/json"

+ "Authorization" = "Bearer " + $auth.Token

+ }

+#1. Assign ΓÇÿMonitored Object ContributorΓÇÖ Role to the operator

+$newguid = (New-Guid).Guid

+$UserObjectID = $user.Id

+$body = @"

+{

+ "properties": {

+ "roleDefinitionId":"/providers/Microsoft.Authorization/roleDefinitions/56be40e24db14ccf93c37e44c597135b",

+ "principalId": `"$UserObjectID`"

+ }

+}

+"@

+$request = "https://management.azure.com/providers/microsoft.insights/providers/microsoft.authorization/roleassignments/$newguid`?api-version=2021-04-01-preview"

+Invoke-RestMethod -Uri $request -Headers $AuthenticationHeader -Method PUT -Body $body

+##########################

+#2. Create Monitored Object

+$request = "https://management.azure.com/providers/Microsoft.Insights/monitoredObjects/$TenantID`?api-version=2021-09-01-preview"

+$body = @'

+{

+ "properties":{

+ "location":"eastus"

+ }

+}

+'@

+$Respond = Invoke-RestMethod -Uri $request -Headers $AuthenticationHeader -Method PUT -Body $body -Verbose

+$RespondID = $Respond.id

+#########

+#3. Associate DCR to Monitored Object

+$request = "https://management.azure.com$RespondId/providers/microsoft.insights/datacollectionruleassociations/assoc?api-version=2021-04-01"

+$body = @"

+ {

+ "properties": {

+ "dataCollectionRuleId": "/subscriptions/$SubscriptionID/resourceGroups/$ResourceGroup/providers/Microsoft.Insights/dataCollectionRules/$DCRName"

+ }

+ }

+"@

+Invoke-RestMethod -Uri $request -Headers $AuthenticationHeader -Method PUT -Body $body

+```

+## Verify successful setup

+Check the ΓÇÿHeartbeatΓÇÖ table (and other tables you configured in the rules) in the Log Analytics workspace that you specified as a destination in the data collection rule(s).

+The `SourceComputerId`, `Computer`, `ComputerIP` columns should all reflect the client device information respectively, and the `Category` column should say 'Azure Monitor Agent'. See example below:

+[](media/azure-monitor-agent-windows-client/azure-monitor-agent-heartbeat-logs.png)

+## Manage the agent

+### Check the agent version

+You can use any of the following options to check the installed version of the agent:

+- Open **Control Panel** > **Programs and Features** > **Azure Monitor Agent** and see the 'Version' listed

+- Open **Settings** > **Apps** > **Apps and Features** > **Azure Monitor Agent** and see the 'Version' listed

+### Uninstall the agent

+You can use any of the following options to check the installed version of the agent:

+- Open **Control Panel** > **Programs and Features** > **Azure Monitor Agent** and click 'Uninstall'

+- Open **Settings** > **Apps** > **Apps and Features** > **Azure Monitor Agent** and click 'Uninstall'

+If you face issues during 'Uninstall', refer to [troubleshooting guidance](#troubleshoot) below

+### Update the agent

+In order to update the version, install the new version you wish to update to.

+## Troubleshoot

+### View agent diagnostic logs

+1. Rerun the installation with logging turned on and specify the log file name:

+ `Msiexec /I AzureMonitorAgentClientSetup.msi /L*V <log file name>`

+2. Runtime logs are collected automatically either at the default location `C:\Resources\Azure Monitor Agent\` or at the file path mentioned during installation.

+ - If you can't locate the path, the exact location can be found on the registry as `AMADataRootDirPath` on `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\AzureMonitorAgent`.

+3. The 'ServiceLogs' folder contains log from AMA Windows Service, which launches and manages AMA processes

+4. 'AzureMonitorAgent.MonitoringDataStore' contains data/logs from AMA processes.

+### Common issues

+#### Missing DLL

+- Error message: "There's a problem with this Windows Installer package. A DLL required for this installer to complete could not be run. …"

+- Ensure you have installed [C++ Redistributable (>2015)](/cpp/windows/latest-supported-vc-redist?view=msvc-170&preserve-view=true) before installing AMA:

+#### Silent install from command prompt fails

+Make sure to start the installer on administrator command prompt. Silent install can only be initiated from the administrator command prompt.

+#### Uninstallation fails due to the uninstaller being unable to stop the service

+- If There's an option to try again, do try it again

+- If retry from uninstaller doesn't work, cancel the uninstall and stop Azure Monitor Agent service from Services (Desktop Application)

+- Retry uninstall

+#### Force uninstall manually when uninstaller doesn't work

+- Stop Azure Monitor Agent service. Then try uninstalling again. If it fails, then proceed with the following steps

+- Delete AMA service with "sc delete AzureMonitorAgent" from admin cmd

+- Download [this tool](https://support.microsoft.com/topic/fix-problems-that-block-programs-from-being-installed-or-removed-cca7d1b6-65a9-3d98-426b-e9f927e1eb4d) and uninstall AMA

+- Delete AMA binaries. They're stored in `Program Files\Azure Monitor Agent` by default

+- Delete AMA data/logs. They're stored in `C:\Resources\Azure Monitor Agent` by default

+- Open Registry. Check `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Azure Monitor Agent`. If it exists, delete the key.

+## Questions and feedback

+Take this [quick survey](https://forms.microsoft.com/r/CBhWuT1rmM) or share your feedback/questions regarding the preview on the [Azure Monitor Agent User Community](https://teams.microsoft.com/l/team/19%3af3f168b782f64561b52abe75e59e83bc%40thread.tacv2/conversations?groupId=770d6aa5-c2f7-4794-98a0-84fd6ae7f193&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47).

+description: Describes how to create a data collection rule to collect events and performance data from virtual machines using the Azure Monitor agent.

+This article describes how to create a [data collection rule](../essentials/data-collection-rule-overview.md) to collect events and performance counters from virtual machines using the Azure Monitor agent. The data collection rule defines data coming into Azure Monitor and specify where it should be sent.

+To apply a DCR to a virtual machine, you create an association for the virtual machine. A virtual machine may have an association to multiple DCRs, and a DCR may have multiple virtual machines associated to it. This allows you to define a set of DCRs, each matching a particular requirement, and apply them to only the virtual machines where they apply.

+One of the ways to create XPath queries is to use Windows Event Viewer to extract XPath queries as shown below.

+- [Collect text logs using Azure Monitor agent.](data-collection-text-log.md)

+ Title: Collect text logs with Azure Monitor agent (preview)

+description: Configure collection of filed-based text logs using a data collection rule on virtual machines with the Azure Monitor agent.

+# Collect text logs with Azure Monitor agent (preview)

+This tutorial shows you how to configure the collection of file-based text logs with the [Azure Monitor agent](azure-monitor-agent-overview.md) and sending the collected data to a custom table in a Log Analytics workspace. This feature uses a [data collection rule](../essentials/data-collection-rule-overview.md) that you can use to define the structure of the log file and its target table.

+> [!NOTE]

+> This feature is currently in public preview and isn't completely implemented in the Azure portal. This tutorial uses Azure Resource Manager templates for steps that can't yet be performed with the portal.

+In this tutorial, you learn to:

+> [!div class="checklist"]

+> * Create a custom table in a Log Analytics workspace.

+> * Create a data collection endpoint to receive data from an agent.

+> * Create a data collection rule that collects data from both a custom text log file.

+> * Create an association to apply the data collection rule to agents.

+## Prerequisites

+To complete this tutorial, you need the following:

+- Log Analytics workspace where you have at least [contributor rights](../logs/manage-access.md#manage-access-using-azure-permissions) .

+- [Permissions to create Data Collection Rule objects](/azure/azure-monitor/essentials/data-collection-rule-overview#permissions) in the workspace.

+- An agent with supported log file as described in the next section.

+## Log files supported

+The log file must meet the following criteria to be collected by this feature:

+- The log file must be stored on a local drive of a virtual machine, virtual machine scale set, or Arc enabled server with the Azure Monitor installed.

+- Each entry in the log file must be delineated with an [ISO 8601 formatted](https://www.iso.org/standard/40874.html) time stamp or an end of line.

+- The log file must not allow circular logging, log rotation where the file is overwritten with new entries, or the file is renamed and the same file name is reused for continued logging.

+## Steps to collect text logs

+The steps to configure log collection are as follows. The detailed steps for each are provided in the sections below:

+1. Create a new table in your workspace to receive the collected data.

+2. Create a data collection endpoint for the Azure Monitor agent to connect.

+3. Create a data collection rule to define the structure of the log file and destination of the collected data.

+4. Create association between the data collection rule and the agent collecting the log file.

+## Create new table in Log Analytics workspace

+The custom table must be created before you can send data to it. When you create the table, you provide its name and a definition for each of its columns.

+Use the **Tables - Update** API to create the table with the PowerShell code below. This code creates a table called *MyTable_CL* with two columns. You can modify this schema to collect a different table.

+> [!IMPORTANT]

+> Custom tables must use a suffix of *_CL*.

+1. Click the **Cloud Shell** button in the Azure portal and ensure the environment is set to **PowerShell**.

+ :::image type="content" source="../logs/media/tutorial-ingestion-time-transformations-api/open-cloud-shell.png" lightbox="../logs/media/tutorial-ingestion-time-transformations-api/open-cloud-shell.png" alt-text="Screenshot of opening Cloud Shell in the Azure portal.":::

+2. Copy the following PowerShell code and replace the **Path** parameter with the appropriate values for your workspace in the `Invoke-AzRestMethod` command. Paste it into the Cloud Shell prompt to run it.

+ ```PowerShell

+ $tableParams = @'

+ {

+ "properties": {

+ "schema": {

+ "name": "MyTable_CL",

+ "columns": [

+ {

+ "name": "TimeGenerated",

+ "type": "DateTime"

+ },

+ {

+ "name": "RawData",

+ "type": "String"

+ }

+ ]

+ }

+ }

+ }

+ '@

+ Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

+ ```

+## Create data collection endpoint

+A [data collection endpoint (DCE)](../essentials/data-collection-endpoint-overview.md) is required for the agent to connect to send the data to Azure Monitor. The DCE must be located in the same region as the Log Analytics Workspace where the data will be sent. If you already have a data collection endpoint for the agent, then you can use the existing one.

+1. In the Azure portal's search box, type in *template* and then select **Deploy a custom template**.

+ :::image type="content" source="../logs/media/tutorial-ingestion-time-transformations-api/deploy-custom-template.png" lightbox="../logs/media/tutorial-ingestion-time-transformations-api/deploy-custom-template.png" alt-text="Screenshot that shows portal blade to deploy custom template.":::

+2. Click **Build your own template in the editor**.

+ :::image type="content" source="../logs/media/tutorial-ingestion-time-transformations-api/build-custom-template.png" lightbox="../logs/media/tutorial-ingestion-time-transformations-api/build-custom-template.png" alt-text="Screenshot that shows portal blade to build template in the editor.":::

+3. Paste the Resource Manager template below into the editor and then click **Save**. You don't need to modify this template since you will provide values for its parameters.

+ :::image type="content" source="../logs/media/tutorial-ingestion-time-transformations-api/edit-template.png" lightbox="../logs/media/tutorial-ingestion-time-transformations-api/edit-template.png" alt-text="Screenshot that shows portal blade to edit Resource Manager template.":::

+ ```json

+ {

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "dataCollectionEndpointName": {

+ "type": "string",

+ "metadata": {

+ "description": "Specifies the name of the Data Collection Endpoint to create."

+ }

+ },

+ "location": {

+ "type": "string",

+ "defaultValue": "westus2",

+ "allowedValues": [

+ "westus2",

+ "eastus2",

+ "eastus2euap"

+ ],

+ "metadata": {

+ "description": "Specifies the location in which to create the Data Collection Endpoint."

+ }

+ }

+ },

+ "resources": [

+ {

+ "type": "Microsoft.Insights/dataCollectionEndpoints",

+ "name": "[parameters('dataCollectionEndpointName')]",

+ "location": "[parameters('location')]",

+ "apiVersion": "2021-04-01",

+ "properties": {

+ "networkAcls": {

+ "publicNetworkAccess": "Enabled"

+ }

+ }

+ }

+ ],

+ "outputs": {

+ "dataCollectionEndpointId": {

+ "type": "string",

+ "value": "[resourceId('Microsoft.Insights/dataCollectionEndpoints', parameters('dataCollectionEndpointName'))]"

+ }

+ }

+ }

+ ```

+4. On the **Custom deployment** screen, specify a **Subscription** and **Resource group** to store the data collection rule and then provide values a **Name** for the data collection endpoint. The **Location** should be the same location as the workspace. The **Region** will already be populated and is used for the location of the data collection endpoint.

+ :::image type="content" source="../logs/media/tutorial-ingestion-time-transformations-api/custom-deployment-values.png" lightbox="../logs/media/tutorial-ingestion-time-transformations-api/custom-deployment-values.png" alt-text="Screenshot that shows portal blade to edit custom deployment values for data collection endpoint.":::

+5. Click **Review + create** and then **Create** when you review the details.

+6. Once the DCE is created, select it so you can view its properties. Note the **Logs ingestion URI** since you'll need this in a later step.

+ :::image type="content" source="../logs/media/tutorial-custom-logs-api/data-collection-endpoint-overview.png" lightbox="../logs/media/tutorial-custom-logs-api/data-collection-endpoint-overview.png" alt-text="Screenshot that shows portal blade with details of data collection endpoint uri.":::

+7. Click **JSON View** to view other details for the DCE. Copy the **Resource ID** since you'll need this in a later step.

+ :::image type="content" source="../logs/media/tutorial-custom-logs-api/data-collection-endpoint-json.png" lightbox="../logs/media/tutorial-custom-logs-api/data-collection-endpoint-json.png" alt-text="Screenshot that shows JSON view for data collection endpoint with the resource ID.":::

+## Create data collection rule

+The [data collection rule (DCR)](../essentials/data-collection-rule-overview.md) defines the schema of data that being collected from the log file, the transformation that will be applied to it, and the destination workspace and table the transformed data will be sent to.

+1. The data collection rule requires the resource ID of your workspace. Navigate to your workspace in the **Log Analytics workspaces** menu in the Azure portal. From the **Properties** page, copy the **Resource ID** and save it for later use.

+ :::image type="content" source="../logs/media/tutorial-custom-logs-api/workspace-resource-id.png" lightbox="../logs/media/tutorial-custom-logs-api/workspace-resource-id.png" alt-text="Screenshot showing workspace resource ID.":::

+1. In the Azure portal's search box, type in *template* and then select **Deploy a custom template**.

+ :::image type="content" source="../logs/media/tutorial-ingestion-time-transformations-api/deploy-custom-template.png" lightbox="../logs/media/tutorial-ingestion-time-transformations-api/deploy-custom-template.png" alt-text="Screenshot that shows portal blade to deploy custom template.":::

+2. Click **Build your own template in the editor**.

+ :::image type="content" source="../logs/media/tutorial-ingestion-time-transformations-api/build-custom-template.png" lightbox="../logs/media/tutorial-ingestion-time-transformations-api/build-custom-template.png" alt-text="Screenshot that shows portal blade to build template in the editor.":::

+3. Paste the Resource Manager template below into the editor and then change the following values:

+ You may choose to modify the following details in the DCR defined in this template:

+ - `streamDeclarations`: Defines the columns of the incoming data. This must match the structure of the log file.

+ - `filePatterns`: Specifies the location and file pattern of the log files to collect. This defines a separate pattern for Windows and Linux agents.

+ - `transformKql`: Specifies a [transformation](../logs/../essentials/data-collection-rule-transformations.md) to apply to the incoming data before it's sent to the workspace. Since data collection rules for Azure Monitor agent don't yet support transformations, this value will always be `source`.

+4. Click **Save**.

+ :::image type="content" source="../logs/media/tutorial-ingestion-time-transformations-api/edit-template.png" lightbox="../logs/media/tutorial-ingestion-time-transformations-api/edit-template.png" alt-text="Screenshot that shows portal blade to edit Resource Manager template.":::

+ ```json

+ {

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "dataCollectionRuleName": {

+ "type": "string",

+ "metadata": {

+ "description": "Specifies the name of the Data Collection Rule to create."

+ }

+ },

+ "location": {

+ "type": "string",

+ "defaultValue": "westus2",

+ "allowedValues": [

+ "westus2",

+ "eastus2",

+ "eastus2euap"

+ ],

+ "metadata": {

+ "description": "Specifies the location in which to create the Data Collection Rule."

+ }

+ },

+ "workspaceName": {

+ "type": "string",

+ "metadata": {

+ "description": "Name of the Log Analytics workspace to use."

+ }

+ },

+ "workspaceResourceId": {

+ "type": "string",

+ "metadata": {

+ "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."

+ }

+ },

+ "endpointResourceId": {

+ "type": "string",

+ "metadata": {

+ "description": "Specifies the Azure resource ID of the Data Collection Endpoint to use."

+ }

+ }

+ },

+ "resources": [

+ {

+ "type": "Microsoft.Insights/dataCollectionRules",

+ "name": "[parameters('dataCollectionRuleName')]",

+ "location": "[parameters('location')]",

+ "apiVersion": "2021-09-01-preview",

+ "properties": {

+ "dataCollectionEndpointId": "[parameters('endpointResourceId')]",

+ "streamDeclarations": {

+ "Custom-MyLogFileFormat": {

+ "columns": [

+ {

+ "name": "TimeGenerated",

+ "type": "datetime"

+ },

+ {

+ "name": "RawData",

+ "type": "string"

+ }

+ ]

+ }

+ },

+ "dataSources": {

+ "logFiles ": [

+ {

+ "streams": [

+ "Custom-MyLogFileFormat "

+ ],

+ "filePatterns": [

+ "C:\\JavaLogs\\*.log"

+ ],

+ "format": "text",

+ "settings": {

+ "text": {

+ "recordStartTimestampFormat": "ISO 8601"

+ }

+ },

+ "name": "myLogFileFormat-Windows"

+ },

+ {

+ "streams": [

+ "Custom-MyLogFileFormat"

+ ],

+ "filePatterns": [

+ "/var/*.log"

+ ],

+ "format": "text",

+ "settings": {

+ "text": {

+ "recordStartTimestampFormat": "ISO 8601"

+ }

+ },

+ "name": "myLogFileFormat-Linux"

+ }

+ ]

+ },

+ "destinations": {

+ "logAnalytics": [

+ {

+ "workspaceResourceId": "[parameters('workspaceResourceId')]",

+ "name": "[parameters('workspaceName')]"

+ }

+ ]

+ },

+ "dataFlows": [

+ {

+ "streams": [

+ "Custom-MyLogFileFormat"

+ ],

+ "destinations": [

+ "[parameters('workspaceName')]"

+ ],

+ "transformKql": "source",

+ "outputStream": "Custom-MyTable_CL"

+ }

+ ]

+ }

+ }

+ ],

+ "outputs": {

+ "dataCollectionRuleId": {

+ "type": "string",

+ "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"

+ }

+ }

+ }

+ ```

+5. On the **Custom deployment** screen, specify a **Subscription** and **Resource group** to store the data collection rule and then provide values defined in the template. This includes a **Name** for the data collection rule and the **Workspace Resource ID** and **Endpoint Resource ID**. The **Location** should be the same location as the workspace. The **Region** will already be populated and is used for the location of the data collection rule.

+ :::image type="content" source="media/data-collection-text-log/custom-deployment-values.png" lightbox="media/data-collection-text-log/custom-deployment-values.png" alt-text="Screenshot that shows portal blade to edit custom deployment values for data collection rule.":::

+6. Click **Review + create** and then **Create** when you review the details.

+7. When the deployment is complete, expand the **Deployment details** box and click on your data collection rule to view its details. Click **JSON View**.

+ :::image type="content" source="media/data-collection-text-log/data-collection-rule-details.png" lightbox="media/data-collection-text-log/data-collection-rule-details.png" alt-text="Screenshot that shows portal blade with data collection rule details.":::

+8. Change the API version to **2021-09-01-preview**.

+ :::image type="content" source="media/data-collection-text-log/data-collection-rule-json-view.png" lightbox="media/data-collection-text-log/data-collection-rule-json-view.png" alt-text="Screenshot that shows JSON view for data collection rule.":::

+9. Copy the **Resource ID** for the data collection rule. You'll use this in the next step.

+## Create association with agent

+The final step is to create a data collection association that associates the data collection rule to the agents with the log file to be collected. A single data collection rule can be used with multiple agents.

+1. From the **Monitor** menu in the Azure portal, select **Data Collection Rules** and select the rule that you just created.

+ :::image type="content" source="media/data-collection-text-log/data-collection-rules.png" lightbox="media/data-collection-text-log/data-collection-rules.png" alt-text="Screenshot that shows portal blade with data collection rules menu item.":::

+2. Select **Resources** and then click **Add** to view the available resources.

+ :::image type="content" source="media/data-collection-text-log/data-collection-rules.png" lightbox="media/data-collection-text-log/data-collection-rules.png" alt-text="Screenshot that shows portal blade with resources for the data collection rule.":::

+3. Select either individual agents to associate the data collection rule, or select a resource group to create an association for all agents in that resource group. Click **Apply**.

+ :::image type="content" source="media/data-collection-text-log/select-resources.png" lightbox="media/data-collection-text-log/select-resources.png" alt-text="Screenshot that shows portal blade to add resources to the data collection rule.":::

+## Next steps

+- Learn more about the [Azure Monitor agent](azure-monitor-agent-overview.md).

+- Learn more about [data collection rules](../essentials/data-collection-rule-overview.md).

+- Learn more about [data collection endpoints](../essentials/data-collection-endpoint-overview.md).

+ Title: Collect text logs with Log Analytics agent in Azure Monitor

+# Collect text logs with Log Analytics agent in Azure Monitor

+> This article covers collecting text logs with the [Log Analytics agent](./log-analytics-agent.md). See [Collect text logs with Azure Monitor agent (preview)](../agents/data-collection-text-log.md) for details on collecting text logs with [Azure Monitor agent](azure-monitor-agent-overview.md).

+- As a best practice, the log file should include the date time that it was created to prevent log rotation overwriting or renaming.

+> This article covers collecting IIS logs with the [Log Analytics agent](./log-analytics-agent.md). See [Collect text logs with Azure Monitor agent (preview)](../agents/data-collection-text-log.md) for details on collecting IIS logs with [Azure Monitor agent](azure-monitor-agent-overview.md).

+Activity log alerts allow you to be notified on events and operations that are logged in [Azure Activity Log](../essentials/activity-log.md). An alert is fired when a new [activity log event](../essentials/activity-log-schema.md) occurs that matches the conditions specified in the alert rule.

+Activity log alert rules are Azure resources, so they can be created by using an Azure Resource Manager template. They also can be created, updated, or deleted in the Azure portal. This article introduces the concepts behind activity log alerts. For more information on creating or usage of activity log alert rules, see [Create and manage activity log alerts](./alerts-activity-log.md).

+You can create activity log alert rules to receive notifications on one of the following activity log event categories:

+| Event Category | Category Description | Example |

+|-|-||

+| Administrative | ARM operation (e.g. create, update, delete, or action) was performed on resources in your subscription, resource group, or on a specific Azure resource.| A virtual machine in your resource group is deleted |

+| Service health | Service incidents (e.g. an outage or a maintenance event) occurred that may impact services in your subscription on a specific region.| An outage impacting VMs in your subscription in East US. |

+| Resource health | The health of a specific resource is degraded, or the resource becomes unavailable. | A VM in your subscription transitions to a degraded or unavailable state. |

+| Autoscale | An Azure Autoscale operation has occurred, resulting in success or failure | An autoscale action on a virtual machine scale set in your subscription failed. |

+| Recommendation | A new Azure Advisor recommendation is available for your subscription | A high-impact recommendation for your subscription was received. |

+| Security | Events detected by Microsoft Defender for Cloud | A suspicious double extension file executed was detected in your subscription |

+| Policy | Operations performed by Azure Policy | Policy Deny event occurred in your subscription. |

+> Alert rules **cannot** be created for events in Alert category of activity log.

+You can configure an activity log alert rule based on any top-level property in the JSON object for an activity log event. For more information, see [Categories in the Activity Log](../essentials/activity-log.md#view-the-activity-log).

+An alternative simple way for creating conditions for activity log alert rules is to explore or filter events via [Activity log in Azure portal](../essentials/activity-log.md#view-the-activity-log). In Azure Monitor - Activity log, one can filter and locate a required event and then create an alert rule to notify on similar events by using the **New alert rule** button.

+Activity log events have a few common properties which can be used to define an activity log alert rule condition:

+- **Resource type**: Resource Manager defined namespace for the target of the alert rule.

+- **Operation name**: The [Azure resource provider operation](../../role-based-access-control/resource-provider-operations.md) name utilized for Azure role-based access control. Operations not registered with Azure Resource Manager cannot be used in an activity log alert rule.

+In addition to these comment properties, different activity log events have category-specific properties that can be used to configure an alert rule for events of each category. For example, when creating a service health alert rule you can configure a condition on the impacted region or service that appear in the event.

+When an activity log alert is fired, it uses an action group to trigger actions or send notifications. An action group is a reusable set of notification receivers, such as email addresses, webhook URLs, or SMS phone numbers. The receivers can be referenced from multiple alerts rules to centralize and group your notification channels. When you define your activity log alert rule, you have two options. You can:

+You can create up to 100 active activity log alert rules per subscription (including rules for all activity log event categories, such as resource health or service health). This limit can't be increased.

+If you are reaching near this limit, there are several guidelines you can follow to optimize the use of activity log alerts rules, so that you can cover more resources and events with the same number of rules:

+* A single resource health alert rule can cover multiple resource types and resources in your subscription. If you're using multiple resource health alert rules per subscription, you can replace them with a smaller number of rules (or even a single rule) that covers multiple resource types.

+## Pricing model

+Each Log Alert rule is billed based the interval at which the log query is evaluated (more frequent query evaluation results in a higher cost). Additionally, for Log Alerts configured for [at scale monitoring](#split-by-alert-dimensions), the cost will also depend on the number of time series created by the dimensions resulting from your query.

+Prices for Log Alert rules are availalble on the [Azure Monitor pricing page](https://azure.microsoft.com/pricing/details/monitor/).

+## View log alerts usage on your Azure bill

+Log Alerts are listed under resource provider `microsoft.insights/scheduledqueryrules` with:

+Connection strings define where to send telemetry data.

+> [!IMPORTANT]

+> Do not use a connection string and instrumentation key simultaneously. Whichever was set last will take precedence.

+> [!NOTE]

+- See [Set daily cap on Log Analytics workspace](logs/daily-cap.md) to control your costs by setting a daily limit on the amount of data that may be ingested in a workspace.

+The developers of each resource provider choose the severity levels of their resource entries. As a result, the actual severity to you can vary depending on how your application is built. For example, items that are "critical" to a particular resource taken in isolation may not be as important as "errors" in a resource type that is central to your Azure application. Be sure to consider this fact when deciding what events to alert on.

+Each event in the Activity Log has a particular category that is described in the following table. See the sections below for more detail on each category and its schema when you access the Activity log from the portal, PowerShell, CLI, and REST API. The schema is different when you [stream the Activity log to storage or Event Hubs](./resource-logs.md#send-to-azure-event-hubs). A mapping of the properties to the [resource logs schema](./resource-logs-schema.md) is provided in the last section of the article.

+Following is an example of an event using this schema:

+## Pricing model

+Processing data to stream logs is charged for [certain services](resource-logs-categories.md#costs) when sent to destinations other than a Log Analytics workspace. There's no direct charge when this data is sent to a Log Analytics workspace, but there is a Log Analytics charge for ingesting the data into a workspace.

+The charge is based on the number of bytes in the exported JSON formatted log data, measured in GB (10^9 bytes).

+Pricing is availalble on the [Azure Monitor pricing page](https://azure.microsoft.com/pricing/details/monitor/).

+* [Create diagnostic settings to send platform logs and metrics to different destinations](../essentials/diagnostic-settings.md).

+* [Azure NAT Gateway](/azure/virtual-network/nat-gateway/troubleshoot-nat)

+| IIS logs and text logs | collected once their timestamp changes | For IIS logs, this is influenced by the [rollover schedule configured on IIS](../agents/data-sources-iis-logs.md). |

+| Record stored in workspace and available for queries | [ingestion_time()](/azure/kusto/query/ingestiontimefunction) | It is recommended to use ingestion_time() if there is a need to filter only records that were ingested in a certain time window. In such case, it is recommended to add also TimeGenerated filter with a larger range. |

+- Scheduled export from a log query using a Logic App. This is similar to the data export feature, but allows you to export historical data from your workspace, using filters and aggregation. This method is subject to [log query limits](../service-limits.md#log-analytics-workspaces) and not intended for scale. See [Archive data from Log Analytics workspace to Azure Storage Account using Logic App](logs-export-logic-app.md).

+ Title: Tutorial - Send custom logs to Azure Monitor Logs using Resource Manager templates

+description: Tutorial on how to send custom logs to a Log Analytics workspace in Azure Monitor using Resource Manager templates.

+# Tutorial: Send custom logs to Azure Monitor Logs using Resource Manager templates (preview)

+[Custom logs](custom-logs-overview.md) in Azure Monitor allow you to send custom data to tables in a Log Analytics workspace with a REST API. This tutorial walks through configuration of a new table and a sample application to send custom logs to Azure Monitor using Resource Manager templates.

+> This tutorial uses Resource Manager templates and REST API to configure custom logs. See [Tutorial: Send custom logs to Azure Monitor Logs using the Azure portal (preview)](tutorial-custom-logs.md) for a similar tutorial using the Azure portal.

+> This tutorial uses PowerShell from Azure Cloud Shell to make REST API calls using the Azure Monitor **Tables** API and the Azure portal to install Resource Manager templates. You can use any other method to make these calls.

+1. Navigate to your workspace in the **Log Analytics workspaces** menu in the Azure portal. From the **Properties** page, copy the **Resource ID** and save it for later use.

+ :::image type="content" source="media/tutorial-custom-logs/new-app-id.png" lightbox="media/tutorial-custom-logs/new-app-id.png" alt-text="Screenshot showing app ID.":::

+ :::image type="content" source="media/tutorial-ingestion-time-transformations-api/open-cloud-shell.png" lightbox="media/tutorial-ingestion-time-transformations-api/open-cloud-shell.png" alt-text="Screenshot of opening Cloud Shell":::

+2. Copy the following PowerShell code and replace the **Path** parameter with the appropriate values for your workspace in the `Invoke-AzRestMethod` command. Paste it into the Cloud Shell prompt to run it.

+3. Paste the Resource Manager template below into the editor and then click **Save**. You don't need to modify this template since you will provide values for its parameters.

+ :::image type="content" source="media/tutorial-ingestion-time-transformations-api/edit-template.png" lightbox="media/tutorial-ingestion-time-transformations-api/edit-template.png" alt-text="Screenshot to edit Resource Manager template.":::

+6. Once the DCE is created, select it so you can view its properties. Note the **Logs ingestion URI** since you'll need this in a later step.

+3. Paste the Resource Manager template below into the editor and then click **Save**.

+ :::image type="content" source="media/tutorial-ingestion-time-transformations-api/edit-template.png" lightbox="media/tutorial-ingestion-time-transformations-api/edit-template.png" alt-text="Screenshot to edit Resource Manager template.":::

+1. From the DCR in the Azure portal, select **Access Control (IAM)** and then **Add role assignment**.

+| Platform Logs | Processing of [diagnostic and auditing information](essentials/resource-logs.md) is charged for [certain services](essentials/resource-logs-categories.md#costs) when sent to destinations other than a Log Analytics workspace. There's no direct charge when this data is sent to a Log Analytics workspace, but there is a charge for the workspace data ingestion and collection. |

+| Metrics | There is no charge for [standard metrics](essentials/metrics-supported.md) collected from Azure resources. There is a cost for cost for collecting [custom metrics](essentials/metrics-custom-overview.md) and for retrieving metrics from the [REST API](essentials/rest-api-walkthrough.md#retrieve-metric-values). |

+| Alerts | Charged based on the type and number of [signals](alerts/alerts-overview.md#what-you-can-alert-on) used by the alert rule, its frequency, and the type of [notification](alerts/action-groups.md) used in response. For [log alerts](alerts/alerts-unified-log.md) configured for [at scale monitoring](alerts/alerts-unified-log.md#split-by-alert-dimensions), the cost will also depend on the number of time series created by the dimensions resulting from your query. |

+| Web tests | There is a cost for [multi-step web tests](app/availability-multistep.md) in Application Insights, but this feature has been deprecated.

+Following is basic guidance that you can use for common resources.

+- **Container insights.** See [Estimating costs to monitor your AKS cluster](containers/container-insights-cost.md#estimating-costs-to-monitor-your-aks-cluster) for guidance on estimating data for your AKS cluster.

+The [Azure Monitor pricing calculator](https://azure.microsoft.com/pricing/calculator/?service=monitor) includes data volume estimation calculators for these three cases.

+- See [Azure Monitor best practices - Cost management](best-practices-cost.md) for best practices on configuring and managing Azure Monitor to minimize your charges.

+* You can modify the Unix permissions on the source volume *but not on the destination volume* that is in a cross-region replication configuration.

+ * <a name="administrators-privilege-users"></a>**Administrators privilege users**

+## April 2022

+* The [Administrators privilege users](create-active-directory-connections.md#administrators-privilege-users) feature is now generally available (GA).

+ You no longer need to register this feature before using it.

+## indexOf

+`indexOf(arrayToSearch, itemToFind)`

+Returns an integer for the index of the first occurrence of an item in an array. The comparison is **case-sensitive** for strings.

+Namespace: [sys](bicep-functions.md#namespaces-for-functions).

+### Parameters

+| Parameter | Required | Type | Description |

+| | | | |

+| arrayToSearch | Yes | array | The array to use for finding the index of the searched item. |

+| itemToFind | Yes | int, string, array, or object | The item to find in the array. |

+### Return value

+An integer representing the first index of the item in the array. The index is zero-based. If the item isn't found, -1 is returned.

+### Examples

+The following example shows how to use the indexOf and lastIndexOf functions:

+```bicep

+var names = [

+ 'one'

+ 'two'

+ 'three'

+]

+var numbers = [

+ 4

+ 5

+ 6

+]

+var collection = [

+ names

+ numbers

+]

+var duplicates = [

+ 1

+ 2

+ 3

+ 1

+]

+output index1 int = lastIndexOf(names, 'two')

+output index2 int = indexOf(names, 'one')

+output notFoundIndex1 int = lastIndexOf(names, 'Three')

+output index3 int = lastIndexOf(numbers, 4)

+output index4 int = indexOf(numbers, 6)

+output notFoundIndex2 int = lastIndexOf(numbers, '5')

+output index5 int = indexOf(collection, numbers)

+output index6 int = indexOf(duplicates, 1)

+output index7 int = lastIndexOf(duplicates, 1)

+```

+The output from the preceding example is:

+| Name | Type | Value |

+| - | - | -- |

+| index1 |int | 1 |

+| index2 | int | 0 |

+| index3 | int | 0 |

+| index4 | int | 2 |

+| index5 | int | 1 |

+| index6 | int | 0 |

+| index7 | int | 3 |

+| notFoundIndex1 | int | -1 |

+| notFoundIndex2 | int | -1 |

+## lastIndexOf

+`lastIndexOf(arrayToSearch, itemToFind)`

+Returns an integer for the index of the last occurrence of an item in an array. The comparison is **case-sensitive** for strings.

+Namespace: [sys](bicep-functions.md#namespaces-for-functions).

+### Parameters

+| Parameter | Required | Type | Description |

+| | | | |

+| arrayToSearch | Yes | array | The array to use for finding the index of the searched item. |

+| itemToFind | Yes | int, string, array, or object | The item to find in the array. |

+### Return value

+An integer representing the last index of the item in the array. The index is zero-based. If the item isn't found, -1 is returned.

+### Examples

+The following example shows how to use the indexOf and lastIndexOf functions:

+```bicep

+var names = [

+ 'one'

+ 'two'

+ 'three'

+]

+var numbers = [

+ 4

+ 5

+ 6

+]

+var collection = [

+ names

+ numbers

+]

+var duplicates = [

+ 1

+ 2

+ 3

+ 1

+]

+output index1 int = lastIndexOf(names, 'two')

+output index2 int = indexOf(names, 'one')

+output notFoundIndex1 int = lastIndexOf(names, 'Three')

+output index3 int = lastIndexOf(numbers, 4)

+output index4 int = indexOf(numbers, 6)

+output notFoundIndex2 int = lastIndexOf(numbers, '5')

+output index5 int = indexOf(collection, numbers)

+output index6 int = indexOf(duplicates, 1)

+output index7 int = lastIndexOf(duplicates, 1)

+```

+The output from the preceding example is:

+| Name | Type | Value |

+| - | - | -- |

+| index1 |int | 1 |

+| index2 | int | 0 |

+| index3 | int | 0 |

+| index4 | int | 2 |

+| index5 | int | 1 |

+| index6 | int | 0 |

+| index7 | int | 3 |

+| notFoundIndex1 | int | -1 |

+| notFoundIndex2 | int | -1 |

+For arrays, the function iterates through each element in the first parameter and adds it to the result if it isn't already present. Then, it repeats the process for the second parameter and any more parameters. If a value is already present, its earlier placement in the array is preserved.

+* [indexOf](./bicep-functions-array.md#indexof)

+* [lastIndexOf](./bicep-functions-array.md#lastindexof)

+If you have a **Delete** lock on a resource and attempt to delete its resource group, the whole delete operation is blocked. Even if the resource group or other resources in the resource group aren't locked, the deletion doesn't happen. You never have a partial deletion.

+When you [cancel an Azure subscription](../../cost-management-billing/manage/cancel-azure-subscription.md#what-happens-after-subscription-cancellation), the resources are initially deactivated but not deleted. A resource lock doesn't block canceling the subscription. After a waiting period, the resources are permanently deleted. The resource lock doesn't prevent the permanent deletion of the resources.

+- A read-only lock on a **AKS cluster** prevents all users from accessing any cluster resources from the **Kubernetes Resources** section of AKS cluster on the left of the Azure portal. These operations require a POST request for authentication.

+> | workspaces | resource group | 4-63 | Alphanumerics and hyphens.<br><br>Start and end with alphanumeric. |

+This article describes the template functions for working with arrays.

+## indexOf

+`indexOf(arrayToSearch, itemToFind)`

+Returns an integer for the index of the first occurrence of an item in an array. The comparison is **case-sensitive** for strings.

+### Parameters

+| Parameter | Required | Type | Description |

+| | | | |

+| arrayToSearch | Yes | array | The array to use for finding the index of the searched item. |

+| itemToFind | Yes | int, string, array, or object | The item to find in the array. |

+### Return value

+An integer representing the first index of the item in the array. The index is zero-based. If the item isn't found, -1 is returned.

+### Examples

+The following example shows how to use the indexOf and lastIndexOf functions:

+```json

+{

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "variables": {

+ "names": [

+ "one",

+ "two",

+ "three"

+ ],

+ "numbers": [

+ 4,

+ 5,

+ 6

+ ],

+ "collection": [

+ "[variables('names')]",

+ "[variables('numbers')]"

+ ],

+ "duplicates": [

+ 1,

+ 2,

+ 3,

+ 1

+ ]

+ },

+ "resources": [],

+ "outputs": {

+ "index1": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('names'), 'two')]"

+ },

+ "index2": {

+ "type": "int",

+ "value": "[indexOf(variables('names'), 'one')]"

+ },

+ "notFoundIndex1": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('names'), 'Three')]"

+ },

+ "index3": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('numbers'), 4)]"

+ },

+ "index4": {

+ "type": "int",

+ "value": "[indexOf(variables('numbers'), 6)]"

+ },

+ "notFoundIndex2": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('numbers'), '5')]"

+ },

+ "index5": {

+ "type": "int",

+ "value": "[indexOf(variables('collection'), variables('numbers'))]"

+ },

+ "index6": {

+ "type": "int",

+ "value": "[indexOf(variables('duplicates'), 1)]"

+ },

+ "index7": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('duplicates'), 1)]"

+ }

+ }

+}

+```

+The output from the preceding example is:

+| Name | Type | Value |

+| - | - | -- |

+| index1 |int | 1 |

+| index2 | int | 0 |

+| index3 | int | 0 |

+| index4 | int | 2 |

+| index5 | int | 1 |

+| index6 | int | 0 |

+| index7 | int | 3 |

+| notFoundIndex1 | int | -1 |

+| notFoundIndex2 | int | -1 |

+## lastIndexOf

+`lastIndexOf(arrayToSearch, itemToFind)`

+Returns an integer for the index of the last occurrence of an item in an array. The comparison is **case-sensitive** for strings.

+### Parameters

+| Parameter | Required | Type | Description |

+| | | | |

+| arrayToSearch | Yes | array | The array to use for finding the index of the searched item. |

+| itemToFind | Yes | int, string, array, or object | The item to find in the array. |

+### Return value

+An integer representing the last index of the item in the array. The index is zero-based. If the item isn't found, -1 is returned.

+### Examples

+The following example shows how to use the indexOf and lastIndexOf functions:

+```json

+{

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "variables": {

+ "names": [

+ "one",

+ "two",

+ "three"

+ ],

+ "numbers": [

+ 4,

+ 5,

+ 6

+ ],

+ "collection": [

+ "[variables('names')]",

+ "[variables('numbers')]"

+ ],

+ "duplicates": [

+ 1,

+ 2,

+ 3,

+ 1

+ ]

+ },

+ "resources": [],

+ "outputs": {

+ "index1": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('names'), 'two')]"

+ },

+ "index2": {

+ "type": "int",

+ "value": "[indexOf(variables('names'), 'one')]"

+ },

+ "notFoundIndex1": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('names'), 'Three')]"

+ },

+ "index3": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('numbers'), 4)]"

+ },

+ "index4": {

+ "type": "int",

+ "value": "[indexOf(variables('numbers'), 6)]"

+ },

+ "notFoundIndex2": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('numbers'), '5')]"

+ },

+ "index5": {

+ "type": "int",

+ "value": "[indexOf(variables('collection'), variables('numbers'))]"

+ },

+ "index6": {

+ "type": "int",

+ "value": "[indexOf(variables('duplicates'), 1)]"

+ },

+ "index7": {

+ "type": "int",

+ "value": "[lastIndexOf(variables('duplicates'), 1)]"

+ }

+ }

+}

+```

+The output from the preceding example is:

+| Name | Type | Value |

+| - | - | -- |

+| index1 |int | 1 |

+| index2 | int | 0 |

+| index3 | int | 0 |

+| index4 | int | 2 |

+| index5 | int | 1 |

+| index6 | int | 0 |

+| index7 | int | 3 |

+| notFoundIndex1 | int | -1 |

+| notFoundIndex2 | int | -1 |

+For arrays, the function iterates through each element in the first parameter and adds it to the result if it isn't already present. Then, it repeats the process for the second parameter and any more parameters. If a value is already present, its earlier placement in the array is preserved.

+* [indexOf](template-functions-array.md#indexof)

+* [lastIndexOf](template-functions-array.md#lastindexof)

+### Enable GitHub authentication and Git deployment for web app

+ > You can use geo-replication to create secondary replicas in the same region as the primary. You can use these secondaries to satisfy read scale-out scenarios in the same region. However, a secondary replica in the same region does not provide additional resilience to catastrophic failures or large scale outages, and therefore is not a suitable failover target for disaster recovery purposes. It also does not guarantee availability zone isolation. Use Business Critical or Premium service tiers [zone redundant configuration](high-availability-sla.md#premium-and-business-critical-service-tier-zone-redundant-availability) or General Purpose service tier [zone redundant configuration](high-availability-sla.md#general-purpose-service-tier-zone-redundant-availability) to achieve availability zone isolation.

+| [Zone redundant configuration for Hyperscale databases](high-availability-sla.md#hyperscale-service-tier-zone-redundant-availability-preview) | The zone redundant configuration feature utilizes [Azure Availability Zones](../../availability-zones/az-overview.md#availability-zones) to replicate databases across multiple physical locations within an Azure region. By selecting [zone redundancy](high-availability-sla.md#hyperscale-service-tier-zone-redundant-availability-preview), you can make your Hyperscale databases resilient to a much larger set of failures, including catastrophic datacenter outages, without any changes to the application logic.|

+|||

+| [Zone redundant configuration for General Purpose tier](high-availability-sla.md#general-purpose-service-tier-zone-redundant-availability) | April 2022 | The zone redundant configuration feature utilizes [Azure Availability Zones](../../availability-zones/az-overview.md#availability-zones) to replicate databases across multiple physical locations within an Azure region. By selecting [zone redundancy](high-availability-sla.md#general-purpose-service-tier-zone-redundant-availability), you can make your provisioned and serverless General Purpose databases and elastic pools resilient to a much larger set of failures, including catastrophic datacenter outages, without any changes to the application logic.|

+### April 2022

+| Changes | Details |

+| | |

+| **General Purpose tier Zone redundancy GA** | Enabling zone redundancy for your provisioned and serverless General Purpose databases and elastic pools is now generally available in select regions. To learn more, including region availability see [General Purpose zone redundancy](high-availability-sla.md#general-purpose-service-tier-zone-redundant-availability). |

+- Use the [zone redundant configuration for general purpose tier](high-availability-sla.md#general-purpose-service-tier-zone-redundant-availability)

+## General Purpose service tier zone redundant availability

+> For general purpose tier the zone-redundant configuration is Generally Available in the following regions: West Europe, North Europe, West US 2, and France Central. This is in preview in the following regions: East US, East US 2, Southeast Asia, Australia East, Japan East, and UK South.

+> Zone-redundant configuration is not available in SQL Managed Instance. In SQL Database this feature is only available when the Gen5 hardware is selected.

+|Multi-AZ|Yes|Yes|Yes|Yes|Yes|Yes|Yes|

+|Multi-AZ|Yes|Yes|Yes|Yes|Yes|Yes|Yes|

+|Multi-AZ|Yes|Yes|Yes|Yes|Yes|

+|Multi-AZ|Yes|Yes|Yes|Yes|

+|Multi-AZ|Yes|Yes|Yes|Yes|Yes|

+|Multi-AZ|Yes|Yes|Yes|Yes|Yes|Yes|Yes|

+|Multi-AZ|Yes|Yes|Yes|Yes|Yes|Yes|Yes|

+ - [High-availability - Zone redundant configuration for General Purpose service tier](high-availability-sla.md#general-purpose-service-tier-zone-redundant-availability)

+| **Availability** | [Default SLA](https://azure.microsoft.com/support/legal/sl#premium-and-business-critical-service-tier-zone-redundant-availability) | [Default SLA](https://azure.microsoft.com/support/legal/sla/azure-sql-sql-managed-instance/)|

+Whenever the database engine or operating system is upgraded, some part of underlying infrastructure fails, or if some critical issue is detected in the `sqlservr.exe` process, Azure Service Fabric will move the stateless process to another stateless compute node. There is a set of spare nodes that is waiting to run new compute service if a failover of the primary node happens in order to minimize failover time. Data in Azure storage layer is not affected, and dat#general-purpose-service-tier-zone-redundant-availability) is enabled. There may be some performance impacts on heavy workloads that are running due to transition time and the fact the new node starts with cold cache.

+| **Availability** | [Default SLA](https://azure.microsoft.com/support/legal/sl#general-purpose-service-tier-zone-redundant-availability) | [Default SLA](https://azure.microsoft.com/support/legal/sla/azure-sql-sql-managed-instance/)|

+|**Availability**|1 replica, no read-scale replicas, <br/>zone-redundant high availability (HA) |3 replicas, 1 [read-scale replica](read-scale-out.md),<br/>zone-redundant high availability (HA)|zone-redundant high availability (HA) (preview)|

+- You'll need to either configure [ExpressRoute](../../expressroute/expressroute-howto-circuit-portal-resource-manager.md) or create a gateway for the virtual network of each SQL Managed Instance, connect the two gateways, and then create the failover group.

+If you haven't configured [ExpressRoute](../../expressroute/expressroute-howto-circuit-portal-resource-manager.md), you can create the primary virtual network gateway with the Azure portal, or PowerShell.

+1. Select **Azure SQL** in the left-hand menu of the [Azure portal](https://portal.azure.com). If **Azure SQL** isn't in the list, select **All services**, then type Azure SQL in the search box. (Optional) Select the star next to **Azure SQL** to favorite it and add it as an item in the left-hand navigation.

+1. Once failover group deployment is complete, you'll be taken back to the **Failover group** page.

+> Azure portal does not support creation of failover groups across different subscriptions. Also, for the existing failover groups across different subscriptions and/or resource groups, failover can't be initiated manually via portal from the primary SQL Managed Instance. Initiate it from the geo-secondary instance instead.

+2. Delete the failover group between instances A and B. At this point the logins will be failing because the SQL aliases for the failover group listeners have been deleted and the gateway won't recognize the failover group name. The secondary databases will be disconnected from the primaries and will become read-write databases.

+> When the failover group is deleted, the DNS records for the listener endpoints are also deleted. At that point, there's a non-zero probability of somebody else creating a failover group with the same name. Because failover group names must be globally unique, this will prevent you from using the same name again. To minimize this risk, don't use generic failover group names.

+- The virtual networks used by the instances of SQL Managed Instance need to be connected through a [VPN Gateway](../../vpn-gateway/vpn-gateway-about-vpngateways.md) or [Express Route](../../expressroute/expressroute-howto-circuit-portal-resource-manager.md). When two virtual networks connect through an on-premises network, ensure there's no firewall rule blocking ports 5022, and 11000-11999. Global VNet Peering is supported with the limitation described in the note below.

+- The two SQL Managed Instance VNets can't have overlapping IP addresses.

+- The secondary SQL Managed Instance is configured with the correct DNS zone ID. DNS zone is a property of a SQL Managed Instance and underlying virtual cluster, and its ID is included in the host name address. The zone ID is generated as a random string when the first SQL Managed Instance is created in each VNet and the same ID is assigned to all other instances in the same subnet. Once assigned, the DNS zone can't be modified. SQL Managed Instances included in the same failover group must share the DNS zone. You accomplish this by passing the primary instance's zone ID as the value of DnsZonePartner parameter when creating the secondary instance.

+There's some overlap of content in the following articles, be sure to make changes to all if necessary:

+Azure RBAC write access is necessary to create and manage failover groups. The [SQL Managed Instance Contributor](../../role-based-access-control/built-in-roles.md#sql-managed-instance-contributor) role has all the necessary permissions to manage failover groups.

+| **Update failover group**| Azure RBAC write access | Failover group </br> All databases within the managed instance|

+| **Batch Python** |[Azure SDK for Python - Docs](/python/api/overview/azure/mgmt-datafactory-readme?view=azure-python) |[PyPI](https://pypi.org/project/azure-batch/) |[Tutorial](tutorial-parallel-python.md)|[GitHub](https://github.com/Azure-Samples/azure-batch-samples/tree/master/Python/Batch) | [Readme](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/batch/azure-batch/README.md) |

+| **Batch Management Python** |[Azure SDK for Python - Docs](/samples/azure-samples/azure-samples-python-management/batch/) |[PyPI](https://pypi.org/project/azure-mgmt-batch/) |- |- |

+This article explains the concepts of face detection and face attribute data. Face detection is the process of locating human faces in an image and optionally returning different kinds of face-related data.

+You use the [Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236) API to detect faces in an image. To get started using the REST API or a client SDK, follow a [quickstart](../Quickstarts/client-libraries.md). Or, for a more in-depth guide, see [Call the detect API](../Face-API-How-to-Topics/HowtoDetectFacesinImage.md).

+## Face rectangle

+Each detected face corresponds to a `faceRectangle` field in the response. This is a set of pixel coordinates for the left, top, width, and height of the detected face. Using these coordinates, you can get the location and size of the face. In the API response, faces are listed in size order from largest to smallest.

+ For more details on how to use these values, see the [Head pose how-to guide](../Face-API-How-to-Topics/how-to-use-headpose.md).

+ Title: Captioning with speech to text - Speech service

+description: An overview of key concepts for captioning with speech to text.

+zone_pivot_groups: programming-languages-speech-sdk

+# Captioning with speech to text

+In this guide, you learn how to create captions with speech to text. This guide covers captioning for speech, but doesn't include speaker ID or sound effects such as bells ringing. Concepts include how to synchronize captions with your input audio, apply profanity filters, get partial results, apply customizations, and identify spoken languages for multilingual scenarios.

+Here are some common captioning scenarios:

+- Online courses and instructional videos

+- Sporting events

+- Voice and video calls

+The following are aspects to consider when using captioning:

+* Let your audience know that captions are generated by an automated service.

+* Center captions horizontally on the screen, in a large and prominent font.

+* Consider whether to use partial results, when to start displaying captions, and how many words to show at a time.

+* Learn about captioning protocols such as [SMPTE-TT](https://ieeexplore.ieee.org/document/7291854).

+* Consider output formats such as SRT (SubRip Subtitle) and WebVTT (Web Video Text Tracks). These can be loaded onto most video players such as VLC, automatically adding the captions on to your video.

+> [!TIP]

+> Try the [Azure Video Analyzer for Media](/azure/azure-video-analyzer/video-analyzer-for-media-docs/video-indexer-overview) as a demonstration of how you can get captions for videos that you upload.

+Captioning can accompany real time or pre-recorded speech. Whether you're showing captions in real time or with a recording, you can use the [Speech SDK](speech-sdk.md) to recognize speech and get transcriptions. You can also use the [Batch transcription API](batch-transcription.md) for pre-recorded video.

+## Input audio to the Speech service

+For real time captioning, use a microphone or audio input stream instead of file input. For examples of how to recognize speech from a microphone, see the [Speech to text quickstart](get-started-speech-to-text.md) and [How to recognize speech](how-to-recognize-speech.md) documentation. For more information about streaming, see [How to use the audio input stream](how-to-use-audio-input-streams.md).

+For captioning of a prerecoding, send file input to the Speech service. For more information, see [How to use compressed audio files](how-to-use-codec-compressed-audio-input-streams.md).

+## Caption and speech synchronization

+You'll want to synchronize captions with the audio track, whether it's done in real time or with a prerecording.

+The Speech service returns the offset and duration of the recognized speech.

+For more information, see [Get speech recognition results](get-speech-recognition-results.md).

+## Get partial results

+Consider when to start displaying captions, and how many words to show at a time. Speech recognition results are subject to change while an utterance is still being recognized. Partial partial results are returned with each `Recognizing` event. As each word is processed, the Speech service re-evaluates an utterance in the new context and again returns the best result. The new result isn't guaranteed to be the same as the previous result. The complete and final transcription of an utterance is returned with the `Recognized` event.

+> [!NOTE]

+> Punctuation of partial results is not available.

+For captioning of prerecorded speech or wherever latency isn't a concern, you could wait for the complete transcription of each utterance before displaying any words. Given the final offset and duration of each word in an utterance, you know when to show subsequent words at pace with the soundtrack.

+Real time captioning presents tradeoffs with respect to latency versus accuracy. You could show the text from each `Recognizing` event as soon as possible. However, if you can accept some latency, you can improve the accuracy of the caption by displaying the text from the `Recognized` event. There's also some middle ground, which is referred to as "stable partial results".

+You can request that the Speech service return fewer `Recognizing` events that are more accurate. This is done by setting the `SpeechServiceResponse_StablePartialResultThreshold` property to a value between `0` and `2147483647`. The value that you set is the number of times a word has to be recognized before the Speech service returns a `Recognizing` event. For example, if you set the `SpeechServiceResponse_StablePartialResultThreshold` value to `5`, the Speech service will affirm recognition of a word at least five times before returning the partial results to you with a `Recognizing` event.

+```csharp

+speechConfig.SetProperty(PropertyId.SpeechServiceResponse_StablePartialResultThreshold, 5);

+```

+```cpp

+speechConfig->SetProperty(PropertyId::SpeechServiceResponse_StablePartialResultThreshold, 5);

+```

+```go

+speechConfig.SetProperty(common.SpeechServiceResponseStablePartialResultThreshold, 5)

+```

+```java

+speechConfig.setProperty(PropertyId.SpeechServiceResponse_StablePartialResultThreshold, 5);

+```

+```javascript

+speechConfig.setProperty(sdk.PropertyId.SpeechServiceResponse_StablePartialResultThreshold, 5);

+```

+```objective-c

+[self.speechConfig setPropertyTo:5 byId:SPXSpeechServiceResponseStablePartialResultThreshold];

+```

+```swift

+self.speechConfig!.setPropertyTo(5, by: SPXPropertyId.speechServiceResponseStablePartialResultThreshold)

+```

+```python

+speech_config.set_property(property_id = speechsdk.PropertyId.SpeechServiceResponse_StablePartialResultThreshold, value = 5)

+```

+Requesting more stable partial results will reduce the "flickering" or changing text, but it can increase latency as you wait for higher confidence results.

+### Stable partial threshold example

+In the following recognition sequence without setting a stable partial threshold, "math" is recognized as a word, but the final text is "mathematics". At another point, "course 2" is recognized, but the final text is "course 201".

+```console

+RECOGNIZING: Text=welcome to

+RECOGNIZING: Text=welcome to applied math

+RECOGNIZING: Text=welcome to applied mathematics

+RECOGNIZING: Text=welcome to applied mathematics course 2

+RECOGNIZING: Text=welcome to applied mathematics course 201

+RECOGNIZED: Text=Welcome to applied Mathematics course 201.

+```

+In the previous example, the transcriptions were additive and no text was retracted. But at other times you might find that the partial results were inaccurate. In either case, the unstable partial results can be perceived as "flickering" when displayed.

+For this example, if the stable partial result threshold is set to `5`, no words are altered or backtracked.

+```console

+RECOGNIZING: Text=welcome to

+RECOGNIZING: Text=welcome to applied

+RECOGNIZING: Text=welcome to applied mathematics

+RECOGNIZED: Text=Welcome to applied Mathematics course 201.

+```

+## Profanity filter

+You can specify whether to mask, remove, or show profanity in recognition results.

+> [!NOTE]

+> Microsoft also reserves the right to mask or remove any word that is deemed inappropriate. Such words will not be returned by the Speech service, whether or not you enabled profanity filtering.

+The profanity filter options are:

+- `Masked`: Replaces letters in profane words with asterisk (*) characters. This is the default option.

+- `Raw`: Include the profane words verbatim.

+- `Removed`: Removes profane words.

+For example, to remove profane words from the speech recognition result, set the profanity filter to `Removed` as shown here:

+```csharp

+speechConfig.SetProfanity(ProfanityOption.Removed);

+```

+```cpp

+speechConfig->SetProfanity(ProfanityOption::Removed);

+```

+```go

+speechConfig.SetProfanity(common.Removed)

+```

+```java

+speechConfig.setProfanity(ProfanityOption.Removed);

+```

+```javascript

+speechConfig.setProfanity(sdk.ProfanityOption.Removed);

+```

+```objective-c

+[self.speechConfig setProfanityOptionTo:SPXSpeechConfigProfanityOption.SPXSpeechConfigProfanityOption_ProfanityRemoved];

+```

+```swift

+self.speechConfig!.setProfanityOptionTo(SPXSpeechConfigProfanityOption_ProfanityRemoved)

+```

+```python

+speech_config.set_profanity(speechsdk.ProfanityOption.Removed)

+```

+Profanity filter is applied to the result `Text` and `MaskedNormalizedForm` properties. Profanity filter isn't applied to the result `LexicalForm` and `NormalizedForm` properties. Neither is the filter applied to the word level results.

+## Language identification

+If the language in the audio could change, use continuous [language identification](language-identification.md). Language identification is used to identify languages spoken in audio when compared against a list of [supported languages](language-support.md#language-identification). You provide up to 10 candidate languages, at least one of which is expected be in the audio. The Speech service returns the most likely language in the audio.

+## Customizations to improve accuracy

+A [phrase list](improve-accuracy-phrase-list.md) is a list of words or phrases that you provide right before starting speech recognition. Adding a phrase to a phrase list increases its importance, thus making it more likely to be recognized.

+Examples of phrases include:

+* Names

+* Geographical locations

+* Homonyms

+* Words or acronyms unique to your industry or organization

+There are some situations where [training a custom model](custom-speech-overview.md) is likely the best option to improve accuracy. For example, if you're captioning orthodontics lectures, you might want to train a custom model with the corresponding domain data.

+## Next steps

+* [Get started with speech to text](get-started-speech-to-text.md)

+* [Get speech recognition results](get-speech-recognition-results.md)

+ Title: "Get speech recognition results - Speech service"

+description: Learn how to get speech recognition results.

+ms.devlang: cpp, csharp, golang, java, javascript, objective-c, python

+zone_pivot_groups: programming-languages-speech-sdk

+keywords: speech to text, speech to text software

+# Get speech recognition results

+## Next steps

+* [Try the speech to text quickstart](get-started-speech-to-text.md)

+* [Improve recognition accuracy with custom speech](custom-speech-overview.md)

+* [Transcribe audio in batches](batch-transcription.md)

+# How to use the audio input stream

+The Speech SDK provides a way to stream audio into the recognizer as an alternative to microphone or file input.

+description: Learn how to use compressed audio files to the Speech service with the Speech SDK.

+To Access the Pre-Call API, you will need to initialize a `callClient` and provision an Azure Communication Services access token. There you can access the `PreCallDiagnostics` feature and the `startTest` method.

+const preCallDiagnosticsResult = await callClient.feature(Features.PreCallDiagnostics).startTest(tokenCredential);

+The Pre-Call API returns a full diagnostic of the device including details like device permissions, availability and compatibility, call quality stats and in-call diagnostics. The results are returned as a `PreCallDiagnosticsResult` object.

+export declare type PreCallDiagnosticsResult = {

+ id: string;

+Individual result objects can be accessed as such using the `preCallDiagnosticsResult` constant above. Results for individual tests will be returned as they are completed with many of the test results being available immediately. In the case of the `inCallDiagnostics` test, the results might take up to 1 minute as the test validates quality of the video and audio.

+const browserSupport = await preCallDiagnosticsResult.browserSupport;

+>[!NOTE]

+>Known issue: `browser support` test returning `Unknown` in cases where it should be returning a correct value.

+ const deviceAccess = await preCallDiagnosticsResult.deviceAccess;

+ const deviceEnumeration = await preCallDiagnosticsResult.deviceEnumeration;

+ const inCallDiagnostics = await preCallDiagnosticsResult.inCallDiagnostics;

+For granular stats on quality metrics like jitter, packet loss, rtt, etc. `callMediaStatistics` are provided as part of the `preCallDiagnosticsResult` feature. You can subscribe to the call media stats to get full collection of them.

+|**[UI Library overview](https://aka.ms/acsstorybook)**| Review the UI Library for the Communication Services |

+## Design resources

+Find comprehensive components, composites, and UX guidance in the [UI Library Design Kit for Figma](https://www.figma.com/community/file/1095841357293210472). This design resource is purpose-built to help design your video calling and chat experiences faster and with less effort.

+ 1. To use the samples, clone this GitHub repository using Git.

+ Title: Quickstart - Get started with UI Library Design Kit

+description: In this quickstart, you will learn how to leverage UI Library Design Kit for Azure Communication Services to quickly design communication experiences using Figma.

+# Get started with UI Library Design Kit (Figma)

+This article describes how to get started with the UI Library Design Kit (Figma).

+Start by getting the [UI Library Design Kit](https://www.figma.com/community/file/1095841357293210472) from Figma.

+## Design faster

+A resource to help design user interfaces built on Azure Communication Services, the UI Library Design Kit includes components, composites, and UX guidance purpose-built to help bring your video calling and chat experiences to life faster.

+## UI Library components and composites

+The same components and composites offered in the UI Library are available in Figma so you can quickly begin designing and prototyping your calling and chat experiences.

+## Built on Fluent

+The UI Library Design Kit's components are based on MicrosoftΓÇÖs Fluent UI; so, theyΓÇÖre built with usability, accessibility, and localization in mind.

+## Next steps

+>[!div class="nextstepaction"]

+>[Get the ACS UI Kit (Figma)](https://www.figma.com/community/file/1095841357293210472)

+1. Choose a virtual machine with Intel SGX capabilities by clicking on **+ Add filter** to create a filter, select **Type** for Filter type, and check only **Confidential compute** from the list in the next dropdown.

+ "identity": {

+ "type": "None"

+ },

+ Title: 'Deploy to Azure Container Apps using Visual Studio Code'

+description: Deploy containerized .NET applications to Azure Container Apps using Visual Studio Code

+# Tutorial: Deploy to Azure Container Apps using Visual Studio Code

+Azure Container Apps enables you to run microservices and containerized applications on a serverless platform. With Container Apps, you enjoy the benefits of running containers while leaving behind the concerns of manually configuring cloud infrastructure and complex container orchestrators.

+In this tutorial, you'll deploy a containerized application to Azure Container Apps using Visual Studio Code.

+## Prerequisites

+- An Azure account with an active subscription is required. If you don't already have one, you can [create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+- Visual Studio Code, available as a [free download](https://code.visualstudio.com/).

+- The following Visual Studio Code extensions installed:

+ - The [Azure Account extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account)

+ - The [Azure Container Apps extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurecontainerapps)

+ - The [Docker extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)

+## Clone the project

+To follow along with this tutorial, [Download the Sample Project](https://github.com/azure-samples/containerapps-albumapi-javascript/archive/refs/heads/master.zip) from [the repository](https://github.com/azure-samples/containerapps-albumapi-javascript) or clone it using the Git command below:

+```bash

+git clone https://github.com/Azure-Samples/containerapps-albumapi-javascript.git

+cd containerapps-albumapi-javascript

+```

+This tutorial uses a JavaScript project, but the steps are language agnostic. To open the project after cloning on Windows, navigate to the project's folder, and right click and choose **Open in VS Code**. For Mac or Linux, you can also use the Visual Studio Code user interface to open the sample project. Select **File -> Open Folder** and then navigate to the folder of the cloned project.

+## Sign in to Azure

+To work with Container Apps and complete this tutorial, you'll need to be signed into Azure. Once you have the Azure Account extension installed, you can sign in using the command palette by typing **Ctrl + shift + p** on Windows and searching for the Azure Sign In command.

+Select **Azure: Sign in**, and Visual Studio Code will launch a browser for you to sign into Azure. Login with the account you'd like to use to work with Container Apps, and then switch back to Visual Studio Code.

+## Create the container registry and Docker image

+The sample project includes a Dockerfile that is used to build a container image for the application. Docker images contain all of the source code and dependencies necessary to run an application. You can build and publish the image for your app directly in Azure; a local Docker installation is not required. An image is required to create and run a container app.

+Container images are stored inside of container registries. You can easily create a container registry and upload an image of your app to it in a single workflow using Visual Studio Code.

+1) First, right click on the Dockerfile in the explorer, and select **Build Image in Azure**. You can also begin this workflow from the command palette by entering **Ctrl + Shift + P** on Windows or **Cmd + Shift + P** on a Mac. When the command palette opens, search for *Build Image in Azure* and select **Enter** on the matching suggestion.

+ :::image type="content" source="media/visual-studio-code/visual-studio-code-build-in-azure-small.png" lightbox="media/visual-studio-code/visual-studio-code-build-in-azure.png" alt-text="A screenshot showing how to build the image in Azure.":::

+2) As the command palette opens, you are prompted to enter a tag for the container. Accept the default, which uses the project name with the `{{.Run.ID}}` replacement token as a suffix. Select **Enter** to continue.

+ :::image type="content" source="media/visual-studio-code/visual-studio-code-container-tag.png" alt-text="A screenshot showing Container Apps tagging.":::

+3) Choose the subscription you would like to use to create your container registry and build your image, and then press enter to continue.

+4) Select **+ Create new registry**, or if you already have a registry you'd like to use, select that item and skip to step 7.

+5) Enter a unique name for the new registry such as *msdocscapps123*, where 123 are unique numbers of your own choosing, and then press enter. Container registry names must be globally unique across all over Azure.

+6) Select **Basic** as the SKU.

+7) Choose **+ Create new resource group**, or select an existing resource group you'd like to use. For a new resource group, enter a name such as `msdocscontainerapps`, and press enter.

+8) Finally, select the location that is nearest to you. Select **Enter** to finalize the workflow, and Azure begins creating the container registry and building the image. This may take a few moments to complete.

+Once the registry is created and the image is built successfully, you are ready to create the container app to host the published image.

+## Create and deploy to the container app

+The Azure Container Apps extension for Visual Studio Code enables you to choose existing Container Apps resources, or create new ones to deploy your applications to. In this scenario you create a new Container App environment and container app to host your application. After installing the Container Apps extension, you can access its features under the Azure control panel in Visual Studio Code.

+### Create the Container Apps environment

+Every container app must be part of a Container Apps environment. An environment provides an isolated network for one or more container apps, making it possible for them to easily invoke each other. You will need to create an environment before you can create the container app itself.

+1) In the Container Apps extension panel, right click on the subscription you would like to use and select **Create Container App Environment**.

+ :::image type="content" source="media/visual-studio-code/visual-studio-code-create-app-environment.png" alt-text="A screenshot showing how to create a Container Apps environment.":::

+2) A command palette workflow will open at the top of the screen. Enter a name for the new Container Apps environment, such as `msdocsappenvironment`, and select **Enter**.

+ :::image type="content" source="media/visual-studio-code/visual-studio-code-container-app-environment.png" alt-text="A screenshot showing the container app environment.":::

+3) Select the desired location for the container app from the list of options.

+ :::image type="content" source="media/visual-studio-code/visual-studio-code-container-env-location.png" alt-text="A screenshot showing the app environment location.":::

+Visual Studio Code and Azure will create the environment for you. This process may take a few moments to complete. Creating a container app environment also creates a log analytics workspace for you in Azure.

+### Create the container app and deploy the Docker image

+Now that you have a container app environment in Azure you can create a container app inside of it. You can also publish the Docker image you created earlier as part of this workflow.

+1) In the Container Apps extension panel, right click on the container environment you created previously and select **Create Container App**

+ :::image type="content" source="media/visual-studio-code/visual-studio-code-create-container-app.png" alt-text="A screenshot showing how to create the container app.":::

+2) A new command palette workflow will open at the top of the screen. Enter a name for the new container app, such as `msdocscontainerapp`, and then select **Enter**.

+ :::image type="content" source="media/visual-studio-code/visual-studio-code-container-name.png" alt-text="A screenshot showing the container app name.":::

+3) Next, you're prompted to choose a container registry hosting solution to pull a Docker image from. For this scenario, select **Azure Container Registries**, though Docker Hub is also supported.

+4) Select the container registry you created previously when publishing the Docker image.

+5) Select the container registry repository you published the Docker image to. Repositories allow you to store and organize your containers in logical groupings.

+6) Select the tag of the image you published earlier.

+7) When prompted for environment variables, choose **Skip for now**. This application does not require any environment variables.

+8) Select **Enable** on the ingress settings prompt to enable an HTTP endpoint for your application.

+9) Choose **External** to configure the HTTP traffic that the endpoint will accept.

+10) Leave the default value of 80 for the port, and then select **Enter** to complete the workflow.

+During this process, Visual Studio Code and Azure create the container app for you. The published Docker image you created earlier is also be deployed to the app. Once this process finishes, Visual Studio Code displays a notification with a link to browse to the site. Click this link, and to view your app in the browser.

+You can also append the `/albums` path at the end of the app URL to view data from a sample API request.

+Congratulations! You successfully created and deployed your first container app using Visual Studio code.

+## Clean up resources

+If you're not going to continue to use this application, you can delete the Azure Container Apps instance and all the associated services at once by removing the resource group.

+Follow these steps in the Azure portal to remove the resources you created:

+1. Select the **msdocscontainerapps** resource group from the *Overview* section.

+1. Select the **Delete resource group** button at the top of the resource group *Overview*.

+1. Enter the resource group name **msdocscontainerapps** in the *Are you sure you want to delete "my-container-apps"* confirmation dialog.

+1. Select **Delete**.

+ The process to delete the resource group may take a few minutes to complete.

+> [!TIP]

+> Having issues? Let us know on GitHub by opening an issue in the [Azure Container Apps repo](https://github.com/microsoft/azure-container-apps).

+## Next steps

+> [!div class="nextstepaction"]

+> [Environments in Azure Container Apps](environment.md)

+ - **Container Apps Environment**: Container Apps Environment: Every container app must be part of a container app environment. An environment provides an isolated network for one or more container apps, making it possible for them to easily invoke each other. Click **New** to open the Create new dialog for your container app environment. Leave the default values and select **OK** to close the environment dialog.

+ Title: Managed identities in Azure Container Apps

+description: Using managed identities in Container Apps

+# Managed identities in Azure Container Apps Preview

+A managed identity from Azure Active Directory (Azure AD) allows your container app to access other Azure AD-protected resources. For more about managed identities in Azure AD, see [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md).

+Your container app can be granted two types of identities:

+- A **system-assigned identity** is tied to your container app and is deleted when your container app is deleted. An app can only have one system-assigned identity.

+- A **user-assigned identity** is a standalone Azure resource that can be assigned to your container app and other resources. A container app can have multiple user-assigned identities. The identity exists until you delete them.

+## Why use a managed identity?

+You can use a managed identity in a running container app to authenticate to any [service that supports Azure AD authentication](../active-directory/managed-identities-azure-resources/services-support-managed-identities.md#azure-services-that-support-azure-ad-authentication).

+With managed identities:

+- Your app connects to resources with the managed identity. You don't need to manage credentials in your container app.

+- You can use role-based access control to grant specific permissions to a managed identity.

+- System-assigned identities are automatically created and managed. They're deleted when your container app is deleted.

+- You can add and delete user-assigned identities and assign them to multiple resources. They're independent of your container app's life cycle.

+### Common use cases

+System-assigned identities are best for workloads that:

+- are contained within a single resource

+- need independent identities

+User-assigned identities are ideal for workloads that:

+- run on multiple resources and can share a single identity

+- need pre-authorization to a secure resource

+## Limitations

+The identity is only available within a running container, which means you can't use a managed identity to:

+- Pull an image from Azure Container Registry

+- Define scaling rules or Dapr configuration

+ - To access resources that require a connection string or key, such as storage resources, you'll still need to include the connection string or key in the `secretRef` of the scaling rule.

+## How to configure managed identities

+You can configure your managed identities through:

+- the Azure CLI

+- your Azure Resource Manager (ARM) template

+When a managed identity is added, deleted, or modified on a running container app, the app doesn't automatically restart and a new revision isn't created.

+> [!NOTE]

+> When adding a managed identity to a container app deployed before April 11, 2022, you must create a new revision.

+### Add a system-assigned identity

+# [Azure CLI](#tab/cli)

+Run the `az containerapp identity assign` command to create a system-assigned identity:

+```azurecli

+az containerapp identity assign --name myApp --resource-group myResourceGroup --system-assigned

+```

+# [ARM template](#tab/arm)

+An ARM template can be used to automate deployment of your container app and resources. To add a system-assigned identity, add an `identity` section to your ARM template.

+```json

+"identity": {

+ "type": "SystemAssigned"

+}

+```

+Adding the system-assigned type tells Azure to create and manage the identity for your application. For a complete ARM template example, see [ARM API Specification](azure-resource-manager-api-spec.md?tabs=arm-template#container-app-examples).

+--

+### Add a user-assigned identity

+Configuring a container app with a user-assigned identity requires that you first create the identity then add its resource identifier to your container app's configuration. You can create user-assigned identities via the Azure portal or the Azure CLI. For information on creating and managing user-assigned identities, see [Manage user-assigned managed identities](../active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md).

+# [Azure CLI](#tab/cli)

+1. Create a user-assigned identity.

+ ```azurecli

+ az identity create --resource-group <GROUP_NAME> --name <IDENTITY_NAME> --output json

+ ```

+ Note the `id` property of the new identity.

+1. Run the `az containerapps identity assign` command to assign the identity to the app. The identities parameter is a space separated list.

+ ```azurecli

+ az containerapp identity assign --resource-group <GROUP_NAME> --name <APP_NAME> \

+ --user-assigned <IDENTITY_RESOURCE_ID>

+ ```

+ Replace `<IDENTITY_RESOURCE_ID>` with the `id` property of the identity. To assign more than one user-assigned identity, supply a space-separated list of identity IDs to the `--user-assigned` parameter.

+# [ARM template](#tab/arm)

+To add one or more user-assigned identities, add an `identity` section to your ARM template. Replace `<IDENTITY1_RESOURCE_ID>` and `<IDENTITY2_RESOURCE_ID>` with the resource identifiers of the identities you want to add.

+Specify each user-assigned identity by adding an item to the `userAssignedIdentities` object with the identity's resource identifier as the key. Use an empty object as the value.

+```json

+"identity": {

+ "type": "UserAssigned",

+ "userAssignedIdentities": {

+ "<IDENTITY1_RESOURCE_ID>": {},

+ "<IDENTITY2_RESOURCE_ID>": {}

+ }

+}

+```

+For a complete ARM template example, see [ARM API Specification](azure-resource-manager-api-spec.md?tabs=arm-template#container-app-examples).

+> [!NOTE]

+> An application can have both system-assigned and user-assigned identities at the same time. In this case, the type property would be `SystemAssigned,UserAssigned`.

+--

+## Configure a target resource

+For some resources, you'll need to configure role assignments for your app's managed identity to grant access. Otherwise, calls from your app to services, such as Azure Key Vault and Azure SQL Database, will be rejected even if you use a valid token for that identity. To learn more about Azure role-based access control (Azure RBAC), see [What is RBAC?](../role-based-access-control/overview.md). To learn more about which resources support Azure Active Directory tokens, see [Azure services that support Azure AD authentication](../active-directory/managed-identities-azure-resources/services-support-managed-identities.md#azure-services-that-support-azure-ad-authentication).

+> [!IMPORTANT]

+> The back-end services for managed identities maintain a cache per resource URI for around 24 hours. If you update the access policy of a particular target resource and immediately retrieve a token for that resource, you may continue to get a cached token with outdated permissions until that token expires. There's currently no way to force a token refresh.

+## Connect to Azure services in app code

+With managed identities, an app can obtain tokens to access Azure resources that use Azure Active Directory, such as Azure SQL Database, Azure Key Vault, and Azure Storage. These tokens represent the application accessing the resource, and not any specific user of the application.

+Container Apps provides an internally accessible [REST endpoint](managed-identity.md?tabs=cli%2Chttp#rest-endpoint-reference) to retrieve tokens. The REST endpoint can be accessed from within the app with a standard HTTP GET, which can be implemented with a generic HTTP client in every language. For .NET, JavaScript, Java, and Python, the Azure Identity client library provides an abstraction over this REST endpoint. Connecting to other Azure services is as simple as adding a credential object to the service-specific client.

+# [.NET](#tab/dotnet)

+> [!NOTE]

+> When connecting to Azure SQL data sources with [Entity Framework Core](/ef/core/), consider [using Microsoft.Data.SqlClient](/sql/connect/ado-net/sql/azure-active-directory-authentication), which provides special connection strings for managed identity connectivity.

+For .NET apps, the simplest way to work with a managed identity is through the [Azure Identity client library for .NET](/dotnet/api/overview/azure/identity-readme). See the respective documentation headings of the client library for information:

+- [Add Azure Identity client library to your project](/dotnet/api/overview/azure/identity-readme#getting-started)

+- [Access Azure service with a system-assigned identity](/dotnet/api/overview/azure/identity-readme#authenticating-with-defaultazurecredential)

+- [Access Azure service with a user-assigned identity](/dotnet/api/overview/azure/identity-readme#specifying-a-user-assigned-managed-identity-with-the-defaultazurecredential)

+The linked examples use [`DefaultAzureCredential`](/dotnet/api/overview/azure/identity-readme#defaultazurecredential). It's useful for most the scenarios because the same pattern works in Azure (with managed identities) and on your local machine (without managed identities).

+# [JavaScript](#tab/javascript)

+For Node.js apps, the simplest way to work with a managed identity is through the [Azure Identity client library for JavaScript](/javascript/api/overview/azure/identity-readme?). See the respective documentation headings of the client library for information:

+- [Add Azure Identity client library to your project](/javascript/api/overview/azure/identity-readme#install-the-package)

+- [Access Azure service with a system-assigned identity](/javascript/api/overview/azure/identity-readme#authenticating-with-defaultazurecredential)

+- [Access Azure service with a user-assigned identity](/javascript/api/overview/azure/identity-readme#authenticating-a-user-assigned-managed-identity-with-defaultazurecredential)

+The linked examples use [`DefaultAzureCredential`](/javascript/api/overview/azure/identity-readme#defaultazurecredential). It's useful for most the scenarios because the same pattern works in Azure (with managed identities) and on your local machine (without managed identities).

+For more code examples of the Azure Identity client library for JavaScript, see [Azure Identity examples](https://github.com/Azure/azure-sdk-for-js/blob/%40azure/identity_2.0.1/sdk/identity/identity/samples/AzureIdentityExamples.md).

+# [Python](#tab/python)

+For Python apps, the simplest way to work with a managed identity is through the [Azure Identity client library for Python](/python/api/overview/azure/identity-readme). See the respective documentation headings of the client library for information:

+- [Add Azure Identity client library to your project](/python/api/overview/azure/identity-readme#getting-started)

+- [Access Azure service with a system-assigned identity](/python/api/overview/azure/identity-readme#authenticating-with-defaultazurecredential)

+- [Access Azure service with a user-assigned identity](/python/api/overview/azure/identity-readme#authenticating-a-user-assigned-managed-identity-with-defaultazurecredential)

+The linked examples use [`DefaultAzureCredential`](/python/api/overview/azure/identity-readme#defaultazurecredential). It's useful for most the scenarios because the same pattern works in Azure (with managed identities) and on your local machine (without managed identities).

+# [Java](#tab/java)

+For Java apps and functions, the simplest way to work with a managed identity is through the [Azure Identity client library for Java](/java/api/overview/azure/identity-readme). See the respective documentation headings of the client library for information:

+- [Add Azure Identity client library to your project](/java/api/overview/azure/identity-readme#include-the-package)

+- [Access Azure service with a system-assigned identity](/java/api/overview/azure/identity-readme#authenticating-with-defaultazurecredential)

+- [Access Azure service with a user-assigned identity](/java/api/overview/azure/identity-readme#authenticating-a-user-assigned-managed-identity-with-defaultazurecredential)

+The linked examples use [`DefaultAzureCredential`](/azure/developer/java/sdk/identity-azure-hosted-auth#default-azure-credential). It's useful for most the scenarios because the same pattern works in Azure (with managed identities) and on your local machine (without managed identities).

+For more code examples of the Azure Identity client library for Java, see [Azure Identity Examples](https://github.com/Azure/azure-sdk-for-java/wiki/Azure-Identity-Examples).

+# [PowerShell](#tab/powershell)

+Use the following script to retrieve a token from the local endpoint by specifying a resource URI of an Azure service. Replace the place holder with the resource URI to obtain the token.

+```powershell

+$resourceURI = "https://<AAD-resource-URI>"

+$tokenAuthURI = $env:IDENTITY_ENDPOINT + "?resource=$resourceURI&api-version=2019-08-01"

+$tokenResponse = Invoke-RestMethod -Method Get -Headers @{"X-IDENTITY-HEADER"="$env:IDENTITY_HEADER"} -Uri $tokenAuthURI

+$accessToken = $tokenResponse.access_token

+```

+# [HTTP GET](#tab/http)

+A raw HTTP GET request looks like the following example.

+X-IDENTITY-HEADER contains the GUID that is stored in the IDENTITY_HEADER environment variable.

+```http

+GET http://localhost:42356/msi/token?resource=https://vault.azure.net&api-version=2019-08-01 HTTP/1.1

+X-IDENTITY-HEADER: 853b9a84-5bfa-4b22-a3f3-0b9a43d9ad8a

+```

+A response might look like this example:

+```http

+HTTP/1.1 200 OK

+Content-Type: application/json

+{

+ "access_token": "eyJ0eXAi…",

+ "expires_on": "1586984735",

+ "resource": "https://vault.azure.net",

+ "token_type": "Bearer",

+ "client_id": "5E29463D-71DA-4FE0-8E69-999B57DB23B0"

+}

+```

+This response is the same as the [response for the Azure AD service-to-service access token request](../active-directory/azuread-dev/v1-oauth2-client-creds-grant-flow.md#service-to-service-access-token-response). To access Key Vault, you'll then add the value of `access_token` to a client connection with the vault.

+### REST endpoint reference

+> [!NOTE]

+> An older version of this endpoint, using the "2017-09-01" API version, used the `secret` header instead of `X-IDENTITY-HEADER` and only accepted the `clientid` property for user-assigned. It also returned the `expires_on` in a timestamp format. `MSI_ENDPOINT` can be used as an alias for `IDENTITY_ENDPOINT`, and `MSI_SECRET` can be used as an alias for `IDENTITY_HEADER`. This version of the protocol is currently required for Linux Consumption hosting plans.

+A container app with a managed identity exposes the identity endpoint by defining two environment variables:

+- IDENTITY_ENDPOINT - local URL from which your container app can request tokens.

+- IDENTITY_HEADER - a header used to help mitigate server-side request forgery (SSRF) attacks. The value is rotated by the platform.

+To get a token for a resource, make an HTTP GET request to this endpoint, including the following parameters:

+| Parameter name | In | Description|

+||||

+| resource | Query | The Azure AD resource URI of the resource for which a token should be obtained. This could be one of the [Azure services that support Azure AD authentication](../active-directory/managed-identities-azure-resources/services-support-managed-identities.md#azure-services-that-support-azure-ad-authentication) or any other resource URI. |

+| api-version | Query | The version of the token API to be used. Use "2019-08-01" or later. |

+| X-IDENTITY-HEADER | Header | The value of the `IDENTITY_HEADER` environment variable. This header mitigates server-side request forgery (SSRF) attacks. |

+| client_id | Query | (Optional) The client ID of the user-assigned identity to be used. Can't be used on a request that includes `principal_id`, `mi_res_id`, or `object_id`. If all ID parameters (`client_id`, `principal_id`, `object_id`, and `mi_res_id`) are omitted, the system-assigned identity is used.|

+| principal_id | Query | (Optional) The principal ID of the user-assigned identity to be used. `object_id` is an alias that may be used instead. Can't be used on a request that includes client_id, mi_res_id, or object_id. If all ID parameters (`client_id`, `principal_id`, `object_id`, and `mi_res_id`) are omitted, the system-assigned identity is used. |

+| mi_res_id| Query | (Optional) The Azure resource ID of the user-assigned identity to be used. Can't be used on a request that includes `principal_id`, `client_id`, or `object_id`. If all ID parameters (`client_id`, `principal_id`, `object_id`, and `mi_res_id`) are omitted, the system-assigned identity is used.|

+> [!IMPORTANT]

+> If you are attempting to obtain tokens for user-assigned identities, you must include one of the optional properties. Otherwise the token service will attempt to obtain a token for a system-assigned identity, which may or may not exist.

+For more information on the REST endpoint, see [REST endpoint reference](#rest-endpoint-reference).

+--

+## View managed identities

+You can show the system-assigned and user-assigned managed identities using the following Azure CLI command. The output will show the managed identity type, tenant IDs and principal IDs of all managed identities assigned to your container app.

+```azurecli

+az containerapps identity show --name <APP_NAME> --resource-group <GROUP_NAME>

+```

+## Remove a managed identity

+When you remove a system-assigned identity, it's deleted from Azure Active Directory. System-assigned identities are also automatically removed from Azure Active Directory when you delete the container app resource itself. Removing user-assigned managed identities from your container app doesn't remove them from Azure Active Directory.

+# [Azure CLI](#tab/cli)

+To remove the system-assigned identity:

+```azurecli

+az containerapp identity remove --name <APP_NAME> --resource-group <GROUP_NAME> --system-assigned

+```

+To remove one or more user-assigned identities:

+```azurecli

+az containerapp identity remove --name <APP_NAME> --resource-group <GROUP_NAME> \

+ --user-assigned <IDENTITY1_RESOURCE_ID> <IDENTITY2_RESOURCE_ID>

+```

+To remove all user-assigned identities:

+```azurecli

+az containerapp identity remove --name <APP_NAME> --resource-group <GROUP_NAME> \

+ --user-assigned <IDENTITY1_RESOURCE_ID> <IDENTITY2_RESOURCE_ID>

+```

+# [ARM template](#tab/arm)

+To remove all identities, set the `type` of the container app's identity to `None` in the ARM template:

+```json

+"identity": {

+ "type": "None"

+}

+```

+--

+## Next steps

+> [!div class="nextstepaction"]

+> [Monitor an app](monitor.md)

+## Try Azure Cosmos DB for free

+[Try Azure Cosmos DB for free](https://azure.microsoft.com/try/cosmosdb/) is a free of charge experience that allows you to experiment with Azure Cosmos DB in the cloud without signing up for an Azure account or using your credit card. The Try Azure Cosmos DB accounts are available for a limited time, currently 30 days. You can renew them at any time. Try Azure Cosmos DB accounts makes it easy to evaluate Azure Cosmos DB, build and test an application or use the Quickstarts or tutorials. You can also create a demo, perform unit testing, or even create a multi-region account and run an app on it without incurring any costs. In a Try Azure Cosmos DB account, you can have one shared throughput database with a maximum of 25 containers and 20,000 RU/s of throughput, or one container with up to 5000 RU/s. To get started, see [Try Azure Cosmos DB for free](https://azure.microsoft.com/try/cosmosdb/) page.

+ * If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

+> [!Note]

+> Once bulk execution is specified in the [CosmosClientOptions](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions), they are effectively immutable for the lifetime of the CosmosClient. Changing the values will have no effect.

+10. Select **I have confirmed that this policy is correct**, then select **Save**.

+13. For **Report versioning**, choose whether you want each version of the report to overwrite the previous version, or if you want more new reports.

+7. In **External ID**, enter the external ID, which is a shared passcode between the AWS role and Cost Management. The same external ID is also used on the **New Connector** page in Cost Management. Microsoft recommends that you use a strong passcode policy when entering the external ID.

+9. Select **Create policy**. A new browser tab opens where you create a policy.

+1. In **Role name with path**, enter a role name and note it. You need to use it in the final role creation step.

+> [!NOTE]

+> The Connector for AWS remains active after the trial period ends if you set the auto-renew configuration to **On** during the initial setup. Otherwise, the connector is disabled following its trial. It may remain disabled for three months before it's permanently deleted. After the connector is deleted, the same connection can't be reactivated. For assistance with a disabled connector or to create a new connection after it's deleted, create a [support request in the Azure portal](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/overview).

+- Complete the setup required for a new AWS connector, as described in the [Create a Cost and Usage report in AWS](#create-a-cost-and-usage-report-in-aws) section.

+## Take other steps

+This article shows the steps needed to transfer billing ownership of an Azure subscription to another account. Before you transfer billing ownership for a subscription, read [Azure subscription and reservation transfer hub](subscription-transfer.md) to ensure that your transfer type is supported.

+The self-service subscription transfer isn't available for your billing account. For more information, see [Azure subscription and reservation transfer hub](subscription-transfer.md) to ensure that your transfer type is supported.

+## Unable to use a virtual or prepaid credit as a payment method.

+Virtual or prepaid credit cards aren't accepted as payment for Azure subscriptions.

+An Azure Expert MSP can request to transfer their customer's Enterprise subscriptions and reservations to the Microsoft Partner Agreement (MPA) that they manage. Supported billing ownership transfer options for subscriptions and reservations include:

+- A direct Enterprise Agreement transfer to MPA

+- An enterprise Microsoft Customer Agreement transfer to MPA

+> [!NOTE]

+> Indirect Enterprise Agreement transfer to a Microsoft Customer Agreement isn't supported.

+You can request billing ownership of the following subscription types.

+* [Enterprise Dev/Test](https://azure.microsoft.com/offers/ms-azr-0148p/)¹

+* Azure Plan¹ [(Microsoft Customer Agreement in Enterprise Motion)](https://www.microsoft.com/Licensing/how-to-buy/microsoft-customer-agreement)

+¹ You must convert an EA Dev/Test subscription to an EA Enterprise offer using a support ticket and respectively, an Azure Plan Dev/Test offer to Azure plan. A Dev/Test subscription will be billed at a pay-as-you-go rate after conversion. There is no discount currently available through the Dev/Test offer to CSP partners.

+The EA subscriptions from non-organization directories can be transferred as long as the directory has a reseller relationship with the CSP. If the directory doesnΓÇÖt have a reseller relationship, you need to make sure to have the organization user in the directory as a *Global Administrator* who can accept the partner relationship. The domain name portion of the username must either be the initial default domain name *[domain name].onmicrosoft.com* or a verified, non-federated custom domain name such as *contoso.com*.

+To add a new user to the directory, see [Quickstart: Add new users to Azure Active Directory to add the new user to the directory](../../active-directory/fundamentals/add-users-azure-active-directory.md).

+| MCA - Enterprise | MPA | <ul><li> Only CSP direct bill partners certified as an [Azure Expert Managed Services Provider (MSP)](https://partner.microsoft.com/membership/azure-expert-msp) can request to transfer Azure products for their customers that have a Microsoft Customer Agreement with a Microsoft representative. For more information, see [Get billing ownership of Azure subscriptions to your MPA account](mpa-request-ownership.md). Product transfers are allowed only for customers who have accepted a Microsoft Customer Agreement (MCA) and purchased an Azure plan with the CSP Program. <li> Self-service reservation transfers are supported. <li> There are limitations and restrictions. For more information, see [Transfer EA subscriptions to a CSP partner](transfer-subscriptions-subscribers-csp.md#transfer-ea-subscriptions-to-a-csp-partner). |

+Virtual or pre-paid credit cards aren't accepted as payment for Azure subscriptions. To see what else may cause your card to be declined, see [Troubleshoot a declined card at Azure sign-up](./troubleshoot-declined-card.md).

+ Title: Transform data in data.world (Preview)

+description: Learn how to transform data in data.world (Preview) by using Data Factory or Azure Synapse Analytics.

+# Transform data in data.world (Preview) using Azure Data Factory or Synapse Analytics

+This article outlines how to use Data Flow to transform data in data.world (Preview). To learn more, read the introductory article for [Azure Data Factory](introduction.md) or [Azure Synapse Analytics](../synapse-analytics/overview-what-is.md).

+> [!IMPORTANT]

+> This connector is currently in preview. You can try it out and give us feedback. If you want to take a dependency on preview connectors in your solution, please contact [Azure support](https://azure.microsoft.com/support/).

+## Supported capabilities

+This data.world connector is supported for the following activities:

+- [Mapping data flow](concepts-data-flow-overview.md)

+## Create a data.world linked service using UI

+Use the following steps to create a data.world linked service in the Azure portal UI.

+1. Browse to the Manage tab in your Azure Data Factory or Synapse workspace and select Linked Services, then select New:

+ # [Azure Data Factory](#tab/data-factory)

+ :::image type="content" source="media/doc-common-process/new-linked-service.png" alt-text="Screenshot of creating a new linked service with Azure Data Factory U I.":::

+ # [Azure Synapse](#tab/synapse-analytics)

+ :::image type="content" source="media/doc-common-process/new-linked-service-synapse.png" alt-text="Screenshot of creating a new linked service with Azure Synapse U I.":::

+2. Search for data.world (Preview) and select the data.world (Preview) connector.

+ :::image type="content" source="media/connector-dataworld/dataworld-connector.png" alt-text="Screenshot showing selecting data.world connector.":::

+3. Configure the service details, test the connection, and create the new linked service.

+ :::image type="content" source="media/connector-dataworld/configure-dataworld-linked-service.png" alt-text="Screenshot of configuration for data.world linked service.":::

+## Connector configuration details

+The following sections provide information about properties that are used to define Data Factory and Synapse pipeline entities specific to data.world.

+## Linked service properties

+The following properties are supported for the data.world linked service:

+| Property | Description | Required |

+|: |: |: |

+| type | The type property must be set to **Dataworld**. |Yes |

+| apiToken | Specify an API token for the data.world. Mark this field as **SecureString** to store it securely. Or, you can [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). |Yes |

+**Example:**

+```json

+{

+ "name": "DataworldLinkedService",

+ "properties": {

+ "type": "Dataworld",

+ "typeProperties": {

+ "apiToken": {

+ "type": "SecureString",

+ "value": "<API token>"

+ }

+ }

+ }

+}

+```

+## Mapping data flow properties

+When transforming data in mapping data flow, you can read tables from data.world. For more information, see the [source transformation](data-flow-source.md) in mapping data flows. You can only use an [inline dataset](data-flow-source.md#inline-datasets) as source type.

+### Source transformation

+The below table lists the properties supported by data.world source. You can edit these properties in the **Source options** tab.

+| Name | Description | Required | Allowed values | Data flow script property |

+| - | -- | -- | -- | - |

+| Dataset name| The ID of the dataset in data.world.| Yes | String | datasetId |

+| Table name | The ID of the table within the dataset in data.world. | No (if `query` is specified) | String | tableId |

+| Query | Enter a SQL query to fetch data from data.world. An example is `select * from MyTable`.| No (if `tableId` is specified)| String | query |

+| Owner | The owner of the dataset in data.world. | Yes | String | owner |

+#### data.world source script example

+When you use data.world as source type, the associated data flow script is:

+```

+source(allowSchemaDrift: true,

+ validateSchema: false,

+ store: 'dataworld',

+ format: 'rest',

+ owner: 'owner1',

+ datasetId: 'dataset1',

+ tableId: 'MyTable') ~> DataworldSource

+```

+## Next steps

+For a list of data stores supported as sources and sinks by the copy activity, see [Supported data stores](copy-activity-overview.md#supported-data-stores-and-formats).

+ Title: Transform data in Twilio (Preview)

+description: Learn how to transform data in Twilio (Preview) by using Data Factory or Azure Synapse Analytics.

+# Transform data in Twilio (Preview) using Azure Data Factory or Synapse Analytics

+This article outlines how to use Data Flow to transform data in Twilio (Preview). To learn more, read the introductory article for [Azure Data Factory](introduction.md) or [Azure Synapse Analytics](../synapse-analytics/overview-what-is.md).

+> [!IMPORTANT]

+> This connector is currently in preview. You can try it out and give us feedback. If you want to take a dependency on preview connectors in your solution, please contact [Azure support](https://azure.microsoft.com/support/).

+## Supported capabilities

+This Twilio connector is supported for the following activities:

+- [Mapping data flow](concepts-data-flow-overview.md)

+## Create a Twilio linked service using UI

+Use the following steps to create a Twilio linked service in the Azure portal UI.

+1. Browse to the Manage tab in your Azure Data Factory or Synapse workspace and select Linked Services, then select New:

+ # [Azure Data Factory](#tab/data-factory)

+ :::image type="content" source="media/doc-common-process/new-linked-service.png" alt-text="Screenshot of creating a new linked service with Azure Data Factory U I.":::

+ # [Azure Synapse](#tab/synapse-analytics)

+ :::image type="content" source="media/doc-common-process/new-linked-service-synapse.png" alt-text="Screenshot of creating a new linked service with Azure Synapse U I.":::

+2. Search for Twilio (Preview) and select the Twilio (Preview) connector.

+ :::image type="content" source="media/connector-twilio/twilio-connector.png" alt-text="Screenshot showing selecting Twilio connector.":::

+3. Configure the service details, test the connection, and create the new linked service.

+ :::image type="content" source="media/connector-twilio/configure-twilio-linked-service.png" alt-text="Screenshot of configuration for Twilio linked service.":::

+## Connector configuration details

+The following sections provide information about properties that are used to define Data Factory and Synapse pipeline entities specific to Twilio.

+## Linked service properties

+The following properties are supported for the Twilio linked service:

+| Property | Description | Required |

+|: |: |: |

+| type | The type property must be set to **Twilio**. | Yes |

+| userName | The account SID of your Twilio account. | No |

+| password | The auth token of your Twilio account. Mark this field as **SecureString** to store it securely. Or, you can [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). |Yes |

+**Example:**

+```json

+{

+ "name": "TwilioLinkedService",

+ "properties": {

+ "type": "Twilio",

+ "typeProperties": {

+ "userName": "<account SID>",

+ "password": {

+ "type": "SecureString",

+ "value": "<auth token>"

+ }

+ }

+ }

+}

+```

+### Source transformation

+When transforming data in mapping data flow, you can read resources from Twilio. For more information, see the [source transformation](data-flow-source.md) in mapping data flows. You can only use an [inline dataset](data-flow-source.md#inline-datasets) as source type.

+The below table lists the properties supported by Twilio source. You can edit these properties in the **Source options** tab.

+| Name | Description | Required | Allowed values | Data flow script property |

+| - | -- | -- | -- | - |

+| Resource | The type of resources that data flow fetch from Twilio. | Yes | `Messages`<br>`Calls` | resource |

+| From | The phone number with country code, for example `+17755425856`. | No | String | from |

+| To | The phone number with country code, for example `+17755425856`. | No | String | to |

+#### Twilio source script example

+When you use Twilio as source type, the associated data flow script is:

+```

+source(allowSchemaDrift: true,

+ validateSchema: false,

+ store: 'twilio',

+ format: 'rest',

+ resource: 'Messages',

+ from: '+17755425856') ~> TwilioSource

+```

+## Next steps

+For a list of data stores supported as sources and sinks by the copy activity, see [Supported data stores](copy-activity-overview.md#supported-data-stores-and-formats).

+1. Select **Access control (IAM)**.

+1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.

+1. Assign a role to a user. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+ 

+Alternatively, user can have owner of the Azure data store add the data share resource's managed identity to the Azure data store manually. This action only needs to be performed once per data share resource.

+To create a role assignment for the data share resource's managed identity manually, use the following steps:

+1. Select **Add > Add role assignment**.

+ :::image type="content" source="../../includes/role-based-access-control/media/add-role-assignment-menu-generic.png" alt-text="Screenshot that shows Access control (IAM) page with Add role assignment menu open.":::

+1. On the **Roles** tab, select one of the roles listed in the role assignment table in the previous section.

+1. On the **Members** tab, select **Managed identity**, and then select **Select members**.

+1. Select **System-assigned managed identity**, search for your Azure Data Share resource, and then select it.

+1. On the **Review + assign** tab, select **Review + assign** to assign the role.

+To learn more about role assignments, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md). If you're sharing data using REST APIs, you can create role assignment using API by referencing [Assign Azure roles using the REST API](../role-based-access-control/role-assignments-rest.md).

+1. Select **Add > Add role assignment**.

+ :::image type="content" source="../../includes/role-based-access-control/media/add-role-assignment-menu-generic.png" alt-text="Screenshot that shows Access control (IAM) page with Add role assignment menu open.":::

+1. On the **Roles** tab, select one of the roles listed in the role assignment table in the previous section. For example, for a storage account, select Storage Blob Data Reader.

+1. On the **Members** tab, select **Managed identity**, and then select **Select members**.

+1. Select **System-assigned managed identity**, search for your Azure Data Share resource, and then select it.

+1. On the **Review + assign** tab, select **Review + assign** to assign the role.

+To learn more about role assignments, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md). If you're receiving data using REST APIs, you can create role assignment using API by referencing [Assign Azure roles using the REST API](../role-based-access-control/role-assignments-rest.md).

+- A Trusted Platform Module (TPM) that performs hardware-based, security-related functions. Specifically, the TPM manages and protects secrets and data that needs to be persisted on the device.

+Get started with Azure DDoS Protection Standard by using the Azure portal.

+A DDoS protection plan defines a set of virtual networks that have DDoS protection standard enabled, across subscriptions. You can configure one DDoS protection plan for your organization and link virtual networks from multiple subscriptions to the same plan.

+In this quickstart, you'll create a DDoS protection plan and link it to a virtual network.

+1. Search the term *DDoS*. When **DDoS protection plan** appears in the search results, select it.

+1. Select **Create**.

+1. Enter or select the following values.

+ |Resource group | Select **Create new** and enter **MyResourceGroup**.|

+ |Name | Enter **MyDdosProtectionPlan**. |

+ |Region | Enter **East US**. |

+1. Select **Review + create** then **Create**

+## Enable DDoS protection for a virtual network

+1. Select **Networking**, and then select **Virtual network**.

+1. Enter or select the following values.

+ | Name | Enter **MyVnet**. |

+ | Region | Enter **East US**. |

+1. Select **Next: IP Addresses** and enter the following values.

+ | Setting | Value |

+ | | |

+ | IPv4 address space | Enter **10.1.0.0/16.** |

+ | Subnet name | Under **Subnet name**, select the **Add subnet** link and enter **mySubnet.** |

+ | Subnet address range | Enter **10.1.0.0/24.** |

+1. Select **Add**.

+1. Select **Next: Security**.

+1. Select **Enable** on the **DDoS Protection Standard** radio.

+1. Select **MyDdosProtectionPlan** from the **DDoS protection plan** pane. The plan you select can be in the same, or different subscription than the virtual network, but both subscriptions must be associated to the same Azure Active Directory tenant.

+1. Select **Review + create** then **Create**.

+1. Enter the name of the virtual network that you want to enable DDoS Protection Standard for in the **Search resources, services, and docs box** at the top of the Azure portal. When the name of the virtual network appears in the search results, select it.

+1. Select **DDoS protection**, under **SETTINGS**.

+1. Select **Standard**. Under **DDoS protection plan**, select an existing DDoS protection plan, or the plan you created in step 1, and then select **Save**. The plan you select can be in the same, or different subscription than the virtual network, but both subscriptions must be associated to the same Azure Active Directory tenant.

+## Configure an Azure DDoS Protection Plan using Azure Firewall Manager (preview)

+Azure Firewall Manager is a platform to manage and protect your network resources at scale. You can associate your virtual networks with a DDoS protection plan within Azure Firewall Manager. This functionality is currently available in Public Preview. See [Configure an Azure DDoS Protection Plan using Azure Firewall Manager](../firewall-manager/configure-ddos.md).

+## Enable DDoS protection for all virtual networks

+This [built-in policy](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2Fproviders%2FMicrosoft.Authorization%2FpolicyDefinitions%2F94de2ad3-e0c1-4caf-ad78-5d47bbc83d3d) will detect any virtual networks in a defined scope that don't have DDoS Protection Standard enabled. This policy will then optionally create a remediation task that will create the association to protect the Virtual Network. See [Azure Policy built-in definitions for Azure DDoS Protection Standard](policy-reference.md) for full list of built-in policies.

+1. Enter *DDoS* in the **Filter** box. When **DDoS protection plans** appear in the results, select it.

+1. Select your DDoS protection plan from the list.

+The _MyVnet_ virtual network should be listed.

+## View protected resources

+1. Filter or scroll down to find the _MyResourceGroup_ resource group.

+1. Select the resource group, then select **Delete resource group**.

+1. Type the resource group name to verify, and then select **Delete**.

+To disable DDoS protection for a virtual network:

+1. Under **DDoS Protection Standard**, select **Disable**.

+If you want to delete a DDoS protection plan, you must first dissociate all virtual networks from it.

+To learn how to view and configure telemetry for your DDoS protection plan, continue to the tutorials.

+> Microsoft Defender for Kubernetes has been replaced with [**Microsoft Defender for Containers**](defender-for-containers-introduction.md). If you've already enabled Defender for Kubernetes on a subscription, you can continue to use it. However, you won't get Defender for Containers' improvements and new features.

+ | Red Hat | Enterprise Linux | 5.4+, 6, 7-7.9, 8-8.5, 9 beta |

+ | Red Hat | CentOS | 5.4-5.11, 6-6.7, 7-7.8, 8-8.5 |

+ | SUSE | Linux Enterprise Server (SLES) | 11, 12, 15, 15 SP1 |

+ | SUSE | openSUSE | 12, 13, 15.0-15.3 |

+ | Oracle | Enterprise Linux | 5.11, 6, 7-7.9, 8-8.5 |

+ | Debian | Debian | 7.x-11.x |

+ | Red Hat | Enterprise Linux | 5.4+, 6, 7-7.9, 8-8.5, 9 beta |

+ | Red Hat | CentOS | 5.4-5.11, 6-6.7, 7-7.8, 8-8.5 |

+ | SUSE | Linux Enterprise Server (SLES) | 11, 12, 15, 15 SP1 |

+ | SUSE | openSUSE | 12, 13, 15.0-15.3 |

+ | Oracle | Enterprise Linux | 5.11, 6, 7-7.9, 8-8.5 |

+ | Debian | Debian | 7.x-11.x |

+- [Deprecated the Azure Cache for Redis recommendation](#deprecated-the-azure-cache-for-redis-recommendation)

+- [New alert variant for Microsoft Defender for Storage (preview) to detect exposure of sensitive data](#new-alert-variant-for-microsoft-defender-for-storage-preview-to-detect-exposure-of-sensitive-data)

+- [Container scan alert title augmented with IP address reputation](#container-scan-alert-title-augmented-with-ip-address-reputation)

+While Microsoft Defender for Servers Plan 2 continues to provide, complete protections from threats and vulnerabilities to your cloud and on-premises workloads, Microsoft Defender for Servers Plan 1 provides endpoint protection only, powered by Microsoft Defender for Endpoint and natively integrated with Defender for Cloud. Read more about the [Microsoft Defender for Servers plans](defender-for-servers-introduction.md#what-are-the-microsoft-defender-for-server-plans).

+In addition, Defender for Cloud also begins gradual support for the [Defender for Endpoint unified agent for Windows Server 2012 R2 and 2016 (Preview)](https://techcommunity.microsoft.com/t5/microsoft-defender-for-endpoint/defending-windows-server-2012-r2-and-2016/ba-p/2783292). Defender for Servers Plan 1 deploys the new unified agent to Windows Server 2012 R2 and 2016 workloads. Defender for Servers Plan 2 deploys the legacy agent to Windows Server 2012 R2 and 2016 workloads, and will deploy the unified agent soon after it's approved for general use.

+### PowerShell script to stream alerts to Splunk and IBM QRadar

+We recommend that you use Event Hubs and a built-in connector to export security alerts to Splunk and IBM QRadar. Now you can use a PowerShell script to set up the Azure resources needed to export security alerts for your subscription or tenant.

+Just download and run the PowerShell script. After you provide a few details of your environment, the script configures the resources for you. The script then produces output that you use in the SIEM platform to complete the integration.

+To learn more, see [Stream alerts to Splunk and QRadar](export-to-siem.md#stream-alerts-to-qradar-and-splunk).

+### Deprecated the Azure Cache for Redis recommendation

+The recommendation `Azure Cache for Redis should reside within a virtual network` (Preview) has been deprecated. WeΓÇÖve changed our guidance for securing Azure Cache for Redis instances. We recommend the use of a private endpoint to restrict access to your Azure Cache for Redis instance, instead of a virtual network.

+### New alert variant for Microsoft Defender for Storage (preview) to detect exposure of sensitive data

+Microsoft Defender for Storage's alerts notify you when threat actors attempt to scan and expose, successfully or not, misconfigured, publicly open storage containers to try to exfiltrate sensitive information.

+To allow for faster triaging and response time, when exfiltration of potentially sensitive data may have occurred, we've released a new variation to the existing `Publicly accessible storage containers have been exposed` alert.

+The new alert, `Publicly accessible storage containers with potentially sensitive data have been exposed`, is triggered with a `High` severity level, after there has been a successful discovery of a publicly open storage container(s) with names that statistically have been found to rarely be exposed publicly, suggesting they might hold sensitive information.

+| Alert (alert type) | Description | MITRE tactic | Severity |

+|--|--|--|--|

+|**PREVIEW - Publicly accessible storage containers with potentially sensitive data have been exposed** <br>(Storage.Blob_OpenContainersScanning.SuccessfulDiscovery.Sensitive)| Someone has scanned your Azure Storage account and exposed container(s) that allow public access. One or more of the exposed containers have names that indicate that they may contain sensitive data. <br> <br> This usually indicates reconnaissance by a threat actor that is scanning for misconfigured publicly accessible storage containers that may contain sensitive data. <br> <br> After a threat actor successfully discovers a container, they may continue by exfiltrating the data. <br> Γ£ö Azure Blob Storage <br> Γ£û Azure Files <br> Γ£û Azure Data Lake Storage Gen2 | Collection | High |

+### Container scan alert title augmented with IP address reputation

+An IP address's reputation can indicate whether the scanning activity originates from a known threat actor, or from an actor that is using the Tor network to hide their identity. Both of these indicators, suggest that there's malicious intent. The IP address's reputation is provided by [Microsoft Threat Intelligence](https://go.microsoft.com/fwlink/?linkid=2128684).

+The addition of the IP address's reputation to the alert title provides a way to quickly evaluate the intent of the actor, and thus the severity of the threat.

+The following alerts will include this information:

+- `Publicly accessible storage containers have been exposed`

+- `Publicly accessible storage containers with potentially sensitive data have been exposed`

+- `Publicly accessible storage containers have been scanned. No publicly accessible data was discovered`

+For example, the added information to the title of the `Publicly accessible storage containers have been exposed` alert will look like this:

+- `Publicly accessible storage containers have been exposed`**`by a suspicious IP address`**

+- `Publicly accessible storage containers have been exposed`**`by a Tor exit node`**

+All of the alerts for Microsoft Defender for Storage will continue to include threat intelligence information in the IP entity under the alert's Related Entities section.

+| [Key Vault recommendations changed to "audit"](#key-vault-recommendations-changed-to-audit) | May 2022 |

+### Key Vault recommendations changed to "audit"

+The Key Vault recommendations listed here are currently disabled so that they don't impact your secure score. We will change their effect to "audit".

+| Recommendation name | Recommendation ID |

+| - | |

+| Validity period of certificates stored in Azure Key Vault should not exceed 12 months | fc84abc0-eee6-4758-8372-a7681965ca44 |

+| Key Vault secrets should have an expiration date | 14257785-9437-97fa-11ae-898cfb24302b |

+| Key Vault keys should have an expiration date | 1aabfa0d-7585-f9f5-1d92-ecb40291d9f2 |

+IoT and ICS devices can be secured using both embedded protocols and proprietary, custom, or non-standard protocols. Use the Horizon Open Development Environment (ODE) SDK to develop dissector plug-ins that decode network traffic, regardless of protocol type.

+Contact [ms-horizon-support@microsoft.com](mailto:ms-horizon-support@microsoft.com) for details about working with the Open Development Environment (ODE) SDK and creating protocol plugins.

+> This feature isn't supported in the **basic** tier.

+1. On the Azure portal menu, select **+ Create a resource**. Search for **ExpressRoute** and then select **Create**.

+ :::image type="content" source="./media/expressroute-howto-circuit-portal-resource-manager/create-an-expressroute-circuit.png" alt-text="Create an ExpressRoute circuit":::

+1. On the **Create ExpressRoute** page. Provide the **Resource Group**, **Region**, and **Name** for the circuit. Then select **Next: Configuration >**.

+1. When you're filling in the values on this page, make sure that you specify the correct SKU tier (Local, Standard, or Premium) and data metering billing model (Unlimited or Metered).

+ | Setting | Description |

+ | | |

+ | Port type | Select if you're connecting to a service provider or directly into Microsoft's global network at a peering location. |

+ | Create new or import from classic | Select if you're creating a new circuit or if you're migrating a classic circuit to Azure Resource Manager. |

+ | Provider | Select the internet service provider who you'll be requesting your service from. |

+ | Peering Location | Select the physical location where you're peering with Microsoft. |

+ | SKU | Select the SKU for the ExpressRoute circuit. You can specify **Local** to get the local SKU, **Standard** to get the standard SKU or **Premium** for the premium add-on. You can change between Standard and Premium but not to Local once created. |

+ | Billing model | Select the billing type for egress data charge. You can specify **Metered** for a metered data plan and **Unlimited** for an unlimited data plan. You can change the billing type from **Metered** to **Unlimited**. |

+ | Allow classic operations | Enable this option to allow classic virtual networks to link to the circuit. |

+ > * The Peering Location indicates the [physical location](expressroute-locations.md) where you are peering with Microsoft. This is **not** linked to "Location" property, which refers to the geography where the Azure Network Resource Provider is located. While they're not related, it is a good practice to choose a Network Resource Provider geographically close to the Peering Location of the circuit.

+ > * You can't change the SKU from **Standard/Premium** to **Local**.

+ > * You can't change the type from **Unlimited** to **Metered**.

+1. Select **Review + create** and then select **Create** to deploy the ExpressRoute circuit.

+You can view all the circuits that you created by searching for **ExpressRoute circuits** in the search box at the top of the portal.

+You can view the properties of the circuit by selecting it. On the Overview page for your circuit, you'll find the **Service Key**. Provide the service key to the service provider to complete the provisioning process. The service key is unique to your circuit.

+ > [!IMPORTANT]

+

+ > [!NOTE]

+ > The Key Vault shouldn't be behind a private endpoint because communicate to the ExpressRoute management plane is required.

+ >

+

+ | Host name | HostName is used for SNI (SSL negotiation) and should match your server side certificate. |

+cascade by inheritance to all associated subscriptions.

+You can create a hierarchy that applies a policy, for example, which limits VM locations to the

+West US region in the management group called "Production". This policy will inherit onto all the Enterprise

+Each directory is given a single top-level management group called the **root** management group. The

+### Important facts about the root management group

+- By default, the root management group's display name is **Tenant root group** and operates itself as a management group. The ID is the same value as the Azure Active Directory (Azure AD) tenant ID.

+- To change the display name, your account must be assigned the **Owner** or **Contributor** role on the

+> Any assignment of user access or policy on the root management group **applies to all

+resource groups, and resources within that Azure AD tenant.

+A few directories that started using management groups early in the preview before June 25, 2018

+- Remove all role and policy assignments from the root management group

+ assignments one level below the root management group. Then you can remove all assignments from

+\*: The **Management Group Contributor** and **Management Group Reader** roles allow users to perform those actions only on the management group scope.

+\*\*: Role assignments on the root management group aren't required to move a subscription or

+management group to and from it.

+See [Manage your resources with management groups](manage.md) for

+**/providers/Microsoft.Management/managementgroups/{_groupId_}**.

+- Add the subscription to the role definition's assignable scope.

+ assignable scopes from Marketing to the root management group so that the definition can be reached by

+- Create another custom role that is defined in the other branch. This new role requires the role

+ - Built-in role example: **Owner**

+**Exception**: If the target or the existing parent management group is the root management group,

+the permissions requirements don't apply. Since the root management group is the default landing

+If the **Owner** role on the subscription is inherited from the current management group, your move

+the **Owner** role. You can't move it to a management group where you're a **Contributor** because you would

+lose ownership of the subscription. If you're directly assigned to the **Owner** role for the

+where you're assigned the **Contributor** role.

+> As a result, moving a management group may not immediately be reflected in the Azure portal.

+[Azure Activity log](../../azure-monitor/essentials/platform-logs-overview.md). You can search all

+example, you can see all role assignments or policy assignment changes made to a particular

+When looking to query on management groups outside the Azure portal, the target scope for

+management groups looks like **"/providers/Microsoft.Management/managementGroups/{_management-group-id_}"**.

+For the regions: Singapore, Brazil South, and East Asia all customer data is stored and processed in the region.

+ Title: Connect to HiveServer2 using Beeline or install Beeline locally to connect from your local - Azure HDInsight

+# Connect to HiveServer2 using Beeline or install Beeline locally to connect from your local

+[Apache Beeline](https://cwiki.apache.org/confluence/display/Hive/HiveServer2+Clients#HiveServer2Clients-BeelineΓÇôNewCommandLineShell) is a Hive client that is included on the head nodes of your HDInsight cluster. This article describes how to connect to HiveServer2 using the Beeline client installed on your HDInsight cluster across different types of connections. It also discusses how to [Install the Beeline client locally](#install-beeline-client).

+[](media/export-data/fhir-mi-enabled.png#lightbox)

+1. Select **Access Control (IAM)**.

+1. Select **Add > Add role assignment**. If the **Add role assignment** option is grayed out, ask your Azure administrator to assign you permission to perform this task.

+ :::image type="content" source="../../../includes/role-based-access-control/media/add-role-assignment-menu-generic.png" alt-text="Screenshot that shows Access control (IAM) page with Add role assignment menu open.":::

+1. On the **Roles** tab, select the [Storage Blob Data Contributor](../../role-based-access-control/built-in-roles.md#storage-blob-data-contributor) role.

+ [](../../../includes/role-based-access-control/media/add-role-assignment-page.png#lightbox)

+1. On the **Members** tab, select **Managed identity**, and then select **Select members**.

+1. Select **System-assigned managed identity**, and then select the FHIR service.

+1. On the **Review + assign** tab, select **Review + assign** to assign the role.

+For more information about assigning roles in the Azure portal, see [Azure built-in roles](../../role-based-access-control/role-assignments-portal.md).

+[](media/export-data/fhir-export-storage.png#lightbox)

+1. Select **Access Control (IAM)**.

+1. Select **Add > Add role assignment**. If the **Add role assignment** option is grayed out, ask your Azure administrator to assign you permission to perform this task.

+ :::image type="content" source="../../../includes/role-based-access-control/media/add-role-assignment-menu-generic.png" alt-text="Screenshot that shows Access control (IAM) page with Add role assignment menu open.":::

+1. On the **Roles** tab, select the [AcrPull](../../role-based-access-control/built-in-roles.md#acrpull) role.

+ [](../../../includes/role-based-access-control/media/add-role-assignment-page.png#lightbox)

+1. On the **Members** tab, select **Managed identity**, and then select **Select members**.

+1. Select **System-assigned managed identity**, and then select the FHIR service.

+1. On the **Review + assign** tab, select **Review + assign** to assign the role.

+For more information about assigning roles in the Azure portal, see [Azure built-in roles](../../role-based-access-control/role-assignments-portal.md).

+- The Microsoft Azure Active Directory (Azure AD) app registrations used for authentication require Global Administrator, Application

+## Main components

+The Azure Industrial IoT Platform is a Microsoft suite of modules (OPC Publisher, OPC Twin, Discovery) and services that are deployed on Azure. The cloud microservices (Registry, OPC Twin, OPC Publisher, Edge Telemetry Processor, Registry Onboarding Processor, Edge Event Processor, Registry Synchronization) are implemented as ASP.NET microservices with a REST interface and run on managed Azure Kubernetes Services or stand-alone on Azure App Service. The deployment can deploy the platform, an entire simulation environment and a Web UI (Industrial IoT Engineering Tool).

+The deployment script allows to select which set of components to deploy.

+- Minimum dependencies:

+ - [IoT Hub](https://azure.microsoft.com/services/iot-hub/) to communicate with the edge and ingress raw OPC UA telemetry data

+ - [Cosmos DB](https://azure.microsoft.com/services/cosmos-db/) to persist state that is not persisted in IoT Hub

+ - [Service Bus](https://azure.microsoft.com/services/service-bus/) as integration event bus

+ - [Event Hubs](https://azure.microsoft.com/services/event-hubs/) contains processed and contextualized OPC UA telemetry data

+ - [Key Vault](https://azure.microsoft.com/services/key-vault/) to manage secrets and certificates

+ - [Storage](https://azure.microsoft.com/product-categories/storage/) for Event Hubs checkpointing

+- Standard dependencies: Minimum +

+ - [SignalR Service](https://azure.microsoft.com/services/signalr-service/) used to scale out asynchronous API notifications, Azure AD app registrations,

+ - [Device Provisioning Service](https://docs.microsoft.com/azure/iot-dps/) used for deploying and provisioning the simulation gateways

+ - [Time Series Insights](https://azure.microsoft.com/services/time-series-insights/)

+ - Workbook, Log Analytics, [Application Insights](https://azure.microsoft.com/services/monitor/) for operations monitoring

+- Micro

+ - App Service Plan, [App Service](https://azure.microsoft.com/services/app-service/) for hosting the cloud microservices

+- UI (Web app):

+ - App Service Plan (shared with microservices), [App Service](https://azure.microsoft.com/services/app-service/) for hosting the Industrial IoT Engineering Tool cloud application

+- Simulation:

+ - [Virtual machine](https://azure.microsoft.com/services/virtual-machines/), Virtual network, IoT Edge used for a factory simulation to show the capabilities of the platform and to generate sample telemetry

+- [Azure Kubernetes Service](https://github.com/Azure/Industrial-IoT/blob/master/docs/deploy/howto-deploy-aks.md) should be used to host the cloud microservices

+## Deploy Azure IIoT Platform using the deployment script

+2. Start the guided deployment. The script will collect the required information, such as Azure account, subscription, target resource and group and application name.

+ .\deploy -version <version> [-type <deploymentType>]

+ ./deploy.sh -version <version> [-type <deploymentType>]

+ Replace \<deploymentType> with the type of deployment (optional parameter).

+ The types of deployments are the followings:

+ - `minimum`: Minimum dependencies

+ - `local`: Minimum and standard dependencies

+ - `services`: Local and microservices

+ - `simulation`: Minimum dependencies and simulation components

+ - `app`: Services and UI

+ - `all` (default): App and simulation

+3. The microservices and the UI are web applications that require authentication, this requires three app registrations in the Azure AD. If the required rights are missing, there are two possible solutions:

+ - Ask the Azure AD admin to grant tenant-wide admin consent for the application

+ - An Azure AD admin can create the Azure AD applications. The deploy/scripts folder contains the aad-register.ps1 script to perform the Azure AD registration separately from the deployment. The output of the script is a file containing the relevant information to be used as part of deployment and must be passed to the deploy.ps1 script in the same folder using the `-aadConfig` argument.

+## Other hosting and deployment methods

+Other hosting and deployment methods:

+- For production deployments that require staging, rollback, scaling, and resilience, the platform can be deployed into [Azure Kubernetes Service (AKS)](https://github.com/Azure/Industrial-IoT/blob/master/docs/deploy/howto-deploy-aks.md)

+- Deploying Azure Industrial IoT Platform microservices into an existing Kubernetes cluster using [Helm](https://github.com/Azure/Industrial-IoT/blob/master/docs/deploy/howto-deploy-helm.md).

+- Deploying [Azure Kubernetes Service (AKS) cluster on top of Azure Industrial IoT Platform created by deployment script and adding Azure Industrial IoT components into the cluster](https://github.com/Azure/Industrial-IoT/blob/master/docs/deploy/howto-add-aks-to-ps1.md).

+## Device groups

+### Add a device group

+Use the following request to create a new device group.

+```http

+PUT https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview

+```

+When you create a device group, you define a `filter` that selects the devices to add to the group. A `filter` identifies a device template and any properties to match. The following example creates device group that contains all devices associated with the "dtmi:modelDefinition:dtdlv2" template where the `provisioned` property is true

+```json

+{

+ "displayName": "Device group 1",

+ "description": "Custom device group.",

+ "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",

+ "organizations": [

+ "seattle"

+ ]

+}

+```

+The request body has some required fields:

+* `@displayName`: Display name of the device group.

+* `@filter`: Query defining which devices should be in this group.

+* `@etag`: ETag used to prevent conflict in device updates.

+* `description`: Short summary of device group.

+The organizations field is only used when an application has an organization hierarchy defined. To learn more about organizations, see [Manage IoT Central organizations](howto-edit-device-template.md)

+The response to this request looks like the following example:

+```json

+{

+ "id": "group1",

+ "displayName": "Device group 1",

+ "description": "Custom device group.",

+ "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",

+ "organizations": [

+ "seattle"

+ ]

+}

+```

+### Get a device group

+Use the following request to retrieve details of a device group from your application:

+```http

+GET https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview

+```

+* deviceGroupId - Unique ID for the device group.

+The response to this request looks like the following example:

+```json

+{

+ "id": "475cad48-b7ff-4a09-b51e-1a9021385453",

+ "displayName": "DeviceGroupEntry1",

+ "description": "This is a default device group containing all the devices for this particular Device Template.",

+ "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",

+ "organizations": [

+ "seattle"

+ ]

+}

+```

+### Update a device group

+```http

+PATCH https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview

+```

+The sample request body looks like the following example which updates the `displayName` of the device group:

+```json

+{

+ "displayName": "New group name"

+}

+```

+The response to this request looks like the following example:

+```json

+{

+ "id": "group1",

+ "displayName": "New group name",

+ "description": "Custom device group.",

+ "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",

+ "organizations": [

+ "seattle"

+ ]

+}

+```

+### Delete a device group

+Use the following request to delete a device group:

+```http

+DELETE https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview

+```

+### List device groups

+Use the following request to retrieve a list of device groups from your application:

+```http

+GET https://{subdomain}.{baseDomain}/api/deviceGroups?api-version=1.2-preview

+```

+The response to this request looks like the following example:

+```json

+{

+ "value": [

+ {

+ "id": "475cad48-b7ff-4a09-b51e-1a9021385453",

+ "displayName": "DeviceGroupEntry1",

+ "description": "This is a default device group containing all the devices for this particular Device Template.",

+ "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",

+ "organizations": [

+ "seattle"

+ ]

+ },

+ {

+ "id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",

+ "displayName": "DeviceGroupEntry2",

+ "description": "This is a default device group containing all the devices for this particular Device Template.",

+ "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",

+ "organizations": [

+ "redmond"

+ ]

+ },

+ {

+ "id": "241ad72b-32aa-4216-aabe-91b240582c8d",

+ "displayName": "DeviceGroupEntry3",

+ "description": "This is a default device group containing all the devices for this particular Device Template.",

+ "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"

+ },

+ {

+ "id": "group4",

+ "displayName": "DeviceGroupEntry4",

+ "description": "This is a default device group containing all the devices for this particular Device Template.",

+ "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""

+ }

+ ]

+}

+```

+ Title: How to implement IoT Edge observability using monitoring and troubleshooting

+description: Learn how to build an observability solution for an IoT Edge System

+# How to implement IoT Edge observability using monitoring and troubleshooting

+In this article, you'll learn the concepts and techniques of implementing both observability dimensions *measuring and monitoring* and *troubleshooting*. You'll learn about the following topics:

+* Define what indicators of the service performance to monitor

+* Measure service performance indicators with metrics

+* Monitor metrics and detect issues with Azure Monitor workbooks

+* Perform basic troubleshooting with the curated workbooks

+* Perform deeper troubleshooting with distributed tracing and correlated logs

+* Optionally, deploy a sample scenario to Azure to reproduce what you learned

+## Scenario

+In order to go beyond abstract considerations, we'll use a *real-life* scenario collecting ocean surface temperatures from sensors into Azure IoT.

+### La Ni├▒a

+

+The La Ni├▒a service measures surface temperature in Pacific Ocean to predict La Ni├▒a winters. There is a number of buoys in the ocean with IoT Edge devices that send the surface temperature to Azure Cloud. The telemetry data with the temperature is pre-processed by a custom module on the IoT Edge device before sending it to the cloud. In the cloud, the data is processed by backend Azure Functions and saved to Azure Blob Storage. The clients of the service (ML inference workflows, decision making systems, various UIs, etc.) can pick up messages with temperature data from the Azure Blob Storage.

+## Measuring and monitoring

+Let's build a measuring and monitoring solution for the La Ni├▒a service focusing on its business value.

+### What do we measure and monitor

+To understand what we're going to monitor, we must understand what the service actually does and what the service clients expect from the system. In this scenario, the expectations of a common La Ni├▒a service consumer may be categorized by the following factors:

+* **_Coverage_**. The data is coming from most installed buoys

+* **_Freshness_**. The data coming from the buoys is fresh and relevant

+* **_Throughput_**. The temperature data is delivered from the buoys without significant delays

+* **_Correctness_**. The ratio of lost messages (errors) is small

+The satisfaction regarding these factors means that the service works according to the client's expectations.

+The next step is to define instruments to measure values of these factors. This job can be done by the following Service Level Indicators (SLI):

+|**Service Level Indicator** | **Factors** |

+|-||

+|Ratio of on-line devices to the total number of devices| Coverage|

+|Ratio of devices reporting frequently to the number of reporting devices| Freshness, Throughput|

+|Ratio of devices successfully delivering messages to the total number of devices|Correctness|

+|Ratio of devices delivering messages fast to the total number of devices| Throughput |

+With that done, we can apply a sliding scale on each indicator and define exact threshold values that represent what it means for the client to be "satisfied". For this scenario, we have selected sample threshold values as laid out in the table below with formal Service Level Objectives (SLOs):

+|**Service Level Objective**|**Factor**|

+|-|-|

+|90% of devices reported metrics no longer than 10 mins ago (were online) for the observation interval| Coverage |

+|95% of online devices send temperature 10 times per minute for the observation interval| Freshness, Throughput |

+|99% of online devices deliver messages successfully with less than 5% of errors for the observation interval| Correctness |

+|95% of online devices deliver 90th percentile of messages within 50 ms for the observation interval|Throughput|

+SLOs definition must also describe the approach of how the indicator values are measured:

+- Observation interval: 24 hours. SLO statements have been true for the last 24 hours. Which means that if an SLI goes down and breaks a corresponding SLO, it will take 24 hours after the SLI has been fixed to consider the SLO good again.

+- Measurements frequency: 5 minutes. We do the measurements to evaluate SLI values every 5 minutes.

+- What is measured: interaction between IoT Device and the cloud, further consumption of the temperature data is out of scope.

+### How do we measure

+At this point, it's clear what we're going to measure and what threshold values we're going to use to determine if the service performs according to the expectations.

+It's a common practice to measure service level indicators, like the ones we've defined, by the means of **_metrics_**. This type of observability data is considered to be relatively small in values. It's produced by various system components and collected in a central observability backend to be monitored with dashboards, workbooks and alerts.

+Let's clarify what components the La Ni├▒a service consists of:

+

+There is an IoT Edge device with `Temperature Sensor` custom module (C#) that generates some temperature value and sends it upstream with a telemetry message. This message is routed to another custom module `Filter` (C#). This module checks the received temperature against a threshold window (0-100 degrees Celsius). If the temperature is within the window, the FilterModule sends the telemetry message to the cloud.

+In the cloud, the message is processed by the backend. The backend consists of a chain of two Azure Functions and storage account.

+Azure .NET Function picks up the telemetry message from the IoT Hub events endpoint, processes it and sends it to Azure Java Function. The Java function saves the message to the storage account blob container.

+An IoT Hub device comes with system modules `edgeHub` and `edgeAgent`. These modules expose through a Prometheus endpoint [a list of built-in metrics](how-to-access-built-in-metrics.md). These metrics are collected and pushed to Azure Monitor Log Analytics service by the [metrics collector module](how-to-collect-and-transport-metrics.md) running on the IoT Edge device. In addition to the system modules, the `Temperature Sensor` and `Filter` modules can be instrumented with some business specific metrics too. However, the service level indicators that we've defined can be measured with the built-in metrics only. So, we don't really need to implement anything else at this point.

+In this scenario, we have a fleet of 10 buoys. One of the buoys has been intentionally set up to malfunction so that we can demonstrate the issue detection and the follow-up troubleshooting.

+### How do we monitor

+We're going to monitor Service Level Objectives (SLO) and corresponding Service Level Indicators (SLI) with Azure Monitor Workbooks. This scenario deployment includes the *La Nina SLO/SLI* workbook assigned to the IoT Hub.

+

+To achieve the best user experience the workbooks are designed to follow the _glance_ -> _scan_ -> _commit_ concept:

+#### Glance

+

+At this level, we can see the whole picture at a single glance. The data is aggregated and represented at the fleet level:

+

+From what we can see, the service is not functioning according to the expectations. There is a violation of the *Data Freshness* SLO.

+Only 90% of the devices send the data frequently, and the service clients expect 95%.

+All SLO and threshold values are configurable on the workbook settings tab:

+

+#### Scan

+By clicking on the violated SLO, we can drill down to the *scan* level and see how the devices contribute to the aggregated SLI value.

+

+There is a single device (out of 10) that sends the telemetry data to the cloud "rarely". In our SLO definition, we've stated that "frequently" means at least 10 times per minute. The frequency of this device is way below that threshold.

+#### Commit

+By clicking on the problematic device, we're drilling down to the *commit* level. This is a curated workbook *Device Details* that comes out of the box with IoT Hub monitoring offering. The *La Nina SLO/SLI* workbook reuses it to bring the details of the specific device performance.

+

+## Troubleshooting

+*Measuring and monitoring* lets us observe and predict the system behavior, compare it to the defined expectations and ultimately detect existing or potential issues. The *troubleshooting*, on the other hand, lets identify and locate the cause of the issue.

+### Basic troubleshooting

+The *commit* level workbook gives a lot of detailed information about the device health. That includes resources consumption at the module and device level, message latency, frequency, QLen, etc. In many cases, this information may help locate the root of the issue.

+In this scenario, all parameters of the trouble device look normal and it's not clear why the device sends messages less frequent than expected. This fact is also confirmed by the *messaging* tab of the device-level workbook:

+

+The `Temperature Sensor` (tempSensor) module produced 120 telemetry messages, but only 49 of them went upstream to the cloud.

+The first step we want to do is to check the logs produced by the `Filter` module. Click the **Troubleshoot live!** button and select the `Filter` module.

+

+Analysis of the module logs doesn't discover the issue. The module receives messages, there are no errors. Everything looks good here.

+### Deep troubleshooting

+There are two observability instruments serving the deep troubleshooting purposes: *traces* and *logs*. In this scenario, traces show how a telemetry message with the ocean surface temperature is traveling from the sensor to the storage in the cloud, what is invoking what and with what parameters. Logs give information on what is happening inside each system component during this process. The real power of *traces* and *logs* comes when they're correlated. With that it's possible to read the logs of a specific system component, such as a module on IoT device or a backend function, while it was processing a specific telemetry message.

+The La Ni├▒a service uses [OpenTelemetry](https://opentelemetry.io) to produce and collect traces and logs in Azure Monitor.

+

+IoT Edge modules `Temperature Sensor` and `Filter` export the logs and tracing data via OTLP (OpenTelemetry Protocol) to the [OpenTelemetryCollector](https://opentelemetry.io/docs/collector/) module, running on the same edge device. The `OpenTelemetryCollector` module, in its turn, exports logs and traces to Azure Monitor Application Insights service.

+The Azure .NET Function sends the tracing data to Application Insights with [Azure Monitor Open Telemetry direct exporter](../azure-monitor/app/opentelemetry-enable.md). It also sends correlated logs directly to Application Insights with a configured ILogger instance.

+The Java backend function uses [OpenTelemetry auto-instrumentation Java agent](../azure-monitor/app/java-in-process-agent.md) to produce and export tracing data and correlated logs to the Application Insights instance.

+By default, IoT Edge modules on the devices of the La Ni├▒a service are configured to not produce any tracing data and the [logging level](/aspnet/core/fundamentals/logging) is set to `Information`. The amount of produced tracing data is regulated by a [ratio based sampler](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry/Trace/TraceIdRatioBasedSampler.cs#L35). The sampler is configured with a desired [probability](https://github.com/open-telemetry/opentelemetry-dotnet/blob/bdcf942825915666dfe87618282d72f061f7567e/src/OpenTelemetry/Trace/TraceIdRatioBasedSampler.cs#L35) of a given activity to be included in a trace. By default, the probability is set to 0. With that in place, the devices don't flood the Azure Monitor with the detailed observability data if it's not requested.

+We've analyzed the `Information` level logs of the `Filter` module and realized that we need to dive deeper to locate the cause of the issue. We're going to update properties in the `Temperature Sensor` and `Filter` module twins and increase the `loggingLevel` to `Debug` and change the `traceSampleRatio` from `0` to `1`:

+

+With that in place, we have to restart the `Temperature Sensor` and `Filter` modules:

+

+In a few minutes, the traces and detailed logs will arrive to Azure Monitor from the trouble device. The entire end-to-end message flow from the sensor on the device to the storage in the cloud will be available for monitoring with *application map* in Application Insights:

+

+From this map we can drill down to the traces and we can see that some of them look normal and contain all the steps of the flow, and some of them, are very short, so nothing happens after the `Filter` module.

+

+Let's analyze one of those short traces and find out what was happening in the `Filter` module, and why it didn't send the message upstream to the cloud.

+Our logs are correlated with the traces, so we can query logs specifying the `TraceId` and `SpanId` to retrieve logs corresponding exactly to this execution instance of the `Filter` module:

+

+The logs show that the module received a message with 70.465-degrees temperature. But the filtering threshold configured on this device is 30 to 70. So the message simply didn't pass the threshold. Apparently, this specific device was configured wrong. This is the cause of the issue we detected while monitoring the La Ni├▒a service performance with the workbook.

+Let's fix the `Filter` module configuration on this device by updating properties in the module twin. We also want to reduce back the `loggingLevel` to `Information` and `traceSampleRatio` to `0`:

+

+Having done that, we need to restart the module. In a few minutes, the device reports new metric values to Azure Monitor. It reflects in the workbook charts:

+

+We see that the message frequency on the problematic device got back to normal. The overall SLO value will become green again, if nothing else happens, in the configured observation interval:

+

+## Try the sample

+At this point, you might want to deploy the scenario sample to Azure to reproduce the steps and play with your own use cases.

+In order to successfully deploy this solution, you need the following:

+- [PowerShell](/powershell/scripting/install/installing-powershell).

+- [Azure CLI](/cli/azure/install-azure-cli).

+- An Azure account with an active subscription. [Create one for free](https://azure.microsoft.com/free).

+1. Clone the [IoT Elms](https://github.com/Azure-Samples/iotedge-logging-and-monitoring-solution) repository.

+ ```sh

+ git clone https://github.com/Azure-Samples/iotedge-logging-and-monitoring-solution.git

+1. Open a PowerShell console and run the `deploy-e2e-tutorial.ps1` script.

+ ```powershell

+ ./Scripts/deploy-e2e-tutorial.ps1

+## Next steps

+In this article, you have set up a solution with end-to-end observability capabilities for monitoring and troubleshooting. The common challenge in such solutions for IoT systems is delivering observability data from the devices to the cloud. The devices in this scenario are supposed to be online and have a stable connection to Azure Monitor, which is not always the case in real life.

+Advance to follow up articles such as [Distributed Tracing with IoT Edge](https://github.com/Azure-Samples/iotedge-logging-and-monitoring-solution/blob/main/docs/iot-edge-distributed-tracing.md) with the recommendations and techniques to handle scenarios when the devices are normally offline or have limited or restricted connection to the observability backend in the cloud.

+* Uses Node.js version 8.11.1 for [multi-tenant based logic apps](logic-apps-overview.md) or [Node.js versions 12.x.x or 14.x.x](https://nodejs.org/en/download/releases/) for [single-tenant based logic apps](single-tenant-overview-compare.md).

+description: 'Learn about model management (MLOps) with Azure Machine Learning. Deploy, manage, track lineage and monitor your models to continuously improve them. '

+For more information, see [Controlled rollout of ML models](./how-to-safely-rollout-managed-endpoints.md).

+Azure ML publishes key events to Azure Event Grid, which can be used to notify and automate on events in the ML lifecycle. For more information, please see [this document](how-to-use-event-grid.md).

+ "Microsoft.MachineLearningServices/workspaces/labeling/projects/summary/read",

+ "Microsoft.MachineLearningServices/workspaces/labeling/labels/read",

+ "Microsoft.MachineLearningServices/workspaces/labeling/labels/write"

+ "NotActions": [

+- If you plan on using an Azure Virtual Network to secure communication between your Azure ML workspace and the AKS cluster, your workspace and its associated resources (storage, key vault, Azure Container Registry) must have private endpoints or service endpoints in the same VNET as AKS cluster's VNET. Please follow tutorial [create a secure workspace](./tutorial-create-secure-workspace.md) to add those private endpoints or service endpoints to your VNET.

+- __Do not directly update the cluster by using a YAML configuration__. While Azure Kubernetes Services supports updates via YAML configuration, Azure Machine Learning deployments will override your changes. The only two YAML fields that will not overwritten are __request limits__ and __cpu and memory__.

+When you [create or attach an AKS cluster](how-to-create-attach-kubernetes.md), you can enable TLS termination with **[AksCompute.provisioning_configuration()](/python/api/azureml-core/azureml.core.compute.akscompute#provisioning-configuration-agent-count-none--vm-size-none--ssl-cname-none--ssl-cert-pem-file-none--ssl-key-pem-file-none--location-none--vnet-resourcegroup-name-none--vnet-name-none--subnet-name-none--service-cidr-none--dns-service-ip-none--docker-bridge-cidr-none--cluster-purpose-none--load-balancer-type-none--load-balancer-subnet-none-)** and **[AksCompute.attach_configuration()](/python/api/azureml-core/azureml.core.compute.akscompute#attach-configuration-resource-group-none--cluster-name-none--resource-id-none--cluster-purpose-none-)** configuration objects. Both methods return a configuration object that has an **enable_ssl** method, and you can use **enable_ssl** method to enable TLS.

+To create an AKS cluster that uses an Internal Load Balancer, use the `load_balancer_type` and `load_balancer_subnet` parameters:

+| `api.azureml.ms` | Azure Active Directory (Azure AD) authentication |

+* Resolve DNS for Azure AD authentication server api.azureml.ms and communicate with it when the deployed service uses Azure AD authentication.

+**Private AKS clusters** have a control plane, which can only be accessed through private IPs. Private AKS clusters must be attached after the cluster is created.

+Regardless default AKS cluster or private AKS cluster used, if your AKS cluster is behind of VNET, your workspace and its associate resources (storage, key vault, and ACR) must have private endpoints or service endpoints in the same VNET as the AKS cluster.

+* If your AKS cluster is behind of a VNET, your workspace and its associated resources (storage, key vault, Azure Container Registry) must have private endpoints or service endpoints in the same VNET as AKS cluster's VNET. Please read tutorial [create a secure workspace](./tutorial-create-secure-workspace.md) to add those private endpoints or service endpoints to your VNET.

+To register a model, you can upload the model files from the run to the model registry:

+ az role assignment create --assignee <principal ID> --role managedidentityoperator --scope <user-assigned managed identity resource ID>

+ The user-assigned managed identity resource ID is Azure resource ID of the user assigned identity, in the format `/subscriptions/<subscription ID>/resourceGroups/<resource group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned managed identity name>`.

+ value={"ResourceId": "<user-assigned managed identity resource id>", "ClientId": "<user-assigned managed identity client ID>"})

+identity.resource_id= "<user-assigned managed identity resource ID>"

+identity.client_id="<user-assigned managed identity client ID>"

+| Offer type | Free Trial | Test Drive | Contact Me | Get It Now |

+| Azure Application (Managed app) | | &#10004; | | &#10004;<sup>1</sup> |

+| Azure Application (Solution template) | | | | &#10004;<sup>1</sup> |

+| Azure Container | | | | &#10004;<sup>1</sup> |

+| Azure Virtual Machine | &#10004; | &#10004; | | &#10004;<sup>1</sup> |

+| Dynamics 365 Business Central | &#10004; | &#10004; | &#10004; | &#10004;<sup>1</sup> |

+| Dynamics 365 apps on Dataverse and Power Apps | &#10004; | &#10004; | &#10004; | &#10004;<sup>1</sup> <sup>2</sup> |

+| Dynamics 365 Operations Apps | &#10004; | &#10004; | &#10004; | &#10004;<sup>1</sup> |

+| IoT Edge module | | | | &#10004;<sup>1</sup> |

+| Managed Service | | | | &#10004;<sup>1</sup> |

+| Power BI App | | | | &#10004;<sup>1</sup> |

+| Software as a service | &#10004; | &#10004; | &#10004; | &#10004;<sup>1</sup> |

+<sup>1</sup> The **Get It Now** listing option includes Get It Now (Free), bring your own license (BYOL), Subscription, and Usage-based pricing. For more information, see [Get It Now](#get-it-now).

+<sup>2</sup> Customers will see a **Get it now** button on the offer listing page in AppSource for offers configured for [ISV app license management](isv-app-license.md). Customers can select this button to contact you to purchase licenses for the app.

+> [!NOTE]

+> Customers will see a **Get it now** button on the offer listing page in AppSource for offers configured for [ISV app license management](isv-app-license.md). Customers can select this button to contact you to purchase licenses for the app.

+<sup>3</sup> Customers will see a **Get it now** button on the offer listing page in AppSource for offers configured for [ISV app license management](isv-app-license.md).

+| SaaS | Both online stores | Both online stores | Both online stores | | Both online stores <sup>1</sup>|

+| Microsoft 365 App | AppSource | AppSource | | | AppSource <sup>2</sup> |

+| Dynamics 365 apps on Dataverse and Power Apps | AppSource | AppSource | | | AppSource <sup>3</sup> |

+<sup>1</sup> SaaS transactable offers in AppSource only accept credit cards at this time.

+<sup>2</sup> Microsoft 365 add-ins are free to install and can be monetized using an SaaS offer. For more information, see [Monetize your app through the commercial marketplace](/office/dev/store/monetize-addins-through-microsoft-commercial-marketplace).

+<sup>3</sup> Applies to offers configured for [ISV app license management](isv-app-license.md).

+| Dynamics 365 apps on Dataverse and Power Apps | Get it now<sup>1</sup><br>Get it now (Free)<br>Free trial (listing)<br>Contact me |

+<sup>1</sup> Customers will see a **Get it now** button on the offer listing page in AppSource for offers configured for [ISV app license management](isv-app-license.md). Customers can select this button to contact you to purchase licenses for the app.

+| Get it now | Enables you to manage your ISV app licenses in Partner Center.<br>Currently available to the following offer type only:<ul><li>Dynamics 365 apps on Dataverse and Power Apps</li></ul><br>For more information about this option, see [ISV app license management](isv-app-license.md). |

+| Offers | ISVs can now offer custom prices, terms, conditions, and pricing for a specific customer through private offers. See [ISV to customer private offers](isv-customer.md) and the [FAQ](isv-customer-faq.yml). | 2022-04-06 |

+|

+**Domain credentials** | You can add **Domain credentials** by selecting the option from the drop-down in the **Add credentials** modal. <br/><br/> To provide domain credentials, you need to specify the **Domain name** which must be provided in the FQDN format (for example, prod.corp.contoso.com). <br/><br/> You also need to specify a friendly name for credentials, username, and password. It is recommended to provide the credentials in the UPN format, for example, user1@contoso.com. <br/><br/> The domain credentials added will be automatically validated for authenticity against the Active Directory of the domain. This is to prevent any account lockouts when the appliance attempts to map the domain credentials against discovered servers. <br/><br/>For the appliance to validate the domain credentials with the domain controller, it should be able to resolve the domain name. Ensure that you have provided the correct domain name while adding the credentials else the validation will fail.<br/><br/> The appliance will not attempt to map the domain credentials that have failed validation. You need to have at least one successfully validated domain credential or at least one non-domain credential to start the discovery.<br/><br/>The domain credentials mapped automatically against the Windows servers will be used to perform software inventory and can also be used to discover web apps, and SQL Server instances and databases _(if you have configured Windows authentication mode on your SQL Servers)_.<br/> [Learn more](/dotnet/framework/data/adonet/sql/authentication-in-sql-server) about the types of authentication modes supported on SQL Servers.

+* The cluster must have a minimum of three worker nodes and three manager nodes.

+* Don't scale the cluster workers to zero, or attempt a cluster shutdown. Deallocating or powering down any virtual machine in the cluster resource group is not supported.

+* Don't have taints that prevent OpenShift components to be scheduled.

+* Don't circumvent the deny assignment that is configured as part of the service, or perform administrative tasks that are normally prohibited by the deny assignment.

+> [!NOTE]

+> As currently Azure Relay doesn't support service tag, you have to use service tag AzureCloud or Internet in NSG rules for the communication to Azure Relay. For the communication to Azure Purview.

+1. Check your database server networking configuration to confirm that there is a private endpoint accessible to the SHIR machine. Add the IP of the machine if it doesn't already have access.

+1. You can scope your scan to specific database objects by choosing the appropriate items in the list.

+This is a suitable scenario, if both Azure Purview and Power BI tenant are configured to allow public access in the network settings.

+This scenario can be used when Azure Purview and Power BI tenant or both, are configured to use private endpoint and deny public access. Additionally, this option is also applicable if Azure Purview and Power BI tenant are configured to allow public access.

+Kusto Query Language is the language you will use to work with and manipulate data in Microsoft Sentinel. The logs you feed into your workspace aren't worth much if you can't analyze them and get the important information hidden in all that data. Kusto Query Language has not only the power and flexibility to get that information, but the simplicity to help you get started quickly. If you have a background in scripting or working with databases, a lot of the content of this article will feel very familiar. If not, don't worry, as the intuitive nature of the language quickly enables you to start writing your own queries and driving value for your organization.

+Kusto Query Language is also used in Azure Monitor (and therefore in Microsoft Sentinel), including some additional Azure Monitor features, which allow you to retrieve, visualize, analyze, and parse data in Log Analytics data stores. In Microsoft Sentinel, you're using tools based on Kusto Query Language whenever youΓÇÖre visualizing and analyzing data and hunting for threats, whether in existing rules and workbooks, or in building your own.

+Because Kusto Query Language is a part of nearly everything you do in Microsoft Sentinel, a clear understanding of how it works helps you get that much more out of your SIEM.

+ You might determine this information during your business use case review, or by evaluating a current SIEM that you already have in place. If you already have a SIEM in place, analyze your data to understand which data sources provide the most value and should be ingested into Microsoft Sentinel.

+ - Whether you'll use a single tenant or multiple tenants

+ - Any compliance requirements you have for data collection and storage

+ - How to control access to Microsoft Sentinel data

+ For more information, see [Workspace architecture best practices](best-practices-workspace-architecture.md) and [Sample workspace designs](sample-workspace-designs.md).

+ Make sure that your budget covers the cost of data ingestion for both Microsoft Sentinel and Azure Log Analytics, any playbooks that will be deployed, and so on.

+ For more information, see:

+ - [Microsoft Sentinel costs and billing](billing.md)

+ - [Microsoft Sentinel pricing](https://azure.microsoft.com/pricing/details/azure-sentinel/)

+ - [Log Analytics pricing](https://azure.microsoft.com/pricing/details/monitor/)

+ - [Logic apps (playbooks) pricing](https://azure.microsoft.com/pricing/details/logic-apps/)

+ - [Integrating Azure Data Explorer for long-term log retention](store-logs-in-azure-data-explorer.md)

+- After you have a subscription, you'll need the [relevant permissions](../role-based-access-control/index.yml) to begin using your subscription. If you are using a new subscription, an admin or higher from the Azure AD tenant should be designated as the [owner/contributor](../role-based-access-control/rbac-and-directory-admin-roles.md) for the subscription.

+ - To maintain the least privileged access available, assign roles at the level of the resource group.

+ - For more control over permissions and access, set up custom roles. For more information, see [Role-based access control](../role-based-access-control/custom-roles.md).

+ - For extra separation between users and security users, you might want to use [resource-context](resource-context-rbac.md) or [table-level RBAC](https://techcommunity.microsoft.com/t5/azure-sentinel/table-level-rbac-in-azure-sentinel/ba-p/965043).

+ For more information about other roles and permissions supported for Microsoft Sentinel, see [Permissions in Microsoft Sentinel](roles.md).

+- A [Log Analytics workspace](../azure-monitor/logs/quick-create-workspace.md) is required to house all of the data that Microsoft Sentinel will be ingesting and using for its detections, analytics, and other features. For more information, see [Microsoft Sentinel workspace architecture best practices](best-practices-workspace-architecture.md). Microsoft Sentinel doesn't support Log Analytics workspaces with a resource lock applied.

+We recommend that when you set up your Microsoft Sentinel workspace, [create a resource group](../azure-resource-manager/management/manage-resource-groups-portal.md) that's dedicated to Microsoft Sentinel and the resources that Microsoft Sentinel users including the Log Analytics workspace, any playbooks, workbooks, and so on.

+A dedicated resource group allows for permissions to be assigned once, at the resource group level, with permissions automatically applied to any relevant resources. Managing access via a resource group helps to ensure that you're using Microsoft Sentinel efficiently without potentially issuing improper permissions. Without a resource group for Microsoft Sentinel, where resources are scattered among multiple resource groups, a user or service principal may find themselves unable to perform a required action or view data due to insufficient permissions.

+To implement more access control to resources by tiers, use extra resource groups to house the resources that should be accessed only by those groups. Using multiple tiers of resource groups enables you to separate access between those tiers.

+## Next steps

+> >[On-board Microsoft Sentinel](quickstart-onboard.md)

+> >[Get visibility into alerts](get-visibility.md)

+> [!WARNING]

+> At this time, AAD client authentication and the Managed Identity Token Service are mutually incompatible on Linux.

+On Linux, you must complete the following steps before you create the cluster. On Windows, you also have the option to [configure Azure AD authentication for an existing cluster](https://github.com/Azure/Service-Fabric-Troubleshooting-Guides/blob/master/Security/Configure%20Azure%20Active%20Directory%20Authentication%20for%20Existing%20Cluster.md).

+ ./uninstall.sh -Y

+ Title: Enable ingress-to-app Transport Layer Security in Azure Spring Cloud

+description: How to enable ingress-to-app Transport Layer Security for an application.

+# Enable ingress-to-app TLS for an application

+**This article applies to:** ✔️ Standard tier ✔️ Enterprise tier

+> [!NOTE]

+> This feature is not available in Basic tier.

+This article describes secure communications in Azure Spring Cloud. The article also explains how to enable ingress-to-app SSL/TLS to secure traffic from an ingress controller to applications that support HTTPS.

+The following picture shows the overall secure communication support in Azure Spring Cloud.

+## Secure communication model within Azure Spring Cloud

+This section explains the secure communication model shown in the overview diagram above.

+1. The client request from the client to the application in Azure Spring Cloud comes into the ingress controller. The request can be either HTTP or HTTPS. The TLS certificate returned by the ingress controller is issued by the Microsoft Azure TLS issuing CA.

+

+ If the app has been mapped to an existing custom domain and is configured as HTTPS only, the request to the ingress controller can only be HTTPS. The TLS certificate returned by the ingress controller is the SSL binding certificate for that custom domain. The server side SSL/TLS verification for the custom domain is done in the ingress controller.

+2. The secure communication between the ingress controller and the applications in Azure Spring Cloud are controlled by the ingress-to-app TLS. You can also control the communication through the portal or CLI, which will be explained later in this article. If ingress-to-app TLS is disabled, the communication between the ingress controller and the apps in Azure Spring Cloud is HTTP. If ingress-to-app TLS is enabled, the communication will be HTTPS and has no relation to the communication between the clients and the ingress controller. The ingress controller won't verify the certificate returned from the apps because the ingress-to-app TLS encrypts the communication.

+3. Communication between the apps and the Azure Spring Cloud services is always HTTPS and handled by Azure Spring Cloud. Such services include config server, service registry, and Eureka server.

+4. You manage the communication between the applications. You can also take advantage of Azure Spring Cloud features to load certificates into the application's trust store. For more information, see [Use TLS/SSL certificates in an application](./how-to-use-tls-certificate.md).

+5. You manage the communication between applications and external services. To reduce your development effort, Azure Spring Cloud helps you manage your public certificates and loads them into your application's trust store. For more information, see [Use TLS/SSL certificates in an application](./how-to-use-tls-certificate.md).

+## Enable ingress-to-app TLS for an application

+The following section shows you how to enable ingress-to-app SSL/TLS to secure traffic from an ingress controller to applications that support HTTPS.

+### Prerequisites

+- A deployed Azure Spring Cloud instance. Follow our [quickstart on deploying via the Azure CLI](./quickstart.md) to get started.

+- If you're unfamiliar with ingress-to-app TLS, see the [end-to-end TLS sample](https://github.com/Azure-Samples/spring-boot-secure-communications-using-end-to-end-tls-ssl).

+- To securely load the required certificates into Spring Boot apps, you can use [keyvault spring boot starter](https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/spring/azure-spring-boot-starter-keyvault-certificates).

+### Enable ingress-to-app TLS on an existing app

+Use the command `az spring-cloud app update --enable-ingress-to-app-tls` to enable or disable ingress-to-app TLS for an app.

+```azurecli

+az spring-cloud app update --enable-ingress-to-app-tls -n app_name -s service_name -g resource_group_name

+az spring-cloud app update --enable-ingress-to-app-tls false -n app_name -s service_name -g resource_group_name

+```

+### Enable ingress-to-app TLS when you bind a custom domain

+Use the command `az spring-cloud app custom-domain update --enable-ingress-to-app-tls` or `az spring-cloud app custom-domain bind --enable-ingress-to-app-tls` to enable or disable ingress-to-app TLS for an app.

+```azurecli

+az spring-cloud app custom-domain update --enable-ingress-to-app-tls -n app_name -s service_name -g resource_group_name

+az spring-cloud app custom-domain bind --enable-ingress-to-app-tls -n app_name -s service_name -g resource_group_name

+```

+### Enable ingress-to-app TLS using the Azure portal

+To enable ingress-to-app TLS in the [Azure portal](https://portal.azure.com/), first create an app, and then enable the feature.

+1. Create an app in the portal as you normally would. Navigate to it in the portal.

+2. Scroll down to the **Settings** group in the left navigation pane.

+3. Select **Ingress-to-app TLS**.

+4. Switch **Ingress-to-app TLS** to *Yes*.

+

+### Verify ingress-to-app TLS status

+Use the command `az spring-cloud app show` to check the value of `enableEndToEndTls`.

+```azurecli

+az spring-cloud app show -n app_name -s service_name -g resource_group_name

+```

+## Next steps

+* [Access Config Server and Service Registry](how-to-access-data-plane-azure-ad-rbac.md)

+* [Enable ingress-to-app Transport Layer Security](./how-to-enable-ingress-to-app-tls.md)

+ Title: Create branch preview environments in Azure Static Web Apps

+description: Expose stable URLs for specific branches to evaluate changes in Azure Static Web Apps

+# Create branch preview environments in Azure Static Web Apps

+You can configure your site to deploy every change made to branches that aren't a production branch. This preview deployment is published at a stable URL that includes the branch name. For example, if the branch is named `dev`, then the environment is available at a location like `<DEFAULT_HOST_NAME>-dev.<LOCATION>.azurestaticapps.net`.

+## Configuration

+To enable stable URL environments, make the following changes to your [configuration file](configuration.md).

+- Set the `production_branch` input on the `static-web-apps-deploy` GitHub action to your production branch name. This ensures changes to your production branch are deployed to the production environment, while changes to other branches are deployed to a preview environment.

+- List the branches you want to deploy to preview environments in the `on > push > branches` array in your workflow configuration so that changes to those branches also trigger the GitHub Actions deployment.

+ - Set this array to `**` if you want to track all branches.

+## Example

+The following example demonstrates how to enable branch preview environments.

+```yml

+name: Azure Static Web Apps CI/CD

+on:

+ push:

+ branches:

+ - main

+ - dev

+ - staging

+ pull_request:

+ types: [opened, synchronize, reopened, closed]

+ branches:

+ - main

+jobs:

+ build_and_deploy_job:

+ ...

+ name: Build and Deploy Job

+ steps:

+ - uses: actions/checkout@v2

+ with:

+ submodules: true

+ - name: Build And Deploy

+ id: builddeploy

+ uses: Azure/static-web-apps-deploy@v1

+ with:

+ ...

+ production_branch: "main"

+```

+> [!NOTE]

+> The `...` denotes code skipped for clarity.

+In this example, the preview environments are defined for the `dev` and `staging` branches. Each branch is deployed to a separate preview environment.

+## Next Steps

+> [!div class="nextstepaction"]

+> [Review pull requests in pre-production environments](./review-publish-pull-requests.md)

+ Title: Preview environments in Azure Static Web Apps

+description: Expose preview environments to evaluate changes in Azure Static Web Apps

+# Preview environments in Azure Static Web Apps

+By default, when you deploy a site to Azure Static Web Apps [each pull request deploys a preview version of your site available through a temporary URL](review-publish-pull-requests.md). This version of the site allows you to review changes before merging pull requests. Once the pull request (PR) is closed, the temporary environment disappears.

+Beyond PR-driven temporary environments, you can enable preview environments that feature stable locations. The URLs for preview environments take on the following form:

+ ```text

+ <DEFAULT_HOST_NAME>-<BRANCH_OR_ENVIRONMENT_NAME>.<LOCATION>.azurestaticapps.net

+ ```

+## Deployment types

+The following deployment types are available in Azure Static Web Apps.

+- **Production**: Changes to production branches are deployed into the production environment. Your custom domain points to this environment, and content served from this location is indexed by search engines.

+- [**Pull requests**](review-publish-pull-requests.md): Pull requests against your production branch deploy to a temporary environment that disappears after the pull request is closed. The URL for this environment includes the PR number as a suffix. For example, if you make your first PR, the preview location looks something like `<DEFAULT_HOST_NAME>-1.<LOCATION>.azurestaticapps.net`.

+- [**Branch**](branch-environments.md): You can optionally configure your site to deploy every change made to branches that aren't a production branch. This preview deployment lives for the entire lifetime of the branch and is published at a stable URL that includes the branch name. For example, if the branch is named `dev`, then the environment is available at a location like `<DEFAULT_HOST_NAME>-dev.<LOCATION>.azurestaticapps.net`.

+## Next Steps

+> [!div class="nextstepaction"]

+> [Review pull requests in pre-production environments](./review-publish-pull-requests.md)

+1. Select **Create** to start the creation of the App Service Static Web App and provision a GitHub Actions for deployment.

+1. On the resource screen, click the _URL_ link to open your deployed application. You may need to wait a minute or two for the GitHub Actions to complete.

+> [Branch preview environments](branch-environments.md)

+| v1.23.1 | April 12, 2022 | April 12, 2023 |

+| v1.23.0 | March 2, 2022 | March 2, 2023 |

+description: Recommendations and examples for creating and updating query-optimization statistics in Azure Synapse SQL.

+SQL pool doesn't have a system stored procedure equivalent to `sp_create_stats` in SQL Server. This stored procedure creates a single column statistics object on every column of the database that doesn't already have statistics.

+Serverless SQL pool lets you create statistics manually. For CSV files, you have to create statistics manually because automatic creation of statistics isn't turned on for CSV files.

+### Examples: Create statistics for column in OPENROWSET path

+The following examples show you how to use various options for creating statistics in Azure Synapse serverless SQL pools. The options that you use for each column depend on the characteristics of your data and how the column will be used in queries. For more information on the stored procedures used in these examples, review [sys.sp_create_openrowset_statistics](/sql/relational-databases/system-stored-procedures/sp-create-openrowset-statistics) and [sys.sp_drop_openrowset_statistics](/sql/relational-databases/system-stored-procedures/sp-drop-openrowset-statistics), which apply to serverless SQL pools only.

+> Following permissions are required to execute `sp_create_openrowset_statistics` and `sp_drop_openrowset_statistics`: ADMINISTER BULK OPERATIONS or ADMINISTER DATABASE BULK OPERATIONS.

+To update statistics, you need to drop and create statistics. For more information, review [sys.sp_create_openrowset_statistics](/sql/relational-databases/system-stored-procedures/sp-create-openrowset-statistics) and [sys.sp_drop_openrowset_statistics](/sql/relational-databases/system-stored-procedures/sp-drop-openrowset-statistics).

+The `sys.sp_drop_openrowset_statistics` stored procedure is used to drop statistics:

+> Following permissions are required to execute `sp_create_openrowset_statistics` and `sp_drop_openrowset_statistics`: ADMINISTER BULK OPERATIONS or ADMINISTER DATABASE BULK OPERATIONS.

+To update the statistics for the year column in the dataset, which is based on the `population.csv` file, you need to drop and create statistics:

+To further improve query performance for serverless SQL pool, see [Best practices for serverless SQL pool](best-practices-serverless-sql-pool.md).

+The Azure Virtual Desktop service updates the agent whenever an update becomes available. Agent updates can include new functionality or fixes for previous issues. You must always have the latest stable version of the agent installed so your VMs don't lose connectivity or security. After you've installed the initial version of the Azure Virtual Desktop agent, the agent will regularly query the Azure Virtual Desktop service to determine if thereΓÇÖs a newer version of the agent, stack, or monitoring agent available. If a newer version exists, the updated component is automatically installed by the flighting system, unless you've configured the Scheduled Agent Updates feature. If you've already configured the Scheduled Agent Updates feature, the agent will only install the updated components during the maintenance window that you specify. For more information, see [Scheduled Agent Updates (preview)](scheduled-agent-updates.md).

+- Because VMs in your host pool may receive agent updates at different times, you'll need to be able to tell the difference between flighting issues and failed agent updates. If you go to the event logs for your VM at **Event Viewer** > **Windows Logs** > **Application** and see an event labeled "ID 3277," that means the Agent update didn't work. If you don't see that event, then the VM is in a different flight and will be updated later. See [Set up diagnostics to monitor agent updates](agent-updates-diagnostics.md) for more information about how to set up diagnostic logs to track updates and make sure they've been installed correctly.

+- To schedule agent updates, see the [Scheduled Agent Updates (preview) document](scheduled-agent-updates.md).

+- To set up diagnostics for this feature, see the [Scheduled Agent Updates Diagnostics guide](agent-updates-diagnostics.md).

+- To find information about the latest and previous agent versions, see the [Agent Updates version notes](whats-new-agent.md).

+ Title: Set up diagnostics for monitoring agent updates

+description: How to set up diagnostic reports to monitor agent updates.

+# Set up diagnostics to monitor agent updates

+Diagnostic logs can tell you which agent version is installed for an update, when it was installed, and if the update was successful. If an update is unsuccessful, it might be because the session host was turned off during the update. If that happened, you should turn the session host back on.

+This article describes how to use diagnostic logs in a Log Analytics workspace to monitor agent updates.

+## Enable sending diagnostic logs to your Log Analytics workspace

+To enable sending diagnostic logs to your Log Analytics workspace:

+1. Create a Log Analytics workspace, if you haven't already. Next, get the workspace ID and primary key by following the instructions in [Use Log Analytics for the diagnostics feature](diagnostics-log-analytics.md#before-you-get-started).

+2. Send diagnostics to the Log Analytics workspace you created by following the instructions in [Push diagnostics data to your workspace](diagnostics-log-analytics.md#push-diagnostics-data-to-your-workspace).

+3. Follow the directions in [How to access Log Analytics](diagnostics-log-analytics.md#how-to-access-log-analytics) to access the logs in your workspace.

+> [!NOTE]

+> The log query results only cover the last 30 days of data in your deployment.

+## Use diagnostics to see when an update becomes available

+To see when agent component updates are available:

+1. Access the logs in your Log Analytics workspace.

+2. Select the **+** button to create a new query.

+3. Copy and paste the following Kusto query to see if agent component updates are available for the specified session host. Make sure to change the **sessionHostName** parameter to the name of your session host.

+> [!NOTE]

+> If you haven't enabled the Scheduled Agent Updates feature, you won't see anything in the NewPackagesAvailable field.

+```kusto

+WVDAgentHealthStatus

+| where TimeGenerated >= ago(30d)

+| where SessionHostName == "sessionHostName"

+| project TimeGenerated, AgentVersion, SessionHostName, LastUpgradeTimeStamp, UpgradeState, UpgradeErrorMsg, NewPackagesAvailable

+| sort by TimeGenerated desc

+| take 1

+```

+## Use diagnostics to see when agent updates are happening

+To see when agent updates are happening or to make sure that the Scheduled Agent Updates feature is working:

+1. Access the logs in your Log Analytics workspace.

+2. Select the **+** button to create a new query.

+3. Copy and paste the following Kusto query to see when the agent has updated for the specified session host. Make sure to change the **sessionHostName** parameter to the name of your session host.

+```kusto

+WVDAgentHealthStatus

+| where TimeGenerated >= ago(30d)

+| where SessionHostName == "sessionHostName"

+| project TimeGenerated, AgentVersion, SessionHostName, LastUpgradeTimeStamp, UpgradeState, UpgradeErrorMsg

+| summarize arg_min(TimeGenerated, *) by AgentVersion

+| sort by TimeGenerated asc

+```

+## Use diagnostics to check for unsuccessful agent updates

+To check if an agent component update was unsuccessful:

+1. Access the logs in your Log Analytics workspace.

+2. Select the **+** button to create a new query.

+3. Copy and paste the following Kusto query to see when the agent has updated for the specified session host. Make sure to change the **sessionHostName** parameter to the name of your session host.

+```kusto

+WVDAgentHealthStatus

+| where TimeGenerated >= ago(30d)

+| where SessionHostName == "sessionHostName"

+| where MaintenanceWindowMissed == true

+| project TimeGenerated, AgentVersion, SessionHostName, LastUpgradeTimeStamp, UpgradeState, UpgradeErrorMsg, MaintenanceWindowMissed

+| sort by TimeGenerated asc

+```

+## Next steps

+For more information about Scheduled Agent Updates and the agent components, check out the following articles:

+- To learn how to schedule agent updates, see [Scheduled Agent Updates (preview)](scheduled-agent-updates.md).

+- For more information about the Azure Virtual Desktop agent, side-by-side stack, and Geneva Monitoring agent, see [Getting Started with the Azure Virtual Desktop Agent](agent-overview.md).

+- Learn more about the latest and previous agent versions at [What's new in the Azure Virtual Desktop agent](whats-new-agent.md).

+- If you're experiencing agent or connectivity-related issues, see the [Azure Virtual Desktop Agent issues troubleshooting guide](troubleshoot-agent.md).

+>Azure Virtual Desktop stores various types of information like host pool names, app group names, workspace names, and user principal names in a datacenter. While creating any of the service objects, the customer has to enter the location where the object needs to be created. The location of this object determines where the information for the object will be stored. The customer will choose an Azure region and the related information will be stored in the associated geography. Customers also choose a region for the Session host Virtual Machines in an additional step in the deployment process. This region can be any Azure region, hence it can be the same region as the service objects or a separate region. For a list of all Azure regions and related geographies, visit [https://azure.microsoft.com/global-infrastructure/geographies/](https://azure.microsoft.com/global-infrastructure/geographies/).

+The service doesn't directly store any user created or app-related information, but it does store customer data like application names and user principal names because they're part of the object setup process. This information is stored in the geography associated with the region the customer created the object in.

+To keep Azure Virtual Desktop reliable and scalable, we aggregate traffic patterns and usage to check the health and performance of the infrastructure control plane. For example, to understand how to ramp up regional infrastructure capacity as service usage increases, we process service usage log data. We then review the logs for peak times and decide which data centers to add to meet this capacity.

+- United States (US)

+- Europe (EU)

+- United Kingdom (UK)

+- Canada (CA)

+In addition we aggregate service-generated from all locations where the service infrastructure is, then send it to the US geography. The data sent to the US region includes scrubbed data, but not customer data.

+ Title: Azure Virtual Desktop Scheduled Agent Updates preview

+description: How to use the Scheduled Agent Updates feature to choose a date and time to update your Azure Virtual Desktop agent components.

+# Scheduled Agent Updates (preview) for Azure Virtual Desktop host pools

+> [!IMPORTANT]

+> The Scheduled Agent Updates feature is currently in preview.

+> See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

+The Scheduled Agent Updates feature (preview) lets you create up to two maintenance windows for the Azure Virtual Desktop agent, side-by-side stack, and Geneva Monitoring agent to get updated so that updates don't happen during peak business hours. To monitor agent updates, you can use Log Analytics to see when agent component updates are available and when updates are unsuccessful.

+This article describes how the Scheduled Agent Updates feature works and how to set it up.

+>[!NOTE]

+> Azure Virtual Desktop (classic) doesn't support the Scheduled Agent Updates feature.

+>[!IMPORTANT]

+>The preview version of this feature currently has the following limitations:

+>

+> - You can only use the Scheduled Agent Updates feature in the Azure public cloud.

+> - You can only configure the Scheduled Agent Updates feature with the Azure portal or REST API.

+## Configure the Scheduled Agent Updates feature using the Azure portal

+To use the Azure portal to configure Scheduled Agent Updates:

+1. Open your browser and go to [the Azure portal](https://portal.azure.com).

+2. In the Azure portal, go to **Azure Virtual Desktop**.

+3. Select **Host pools**, then go to the host pool where you want to enable the feature. You can only configure this feature for existing host pools. You can't enable this feature when you create a new host pool.

+4. In the host pool, select **Scheduled Agent Updates**. Scheduled Agent Updates is disabled by default. This means that, unless you enable this setting, the agent can get updated at any time by the agent update flighting service. Select the **Scheduled agent updates** checkbox to enable the feature.

+ > [!div class="mx-imgBorder"]

+ > 

+5. Enter your preferred time zone setting. If you select **Use local session host time zone**, Scheduled Agent Updates will automatically use the VM's local time zone. If you don't select **Use local session host time zone**, you'll need to specify a time zone.

+6. Select a day and time for the **Maintenance window**. If you'd like to make an optional second maintenance window, you can also select a date and time for it here. Since Scheduled Agent Updates is a host pool setting, the time zone setting and maintenance windows you configure will be applied to all session hosts in the host pool.

+7. Select **Apply** to apply your settings.

+ > [!div class="mx-imgBorder"]

+ > 

+## Additional information

+### How the feature works

+The Scheduled Agent Updates feature updates the Azure Virtual Desktop agent, side-by-side stack, and Geneva Monitoring agent if any one or more of these components needs to be updated. Any reference to the agent components is referring to these three components. Scheduled Agent Updates doesn't apply to the initial installation of the agent components. When you install the agent on a virtual machine (VM), the agent will automatically install the side-by-side stack and the Geneva Monitoring agent regardless of which maintenance windows you set. Any non-critical updates after installation will only happen within your maintenance windows. Host pools with the Scheduled Agent Updates feature enabled will receive the agent update after the agent has been fully flighted to production. For more information about how agent flighting works, see [Agent update process](agent-overview.md#agent-update-process).

+The agent component update won't succeed if the session host VM is shut down or deallocated during the scheduled update time. If you enable Scheduled Agent Updates, make sure all session hosts in your host pool are on during your configured maintenance window time. The broker will attempt to update the agent components during each specified maintenance window up to four times. After the fourth try, the broker will install the update by force. This process gives time for installation retries if an update is unsuccessful, and also prevents session hosts from having outdated versions of agent components. If a critical agent component update is available, the broker will install the agent component by force for security purposes.

+### Maintenance window and time zone information

+- You must specify at least one maintenance window. Configuring the second maintenance window is optional. Creating two maintenance windows gives the agent components additional opportunities to update if the first update during one of the windows is unsuccessful.

+- All maintenance windows are two hours long to account for situations where all three agent components must be updated at the same time. For example, if your maintenance window is Saturday at 9:00 AM PST, the updates will happen between 9:00 AM PST and 11:00 AM PST.

+- The **Use session host local time** parameter isn't selected by default. If you want the agent component update to be in the same time zone for all session hosts in your host pool, you'll need to specify a single time zone for your maintenance windows. Having a single time zone helps when all your session hosts or users are located in the same time zone.

+- If you select **Use session host local time**, the agent component update will be in the local time zone of each session host in the host pool. Use this setting when all session hosts in your host pool or their assigned users are in different time zones. For example, let's say you have one host pool with session hosts in West US in the Pacific Standard Time zone and session hosts in East US in the Eastern Standard Time zone, and you've set the maintenance window to be Saturday at 9:00 PM. Enabling **Use session host local time** ensures that updates to all session hosts in the host pool will happen at 9:00 PM in their respective time zones. Disabling **Use session host local time** and setting the time zone to be Central Standard Time ensures that updates to the session hosts in the host pool will happen at 9:00 PM Central Standard Time, regardless of the session hosts' local time zones.

+- The local time zone for VMs you create using the Azure portal is set to Coordinated Universal Time (UTC) by default. If you want to change the VM time zone, run the [Set-TimeZone PowerShell cmdlet](/powershell/module/microsoft.powershell.management/set-timezone?view=powershell-7.1&preserve-view=true) on the VM.

+- To get a list of available time zones for a VM, run the [Get-TimeZone PowerShell cmdlet]/powershell/module/microsoft.powershell.management/get-timezone?view=powershell-7.1&preserve-view=true) on the VM.

+## Next steps

+For more information related to Scheduled Agent Updates and agent components, check out the following resources:

+- Learn how to set up diagnostics for this feature at the [Scheduled Agent Updates Diagnostics guide](agent-updates-diagnostics.md).

+- Learn more about the Azure Virtual Desktop agent, side-by-side stack, and Geneva Monitoring agent at [Getting Started with the Azure Virtual Desktop Agent](agent-overview.md).

+- For more information about the current and earlier versions of the Azure Virtual Desktop agent, see [Azure Virtual Desktop agent updates](whats-new-agent.md).

+- If you're experiencing agent or connectivity-related issues, see the [Azure Virtual Desktop Agent issues troubleshooting guide](troubleshoot-agent.md).

+ Title: Azure Virtual Desktop RDP Shortpath for public networks (preview) - Azure

+description: How to set up RDP Shortpath for public networks for Azure Virtual Desktop (preview).

+# Azure Virtual Desktop RDP Shortpath for public networks (preview)

+Remote Desktop Protocol (RDP) can use multiple different types of network transport to establish a connection between Remote Desktop Client and Session host.

+- Reverse connect - by default, RDP uses a TCP-based [reverse connect transport](./network-connectivity.md). This transport provides the best compatibility with various networking configurations and has a high success rate for establishing RDP connections. This transport is also used as a fallback if the RDP Shortpath connection is unsuccessful.

+- RDP Shortpath for managed networks - UDP-based transport designed for direct connectivity in controlled network setups. For example, connectivity over the ExpressRoute or Azure Stack HCI deployments. For more information, see the [documentation](./shortpath.md).

+- RDP Shortpath for public networks, currently in preview, is described in this document.

+ > [!NOTE]

+ > During the preview, RDP Shortpath for managed networks is incompatible with RDP Shortpath for public networks. If you want to participate in the preview, refer to the [documentation](./shortpath.md) for disabling RDP Shortpath for managed networks.

+RDP Shortpath transport is a feature of Azure Virtual Desktop that establishes a direct UDP data flow between Remote Desktop Client and Session host. RDP uses this data flow to deliver Remote Desktop and RemoteApp while offering better reliability and consistent latency.

+## Key benefits

+Both RDP Shortpath for managed and public networks provide the same set of core benefits:

+- RDP Shortpath transport is based on the [Universal Rate Control Protocol (URCP)](https://www.microsoft.com/research/publication/urcp-universal-rate-control-protocol-for-real-time-communication-applications/). URCP enhances UDP with active monitoring of the network conditions and provides fair and full link utilization. URCP operates at low delay and loss levels as needed by Remote Desktop. URCP achieves the best performance by dynamically learning network parameters and providing protocol with a rate control mechanism.

+- RDP Shortpath establishes the direct connectivity between the Remote Desktop client and the session host. Direct connectivity reduces dependency on the Azure Virtual Desktop gateways, improves the connection's reliability, and increases available bandwidth for each user session.

+- The removal of extra relay reduces round-trip time, which improves user experience with latency-sensitive applications and input methods.

+## Connection security

+RDP Shortpath for public networks extends RDP multi-transport capabilities. It doesn't replace the reverse connect transport but complements it. The initial session brokering is managed through the Azure Virtual Desktop infrastructure.

+Each RDP session uses a dynamically assigned UDP socket that accepts the Shortpath traffic previously authenticated over a reverse connect transport. This socket will ignore all connection attempts unless they match the reverse connect session. Before the UDP socket is open, any new RDP session must establish the unique reverse connect transport.

+RDP Shortpath uses a TLS connection between the client and the session host using the session host's certificates. By default, the certificate used for RDP encryption is self-generated by the OS during the deployment. If desired, customers may deploy centrally managed certificates issued by the enterprise certification authority. For more information about certificate configurations, see [Windows Server documentation](/troubleshoot/windows-server/remote/remote-desktop-listener-certificate-configurations).

+## Network Address Translation and firewalls

+Most Azure Virtual Desktop clients run on computers on the private network. Internet access is provided through a Network Address Translation (NAT) gateway device. Therefore, the NAT gateway modifies all network requests from the private network and destined to the Internet. Such modification intends to share a single public IP address across all of the computers on the private network.

+Because of IP packet modification, the recipient of the traffic will see the public IP address of the NAT gateway instead of the actual sender. When traffic comes back to the NAT gateway, it will take care to forward it to the intended recipient without the sender's knowledge. In most scenarios, the computers hidden behind such a NAT aren't aware translation is happening and don't know the network address of the NAT gateway.

+NAT is also applicable to the Azure Virtual Networks, where all session hosts reside. When a session host tries to reach the network address on the Internet, the NAT Gateway or Azure Load Balancer performs the address translation. For more information about various types of Source Network Address Translation, see the [documentation](/azure/load-balancer/load-balancer-outbound-connections.md).

+Most networks typically include firewalls that inspect traffic and block it based on rules. Most customers configure their firewalls to prevent incoming connections (that is, unsolicited packets from the Internet sent without a request). Firewalls employ different techniques to track data flow to distinguish between solicited and unsolicited traffic. In the context of TCP, the firewall tracks SYN and ACK packets, and the process is straightforward. UDP firewalls usually use heuristics based on packet addresses to associate traffic with UDP flows and allow or block it.

+There are many different NAT implementations available. In most cases, NAT gateway and firewall are the functions of the same physical or virtual device.

+## How RDP Shortpath works for public networks

+RDP Shortpath uses a standardized set of methods for traversal of NAT gateways. As a result, user sessions directly establish a UDP flow between the client and the session host. More specifically, RDP Shortpath uses STUN protocol to discover the external IP address of the NAT router.

+There are four primary components used to establish the RDP Shortpath data flow:

+- Remote Desktop Client

+- Session Host

+- Azure Virtual Desktop Gateway

+- Azure Virtual Desktop STUN Server

+In Azure Virtual Desktop, every RDP connection starts with establishing the [reverse connect transport](./network-connectivity.md) over the Azure Virtual Desktop Gateway.

+After the user authentication, the client and session host establish the initial RDP transport, and the client and session host start exchanging their capabilities.

+If RDP Shortpath for public networks is enabled on the session host, then the session host initiates a process called Candidate Gathering.

+- At this stage, the session host enumerates all network interfaces assigned to a VM, including virtual interfaces like VPN and Teredo.

+- Remote Desktop Service allocates UDP socket on each interface and stores the IP:Port pair in the candidate table as a *local candidate*.

+- Remote Desktop Service uses each UDP socket allocated in the previous step to try reaching the Azure Virtual Desktop STUN Server on the public Internet. Communication is done by sending a small UDP packet to port 3478

+- If the packet reaches the STUN server, the STUN server responds with the session host public IP and listener port. This information is stored in the candidate table as a *reflexive candidate*.

+After the session host gathers all candidates, the session host uses the established reverse connect transport to pass the candidate list to the client.

+When the client receives the list of candidates from the server, the client performs the candidate gathering on its side. Then the client sends its candidate list to the session host.

+After the session host and client exchange their candidate lists, both parties attempt to connect with each other using all the gathered candidates. This connection attempt is simultaneous on both sides.

+Many of the NAT gateways are configured to allow the incoming traffic to the socket as soon as the outbound data transfer initializes it. This behavior of NAT gateways is the reason the simultaneous connection is essential.

+After the initial packet exchange, the client and session host may establish one or many data flows. After that, Remote Desktop Protocol chooses the fastest network path. Client then establishes a secure TLS connection with the session host and initiates the RDP Shortpath transport.

+After RDP establishes the Shortpath, all Dynamic Virtual Channels (DVCs), including remote graphics, input, and device redirection move to the new transport.

+## Enabling the preview of RDP Shortpath for public networks

+To participate in the preview of RDP Shortpath, you need to enable the Shortpath functionality. You can configure RDP Shortpath on any number of session hosts used in your environment. There's no requirement to enable RDP Shortpath on all hosts in the pool.

+We recommend you use a validation host pool by following the steps in [Define your host pool as a validation host pool](create-validation-host-pool.md#define-your-host-pool-as-a-validation-host-pool).

+Follow the steps below to configure session host:

+1. Connect to the session host

+2. Open the elevated command prompt

+3. Enable the RDP Shortpath for public networks:

+```cmd

+REG ADD "HKLM\SYSTEM\CurrentControlSet\Control\Terminal Server\WinStations" /v ICEControl /t REG_DWORD /d 2 /f

+```

+## Disabling the preview of RDP Shortpath for public networks

+If you decide to disable the preview of RDP Shortpath, you can disable the Shortpath functionality.

+Follow the steps below to configure session host:

+1. Connect to the session host

+2. Open elevated command prompt

+3. Disable the RDP Shortpath for public networks:

+```cmd

+REG DELETE "HKLM\SYSTEM\CurrentControlSet\Control\Terminal Server\WinStations" /v ICEControl /f

+```

+## Network configuration

+To support RDP Shortpath for public networks, you typically don't need any particular configuration. Azure Virtual Desktop client and Session host will automatically discover the direct data flow if it's possible in your network configuration. However, every environment is unique, and some network configurations may negatively affect the rate of success of the direct connection.

+Follow the recommendations below to increase the probability of a direct data flow.

+### Allow outbound UDP connectivity

+RDP Shortpath uses UDP to establish a data flow. If a firewall on your network blocks UDP traffic, RDP Shortpath will fail, and the connection will fall back to TCP-based reverse connect transport.

+Azure Virtual Desktop uses STUN servers provided by [Azure Communication Services](/communication-services) and Microsoft Teams.

+By the nature of the feature, outbound connectivity from the session hosts to the client is required. Unfortunately, you can't predict where your users are located in most cases. Therefore, we recommend allowing outbound UDP connectivity to the Internet.

+You can [limit the port range](#limiting-port-range-used-on-the-client-side) used to listen to the incoming UDP flow.

+Use the following table for reference when configuring firewalls for RDP Shortpath.

+#### Session host virtual network

+| Name | Source | Destination Port | Protocol | Destination | Action |

+|-|--||-||--|

+| RDP Shortpath Server Endpoint | VM Subnet | 1024-65535 | UDP | * | Allow |

+| STUN Access | VM Subnet | 3478 | UDP | 13.107.17.41/24, 13.107.64.0/18, 20.202.0.0/16, 52.112.0.0/14, 52.120.0.0/14 | Allow |

+#### Client network

+| Name | Source | Destination Port | Protocol | Destination | Action |

+|-|-||-||--|

+| RDP Shortpath Server Endpoint | Client network | 1024-65535 | UDP | Public IP addresses assigned to NAT Gateway or Azure Firewall | Allow |

+| STUN Access | Client network | 3478 | UDP | 13.107.17.41/24, 13.107.64.0/18, 20.202.0.0/16, 52.112.0.0/14, 52.120.0.0/14 | Allow |

+ > [!NOTE]

+ > The IP ranges for STUN servers used in preview would change at the feature's release to General Availability.

+### Limiting port range used on the client side

+By default, RDP Shortpath for public networks uses an ephemeral port range (49152ΓÇô65535) to establish a direct path between server and client. However, you may want to configure the server to use a smaller, predictable port range in some cases.

+To enable a limited port range, you can use the following command on the session host:

+```cmd

+REG ADD HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services /v ICEEnableClientPortRange /t REG_DWORD /d 1 /f

+```

+When you enable this setting on the session host, the Azure Virtual Desktop client will randomly select the port from the range for every connection. If the specified port range is exhausted, the client's operating system will choose a port to use.

+By default, when the port range configuration is enabled, the client will choose a port from the range of 38300-39299.

+If you want to change the port numbers, you can customize a UDP port range for the Azure Virtual Desktop client.

+When choosing the base and pool size, consider the number of ports setting to ensure that the upper bound doesn't exceed 49151. For example, if you select 38300 as a port base and 1000 as pool size, the upper bound will be 39299.

+To specify the port range, use the following commands, substituting the base port and the number of ports.

+```cmd

+reg add HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services /v ICEClientPortBase /t REG_DWORD /d 38300 /f

+reg add HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services /v ICEClientPortRange /t REG_DWORD /d 1000 /f

+```

+### Disabling RDP Shortpath on the client

+To disable RDP Shortpath for a specific client, you can use the following Group Policy to disable the UDP support:

+1. On the client, run **gpedit.msc**.

+2. Go to **Computer Configuration** > **Administration Templates** > **Windows Components** > **Remote Desktop Services** > **Remote Desktop Connection Client**.

+3. Set the **"Turn Off UDP On Client"** setting to **Enabled**

+### Teredo support

+While not required for RDP Shortpath, Teredo adds extra NAT traversal candidates and increases the chance of the successful RDP Shortpath connection in IPv4-only networks.

+You can enable Teredo on both Session host and Client side by running the following command:

+```cmd

+netsh interface Teredo set state type=enterpriseclient

+```

+### UPnP support

+To improve the chances of a direct connection, on the side of the Remote Desktop client, RDP Shortpath may use [UPnP](/windows/win32/upnp/universal-plug-and-play-start-page.md) to configure a port mapping on the NAT router. UPnP is a standard technology used by various applications, such as Xbox, Delivery Optimization, and Teredo. UPnP is generally available on the routers typically found on a home network. UPnP protocol is enabled by default on most home routers and access points. UPnP is often disabled on corporate networking.

+## General recommendations

+- Avoid using force tunneling configurations if your users access Azure Virtual desktop over the Internet.

+- Make sure you aren't using double NAT or Carrier-Grade-NAT (CGN) configurations.

+- Recommend users to not disable UPnP on their home routers.

+- Avoid using cloud packet-inspection Services

+- Avoid using TCP-based VPN solutions

+- Enable IPv6 connectivity or Teredo

+## Verify your network connectivity

+Next, you'll need to make sure your network is using RDP Shortpath. You can verify the transport with either a "Connection Information" dialog or by using Log Analytics.

+### Connection Information dialog

+To make sure connections are using RDP Shortpath, open the "Connection Information" dialog by going to the **Connection** tool bar on the top of the screen and select the antenna icon, as shown in the following screenshot.

+### Use Log Analytics

+If you're using [Azure Log Analytics](./diagnostics-log-analytics.md), you can monitor connections by querying the [WVDConnections table](/azure/azure-monitor/reference/tables/wvdconnections). A column named UdpUse indicates whether Azure Virtual Desktop RDP Stack is using UDP protocol on the current user connection.

+The possible values are:

+- **0** - user connection isn't using RDP Shortpath.

+- **1** - The user connection is using RDP Shortpath for managed networks.

+- **2** - The user connection is using RDP Shortpath for public networks.

+

+The following query lets you review connection information. You can run this query in the [Log Analytics query editor](../azure-monitor/logs/log-analytics-tutorial.md#write-a-query). For each query, replace `userupn` with the UPN of the user you want to look up.

+```kusto

+let Events = WVDConnections | where UserName == "userupn" ;

+Events

+| where State == "Connected"

+| project CorrelationId , UserName, ResourceAlias , StartTime=TimeGenerated, UdpUse, SessionHostName, SessionHostSxSStackVersion

+| join (Events

+| where State == "Completed"

+| project EndTime=TimeGenerated, CorrelationId, UdpUse)

+on CorrelationId

+| project StartTime, Duration = EndTime - StartTime, ResourceAlias, UdpUse, SessionHostName, SessionHostSxSStackVersion

+| sort by StartTime asc

+```

+You can verify if RDP Shortpath is enabled for a specific user session by running the following Log Analytics query:

+```kusto

+WVDCheckpoints

+|where Name contains "Shortpath"

+```

+## Troubleshooting

+### Verifying STUN server connectivity and NAT type

+If you're unable to establish connection using the RDP Shortpath transport, you use the following PowerShell script to validate connectivity to STUN servers

+```powershell

+function Test-StunEndpoint

+{

+ param

+ (

+ [Parameter(Mandatory)]

+ $UdpClient,

+ [Parameter(Mandatory)]

+ $StunEndpoint

+ )

+ $ipendpoint = $null

+ try

+ {

+ $UdpClient.client.ReceiveTimeout = 5000

+ $listenport = $UdpClient.client.localendpoint.port

+ $endpoint = New-Object -TypeName System.Net.IPEndPoint -ArgumentList ([IPAddress]::Any, $listenport)

+

+ [Byte[]] $payload =

+ 0x00, 0x01, # Message Type: 0x0001 (Binding Request)

+ 0x00, 0x00, # Message Length: 0 bytes excluding header

+ 0x21, 0x12, 0xa4, 0x42 # Magic Cookie: Always 0x2112A442

+ $LocalTransactionId = ([guid]::NewGuid()).ToByteArray()[1..12]

+ $payload = $payload + $LocalTransactionId

+ try

+ {

+ $null = $UdpClient.Send($payload, $payload.length, $StunEndpoint)

+ }

+ catch

+ {

+ throw "Unable to send data, check if $($StunEndpoint.AddressFamily) is configured"

+ }

+

+

+ try

+ {

+ $content = $UdpClient.Receive([ref]$endpoint)

+ }

+ catch

+ {

+ try

+ {

+ $null = $UdpClient.Send($payload, $payload.length, $StunEndpoint)

+ $content = $UdpClient.Receive([ref]$endpoint)

+ }

+ catch

+ {

+ try

+ {

+ $null = $UdpClient.Send($payload, $payload.length, $StunEndpoint)

+ $content = $UdpClient.Receive([ref]$endpoint)

+ }

+ catch

+ {

+ throw "Unable to receive data, check if firewall allows access to $($StunEndpoint.ToString())"

+ }

+ }

+ }

+

+

+ if (-not $content)

+ {

+ throw 'Null response.'

+ }

+

+ [Byte[]]$messageType = $content[0..1]

+ [Byte[]]$messageCookie = $content[4..7]

+ [Byte[]]$TransactionId = $content[8..19]

+ [Byte[]]$AttributeType = $content[20..21]

+ [Byte[]]$AttributeLength = $content[22..23]

+ if ([System.BitConverter]::IsLittleEndian)

+ {

+ [Array]::Reverse($AttributeLength)

+ }

+ if ( -not ([BitConverter]::ToString($messageType)) -eq '01-01')

+ {

+ throw "Invalid message type: $([BitConverter]::ToString($messageType))"

+ }

+ if ( -not ([BitConverter]::ToString($messageCookie)) -eq '21-12-A4-42')

+ {

+ throw "Invalid message cookie: $([BitConverter]::ToString($messageCookie))"

+ }

+

+ if (-not ([BitConverter]::ToString($TransactionId)) -eq [BitConverter]::ToString($LocalTransactionId) )

+ {

+ throw "Invalid message id: $([BitConverter]::ToString($TransactionId))"

+ }

+ if (-not ([BitConverter]::ToString($AttributeType)) -eq '00-20' )

+ {

+ throw "Invalid Attribute Type: $([BitConverter]::ToString($AttributeType))"

+ }

+ $ProtocolByte = $content[25]

+ if (-not (($ProtocolByte -eq 1) -or ($ProtocolByte -eq 2)))

+ {

+ throw "Invalid Address Type: $([BitConverter]::ToString($ProtocolByte))"

+ }

+ $portArray = $content[26..27]

+ if ([System.BitConverter]::IsLittleEndian)

+ {

+ [Array]::Reverse($portArray)

+ }

+ $port = [Bitconverter]::ToUInt16($portArray, 0) -bxor 0x2112

+

+ if ($ProtocolByte -eq 1)

+ {

+ $IPbytes = $content[28..31]

+ if ([System.BitConverter]::IsLittleEndian)

+ {

+ [Array]::Reverse($IPbytes)

+ }

+ $IPByte = [System.BitConverter]::GetBytes(([Bitconverter]::ToUInt32($IPbytes, 0) -bxor 0x2112a442))

+

+ if ([System.BitConverter]::IsLittleEndian)

+ {

+ [Array]::Reverse($IPByte)

+ }

+ $IP = [ipaddress]::new($IPByte)

+ }

+ elseif ($ProtocolByte -eq 2)

+ {

+ $IPbytes = $content[28..44]

+ [Byte[]]$magic = $content[4..19]

+ for ($i = 0; $i -lt $IPbytes.Count; $i ++)

+ {

+ $IPbytes[$i] = $IPbytes[$i] -bxor $magic[$i]

+ }

+ $IP = [ipaddress]::new($IPbytes)

+ }

+ $ipendpoint = [IPEndpoint]::new($IP, $port)

+ }

+ catch

+ {

+ Write-Host -Object "Failed to communicate $($StunEndpoint.ToString()) with error: $_" -ForegroundColor Red

+ }

+ return $ipendpoint

+}

+$UdpClient6 = [Net.Sockets.UdpClient]::new([Net.Sockets.AddressFamily]::InterNetworkV6)

+$UdpClient = [Net.Sockets.UdpClient]::new([Net.Sockets.AddressFamily]::InterNetwork)

+

+$ipendpoint1 = Test-StunEndpoint -UdpClient $UdpClient -StunEndpoint ([IPEndpoint]::new(([Net.Dns]::GetHostAddresses('worldaz.turn.teams.microsoft.com')|Where-Object -FilterScript {$_.AddressFamily -EQ 'InterNetwork'})[0].Address, 3478))

+$ipendpoint2 = Test-StunEndpoint -UdpClient $UdpClient -StunEndpoint ([IPEndpoint]::new([ipaddress]::Parse('13.107.17.41'), 3478))

+$ipendpoint3 = Test-StunEndpoint -UdpClient $UdpClient6 -StunEndpoint ([IPEndpoint]::new([ipaddress]::Parse('2a01:111:202f::155'), 3478))

+$localendpoint1 = $UdpClient.Client.LocalEndPoint

+$localEndpoint2 = $UdpClient6.Client.LocalEndPoint

+if ($null -ne $ipendpoint1)

+{

+ if ($ipendpoint1.Port -eq $localendpoint1.Port)

+ {

+ Write-Host -Object 'Local NAT uses port preservation' -ForegroundColor Green

+ }

+ else

+ {

+ Write-Host -Object 'Local NAT does not use port preservation, custom port range may not work with Shortpath' -ForegroundColor Red

+ }

+ if ($null -eq $ipendpoint2)

+ {

+ if ($ipendpoint1.Equals($ipendpoint2))

+ {

+ Write-Host -Object 'Local NAT reuses SNAT ports' -ForegroundColor Green

+ }

+ else

+ {

+ Write-Host -Object 'Local NAT does not reuse SNAT ports, preventing Shortpath from connecting this endpoint' -ForegroundColor Red

+ }

+ }

+}

+Write-Output -InputObject "`nLocal endpoints:`n$localendpoint1`n$localEndpoint2"

+Write-Output -InputObject "`nDiscovered external endpoints:`n$ipendpoint1`n$ipendpoint2`n$ipendpoint3`n"

+$UdpClient.Close()

+$UdpClient6.Close()

+Pause

+```

+## References

+- [RFC 8839](https://datatracker.ietf.org/doc/html/rfc8839) - Session Description Protocol (SDP) Offer/Answer Procedures for Interactive Connectivity Establishment (ICE)

+- [RFC 8489](https://datatracker.ietf.org/doc/html/rfc8489) - Session Traversal Utilities for NAT (STUN)

+- [RFC 2663](https://datatracker.ietf.org/doc/html/rfc2663) - IP Network Address Translator (NAT) Terminology and Considerations

+## Next steps

+- To learn about Azure Virtual Desktop network connectivity, see [Understanding Azure Virtual Desktop network connectivity](network-connectivity.md).

+## Version 1.0.4230.1600

+This update was released in March 2022 and includes the following changes:

+- Fixes an issue with the agent health check result being empty for the first agent heart beat.

+- Added Azure VM ID to the WVDAgentHealthStatus Log Analytics table.

+- Updated the agent's update logic to install the Geneva Monitoring agent sooner.

+- Updated the agent's Azure Instance Metadata Service health check to be Azure Stack HCI-friendly.

+> - When encrypting Linux OS volumes, the VM should be considered unavailable. We strongly recommend to avoid SSH logins while the encryption is in progress to avoid issues blocking any open files that will need to be accessed during the encryption process. To check progress, use the [Get-AzVMDiskEncryptionStatus](/powershell/module/az.compute/get-azvmdiskencryptionstatus) PowerShell cmdlet or the [vm encryption show](/cli/azure/vm/encryption#az-vm-encryption-show) CLI command. This process can be expected to take a few hours for a 30GB OS volume, plus additional time for encrypting data volumes. Data volume encryption time will be proportional to the size and quantity of the data volumes; the `encrypt format all` option is faster than in-place encryption, but will result in the loss of all data on the disks.

+## Guest Configuration resource provider error codes

+See below for a list of the possible error messages when enabling the extension

+|Error Code|Description|

+|-|-|

+|NoComplianceReport|VM has not reported the compliance data.|

+|GCExtensionMissing|Guest Configuration extension is missing.|

+|ManagedIdentityMissing|Managed identity is missing.|

+|UserIdentityMissing|User assigned identity is missing.|

+|GCExtensionManagedIdentityMissing|Guest Configuration extension and managed identity is missing.|

+|GCExtensionUserIdentityMissing|Guest Configuration extension and user identity is missing.|

+|GCExtensionIdentityMissing|Guest Configuration extension, managed identity and user identity are missing.|

+ssh -i .\Downloads\myKey.pem azureuser@10.111.12.123

+ > Deallocating the VM also releases any dynamic IP addresses assigned to the VM. The OS and data disks are not affected.

+ >

+ > If you are resizing a production VM, consider using [Azure Capacity Reservations](capacity-reservation-overview.md) to reserve Compute capacity in the region.

+

+ > Deallocating the VM also releases any dynamic IP addresses assigned to the VM. The OS and data disks are not affected.

+ >

+ > If you are resizing a production VM, consider using [Azure Capacity Reservations](capacity-reservation-overview.md) to reserve Compute capacity in the region.

+ > Deallocating the VM also releases any dynamic IP addresses assigned to the VM. The OS and data disks are not affected.

+ >

+ > If you are resizing a production VM, consider using [Azure Capacity Reservations](capacity-reservation-overview.md) to reserve Compute capacity in the region.

+* A connected group can have up to 250 virtual networks. Virtual networks in a mesh topology are in a connected group, therefore a mesh configuration has a limit of 250 virtual networks.

+* You can have network groups with or without direct connectivity enabled in the same hub-and-spoke configuration, as long as the total number of virtual networks peered to the hub **doesn't exceed 500** virtual networks.

+ * If the network group peered with the hub **has direct connectivity enabled**, these virtual networks are in a *connected group*, therefore the network group has a limit of 250 virtual networks.

+ * If the network group peered with the hub **doesn't have direct connectivity enabled**, the network group can have up to the total limit for a hub-and-spoke topology.

+* A virtual network can be part of up to two connected groups.

+ **Example:**

+ * A virtual network can be part of two mesh configurations.

+ * A virtual network can be part of a mesh topology and a network group that has direct connectivity enabled in a hub-and-spoke topology.

+ * A virtual network can be part of two network groups with direct connectivity enabled in the same or different hub-and-spoke configuration.

+* You can have virtual networks with overlapping IP spaces in the same connected group. However, communication to an overlapped IP address will be dropped.

+After the previous steps are completed, the public IP range can complete the **Provisioning** phase. The range will be created as a custom IP prefix resource in your subscription. Public IP prefixes and public IPs can be derived from your range and associated to any Azure resource that supports Standard SKU Public IPs (IPs derived from a custom IP prefix can also be safeguarded with [DDoS Protection Standard](../../ddos-protection/ddos-protection-overview.md). The IPs won't be advertised at this point and not reachable.

+To confirm private communication between the **myVM2** and **myVM1** VMs, enter `ping myVM1 -c 4`.

+You'll receive a reply message like this:

+azureuser@myVM2:~$ ping myVM1 -c 4

+PING myVM1.h0o2foz2r0tefncddcnfqm2lid.bx.internal.cloudapp.net (10.0.0.4) 56(84) bytes of data.

+64 bytes from myvm1.internal.cloudapp.net (10.0.0.4): icmp_seq=1 ttl=64 time=2.77 ms

+64 bytes from myvm1.internal.cloudapp.net (10.0.0.4): icmp_seq=2 ttl=64 time=1.95 ms

+64 bytes from myvm1.internal.cloudapp.net (10.0.0.4): icmp_seq=3 ttl=64 time=2.19 ms

+64 bytes from myvm1.internal.cloudapp.net (10.0.0.4): icmp_seq=4 ttl=64 time=1.85 ms

+ myVM1.h0o2foz2r0tefncddcnfqm2lid.bx.internal.cloudapp.net ping statistics

+4 packets transmitted, 4 received, 0% packet loss, time 3003ms

+rtt min/avg/max/mdev = 1.859/2.195/2.770/0.357 ms

+```

+1. In the Bastion connection of **myVM1**, open PowerShell.

+2. Enter `ping myVM2`.

+ You'll get a reply message like this:

+ PS C:\Users\myVM1> ping myVM2

+ Pinging myVM2.ovvzzdcazhbu5iczfvonhg2zrb.bx.internal.cloudapp.net

+ Request timed out.

+ Request timed out.

+ Request timed out.

+ Request timed out.

+ Ping statistics for 10.0.0.5:

+ Packets: Sent = 4, Received = 0, Lost = 4 (100% loss),

+ ```

+ The ping fails, because it uses the Internet Control Message Protocol (ICMP). By default, ICMP isn't allowed through your Windows firewall.

+1. To allow **myVM2** to ping **myVM1** in a later step, enter this command:

+ ```powershell

+ New-NetFirewallRule ΓÇôDisplayName "Allow ICMPv4-In" ΓÇôProtocol ICMPv4

+ That command lets ICMP inbound through the Windows firewall.

+3. Close the Bastion connection to **myVM1**.

+5. Open PowerShell on **myVM2**, enter `ping myVM1`.

+ You'll receive a successful reply message like this:

+ Pinging myVM1.cs4wv3rxdjgedggsfghkjrxuqf.bx.internal.cloudapp.net [10.1.0.4] with 32 bytes of data:

+This example returns the public IP address of the **myVM1** VM:

+1. In the Remote Desktop of **myVM1**, open PowerShell.

+1. Enter `ping myVM2`.

+ You'll get a reply message like this:

+ PS C:\Users\myVM1> ping myVM2

+ Pinging myVM2.ovvzzdcazhbu5iczfvonhg2zrb.bx.internal.cloudapp.net

+1. To allow **myVM2** to ping **myVM1** in a later step, enter this command:

+1. Close the remote desktop connection to **myVM1**.

+1. Repeat the steps in [Connect to a VM from the internet](#connect-to-a-vm-from-the-internet). This time, connect to **myVM2**.

+1. From a command prompt on the **myVM2** VM, enter `ping myVM1`.

+ You'll get a reply message like this:

+ C:\windows\system32>ping myVM1

+ Pinging myVM1.e5p2dibbrqtejhq04lqrusvd4g.bx.internal.cloudapp.net [10.0.0.4] with 32 bytes of data:

+ You receive replies from **myVM1**, because you allowed ICMP through the Windows firewall on the **myVM1** VM in a previous step.

+1. Close the remote desktop connection to **myVM2**.

+> [!IMPORTANT]

+> If a Point-to-site VPN configuration used for a global profile is configured to authenticate users using the RADIUS protocol, make sure "Use Remote/On-premises RADIUS server" is turned on for all Point-to-site VPN Gateways using that configuration. Additionally, ensure your RADIUS server is configured to accept authentication requests from theRADIUS proxy IP addresses of **all** Point-to-site VPN Gateways using this VPN configuration.

+ :::image type="content" source="./media/nat-rules-vpn-gateway/vpn-site-static.png" alt-text="Screenshot showing how to edit the Private Address space of a VPN site" lightbox="./media/nat-rules-vpn-gateway/vpn-site-static.png":::

+### How is Virtual WAN SLA calculated?

+Virtual WAN is a networking-as-a-service platform that has a 99.95% SLA. However, Virtual WAN combines many different components such as Azure Firewall, Site-to-site VPN, ExpressRoute, Point-to-site VPN, and Virtual WAN Hub/Integrated Network Virtual Appliances.

+The SLA for each component is calculated individually. For example, if ExpressRoute has a 10 minute downtime, the availability of ExpressRoute would be calculated as (Maximum Available Minutes - downtime) / Maximum Available Minutes * 100.