-Azure Active Directory Domain Services (Azure AD DS) supports a one-time move for customers currently using the Classic virtual network model to the Resource Manager virtual network model. Azure AD DS managed domains that use the Resource Manager deployment model provide additional features such as fine-grained password policy, audit logs, and account lockout protection.

-This article outlines considerations for migration, then the required steps to successfully migrate an existing managed domain. For some of the benefits, see [Benefits of migration from the Classic to Resource Manager deployment model in Azure AD DS][migration-benefits].

-The migration process takes an existing managed domain that runs in a Classic virtual network and moves it to an existing Resource Manager virtual network. The migration is performed using PowerShell, and has two main stages of execution: *preparation* and *migration*.

-

-In the *preparation* stage, Azure AD DS takes a backup of the domain to get the latest snapshot of users, groups, and passwords synchronized to the managed domain. Synchronization is then disabled, and the cloud service that hosts the managed domain is deleted. During the preparation stage, the managed domain is unable to authenticate users.

-

-In the *migration* stage, the underlying virtual disks for the domain controllers from the Classic managed domain are copied to create the VMs using the Resource Manager deployment model. The managed domain is then recreated, which includes the LDAPS and DNS configuration. Synchronization to Azure AD is restarted, and LDAP certificates are restored. There's no need to rejoin any machines to a managed domainΓÇôthey continue to be joined to the managed domain and run without changes.

-

-## Example scenarios for migration

-Some common scenarios for migrating a managed domain include the following examples.

-> [!NOTE]

-> Don't convert the Classic virtual network until you have confirmed a successful migration. Converting the virtual network removes the option to roll back or restore the managed domain if there are any problems during the migration and verification stages.

-### Migrate Azure AD DS to an existing Resource Manager virtual network (recommended)

-A common scenario is where you've already moved other existing Classic resources to a Resource Manager deployment model and virtual network. Peering is then used from the Resource Manager virtual network to the Classic virtual network that continues to run Azure AD DS. This approach lets the Resource Manager applications and services use the authentication and management functionality of the managed domain in the Classic virtual network. Once migrated, all resources run using the Resource Manager deployment model and virtual network.

-

-High-level steps involved in this example migration scenario include the following parts:

-1. Remove existing VPN gateways or virtual network peering configured on the Classic virtual network.

-1. Migrate the managed domain using the steps outlined in this article.

-1. Test and confirm a successful migration, then delete the Classic virtual network.

-### Migrate multiple resources including Azure AD DS

-In this example scenario, you migrate Azure AD DS and other associated resources from the Classic deployment model to the Resource Manager deployment model. If some resources continued to run in the Classic virtual network alongside the managed domain, they can all benefit from migrating to the Resource Manager deployment model.

-

-High-level steps involved in this example migration scenario include the following parts:

-1. Remove existing VPN gateways or virtual network peering configured on the Classic virtual network.

-1. Migrate the managed domain using the steps outlined in this article.

-1. Set up virtual network peering between the Classic virtual network and Resource Manager network.

-1. Test and confirm a successful migration.

-1. [Move additional Classic resources like VMs][migrate-iaas].

-### Migrate Azure AD DS but keep other resources on the Classic virtual network

-With this example scenario, you have the minimum amount of downtime in one session. You only migrate Azure AD DS to a Resource Manager virtual network, and keep existing resources on the Classic deployment model and virtual network. In a following maintenance period, you can migrate the additional resources from the Classic deployment model and virtual network as desired.

-

-High-level steps involved in this example migration scenario include the following parts:

-1. Remove existing VPN gateways or virtual network peering configured on the Classic virtual network.

-1. Migrate the managed domain using the steps outlined in this article.

-1. Set up virtual network peering between the Classic virtual network and the new Resource Manager virtual network.

-1. Later, [migrate the additional resources][migrate-iaas] from the Classic virtual network as needed.

-As you prepare and then migrate a managed domain, there are some considerations around the availability of authentication and management services. The managed domain is unavailable for a period of time during migration. Applications and services that rely on Azure AD DS experience downtime during migration.

-If you need to roll back, the IP addresses may change after rolling back.

-### Downtime

-The migration process involves the domain controllers being offline for a period of time. Domain controllers are inaccessible while Azure AD DS is migrated to the Resource Manager deployment model and virtual network.

-On average, the downtime is around 1 to 3 hours. This time period is from when the domain controllers are taken offline to the moment the first domain controller comes back online. This average doesn't include the time it takes for the second domain controller to replicate, or the time it may take to migrate additional resources to the Resource Manager deployment model.

-By default, 5 bad password attempts in 2 minutes lock out an account for 30 minutes.

-### Roll back and restore

-If the migration isn't successful, there's process to roll back or restore a managed domain. Rollback is a self-service option to immediately return the state of the managed domain to before the migration attempt. Azure support engineers can also restore a managed domain from backup as a last resort. For more information, see [how to roll back or restore from a failed migration](#roll-back-and-restore-from-migration).

-### LDAPS and TLS/SSL certificate expiration

-If your managed domain is configured for LDAPS, confirm that your current TLS/SSL certificate is valid for more than 30 days. A certificate that expires within the next 30 days causes the migration processes to fail. If needed, renew the certificate and apply it to your managed domain, then begin the migration process.

-The migration to the Resource Manager deployment model and virtual network is split into 5 main steps:

-| Step | Performed through | Estimated time | Downtime | Roll back/Restore? |

-||--|--|--|-|

-| [Step 1 - Update and locate the new virtual network](#update-and-verify-virtual-network-settings) | Azure portal | 15 minutes | No downtime required | N/A |

-| [Step 2 - Prepare the managed domain for migration](#prepare-the-managed-domain-for-migration) | PowerShell | 15 ΓÇô 30 minutes on average | Downtime of Azure AD DS starts after this command is completed. | Roll back and restore available. |

-| [Step 3 - Move the managed domain to an existing virtual network](#migrate-the-managed-domain) | PowerShell | 1 ΓÇô 3 hours on average | One domain controller is available once this command is completed. | On failure, both rollback (self-service) and restore are available. |

-| [Step 4 - Test and wait for the replica domain controller](#test-and-verify-connectivity-after-the-migration)| PowerShell and Azure portal | 1 hour or more, depending on the number of tests | Both domain controllers are available and should function normally, downtime ends. | N/A. Once the first VM is successfully migrated, there's no option for rollback or restore. |

-| [Step 5 - Optional configuration steps](#optional-post-migration-configuration-steps) | Azure portal and VMs | N/A | No downtime required | N/A |

- For information on how to check and update your PowerShell version, see [Azure PowerShell overview][azure-powershell].

- Make sure that network settings don't block necessary ports required for Azure AD DS. Ports must be open on both the Classic virtual network and the Resource Manager virtual network. These settings include route tables (although it's not recommended to use route tables) and network security groups.

- | Service tag | CorpNetSaw | * | Any | RDP | 3389 | TCP | Allow | Optional | Debugging for support |

- Note that the **CorpNetSaw** service tag isn't available by using Azure portal, and the network security group rule for **CorpNetSaw** has to be added by using [PowerShell](powershell-create-instance.md#create-a-network-security-group).

-## Prepare the managed domain for migration

-Azure PowerShell is used to prepare the managed domain for migration. These steps include taking a backup, pausing synchronization, and deleting the cloud service that hosts Azure AD DS. When this step completes, Azure AD DS is taken offline for a period of time. If the preparation step fails, you can [roll back to the previous state](#roll-back).

-To prepare the managed domain for migration, complete the following steps:

-1. Create a variable to hold the credentials for by the migration script using the [Get-Credential][get-credential] cmdlet.

-1. Define a variable for your Azure subscription ID. If needed, you can use the [Get-AzSubscription](/powershell/module/az.accounts/get-azsubscription) cmdlet to list and view your subscription IDs. Provide your own subscription ID in the following command:

-1. Now run the `Migrate-Aadds` cmdlet using the *-Prepare* parameter. Provide the *-ManagedDomainFqdn* for your own managed domain, such as *aaddscontoso.com*:

- -Prepare `

-## Migrate the managed domain

-With the managed domain prepared and backed up, the domain can be migrated. This step recreates the Azure AD DS domain controller VMs using the Resource Manager deployment model. This step can take 1 to 3 hours to complete.

-Run the `Migrate-Aadds` cmdlet using the *-Commit* parameter. Provide the *-ManagedDomainFqdn* for your own managed domain prepared in the previous section, such as *aaddscontoso.com*.

-Specify the target resource group that contains the virtual network you want to migrate Azure AD DS to, such as *myResourceGroup*. Provide the target virtual network, such as *myVnet*, and the subnet, such as *DomainServices*.

-After this command runs, you can't then roll back:

-```powershell

-Migrate-Aadds `

- -Commit `

- -ManagedDomainFqdn aaddscontoso.com `

- -VirtualNetworkResourceGroupName myResourceGroup `

- -VirtualNetworkName myVnet `

- -VirtualSubnetName DomainServices `

- -Credentials $creds `

- -SubscriptionId $subscriptionId

-```

-After the script validates the managed domain is prepared for migration, enter *Y* to start the migration process.

-> Don't convert the Classic virtual network to a Resource Manager virtual network during the migration process. If you convert the virtual network, you can't then rollback or restore the managed domain as the original virtual network won't exist anymore.

-## Roll back and restore from migration

-Up to a certain point in the migration process, you can choose to roll back or restore the managed domain.

-### Roll back

-If there's an error when you run the PowerShell cmdlet to prepare for migration in step 2 or for the migration itself in step 3, the managed domain can roll back to the original configuration. This roll back requires the original Classic virtual network. The IP addresses may still change after rollback.

-Run the `Migrate-Aadds` cmdlet using the *-Abort* parameter. Provide the *-ManagedDomainFqdn* for your own managed domain prepared in a previous section, such as *aaddscontoso.com*, and the Classic virtual network name, such as *myClassicVnet*:

-```powershell

-Migrate-Aadds `

- -Abort `

- -ManagedDomainFqdn aaddscontoso.com `

- -ClassicVirtualNetworkName myClassicVnet `

- -Credentials $creds `

- -SubscriptionId $subscriptionId

-```

-### Restore

-As a last resort, Azure AD Domain Services can be restored from the last available backup. A backup is taken in step 1 of the migration to make sure that the most current backup is available. This backup is stored for 30 days.

-To restore the managed domain from backup, [open a support case ticket using the Azure portal][azure-support]. Provide your directory ID, domain name, and reason for restore. The support and restore process may take multiple days to complete.

-You can download the latest version of the agent using [this link](https://aka.ms/onpremprovisioningagent).

-|Number of Azure AD Connect provisioning agents to deploy|Two (for high availability and failover)

-|Number of provisioning connector apps to configure|One app per child domain|

-|Server host for Azure AD Connect provisioning agent|Windows Server 2016 with line of sight to geolocated Active Directory domain controllers</br>Can coexist with Azure AD Connect service|

-|Number of Azure AD Connect provisioning agents to deploy on-premises|Two per disjoint Active Directory forest|

-|Number of provisioning connector apps to configure|One app per child domain|

-|Server host for Azure AD Connect provisioning agent|Windows Server 2016 with line of sight to geolocated Active Directory domain controllers</br>Can coexist with Azure AD Connect service|

-The cloud HR app to Active Directory user provisioning solution requires that you deploy one or more Azure AD Connect provisioning agents on servers that run Windows Server 2016 or greater. The servers must have a minimum of 4-GB RAM and .NET 4.7.1+ runtime. Ensure that the host server has network access to the target Active Directory domain.

-* If you are using scoping filters, configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-Use this topology to manage multiple independent child AD domains belonging to the same forest, if managers always exist in the same domain as the user and your unique ID generation rules for attributes like *userPrincipalName*, *samAccountName* and *mail* does not require a forest-wide lookup. It also offers the flexibility of delegating the administration of each provisioning job by domain boundary.

-Use this topology if you want to use a single provisioning app to manage users belonging to all your parent and child AD domains. This topology is recommended if provisioning rules are consistent across all domains and there is no requirement for delegated administration of provisioning jobs. This topology supports resolving cross-domain manager references and can perform forest-wide uniqueness check.

-* If you are using scoping filters, configure [skip out of scope deletions flag](skip-out-of-scope-deletions.md) to prevent accidental account deactivations.

-In large organizations, it is not uncommon to have multiple HR systems. During business M&A (mergers and acquisitions) scenarios, you may come across a need to connect your on-premises Active Directory to multiple HR sources. We recommend the topology below if you have multiple HR sources and would like to channel the identity data from these HR sources to either the same or different on-premises Active Directory domains.

-With text message verification during SSPR or Azure AD Multi-Factor Authentication, an SMS is sent to the mobile phone number containing a verification code. To complete the sign-in process, the verification code provided is entered into the sign-in interface.

-> Safari is supported for device-based Conditional Access, but it can not satisfy the **Require approved client app** or **Require app protection policy** conditions. A managed browser like Microsoft Edge will satisfy approved client app and app protection policy requirements.

-> Group filtering applies to tokens emitted for apps where group claims and filtering was configured in the **Enterprise apps** blade in the portal.

- | `SecurityGroup` | Emits security groups that the user is a member of in the group claim. |

-## Retrieve accounts that were flagged with AD FS Bad Password attempts

-To retrieve accounts that were flagged with AD FS Bad Password attempts, use the following steps.

-The audit activity report is available in all editions of Azure AD. To access the audit logs, you need to have one of the following roles:

-You can also access the audit log through the [Microsoft Graph API](/graph/api/resources/azure-ad-auditlog-overview).

-> | Manage terms of use | [Global Administrator](permissions-reference.md#global-administrator) | |

-1. Download Astra Trident from its [GitHub repository](https://github.com/NetApp/trident/releases). Choose from the desired version and download the installer bundle.

- ```bash

- wget https://github.com/NetApp/trident/releases/download/v21.07.1/trident-installer-21.07.1.tar.gz

- tar xzvf trident-installer-21.07.1.tar.gz

- ```

-2. Run the [kubectl create][kubectl-create] command to create the *trident* namespace:

-3. Run the [kubectl apply][kubectl-apply] command to deploy the Trident operator using the bundle file:

- kubectl apply -f trident-installer/deploy/bundle.yaml -n trident

-4. Run the following command to create a `TridentOrchestrator` to install Astra Trident.

- kubectl apply -f trident-installer/deploy/crds/tridentorchestrator_cr.yaml

-5. To confirm Astra Trident was installed successfully, run the following [kubectl describe][kubectl-describe] command:

- Autosupport Image: netapp/trident-autosupport:21.01

- Trident Image: netapp/trident:21.07.1

- Version: v21.07.1

-1. Before creating a backend, you need to update `backend-anf.yaml` to include details about the Azure NetApp Files subscription, such as:

- kubectl apply -f trident-installer/sample-input/backends-samples/azure-netapp-files/backend-anf.yaml -n trident

- image: mcr.microsoft.com/oss/nginx/nginx:latest1.15.5-alpine

-## Limitation

-Certificate rotation is not supported for stopped AKS clusters.

-# Open Service Mesh (OSM) add-on in Azure Kubernetes Service (OSM)

-description: Understand the Kubernetes version support policy and lifecycle of clusters in Azure Kubernetes Service (AKS)

-> AKS follows 12 months of support for a generally available (GA) Kubernetes version. To read more about our support policy for Kubernetes versioning, please read our [FAQ](https://learn.microsoft.com/azure/aks/supported-kubernetes-versions?tabs=azure-cli#faq).

-When you upgrade by alias minor version, only a higher minor version is supported. For example, upgrading from `1.14.x` to `1.14` won't trigger an upgrade to the latest GA `1.14` patch, but upgrading to `1.15` will trigger an upgrade to the latest GA `1.15` patch. If you wish to upgrade your patch version in the same minor version, please use [auto-upgrade](https://learn.microsoft.com/azure/aks/auto-upgrade-cluster#using-cluster-auto-upgrade).

-AKS defines a GA version as a version enabled in all SLO or SLA measurements and available in all regions. AKS supports three GA minor versions of Kubernetes:

-* The latest GA minor version released in AKS (which we'll refer to as N).

- * Each supported minor version also supports a maximum of two (2) stable patches.

-The supported window of Kubernetes versions on AKS is known as "N-2": (N (Latest release) - 2 (minor versions)).

-> If customers are running an unsupported Kubernetes version, they'll be asked to upgrade when requesting support for the cluster. Clusters running unsupported Kubernetes releases aren't covered by the [AKS support policies](./support-policies.md).

-In addition to the above, AKS supports a maximum of two **patch** releases of a given minor version. So given the following supported versions:

-* AKS publishes a pre-announcement with the planned date of the new version release and respective old version deprecation. This announcement is published on the [AKS release notes](https://aka.ms/aks/releasenotes) at least 30 days before removal.

-* AKS uses [Azure Advisor](../advisor/advisor-overview.md) to alert users if a new version will cause issues in their cluster because of deprecated APIs. Azure Advisor is also used to alert the user if they're currently out of support.

- > Visit [manage Azure subscriptions](../cost-management-billing/manage/add-change-subscription-administrator.md#assign-a-subscription-administrator) to determine who your subscription administrators are and make any necessary changes.

-* Users have **30 days** from version removal to upgrade to a supported minor version release to continue receiving support.

-* Because of the urgent nature of patch versions, they can be introduced into the service as they become available. Once available, patches will have a two month minimum lifecycle.

-* In general, AKS doesn't broadly communicate the release of new patch versions. However, AKS constantly monitors and validates available CVE patches to support them in AKS in a timely manner. If a critical patch is found or user action is required, AKS will notify users to upgrade to the newly available patch.

-* Users have **30 days** from a patch release's removal from AKS to upgrade into a supported patch and continue receiving support. However, you'll **no longer be able to create clusters or node pools once the version is deprecated/removed.**

-[az aks get-versions][az-aks-get-versions] command. The following example lists available Kubernetes versions for the *EastUS* region:

-The AKS team publishes pre-announcements with planned dates of the new Kubernetes versions in the AKS docs, our [GitHub](https://github.com/Azure/AKS/releases), and emails to subscription administrators who own clusters that are going to fall out of support. AKS also uses [Azure Advisor](../advisor/advisor-overview.md) to alert customers in the Azure portal to notify users if they're out of support. It also alerts them of deprecated APIs that will affect their application or development processes.

-Starting with Kubernetes 1.19, the [open source community has expanded support to one year](https://kubernetes.io/blog/2020/08/31/kubernetes-1-19-feature-one-year-support/). AKS commits to enabling patches and support matching the upstream commitments. For AKS clusters on 1.19 and greater, you'll be able to upgrade at a minimum of once a year to stay on a supported version.

-### What happens when a user upgrades a Kubernetes cluster with a minor version that isn't supported?

-> We recommend you review [Azure AD workload identity][workload-identity-overview] (preview).

-description: In this Azure Kubernetes Service (AKS) article, you deploy an Azure Kubernetes Service cluster and configure it with an Azure AD workload identity (preview).

-# Deploy and configure workload identity (preview) on an Azure Kubernetes Service (AKS) cluster

-* Deploy an AKS cluster using the Azure CLI that includes the OpenID Connect Issuer and an Azure AD workload identity (preview)

-This article assumes you have a basic understanding of Kubernetes concepts. For more information, see [Kubernetes core concepts for Azure Kubernetes Service (AKS)][kubernetes-concepts]. If you aren't familiar with Azure AD workload identity (preview), see the following [Overview][workload-identity-overview] article.

-## Install the aks-preview Azure CLI extension

-To install the aks-preview extension, run the following command:

-```azurecli

-az extension add --name aks-preview

-```

-Run the following command to update to the latest version of the extension released:

-```azurecli

-az extension update --name aks-preview

-```

-## Register the 'EnableWorkloadIdentityPreview' feature flag

-Register the `EnableWorkloadIdentityPreview` feature flag by using the [az feature register][az-feature-register] command, as shown in the following example:

-```azurecli-interactive

-az feature register --namespace "Microsoft.ContainerService" --name "EnableWorkloadIdentityPreview"

-```

-It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [az feature show][az-feature-show] command:

-```azurecli-interactive

-az feature show --namespace "Microsoft.ContainerService" --name "EnableWorkloadIdentityPreview"

-```

-When the status reflects *Registered*, refresh the registration of the *Microsoft.ContainerService* resource provider by using the [az provider register][az-provider-register] command:

-```azurecli-interactive

-az provider register --namespace Microsoft.ContainerService

-```

-# Migrate from pod managed-identity to workload identity (preview)

-# Use Azure AD workload identity (preview) with Azure Kubernetes Service (AKS)

-Today with Azure Kubernetes Service (AKS), you can assign [managed identities at the pod-level][use-azure-ad-pod-identity], which has been a preview feature. This pod-managed identity allows the hosted workload or application access to resources through Azure Active Directory (Azure AD). For example, a workload stores files in Azure Storage, and when it needs to access those files, the pod authenticates itself against the resource as an Azure managed identity. This authentication method has been replaced with [Azure Active Directory (Azure AD) workload identities][azure-ad-workload-identity] (preview), which integrate with the Kubernetes native capabilities to federate with any external identity providers. This approach is simpler to use and deploy, and overcomes several limitations in Azure AD pod-managed identity:

-This article helps you understand this new authentication feature, and reviews the options available to plan your migration phases and project strategy.

- * [.NET][dotnet-azure-identity-client-library] 1.5.0

- * [Java][java-azure-identity-client-library] 1.4.0

- * [JavaScript][javascript-azure-identity-client-library] 2.0.0

- * [Python][python-azure-identity-client-library] 1.7.0

-## Language SDK examples

- - [Azure Identity SDK](https://azure.github.io/azure-workload-identity/docs/topics/language-specific-examples/azure-identity-sdk.html)

- - [MSAL](https://azure.github.io/azure-workload-identity/docs/topics/language-specific-examples/msal.html)

-Similar to other webhook addons, the certificate will be rotated by cluster certificate [auto rotation](https://learn.microsoft.com/azure/aks/certificate-rotation#certificate-auto-rotation) operation.

-[azure-instance-metadata-service]: ../virtual-machines/linux/instance-metadata-service.md

-[dotnet-azure-identity-client-library]: /dotnet/api/overview/azure/identity-readme

-[java-azure-identity-client-library]: /java/api/overview/azure/identity-readme

-[javascript-azure-identity-client-library]: /javascript/api/overview/azure/identity-readme

-[python-azure-identity-client-library]: /python/api/overview/azure/identity-readme

-A managed identity can also be added to the Analysis Services Admins list. For example, you might have a [Logic App with a system-assigned managed identity](../logic-apps/create-managed-service-identity.md), and want to grant it the ability to administer your server.

-In most parts of the Azure portal and APIs, managed identities are identified using their service principal object ID. However, Analysis Services requires that they be identified using their client ID. To obtain the client ID for a service principal, you can use the Azure CLI:

-```azurecli

-az ad sp show --id <ManagedIdentityServicePrincipalObjectId> --query appId -o tsv

-```

-Alternatively you can use PowerShell:

-```powershell

-(Get-AzureADServicePrincipal -ObjectId <ManagedIdentityServicePrincipalObjectId>).AppId

-```

-You can then use this client ID in conjunction with the tenant ID to add the managed identity to the Analysis Services Admins list, as described above.

-Analysis Services also supports operations performed by managed identities using service principals. To learn more, see [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md) and [Azure services that support Azure AD authentication](../active-directory/managed-identities-azure-resources/services-support-managed-identities.md#azure-analysis-services).

-| [Get authorization context](get-authorization-context-policy.md) | ✔️ | ❌ | ❌ |

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

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

-description: Learn how to create and use an authorization in Azure API Management. An authorization manages authorization tokens to OAuth 2.0 backend services. The example uses GitHub as an identity provider.

-# Configure and use an authorization

-In this article, you learn how to create an [authorization](authorizations-overview.md) (preview) in API Management and call a GitHub API that requires an authorization token. The authorization code grant type will be used.

-Four steps are needed to set up an authorization with the authorization code grant type:

-

-1. Register an application in the identity provider (in this case, GitHub).

-1. Configure an authorization in API Management.

-1. Authorize with GitHub and configure access policies.

-1. Create an API in API Management and configure a policy.

-## Prerequisites

-## Step 1: Register an application in GitHub

-1. Sign in to GitHub.

-1. In your account profile, go to **Settings > Developer Settings > OAuth Apps > Register a new application**.

-

- :::image type="content" source="media/authorizations-how-to/register-application.png" alt-text="Screenshot of registering a new OAuth application in GitHub.":::

- 1. Enter an **Application name** and **Homepage URL** for the application.

- 1. Optionally, add an **Application description**.

- 1. In **Authorization callback URL** (the redirect URL), enter `https://authorization-manager.consent.azure-apim.net/redirect/apim/<YOUR-APIM-SERVICENAME>`, substituting the API Management service name that is used.

-1. Select **Register application**.

-1. In the **General** page, copy the **Client ID**, which you'll use in a later step.

-1. Select **Generate a new client secret**. Copy the secret, which won't be displayed again, and which you'll use in a later step.

- :::image type="content" source="media/authorizations-how-to/generate-secret.png" alt-text="Screenshot showing how to get client ID and client secret for the application in GitHub.":::

-## Step 2: Configure an authorization in API Management

-1. Sign into Azure portal and go to your API Management instance.

-1. In the left menu, select **Authorizations** > **+ Create**.

-

- :::image type="content" source="media/authorizations-how-to/create-authorization.png" alt-text="Screenshot of creating an API Management authorization in the Azure portal.":::

-1. In the **Create authorization** window, enter the following settings, and select **Create**:

-

- |Settings |Value |

- |||

- |**Provider name** | A name of your choice, such as *github-01* |

- |**Identity provider** | Select **GitHub** |

- |**Grant type** | Select **Authorization code** |

- |**Client id** | Paste the value you copied earlier from the app registration |

- |**Client secret** | Paste the value you copied earlier from the app registration |

- |**Scope** | Set the scope to `User` |

- |**Authorization name** | A name of your choice, such as *auth-01* |

-

-1. After the authorization provider and authorization are created, select **Next**.

-1. On the **Login** tab, select **Login with GitHub**. Before the authorization will work, it needs to be authorized at GitHub.

- :::image type="content" source="media/authorizations-how-to/authorize-with-github.png" alt-text="Screenshot of logging into the GitHub authorization from the portal.":::

-## Step 3: Authorize with GitHub and configure access policies

-1. Sign in to your GitHub account if you're prompted to do so.

-1. Select **Authorize** so that the application can access the signed-in userΓÇÖs account.

-

- :::image type="content" source="media/authorizations-how-to/consent-to-authorization.png" alt-text="Screenshot of consenting to authorize with GitHub.":::

- After authorization, the browser is redirected to API Management and the window is closed. If prompted during redirection, select **Allow access**. In API Management, select **Next**.

-1. On the **Access policy** page, create an access policy so that API Management has access to use the authorization. Ensure that a managed identity is configured for API Management. [Learn more about managed identities in API Management](api-management-howto-use-managed-service-identity.md#create-a-system-assigned-managed-identity).

-1. Select **Managed identity** **+ Add members** and then select your subscription.

-1. In **Managed identity**, select **API Management service**, and then select the API Management instance that is used. Click **Select** and then **Complete**.

-

- :::image type="content" source="media/authorizations-how-to/select-managed-identity.png" alt-text="Screenshot of selecting a managed identity to use the authorization.":::

-

-## Step 4: Create an API in API Management and configure a policy

-1. Sign into Azure portal and go to your API Management instance.

-1. In the left menu, select **APIs > + Add API**.

-1. Select **HTTP** and enter the following settings. Then select **Create**.

- |Setting |Value |

- |||

- |**Display name** | *github* |

- |**Web service URL** | https://api.github.com/users |

- |**API URL suffix** | *github* |

-2. Navigate to the newly created API and select **Add Operation**. Enter the following settings and select **Save**.

- |Setting |Value |

- |||

- |**Display name** | *getdata* |

- |**URL** | /data |

- :::image type="content" source="media/authorizations-how-to/add-operation.png" alt-text="Screenshot of adding a getdata operation to the API in the portal.":::

-1. In the **Inbound processing** section, select the (**</>**) (code editor) icon.

-1. Copy the following, and paste in the policy editor. Make sure the provider-id and authorization-id correspond to the names in step 2.3. Select **Save**.

- ```xml

- <policies>

- <inbound>

- <base />

- <get-authorization-context provider-id="github-01" authorization-id="auth-01" context-variable-name="auth-context" identity-type="managed" ignore-error="false" />

- <set-header name="Authorization" exists-action="override">

- <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>

- </set-header>

- <rewrite-uri template="@(context.Request.Url.Query.GetValueOrDefault("username",""))" copy-unmatched-params="false" />

- <set-header name="User-Agent" exists-action="override">

- <value>API Management</value>

- </set-header>

- </inbound>

- <backend>

- <base />

- </backend>

- <outbound>

- <base />

- </outbound>

- <on-error>

- <base />

- </on-error>

- </policies>

- ```

- The policy to be used consists of four parts.

- - Fetch an authorization token.

- - Create an HTTP header with the fetched authorization token.

- - Create an HTTP header with a `User-Agent` header (GitHub requirement). [Learn more](https://docs.github.com/rest/overview/resources-in-the-rest-api#user-agent-required)

- - Because the incoming request to API Management will consist of a query parameter called *username*, add the username to the backend call.

- > [!NOTE]

- > The `get-authorization-context` policy references the authorization provider and authorization that were created earlier. [Learn more](get-authorization-context-policy.md) about how to configure this policy.

- :::image type="content" source="media/authorizations-how-to/policy-configuration-cropped.png" lightbox="media/authorizations-how-to/policy-configuration.png" alt-text="Screenshot of configuring policy in the portal.":::

-1. Test the API.

- 1. On the **Test** tab, enter a query parameter with the name *username*.

- 1. As value, enter the username that was used to sign into GitHub, or another valid GitHub username.

- 1. Select **Send**.

- :::image type="content" source="media/authorizations-how-to/test-api.png" alt-text="Screenshot of testing the API successfully in the portal.":::

- A successful response returns user data from the GitHub API.

-## Next steps

-Learn more about [access restriction policies](api-management-access-restriction-policies.md).

-description: Learn about authorizations in Azure API Management, a feature that simplifies the process of managing OAuth 2.0 authorization tokens to APIs

-# Authorizations overview

-API Management authorizations (preview) simplify the process of managing authorization tokens to OAuth 2.0 backend services.

-By configuring any of the supported identity providers and creating an authorization using the standardized OAuth 2.0 flow, API Management can retrieve and refresh access tokens to be used inside of API management or sent back to a client.

-This feature enables APIs to be exposed with or without a subscription key, and the authorization to the backend service uses OAuth 2.0.

-Some example scenarios that will be possible through this feature are:

-The feature consists of two parts, management and runtime:

-* The **management** part takes care of configuring identity providers, enabling the consent flow for the identity provider, and managing access to the authorizations.

-* The **runtime** part uses the [`get-authorization-context`](get-authorization-context-policy.md) policy to fetch and store access and refresh tokens. When a call comes into API Management, and the `get-authorization-context` policy is executed, it will first validate if the existing authorization token is valid. If the authorization token has expired, the refresh token is used to try to fetch a new authorization and refresh token from the configured identity provider. If the call to the backend provider is successful, the new authorization token will be used, and both the authorization token and refresh token will be stored encrypted.

-### Requirements

-### Limitations

-For public preview the following limitations exist:

-### Authorization providers

-

-Authorization provider configuration includes which identity provider and grant type are used. Each identity provider requires different configurations.

-* An authorization provider configuration can only have one grant type.

-* One authorization provider configuration can have multiple authorizations.

-* You can find the supported identity providers for public preview in [this](https://github.com/Azure/APIManagement-Authorizations/blob/main/docs/identityproviders.md) GitHub repository.

-With the Generic OAuth 2.0 provider, other identity providers that support the standards of OAuth 2.0 flow can be used.

-### Authorizations

-To use an authorization provider, at least one *authorization* is required. The process of configuring an authorization differs based on the used grant type. Each authorization provider configuration only supports one grant type. For example, if you want to configure Azure AD to use both grant types, two authorization provider configurations are needed.

-**Authorization code grant type**

-Authorization code grant type is bound to a user context, meaning a user needs to consent to the authorization. As long as the refresh token is valid, API Management can retrieve new access and refresh tokens. If the refresh token becomes invalid, the user needs to reauthorize. All identity providers support authorization code. [Read more about Authorization code grant type](https://www.rfc-editor.org/rfc/rfc6749?msclkid=929b18b5d0e611ec82a764a7c26a9bea#section-1.3.1).

-**Client credentials grant type**

-Client credentials grant type isn't bound to a user and is often used in application-to-application scenarios. No consent is required for client credentials grant type, and the authorization doesn't become invalid. [Read more about Client Credentials grant type](https://www.rfc-editor.org/rfc/rfc6749?msclkid=929b18b5d0e611ec82a764a7c26a9bea#section-1.3.4).

-### Access policies

-Access policies determine which identities can use the authorization that the access policy is related to. The supported identities are managed identities, user identities, and service principals. The identities must belong to the same tenant as the API Management tenant.

-### Process flow for creating authorizations

-The following image shows the process flow for creating an authorization in API Management using the grant type authorization code. For public preview no API documentation is available.

-1. Client sends a request to create an authorization provider.

-1. Authorization provider is created, and a response is sent back.

-1. Client sends a request to create an authorization.

-1. Authorization is created, and a response is sent back with the information that the authorization is not "connected".

-1. Client sends a request to retrieve a login URL to start the OAuth 2.0 consent at the identity provider. The request includes a post-redirect URL to be used in the last step.

-1. Response is returned with a login URL that should be used to start the consent flow.

-1. Client opens a browser with the login URL that was provided in the previous step. The browser is redirected to the identity provider OAuth 2.0 consent flow.

-1. After the consent is approved, the browser is redirected with an authorization code to the redirect URL configured at the identity provider.

-1. API Management uses the authorization code to fetch access and refresh tokens.

-1. API Management receives the tokens and encrypts them.

-1. API Management redirects to the provided URL from step 5.

-### Process flow for runtime

-The following image shows the process flow to fetch and store authorization and refresh tokens based on a configured authorization. After the tokens have been retrieved a call is made to the backend API.

-1. Client sends request to API Management instance.

-1. The policy [`get-authorization-context`](get-authorization-context-policy.md) checks if the access token is valid for the current authorization.

-1. If the access token has expired but the refresh token is valid, API Management tries to fetch new access and refresh tokens from the configured identity provider.

-1. The identity provider returns both an access token and a refresh token, which are encrypted and saved to API Management.

-1. After the tokens have been retrieved, the access token is attached using the `set-header` policy as an authorization header to the outgoing request to the backend API.

-1. Response is returned to API Management.

-1. Response is returned to the client.

-### Error handling

-If acquiring the authorization context results in an error, the outcome depends on how the attribute `ignore-error` is configured in the policy `get-authorization-context`. If the value is set to `false` (default), an error with `500 Internal Server Error` will be returned. If the value is set to `true`, the error will be ignored and execution will proceed with the context variable set to `null`.

-If the value is set to `false`, and the on-error section in the policy is configured, the error will be available in the property `context.LastError`. By using the on-error section, the error that is sent back to the client can be adjusted. Errors from API Management can be caught using standard Azure alerts. Read more about [handling errors in policies](api-management-error-handling-policies.md).

-### Authorizations FAQ

-##### How can I provide feedback and influence the roadmap for this feature?

-Please use [this](https://aka.ms/apimauthorizations/feedback) form to provide feedback.

-##### How are the tokens stored in API Management?

-The access token and other secrets (for example, client secrets) are encrypted with an envelope encryption and stored in an internal, multitenant storage. The data are encrypted with AES-128 using a key that is unique per data; those keys are encrypted asymmetrically with a master certificate stored in Azure Key Vault and rotated every month.

-##### When are the access tokens refreshed?

-When the policy `get-authorization-context` is executed at runtime, API Management checks if the stored access token is valid. If the token has expired or is near expiry, API Management uses the refresh token to fetch a new access token and a new refresh token from the configured identity provider. If the refresh token has expired, an error is thrown, and the authorization needs to be reauthorized before it will work.

-##### What happens if the client secret expires at the identity provider?

-At runtime API Management can't fetch new tokens, and an error will occur.

-##### Is this feature supported using API Management running inside a VNet?

-Yes, as long as API Management gateway has outbound internet connectivity on port `443`.

-##### What happens when an authorization provider is deleted?

-##### Are the access tokens cached by API Management?

-##### What grant types are supported?

-For public preview, the Azure AD identity provider supports authorization code and client credentials.

-The other identity providers support authorization code. After public preview, more identity providers and grant types will be added.

-### Next steps

- * [OAuth 2.0 overview](https://aaronparecki.com/oauth-2-simplified/)

- * [OAuth 2.0 specification](https://oauth.net/2/)

-description: Reference for identity providers supported in authorizations in Azure API Management. API Management authorizations manage OAuth 2.0 authorization tokens to APIs.

-# Authorizations reference

-This article is a reference for the supported identity providers in API Management [authorizations](authorizations-overview.md) (preview) and their configuration options.

-## Azure Active Directory

-**Supported grant types**: authorization code and client credentials

-### Authorization provider - Authorization code grant type

-| Name | Required | Description | Default |

-|||||

-| Provider name | Yes | Name of Authorization provider. | |

-| Client id | Yes | The id used to identify this application with the service provider. | |

-| Client secret | Yes | The shared secret used to authenticate this application with the service provider. ||

-| Login URL | No | The Azure Active Directory login URL. | https://login.windows.net |

-| Tenant ID | No | The tenant ID of your Azure Active Directory application. | common |

-| Resource URL | Yes | The resource to get authorization for. | |

-| Scopes | No | Scopes used for the authorization. Multiple scopes could be defined separate with a space, for example, "User.Read User.ReadBasic.All" | |

-### Authorization - Authorization code grant type

-| Name | Required | Description | Default |

-|||||

-| Authorization name | Yes | Name of Authorization. | |

-

-### Authorization provider - Client credentials code grant type

-| Name | Required | Description | Default |

-|||||

-| Provider name | Yes | Name of Authorization provider. | |

-| Login URL | No | The Azure Active Directory login URL. | https://login.windows.net |

-| Tenant ID | No | The tenant ID of your Azure Active Directory application. | common |

-| Resource URL | Yes | The resource to get authorization for. | |

-### Authorization - Client credentials code grant type

-| Name | Required | Description | Default |

-|||||

-| Authorization name | Yes | Name of Authorization. | |

-| Client id | Yes | The id used to identify this application with the service provider. | |

-| Client secret | Yes | The shared secret used to authenticate this application with the service provider. ||

-

-## Google, LinkedIn, Spotify, Dropbox, GitHub

-**Supported grant types**: authorization code

-### Authorization provider - Authorization code grant type

-| Name | Required | Description | Default |

-|||||

-| Provider name | Yes | Name of Authorization provider. | |

-| Client id | Yes | The id used to identify this application with the service provider. | |

-| Client secret | Yes | The shared secret used to authenticate this application with the service provider. ||

-| Scopes | No | Scopes used for the authorization. Depending on the identity provider, multiple scopes are separated by space or comma. Default for most identity providers is space. | |

-### Authorization - Authorization code grant type

-| Name | Required | Description | Default |

-|||||

-| Authorization name | Yes | Name of Authorization. | |

-

-## Generic OAuth 2

-**Supported grant types**: authorization code

-### Authorization provider - Authorization code grant type

-| Name | Required | Description | Default |

-|||||

-| Provider name | Yes | Name of Authorization provider. | |

-| Client id | Yes | The id used to identify this application with the service provider. | |

-| Client secret | Yes | The shared secret used to authenticate this application with the service provider. ||

-| Authorization URL | No | The authorization endpoint URL. | |

-| Token URL | No | The token endpoint URL. | |

-| Refresh URL | No | The token refresh endpoint URL. | |

-| Scopes | No | Scopes used for the authorization. Depending on the identity provider, multiple scopes are separated by space or comma. Default for most identity providers is space. | |

-### Authorization - Authorization code grant type

-| Name | Required | Description | Default |

-|||||

-| Authorization name | Yes | Name of Authorization. | |

-## Next steps

-Learn more about [authorizations](authorizations-overview.md) and how to [create and use authorizations](authorizations-how-to.md)

-Use the `get-authorization-context` policy to get the authorization context of a specified [authorization](authorizations-overview.md) (preview) configured in the API Management instance.

-The policy fetches and stores authorization and refresh tokens from the configured authorization provider.

-If `identity-type=jwt` is configured, a JWT token is required to be validated. The audience of this token must be `https://azure-api.net/authorization-manager`.

-| provider-id | The authorization provider resource identifier. | Yes | N/A |

-| authorization-id | The authorization resource identifier. | Yes | N/A |

-| context-variable-name | The name of the context variable to receive the [`Authorization` object](#authorization-object). | Yes | N/A |

-| identity-type | Type of identity to be checked against the authorization access policy. <br> - `managed`: managed identity of the API Management service. <br> - `jwt`: JWT bearer token specified in the `identity` attribute. | No | `managed` |

-| identity | An Azure AD JWT bearer token to be checked against the authorization permissions. Ignored for `identity-type` other than `jwt`. <br><br>Expected claims: <br> - audience: `https://azure-api.net/authorization-manager` <br> - `oid`: Permission object ID <br> - `tid`: Permission tenant ID | No | N/A |

-| ignore-error | Boolean. If acquiring the authorization context results in an error (for example, the authorization resource is not found or is in an error state): <br> - `true`: the context variable is assigned a value of null. <br> - `false`: return `500` | No | `false` |

-| Claims | Claims returned from the authorization serverΓÇÖs token response API (see [RFC6749#section-5.1](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1)). |

-description: Learn how Hotpatch for Windows Server Azure Edition works and how to enable it

-<!--

-> Hotpatch is currently in Public Preview. An opt-in procedure is needed to use the Hotpatch capability described below.

-> This preview is provided without a service level agreement, and is not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.

-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-> [!IMPORTANT]

-> Hotpatch is supported on _Windows Server 2022 Datacenter: Azure Edition (Server Core)_.

-Hotpatching is a new way to install updates on supported _Windows Server Azure Edition_ virtual machines (VMs) that doesnΓÇÖt require a reboot after installation. This article covers information about Hotpatch for supported _Windows Server Azure Edition_ VMs, which has the following benefits:

-* Better protection, as the Hotpatch update packages are scoped to Windows security updates that install faster without rebooting

-Hotpatch works by first establishing a baseline with a Windows Update Latest Cumulative Update. Hotpatches are periodically released (for example, on the second Tuesday of the month) that build on that baseline. Hotpatches will contain updates that don't require a reboot. Periodically (starting at every three months), the baseline is refreshed with a new Latest Cumulative Update.

-There are two types of baselines: **Planned baselines** and **unplanned baselines**.

-* **Planned baselines** are released on a regular cadence, with hotpatch releases in between. Planned baselines include all the updates in a comparable _Latest Cumulative Update_ for that month, and require a reboot.

-* **Unplanned baselines** are released when an important update (such as a zero-day fix) is released, and that particular update can't be released as a Hotpatch. When unplanned baselines are released, a hotpatch release will be replaced with an unplanned baseline in that month. Unplanned baselines also include all the updates in a comparable _Latest Cumulative Update_ for that month, and also require a reboot.

-To start using Hotpatch on a new VM, follow these steps:

- * You can preview onboarding Automanage machine best practices during VM creation in the Azure portal using [this link](https://aka.ms/AzureEdition).

- * Ensure that a supported _Windows Server Azure Edition_ image is selected in the Image dropdown. Use [this guide](automanage-windows-server-services-overview.md#getting-started-with-windows-server-azure-edition) to determine which images are supported.

- * On the Management tab under section ΓÇÿGuest OS updatesΓÇÖ, the checkbox for 'Enable hotpatch' will be selected. Patch orchestration options will be set to 'Azure-orchestrated'.

- * If you create a VM using [this link](https://aka.ms/AzureEdition), on the Management tab under section 'Azure Automanage', select 'Dev/Test' or 'Production' for 'Azure Automanage environment' to evaluate Automanage machine best practices while in preview.

-With Hotpatch enabled on supported _Windows Server Azure Edition_ VMs, most monthly security updates are delivered as hotpatches that don't require reboots. Latest Cumulative Updates sent on planned or unplanned baseline months will require VM reboots. Additional Critical or Security patches may also be available periodically which may require VM reboots.

-Patches are installed within 30 days of the monthly patch releases, following [availability-first principles](../virtual-machines/automatic-vm-guest-patching.md#availability-first-updates). Patches are installed only during off-peak hours for the VM, depending on the time zone of the VM. The VM must be running during the off-peak hours for patches to be automatically installed. If a VM is powered off during a periodic assessment, the VM will be assessed and applicable patches will be installed automatically during the next periodic assessment when the VM is powered on. The next periodic assessment usually happens within a few days.

-To view the patch status for your VM, navigate to the **Guest + host updates** section for your VM in the Azure portal. Under the **Guest OS updates** section, click on ΓÇÿGo to Hotpatch (Preview)ΓÇÖ to view the latest patch status for your VM.

-On this screen, you'll see the Hotpatch status for your VM. You can also review if there any available patches for your VM that haven't been installed. As described in the ΓÇÿPatch installationΓÇÖ section above, all security and critical updates will be automatically installed on your VM using [Automatic VM Guest Patching](../virtual-machines/automatic-vm-guest-patching.md) and no extra actions are required. Patches with other update classifications aren't automatically installed. Instead, they're viewable in the list of available patches under the ΓÇÿUpdate complianceΓÇÖ tab. You can also view the history of update deployments on your VM through the ΓÇÿUpdate historyΓÇÖ. Update history from the past 30 days is displayed, along with patch installation details.

-Hotpatch covers Windows Security updates and maintains parity with the content of security updates issued to in the regular (non-Hotpatch) Windows update channel.

-There are some important considerations to running a supported _Windows Server Azure Edition_ VM with Hotpatch enabled. Reboots are still required to install updates that aren't included in the Hotpatch program. Reboots are also required periodically after a new baseline has been installed. These reboots keep the VM in sync with non-security patches included in the latest cumulative update.

-* Patches that are currently not included in the Hotpatch program include non-security updates released for Windows, and non-Windows updates (such as .NET patches). These types of patches need to be installed during a baseline month, and will require a reboot.

-### Why should I use Hotpatch?

-* When you use Hotpatch on a supported _Windows Server Azure Edition_ image, your VM will have higher availability (fewer reboots), and faster updates (smaller packages that are installed faster without the need to restart processes). This process results in a VM that is always up to date and secure.

-### What types of updates are covered by Hotpatch?

-### When will I receive the first Hotpatch update?

-### What will the Hotpatch schedule look like?

-* Hotpatching works by establishing a baseline with a Windows Update Latest Cumulative Update, then builds upon that baseline with Hotpatch updates released monthly. Baselines will be released starting out every three months. See the image below for an example of an annual three-month schedule (including example unplanned baselines due to zero-day fixes).

-### Are reboots still needed for a VM enrolled in Hotpatch?

-* Reboots are still required to install updates not included in the Hotpatch program, and are required periodically after a baseline (Windows Update Latest Cumulative Update) has been installed. This reboot will keep your VM in sync with all the patches included in the cumulative update. Baselines (which require a reboot) will start out on a three-month cadence and increase over time.

-### Are my applications affected when a Hotpatch update is installed?

-* Because Hotpatch patches the in-memory code of running processes without the need to restart the process, your applications will be unaffected by the patching process. Note that this is separate from any potential performance and functionality implications of the patch itself.

-### Can I turn off Hotpatch on my VM?

-* You can turn off Hotpatch on a VM via the Azure portal. Turning off Hotpatch will unenroll the VM from Hotpatch, which reverts the VM to typical update behavior for Windows Server. Once you unenroll from Hotpatch on a VM, you can re-enroll that VM when the next Hotpatch baseline is released.

-### How can I get troubleshooting support for Hotpatching?

-<!--

-> Hotpatch is currently in Public Preview. An opt-in procedure is needed to use the Hotpatch capability described below.

-> This preview is provided without a service level agreement, and is not recommended for production workloads. Certain features might not be supported or might have constrained capabilities.

-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-Hotpatch gives you the ability to apply security updates on your VM without rebooting. Additionally, Automanage for Windows Server automates the onboarding, configuration, and orchestration of hot patching. To learn more, see [Hotpatch](automanage-hotpatch.md).

-

-It's important to consider up front, which Automanage for Windows Server capabilities you would like to use, then choose a corresponding VM image that supports all of those capabilities. Some of the _Windows Server Azure Edition_ images support only a subset of capabilities, see the table below for more details.

-<!--

-> [Learn more about Azure Automanage](overview-about.md)

-[Render service V2] introduces a new version of the [Get Map Tile V2 API] that supports using Azure Maps tiles not only in the Azure Maps SDKs but other map controls as well. It includes raster and vector tile formats, 256x256 or 512x512 tile sizes (where applicable) and numerous map types such as road, weather, contour, or map tiles. For a complete list, see [TilesetID] in the REST API documentation. It's recommended that you use Render service V2 instead of Render service V1. You're required to display the appropriate copyright attribution on the map anytime you use the Azure Maps Render service V2, either as basemaps or layers, in any third-party map control. For more information, see [How to use the Get Map Attribution API].

-[Render service V2]: /rest/api/maps/render-v2

-description: How to configure a browser-less application which supports sign-in to Azure AD and calls Azure Maps REST APIs.

-# Secure an input constrained device with Azure AD and Azure Maps REST APIs

-This guide discusses how to secure public applications or devices that cannot securely store secrets or accept browser input. These types of applications fall under the category of IoT or internet of things. Some examples of these applications may include: Smart TV devices or sensor data emitting applications.

-> * **Prerequisite Reading:** [Scenario: Desktop app that calls web APIs](../active-directory/develop/scenario-desktop-overview.md)

-Create the device based application in Azure AD to enable Azure AD sign in. This application will be granted access to Azure Maps REST APIs.

- > [!div class="mx-imgBorder"]

- > 

-2. Enter a **Name**, choose **Accounts in this organizational directory only** as the **Supported account type**. In **Redirect URIs**, specify **Public client / native (mobile & desktop)** then add `https://login.microsoftonline.com/common/oauth2/nativeclient` to the value. For more details please see Azure AD [Desktop app that calls web APIs: App registration](../active-directory/develop/scenario-desktop-app-registration.md). Then **Register** the application.

- > [!div class="mx-imgBorder"]

- > 

-3. Navigate to **Authentication** and enable **Treat application as a public client**. This will enable device code authentication with Azure AD.

- > [!div class="mx-imgBorder"]

- > 

- > [!div class="mx-imgBorder"]

- > 

- > [!div class="mx-imgBorder"]

- > 

-6. Configure Azure role-based access control (Azure RBAC) for users or groups. See [Grant role-based access for users to Azure Maps](#grant-role-based-access-for-users-to-azure-maps).

-7. Add code for acquiring token flow in the application, for implementation details see [Device code flow](../active-directory/develop/scenario-desktop-acquire-token-device-code-flow.md). When acquiring tokens, reference the scope: `user_impersonation` which was selected on earlier steps.

- > See recommendations on [Desktop app that calls web APIs: Code configuration](../active-directory/develop/scenario-desktop-app-configuration.md)

- The sample request body below is in GeoJSON:

-> [View usage metrics](how-to-view-api-usage.md)

-This article describes how to secure a single-page web application with Azure Active Directory (Azure AD), when the user isn't able to sign in to Azure AD.

-To create this non-interactive authentication flow, we'll create an Azure Function secure web service that's responsible for acquiring access tokens from Azure AD. This web service will be exclusively available only to your single-page web application.

-> [!Tip]

-1. Create a function in the Azure portal. For more information, see [Getting started with Azure Functions](../azure-functions/functions-get-started.md).

-2. Configure CORS policy on the Azure function to be accessible by the single-page web application. The CORS policy secures browser clients to the allowed origins of your web application. For more information, see [Add CORS functionality](../app-service/app-service-web-tutorial-rest-api.md#add-cors-functionality).

-3. [Add a system-assigned identity](../app-service/overview-managed-identity.md?tabs=dotnet#add-a-system-assigned-identity) on the Azure function to enable creation of a service principal to authenticate to Azure AD.

-4. Grant role-based access for the system-assigned identity to the Azure Maps account. For details, see [Grant role-based access](#grant-role-based-access-for-users-to-azure-maps).

-5. Write code for the Azure function to obtain Azure Maps access tokens using system-assigned identity with one of the supported mechanisms or the REST protocol. For more information, see [Obtain tokens for Azure resources](../app-service/overview-managed-identity.md?tabs=dotnet#add-a-system-assigned-identity)

- 1. [Create a function access key](../azure-functions/functions-bindings-http-webhook-trigger.md?tabs=csharp#authorization-keys)

-description: How to configure a single page application which supports Azure AD single-sign-on with Azure Maps Web SDK.

-The following guide pertains to an application which is hosted on a content server or has minimal web server dependencies. The application provides protected resources secured only to Azure AD users. The objective of the scenario is to enable the web application to authenticate to Azure AD and call Azure Maps REST APIs on behalf of the user.

- > [!div class="mx-imgBorder"]

- > 

-2. Enter a **Name**, choose a **Support account type**, provide a redirect URI which will represent the url which Azure AD will issue the token and is the url where the map control is hosted. For a detailed sample please see [Azure Maps Azure AD samples](https://github.com/Azure-Samples/Azure-Maps-AzureAD-Samples/tree/master/src/ImplicitGrant). Then select **Register**.

- > [!div class="mx-imgBorder"]

- > 

- > [!div class="mx-imgBorder"]

- > 

-

-description: The map copyright attribution information must be displayed in any applications that use the Render V2 API, including web and mobile applications. In this article, you'll learn how to display the correct attribution every time you display or update a tile.

-When using the [Azure Maps Render service V2], either as a basemap or layer, you're required to display the appropriate data provider copyright attribution on the map. This information should be displayed in the lower right-hand corner of the map.

-The above image is an example of a map from the Render service V2, displaying the road style. It shows the copyright attribution in the lower right-hand corner of the map.

-The above image is an example of a map from the Render service V2, displaying the satellite style. note that there's another data provider listed.

-The attribution is automatically displayed and updated on the map When using any of the Azure Maps SDKs. This includes the [Web SDK], [Android SDK] and the [iOS SDK].

-You'll need the following information to run the `attribution` command:

-* For more information, see the [Azure Maps Render service V2] documentation.

-[Azure Maps Render service V2]: /rest/api/maps/render-v2

-[Web SDK]: how-to-use-map-control.md

-[Android SDK]: how-to-use-android-map-control-library.md

-[iOS SDK]: how-to-use-ios-map-control-library.md

-[Tileset Create API]: /rest/api/maps/v2/tileset/create

-[Zoom levels and tile grid]: zoom-levels-and-tile-grid.md

-[Authentication with Azure Maps]: azure-maps-authentication.md

-The Route Directions and Route Matrix APIs in Azure Maps [Route service] can be used to calculate the estimated arrival times (ETAs) for each requested route. Route APIs consider factors such as real-time traffic information and historic traffic data, like the typical road speeds on the requested day of the week and time of day. The APIs return the shortest or fastest routes available to multiple destinations at a time in sequence or in optimized order, based on time or distance. Users can also request specialized routes and details for walkers, bicyclists, and commercial vehicles like trucks. In this article, we'll share the best practices to call Azure Maps [Route service], and you'll learn how-to:

-The Route Directions APIs return instructions including the travel time and the coordinates for a route path. The Route Matrix API lets you calculate the travel time and distances for a set of routes that are defined by origin and destination locations. For every given origin, the Matrix API calculates the cost (travel time and distance) of routing from that origin to every given destination. These API allow you to specify parameters such as the desired departure time, arrival times, and the vehicle type, like car or truck. They all use real-time or predictive traffic data accordingly to return the most optimal routes.

-Here is a comparison to show some capabilities of the Route Directions and Matrix APIs:

-By default, the Route service assumes the traveling mode is a car and the departure time is now. It returns route based on real-time traffic conditions unless a route calculation request specifies otherwise. Fixed time-dependent traffic restrictions, like 'Left turns aren't allowed between 4:00 PM to 6:00 PM' are captured and will be considered by the routing engine. Road closures, like roadworks, will be considered unless you specifically request a route that ignores the current live traffic. To ignore the current traffic, set `traffic` to `false` in your API request.

-The route calculation **travelTimeInSeconds** value includes the delay due to traffic. It's generated by leveraging the current and historic travel time data, when departure time is set to now. If your departure time is set in the future, the APIs return predicted travel times based on historical data.

-If you include the **computeTravelTimeFor=all** parameter in your request, then the summary element in the response will have the following additional fields including historical traffic conditions:

-The response contains a summary element, like the one below. Because the departure time is set to the future, the **trafficDelayInSeconds** value is zero. The **travelTimeInSeconds** value is calculated using time-dependent historic traffic data. So, in this case, the **travelTimeInSeconds** value is equal to the **historicTrafficTravelTimeInSeconds** value.

-In the second example below, we have a real-time routing request, where departure time is now. It's not explicitly specified in the URL because it's the default value.

-The response contains a summary as shown below. Because of congestions, the **trafficDelaysInSeconds** value is greater than zero. It's also greater than **historicTrafficTravelTimeInSeconds**.

-By default, the Route service will return an array of coordinates. The response will contain the coordinates that make up the path in a list named `points`. Route response also includes the distance from the start of the route and the estimated elapsed time. These values can be used to calculate the average speed for the entire route.

-Changing the US Hazmat Class, from the above query, will result in a different route to accommodate this change.

-The response below is for a truck carrying a class 9 hazardous material, which is less dangerous than a class 1 hazardous material. When you expand the `guidance` element to read the directions, you'll notice that the directions aren't the same. There are more route instructions for the truck carrying class 1 hazardous material.

-This option can be used to color the sections when rendering the map, as in the image below:

-For multi-stop routing, up to 150 waypoints may be specified in a single route request. The starting and ending coordinate locations can be the same, as would be the case with a round trip. But you need to provide at least one additional waypoint to make the route calculation. Waypoints can be added to the query in-between the origin and destination coordinates.

-The image below illustrates the path resulting from this query. This path is one possible route. It's not the optimal path based on time or distance.

-The image below illustrates the path resulting from this query.

-When calling [Post Route Directions], you can set the minimum deviation time or the distance constraints, along with the supporting points. Use these parameters if you want to offer alternative routes, but you also want to limit the travel time. When these constraints are used, the alternative routes will follow the reference route from the origin point for the given time or distance. In other words, the other routes diverge from the reference route per the given constraints.

-The image below is an example of rendering alternative routes with specified deviation limits for the time and the distance.

-> [Azure Maps Route service](/rest/api/maps/route)

-> [How to use the Service module](./how-to-use-services-module.md)

-> [Show route on the map](./map-route.md)

-> [Azure Maps npm Package](https://www.npmjs.com/package/azure-maps-rest )

-[Route service]: /rest/api/maps/route

-[subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account

-[Routing Coverage]: routing-coverage.md

-[Postman]: https://www.postman.com/downloads/

-[RouteType]: /rest/api/maps/route/postroutedirections#routetype

-[Post Route Directions]: /rest/api/maps/route/postroutedirections

-[Azure Maps Data feedback site](https://feedback.azuremaps.com) provides an easy way for our customers to provide map data feedback, especially on business points of interest and residential addresses. This article guides you on how to provide different kinds of feedback using the Azure Maps feedback site.

-## Add a business place or a residential address

-You may want to provide feedback about a missing point of interest or a residential address. There are two ways to do so. Open the Azure Map data feedback site, search for the missing location's coordinates, and then click "Add a place"

-Or, you can interact with the map. Click on the location to drop a pin at the coordinate and click "Add a place".

-Upon clicking, you'll be directed to a form to provide the corresponding details for the place.

-## Fix a business place or a residential address

-The feedback site also allows you to search and locate a business place or an address. You can provide feedback to fix the address or the pin location, if they aren't correct. To provide feedback to fix the address, use the search bar to search for a business place or residential address. Click on the location of your interest from the results list. Click on "Fix this place".

-To provide feedback to fix the address, fill out the "Fix a place" form, and then click on the "submit" button.

-If the pin location for the place is wrong, check the checkbox on the "Fix a place" form that says "The pin location is incorrect". Move the pin to the correct location, and then click the "submit" button.

-## Add a comment

-In addition to letting you search for a location, the feedback tool also lets you add a free form text comment for details related to the location. To add a comment, search for the location or click on the location. Click "Add a comment", write a comment, and then click "Submit".

-## Track status

-You can also track the status of your request by checking the "I want to track status" box and providing your email while making a request. You will receive a tracking link in the email that provides an up-to-date status of your request.

-To post any technical questions related to Azure Maps, visit:

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

-Prometheus alert rules allow you to define alert conditions, using queries which are written in Prometheus Query Language (Prom QL) that are applied on Prometheus metrics stored in [Azure Monitor managed services for Prometheus](../essentials/prometheus-metrics-overview.md). Whenever the alert query results in one or more time series meeting the condition, the alert counts as pending for these metric and label sets. A pending alert becomes active after a user-defined period of time during which all the consecutive query evaluations for the respective time series meet the alert condition. Once an alert becomes active, it is fired and would trigger your actions or notifications of choice, as defined in the Azure Action Groups configured in your alert rule.

-Prometheus alert rules are created as part of a Prometheus rule group which is stored in [Azure Monitor workspace](../essentials/azure-monitor-workspace-overview.md). See [Azure Monitor managed service for Prometheus rule groups](../essentials/prometheus-rule-groups.md) for details.

-## Next steps

-Send diagnostic tracing logs for your ASP.NET/ASP.NET Core application from ILogger, NLog, log4Net, or System.Diagnostics.Trace to [Azure Application Insights][start]. For Python applications, send diagnostic tracing logs by using AzureLogHandler in OpenCensus Python for Azure Monitor. You can then explore and search for them. Those logs are merged with the other log files from your application. You can use them to identify traces that are associated with each user request and correlate them with other events and exception reports.

-[Add Application Insights to your project](./asp-net.md) if you haven't done that yet. You'll see an option to include the log collector.

-Now you can easily filter out in [Search][diagnostic] all the messages of a particular severity level that relate to a particular database.

-In your app's overview pane in the [Application Insights portal][portal], select [Search][diagnostic].

-You probably installed the logging adapter NuGet package without installing Application Insights. In Solution Explorer, right-click *ApplicationInsights.config*, and select **Update Application Insights**. You'll be prompted to sign in to Azure and create an Application Insights resource or reuse an existing one. That should fix the problem.

-* [Diagnose failures and exceptions in ASP.NET][exceptions]

-* [Learn more about Search][diagnostic]

-* [Set up availability and responsiveness tests][availability]

-* [Troubleshooting][qna]

-# Optimize costs in Azure Monitor

-You can significantly reduce your cost for Azure Monitor by understanding your different configuration options and opportunities to reduce the amount of data that it collects. Before you use this article, you should see [Azure Monitor cost and usage](usage-estimated-costs.md) to understand the different ways that Azure Monitor charges and how to view your monthly bill.

-> [!NOTE]

-> This article describes [Cost optimization](/azure/architecture/framework/cost/) for Azure Monitor as part of the [Azure Well-Architected Framework](/azure/architecture/framework/). This is a set of guiding tenets that can be used to improve the quality of a workload. The framework consists of five pillars of architectural excellence:

->

-> - Reliability

-> - Security

-> - Cost Optimization

-> - Operational Excellence

-> - Performance Efficiency

-## Design considerations

-Azure Monitor includes the following design considerations related to cost:

-## Checklist

-**Log Analytics workspace configuration**

-> [!div class="checklist"]

-> - Configure pricing tier or dedicated cluster to optimize your cost depending on your usage.

-> - Configure tables used for debugging, troubleshooting, and auditing as Basic Logs.

-> - Configure data retention and archiving.

-**Data collection**

-> - Use diagnostic settings and transformations to collect only critical resource log data from Azure resources.

-> - Configure VM agents to collect only critical events.

-> - Use transformations to filter resource logs for [supported tables](logs/tables-feature-support.md).

-> - Ensure that VMs aren't sending data to multiple workspaces.

-**Monitor usage**

-> [!div class="checklist"]

-> - Send alert when data collection is high.

-> - Analyze your collected data at regular intervals to determine if there are opportunities to further reduce your cost.

-> - Consider a daily cap as a preventative measure to ensure that you don't exceed a particular budget.

-## Configuration recommendations

-### Log Analytics workspace configuration

-You may be able to significantly reduce your costs by optimizing the configuration of your Log Analytics workspaces. You can commit to a minimum amount of data collection in exchange for a reduced rate, and optimize your costs for the functionality and retention of data in particular tables.

-| Recommendation | Description |

-|:|:|

-| Configure pricing tier or dedicated cluster for your Log Analytics workspaces. | By default, Log Analytics workspaces will use pay-as-you-go pricing with no minimum data volume. If you collect enough amount of data, you can significantly decrease your cost by using a [commitment tier](logs/cost-logs.md#commitment-tiers) or [dedicated cluster](logs/logs-dedicated-clusters.md), which allows you to commit to a daily minimum of data collected in exchange for a lower rate.<br><br>See [Azure Monitor Logs cost calculations and options](logs/cost-logs.md) for details on commitment tiers and guidance on determining which is most appropriate for your level of usage. See [Usage and estimated costs](usage-estimated-costs.md#usage-and-estimated-costs) to view estimated costs for your usage at different pricing tiers.

-| Configure tables used for debugging, troubleshooting, and auditing as Basic Logs. | Tables in a Log Analytics workspace configured for [Basic Logs](logs/basic-logs-configure.md) have a lower ingestion cost in exchange for limited features and a charge for log queries. If you query these tables infrequently, this query cost can be more than offset by the reduced ingestion cost.<br><br>See [Configure Basic Logs in Azure Monitor](logs/basic-logs-configure.md) for more information about Basic Logs and [Query Basic Logs in Azure Monitor](.//logs/basic-logs-query.md) for details on query limitations. |

-| Configure data retention and archiving. | There is a charge for retaining data in a Log Analytics workspace beyond the default of 30 days (90 days in Sentinel if enabled on the workspace). If you need to retain data for compliance reasons or for occasional investigation or analysis of historical data, configure [Archived Logs](logs/data-retention-archive.md), which allows you to retain data for up to seven years at a reduced cost.<br><br>See [Configure data retention and archive policies in Azure Monitor Logs](logs/data-retention-archive.md) for details on how to configure your workspace and how to work with archived data. |

-### Data collection

-Since Azure Monitor charges for the collection of data, your goal should be to collect the minimal amount of data required to meet your monitoring requirements. You have an opportunity to reduce your monitoring costs by modifying your configuration to stop collecting data that you're not using for alerting or analysis.

-#### Azure resources

-| Recommendation | Description |

-| Collect only critical resource log data from Azure resources. | When you create [diagnostic settings](essentials/diagnostic-settings.md) to send [resource logs](essentials/resource-logs.md) for your Azure resources to a Log Analytics database, only specify those categories that you require. Since diagnostic settings don't allow granular filtering of resource logs, you can use a [workspace transformation](essentials/data-collection-transformations.md?#workspace-transformation-dcr) to further filter unneeded data for those resources that use a [supported table](logs/tables-feature-support.md). See [Diagnostic settings in Azure Monitor](essentials/diagnostic-settings.md#controlling-costs) for details on how to configure diagnostic settings and using transformations to filter their data. |

-#### Virtual machines

-| Recommendation | Description |

-|:|:|

-| Configure VM agents to collect only critical events. | Virtual machines can vary significantly in the amount of data they collect, depending on the amount of telemetry generated by the applications and services they have installed. See [Monitor virtual machines with Azure Monitor: Workloads](vm/monitor-virtual-machine-data-collection.md#controlling-costs) for guidance on data to collect and strategies for using XPath queries and transformations to limit it.|

-| Ensure that VMs aren't sending duplicate data. | Any configuration that uses multiple agents on a single machine or where you multi-home agents to send data to multiple workspaces may incur charges for the same data multiple times. If you do multi-home agents, make sure you're sending unique data to each workspace. See [Analyze usage in Log Analytics workspace](logs/analyze-usage.md) for guidance on analyzing your collected data to make sure you aren't collecting duplicate data. If you're migrating between agents, continue to use the Log Analytics agent until you [migrate to the Azure Monitor agent](./agents/azure-monitor-agent-migration.md) rather than using both together unless you can ensure that each is collecting unique data. |

-#### Container insights

-| Recommendation | Description |

-|:|:|

-| Configure agent collection to remove unneeded data. | Analyze the data collected by Container insights as described in [Controlling ingestion to reduce cost](containers/container-insights-cost.md#control-ingestion-to-reduce-cost) and adjust your configuration to stop collection of data in ContainerLogs you don't need. |

-| Modify settings for collection of metric data | You can reduce your costs by modifying the default collection settings Container insights uses for the collection of metric data. See [Enable cost optimization settings (preview)](containers/container-insights-cost-config.md) for details on modifying both the frequency that metric data is collected and the namespaces that are collected. |

-| Limit Prometheus metrics collected | If you configured Prometheus metric scraping, then follow the recommendations at [Controlling ingestion to reduce cost](containers/container-insights-cost.md#prometheus-metrics-scraping) to optimize your data collection for cost. |

-| Configure Basic Logs | [Convert your schema to ContainerLogV2](containers/container-insights-logging-v2.md) which is compatible with Basic logs and can provide significant cost savings as described in [Controlling ingestion to reduce cost](containers/container-insights-cost.md#configure-basic-logs). |

-#### Application Insights

-| Recommendation | Description |

-| Change to Workspace-based Application Insights | Ensure that your Application Insights resources are [Workspace-based](app/create-workspace-resource.md) so that they can leveage new cost savings tools such as [Basic Logs](logs/basic-logs-configure.md), [Commitment Tiers](logs/cost-logs.md#commitment-tiers), [Retention by data type and Data Archive](logs/data-retention-archive.md#set-retention-and-archive-policy-by-table). |

-#### All log data collection

-| Recommendation | Description |

-|:|:|

-| Remove unnecssary data during data ingestion | After following all of the preveious recommendations, consider using Azure Monitor [data collection transformations](essentials/data-collection-transformations.md) to reduce the size of your data during ingestion. |

-## Monitor workspace and analyze usage

-After you've configured your environment and data collection for cost optimization, you need to continue to monitor it to ensure that you don't experience unexpected increases in billable usage. You should also analyze your usage regularly to determine if you have other opportunities to further filter out collected data that hasn't proven to be useful.

-| Recommendation | Description |

-|:|:|

-| Send alert when data collection is high. | To avoid unexpected bills, you should be proactively notified anytime you experience excessive usage. Notification allows you to address any potential anomalies before the end of your billing period. See [Send alert when data collection is high](logs/analyze-usage.md#send-alert-when-data-collection-is-high) for details. |

-| Analyze collected data | Periodically analyze data collection using methods in [Analyze usage in Log Analytics workspace](logs/analyze-usage.md) to determine if there's additional configuration that can decrease your usage further. This is particularly important when you add a new set of data sources, such as a new set of virtual machines or onboard a new service. |

-| Consider a daily cap as a preventative measure to ensure that you don't exceed a particular budget. | A [daily cap](logs/daily-cap.md) disables data collection in a Log Analytics workspace for the rest of the day after your configured limit is reached. This shouldn't be used as a method to reduce costs as described in [When to use a daily cap](logs/daily-cap.md). See [Set daily cap on Log Analytics workspace](logs/daily-cap.md) for information on how the daily cap works and how to configure one. |

-Distributed tracing in Azure Monitor is enabled with the [Application Insights SDK](app/distributed-tracing.md). Trace data is stored with other application log data collected by Application Insights. This way it's available to the same analysis tools as other log data including log queries, dashboards, and alerts.

-Read more about distributed tracing at [What is distributed tracing?](app/distributed-tracing.md).

-| | Dependency information between application components to support Application Map and telemetry correlation. | [Telemetry correlation in Application Insights](app/correlation.md) <br> [Application Map](app/app-map.md) |

-> In some multi-workspace scenarios, the CPU and data measurements won't be accurate and will represent the measurement of only a few of the workspaces.

-| [Segregate operational and security data](#segregate-operational-and-security-data) | Many customers will create separate workspaces for their operational and security data for data ownership and the extra cost from Microsoft Sentinel. In some cases, you might be able to save costs by consolidating into a single workspace to qualify for a commitment tier. |

-### Segregate operational and security data

-Most customers who use both Azure Monitor and Microsoft Sentinel will create a dedicated workspace for each to segregate ownership of data between operational and security teams. This approach also helps to optimize costs. If Microsoft Sentinel is enabled in a workspace, all data in that workspace is subject to Microsoft Sentinel pricing, even if it's operational data collected by Azure Monitor.

-The exception is if combining data in the same workspace helps you reach a [commitment tier](#commitment-tiers), which provides a discount to your ingestion charges. For example, consider an organization that has operational data and security data each ingesting about 50 GB per day. Combining the data in the same workspace would allow a commitment tier at 100 GB per day. That scenario would provide a 15% discount for Azure Monitor and a 50% discount for Microsoft Sentinel.

-Each Log Analytics workspaces resides in a [particular Azure region](https://azure.microsoft.com/global-infrastructure/geographies/). You might have regulatory or compliance purposes for keeping data in a particular region. For example, an international company might locate a workspace in each major geographical region, such as the United States and Europe.

- ```bash

- func new -n index -t HttpTrigger

- ```

- ```json

- {

- "bindings": [

- {

- "authLevel": "anonymous",

- "type": "httpTrigger",

- "direction": "in",

- "name": "req",

- "methods": [

- "get",

- "post"

- ]

- },

- {

- "type": "http",

- "direction": "out",

- "name": "res"

- }

- ]

- }

- ```

- ```javascript

- var fs = require('fs').promises

- module.exports = async function (context, req) {

- const path = context.executionContext.functionDirectory + '/../content/https://docsupdatetracker.net/index.html'

- try {

- var data = await fs.readFile(path);

- context.res = {

- headers: {

- 'Content-Type': 'text/html'

- },

- body: data

- }

- context.done()

- } catch (err) {

- context.log.error(err);

- context.done(err);

- }

- }

- ```

- ```bash

- func new -n negotiate -t HttpTrigger

- ```

- ```json

- {

- "disabled": false,

- "bindings": [

- {

- "authLevel": "anonymous",

- "type": "httpTrigger",

- "direction": "in",

- "methods": [

- "post"

- ],

- "name": "req",

- "route": "negotiate"

- },

- {

- "type": "http",

- "direction": "out",

- "name": "res"

- },

- {

- "type": "signalRConnectionInfo",

- "name": "connectionInfo",

- "hubName": "serverless",

- "connectionStringSetting": "AzureSignalRConnectionString",

- "direction": "in"

- }

- ]

- }

- ```

- ```bash

- func new -n broadcast -t TimerTrigger

- ```

- ```json

- {

- "bindings": [

- {

- "name": "myTimer",

- "type": "timerTrigger",

- "direction": "in",

- "schedule": "*/5 * * * * *"

- },

- {

- "type": "signalR",

- "name": "signalRMessages",

- "hubName": "serverless",

- "connectionStringSetting": "AzureSignalRConnectionString",

- "direction": "out"

- }

- ]

- }

- ```

-

- ```javascript

- var https = require('https');

-

- var etag = '';

- var star = 0;

-

- module.exports = function (context) {

- var req = https.request("https://api.github.com/repos/azure/azure-signalr", {

- method: 'GET',

- headers: {'User-Agent': 'serverless', 'If-None-Match': etag}

- }, res => {

- if (res.headers['etag']) {

- etag = res.headers['etag']

- }

-

- var body = "";

-

- res.on('data', data => {

- body += data;

- });

- res.on("end", () => {

- if (res.statusCode === 200) {

- var jbody = JSON.parse(body);

- star = jbody['stargazers_count'];

- }

-

- context.bindings.signalRMessages = [{

- "target": "newMessage",

- "arguments": [ `Current star count of https://github.com/Azure/azure-signalr is: ${star}` ]

- }]

- context.done();

- });

- }).on("error", (error) => {

- context.log(error);

- context.res = {

- status: 500,

- body: error

- };

- context.done();

- });

- req.end();

- }

- ```

-Emotion detection is an Azure Video Indexer AI feature that automatically detects emotions a video's transcript lines. Each sentence can either be detected as "Anger", "Fear", "Joy", "Neutral", and "Sad". The model works on text only (labeling emotions in video transcripts.) This model doesn't infer the emotional state of people, may not perform where input is ambiguous or unclear, like sarcastic remarks. Thus, the model shouldn't be used for things like assessing employee performance or the emotional state of a person.

-The model doesn't have context of the input data, which can impact its accuracy. To increase the accuracy, it's recommended for the input data to be in a clear and unambiguous format.

-## Example use cases

-* Personalization of keywords to match customer interests, for example websites about England posting promotions about English movies or festivals.

-* Deep-searching archives for insights on specific keywords to create feature stories about companies, personas or technologies, for example by a news agency.

- "BrandsCategories": null

-## Observed people tracing improvements

-

-

-

-2. Select **Access polices**

-3. Ensure the access policies include the following property:

-| Cloud Service | Cloud Service with a deployment in a single slot only. | Cloud Services containing a prod slot deployment can be migrated. It is not reccomended to migrate staging slot as this can result in issues with retaining service FQDN |

-distribution=$(. /etc/os-release;echo $ID$VERSION_ID)

-curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

-* Pre-configured, which means the AI models that the feature uses are not customizable. You just send your data, and use the feature's output in your applications.

- [Named entity recognition](./named-entity-recognition/overview.md) is a pre-configured feature that categorizes entities (words or phrases) in unstructured text across several pre-defined category groups. For example: people, events, places, dates, [and more](./named-entity-recognition/concepts/named-entity-categories.md).

- [PII detection](./personally-identifiable-information/overview.md) is a pre-configured feature that identifies, categorizes, and redacts sensitive information in both [unstructured text documents](./personally-identifiable-information/how-to-call.md), and [conversation transcripts](./personally-identifiable-information/how-to-call-for-conversations.md). For example: phone numbers, email addresses, forms of identification, [and more](./personally-identifiable-information/concepts/entity-categories.md).

- [Language detection](./language-detection/overview.md) is a pre-configured feature that can detect the language a document is written in, and returns a language code for a wide range of languages, variants, dialects, and some regional/cultural languages.

- [Sentiment analysis and opinion mining](./sentiment-opinion-mining/overview.md) are pre-configured features that help you find out what people think of your brand or topic by mining text for clues about positive or negative sentiment, and can associate them with specific aspects of the text.

- [Summarization](./summarization/overview.md) is a pre-configured feature that uses extractive text summarization to produce a summary of documents and conversation transcriptions. It extracts sentences that collectively represent the most important or relevant information within the original content.

- [Key phrase extraction](./key-phrase-extraction/overview.md) is a pre-configured feature that evaluates and returns the main concepts in unstructured text, and returns them as a list.

- [Entity linking](./entity-linking/overview.md) is a pre-configured feature that disambiguates the identity of entities (words or phrases) found in unstructured text and returns links to Wikipedia.

- [Text analytics for health](./text-analytics-for-health/overview.md) is a pre-configured feature that extracts and labels relevant medical information from unstructured texts such as doctor's notes, discharge summaries, clinical documents, and electronic health records.

-| Extract categories of information without creating a custom model. | Unstructured text | The [pre-configured NER feature](./named-entity-recognition/overview.md) | |

-| Extract medical information from clinical/medical documents. | Unstructured text | [Text analytics for health](./text-analytics-for-health/overview.md) | |

-| Build an conversational application that responds to user inputs. | Unstructured user inputs | [Question answering](./question-answering/overview.md) | Γ£ô |

-\* If a feature is customizable, you can train an AI model using our tools to fit your data specifically. Otherwise a feature is pre-configured, meaning the AI models it uses cannot be changed. You just send your data, and use the feature's output in your applications.

-description: Learn about Call Summary and Call Diagnostic Logs in Azure Monitor

-# Call Summary and Call Diagnostic Logs

-> [!IMPORTANT]

-> The following refers to logs enabled through [Azure Monitor](../../../azure-monitor/overview.md) (see also [FAQ](../../../azure-monitor/faq.yml)). To enable these logs for your Communications Services, see: [Enable logging in Diagnostic Settings](./enable-logging.md)

-## Data Concepts

-The following are high level descriptions of data concepts specific to Voice and Video calling within your Communications Services that are important to review in order to understand the meaning of the data captured in the logs.

-### Entities and IDs

-A *Call*, as it relates to the entities represented in the data, is an abstraction represented by the `correlationId`. `CorrelationId`s are unique per Call, and are time-bound by `callStartTime` and `callDuration`. Every Call is an event that contains data from two or more *Endpoints*, which represent the various human, bot, or server participants in the Call.

-A *Participant* (`participantId`) is present only when the Call is a *Group* Call, as it represents the connection between an Endpoint and the server.

-An *Endpoint* is the most unique entity, represented by `endpointId`. `EndpointType` tells you whether the Endpoint represents a human user (PSTN, VoIP), a Bot (Bot), or the server that is managing multiple Participants within a Call. When an `endpointType` is `"Server"`, the Endpoint will not be assigned a unique ID. By analyzing endpointType and the number of `endpointIds`, you can determine how many users and other non-human Participants (bots, servers) join a Call. Our native SDKs (Androis, iOS) reuse the same `endpointId` for a user across multiple Calls, thus enabling an understanding of experience across sessions. This differs from web-based Endpoints, which will always generate a new `endpointId` for each new Call.

-A *Stream* is the most granular entity, as there is one Stream per direction (inbound/outbound) and `mediaType` (e.g. audio, video).

-## Data Definitions

-### Call Summary Log

-The Call Summary Log contains data to help you identify key properties of all Calls. A different Call Summary Log will be created per each `participantId` (`endpointId` in the case of P2P calls) in the Call.

-> [!IMPORTANT]

-> Participant information in the call summary log will vary based on the participant tenant. The SDK and OS version will be redacted if the participant is not within the same tenant (also referred to as cross-tenant) as the ACS resource. Cross-tenantsΓÇÖ participants are classified as external users invited by a resource tenant to join and collaborate during a call.

-| Property | Description |

-|-||

-| time | The timestamp (UTC) of when the log was generated. |

-| operationName | The operation associated with log record. |

-| operationVersion | The api-version associated with the operation, if the `operationName` was performed using an API. If there is no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the `properties` blob of an event are the same within a particular log category and resource type. |

-| correlationId | `correlationId` is the unique ID for a Call. The `correlationId` identifies correlated events from all of the participants and endpoints that connect during a single Call, and it can be used to join data from different logs. If you ever need to open a support case with Microsoft, the `correlationId` will be used to easily identify the Call you're troubleshooting. |

-| identifier | This is the unique ID for the user. The identity can be an Azure Communications Services user, Azure AD user ID, Teams anonymous user ID or Teams bot ID. You can use this ID to correlate user events across different logs. |

-| callStartTime | A timestamp for the start of the call, based on the first attempted connection from any Endpoint. |

-| callDuration | The duration of the Call expressed in seconds, based on the first attempted connection and end of the last connection between two endpoints. |

-| callType | Will contain either `"P2P"` or `"Group"`. A `"P2P"` Call is a direct 1:1 connection between only two, non-server endpoints. A `"Group"` Call is a Call that has more than two endpoints or is created as `"Group"` Call prior to the connection. |

-| teamsThreadId | This ID is only relevant when the Call is organized as a Microsoft Teams meeting, representing the Microsoft Teams ΓÇô Azure Communication Services interoperability use-case. This ID is exposed in operational logs. You can also get this ID through the Chat APIs. |

-| participantId | This ID is generated to represent the two-way connection between a `"Participant"` Endpoint (`endpointType` = `"Server"`) and the server. When `callType` = `"P2P"`, there is a direct connection between two endpoints, and no `participantId` is generated. |

-| participantStartTime | Timestamp for beginning of the first connection attempt by the participant. |

-| participantDuration | The duration of each Participant connection in seconds, from `participantStartTime` to the timestamp when the connection is ended. |

-| participantEndReason | Contains Calling SDK error codes emitted by the SDK when relevant for each `participantId`. See Calling SDK error codes below. |

-| endpointId | Unique ID that represents each Endpoint connected to the call, where the Endpoint type is defined by `endpointType`. When the value is `null`, the connected entity is the Communication Services server (`endpointType`= `"Server"`). `EndpointId` can sometimes persist for the same user across multiple calls (`correlationId`) for native clients. The number of `endpointId`s will determine the number of Call Summary Logs. A distinct Summary Log is created for each `endpointId`. |

-| endpointType | This value describes the properties of each Endpoint connected to the Call. Can contain `"Server"`, `"VOIP"`, `"PSTN"`, `"BOT"`, or `"Unknown"`. |

-| sdkVersion | Version string for the Communication Services Calling SDK version used by each relevant Endpoint. (Example: `"1.1.00.20212500"`) |

-| osVersion | String that represents the operating system and version of each Endpoint device. |

-| participantTenantId | The ID of the Microsoft tenant associated with the participant. This field is used to guide cross-tenant redaction.

-### Call Diagnostic Log

-Call Diagnostic Logs provide important information about the Endpoints and the media transfers for each Participant, as well as measurements that help to understand quality issues.

-For each Endpoint within a Call, a distinct Call Diagnostic Log is created for outbound media streams (audio, video, etc.) between Endpoints.

-In a P2P Call, each log contains data relating to each of the outbound stream(s) associated with each Endpoint. In Group Calls the participantId serves as key identifier to join the related outbound logs into a distinct Participant connection. Please note that Call diagnostic logs will remain intact and will be the same regardless of the participant tenant.

-> Note: In this document P2P and group calls are by default within the same tenant, for all call scenarios that are cross-tenant they will be specified accordingly throughout the document.

-| Property | Description |

-||-|

-| operationName | The operation associated with log record. |

-| operationVersion | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there is no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the `properties` blob of an event are the same within a particular log category and resource type. |

-| correlationId | The `correlationId` identifies correlated events from all of the participants and endpoints that connect during a single Call. `correlationId` is the unique ID for a Call. If you ever need to open a support case with Microsoft, the `correlationId` will be used to easily identify the Call you're troubleshooting. |

-| participantId | This ID is generated to represent the two-way connection between a "Participant" Endpoint (`endpointType` = `ΓÇ£ServerΓÇ¥`) and the server. When `callType` = `"P2P"`, there is a direct connection between two endpoints, and no `participantId` is generated. |

-| identifier | This is the unique ID for the user. The identity can be an Azure Communications Services user, Azure AD user ID, Teams object ID or Teams bot ID. You can use this ID to correlate user events across different logs. |

-| endpointId | Unique ID that represents each Endpoint connected to the call, with Endpoint type defined by `endpointType`. When the value is `null`, it means that the connected entity is the Communication Services server. `EndpointId` can persist for the same user across multiple calls (`correlationId`) for native clients but will be unique for every Call when the client is a web browser. |

-| endpointType | This value describes the properties of each `endpointId`. Can contain `ΓÇ£ServerΓÇ¥`, `ΓÇ£VOIPΓÇ¥`, `ΓÇ£PSTNΓÇ¥`, `ΓÇ£BOTΓÇ¥`, `"Voicemail"`, `"Anonymous"`, or `"Unknown"`. |

-| mediaType | This string value describes the type of media being transmitted between endpoints within each stream. Possible values include `ΓÇ£AudioΓÇ¥`, `ΓÇ£VideoΓÇ¥`, `ΓÇ£VBSSΓÇ¥` (Video-Based Screen Sharing), and `ΓÇ£AppSharingΓÇ¥`. |

-| streamId | Non-unique integer which, together with `mediaType`, can be used to uniquely identify streams of the same `participantId`. |

-| transportType | String value which describes the network transport protocol per `participantId`. Can contain `"UDPΓÇ¥`, `ΓÇ£TCPΓÇ¥`, or `ΓÇ£UnrecognizedΓÇ¥`. `"Unrecognized"` indicates that the system could not determine if the `transportType` was TCP or UDP. |

-| roundTripTimeAvg | This is the average time it takes to get an IP packet from one Endpoint to another within a `participantDuration`. This network propagation delay is essentially tied to physical distance between the two points and the speed of light, including additional overhead taken by the various routers in between. The latency is measured as one-way or Round-trip Time (RTT). Its value expressed in milliseconds, and an RTT greater than 500ms should be considered as negatively impacting the Call quality. |

-| roundTripTimeMax | The maximum RTT (ms) measured per media stream during a `participantDuration` in a group Call or `callDuration` in a P2P Call. |

-| jitterAvg | This is the average change in delay between successive packets. Azure Communication Services can adapt to some levels of jitter through buffering. It's only when the jitter exceeds the buffering, which is approximately at `jitterAvg` >30 ms, that a negative quality impact is likely occurring. The packets arriving at different speeds cause a speaker's voice to sound robotic. This is measured per media stream over the `participantDuration` in a group Call or `callDuration` in a P2P Call. |

-| jitterMax | The is the maximum jitter value measured between packets per media stream. Bursts in network conditions can cause issues in the audio/video traffic flow. |

-| packetLossRateAvg | This is the average percentage of packets that are lost. Packet loss directly affects audio qualityΓÇöfrom small, individual lost packets that have almost no impact to back-to-back burst losses that cause audio to cut out completely. The packets being dropped and not arriving at their intended destination cause gaps in the media, resulting in missed syllables and words, and choppy video and sharing. A packet loss rate of greater than 10% (0.1) should be considered a rate that's likely having a negative quality impact. This is measured per media stream over the `participantDuration` in a group Call or `callDuration` in a P2P Call. |

-| packetLossRateMax | This value represents the maximum packet loss rate (%) per media stream over the `participantDuration` in a group Call or `callDuration` in a P2P Call. Bursts in network conditions can cause issues in the audio/video traffic flow.

-### P2P vs. Group Calls

-There are two types of Calls (represented by `callType`): P2P and Group.

-**P2P** calls are a connection between only two Endpoints, with no server Endpoint. P2P calls are initiated as a Call between those Endpoints and are not created as a group Call event prior to the connection.

- :::image type="content" source="media\call-logs-azure-monitor\p2p-diagram.png" alt-text="Screenshot displays P2P call across 2 endpoints.":::

-**Group** Calls include any Call that has more than 2 Endpoints connected. Group Calls will include a server Endpoint, and the connection between each Endpoint and the server. P2P Calls that add an additional Endpoint during the Call cease to be P2P, and they become a Group Call. By viewing the `participantStartTime` and `participantDuration`, the timeline of when each Endpoint joined the Call can be determined.

- :::image type="content" source="media\call-logs-azure-monitor\group-call-version-a.png" alt-text="Screenshot displays group call across multiple endpoints.":::

-## Log Structure

-Two types of logs are created: **Call Summary** logs and **Call Diagnostic** logs.

-Call Summary Logs contain basic information about the Call, including all the relevant IDs, timestamps, Endpoint and SDK information. For each participant within a call, a distinct call summary log is created (if someone rejoins a call, they will have the same EndpointId, but a different ParticipantId, so there will be two Call Summary logs for that endpoint).

-Call Diagnostic Logs contain information about the Stream as well as a set of metrics that indicate quality of experience measurements. For each Endpoint within a Call (including the server), a distinct Call Diagnostic Log is created for each media stream (audio, video, etc.) between Endpoints. In a P2P Call, each log contains data relating to each of the outbound stream(s) associated with each Endpoint. In a Group Call, each stream associated with `endpointType`= `"Server"` will create a log containing data for the inbound streams, and all other streams will create logs containing data for the outbound streams for all non-sever endpoints. In Group Calls, use the `participantId` as the key to join the related inbound/outbound logs into a distinct Participant connection.

-### Example 1: P2P Call

-The below diagram represents two endpoints connected directly in a P2P Call. In this example, 2 Call Summary Logs would be created (one per `participantID`) and four Call Diagnostic Logs would be created (one per media stream). Each log will contain data relating to the outbound stream of the `participantID`.

-### Example 2: Group Call

-The below diagram represents a Group Call example with three `participantIDs`, which means three `participantIDs` (`endpointIds` can potentially appear in multiple Participants, e.g. when rejoining a Call from the same device) and a Server Endpoint. One Call Summary Logs would be created per `participantID`, and four Call Diagnostic Logs would be created relating to each `participantID`, one for each media stream.

-

-### Example 3: P2P Call cross-tenant

-The below diagram represents two participants across multiple tenants that are connected directly in a P2P Call. In this example, one Call Summary Logs would be created (one per participant) with redacted OS and SDK versioning and four Call Diagnostic Logs would be created (one per media stream). Each log will contain data relating to the outbound stream of the `participantID`.

-

-### Example 4: Group Call cross-tenant

-The below diagram represents a Group Call example with three `participantIds` across multiple tenants. One Call Summary Logs would be created per participant with redacted OS and SDK versioning, and four Call Diagnostic Logs would be created relating to each `participantId` , one for each media stream.

-> [!NOTE]

-> Only outbound diagnostic logs will be supported in this release.

-> Please note that participants and bots identity are treated the same way, as a result OS and SDK versioning associated to the bot and the participant will be redacted

-

-## Sample Data

-### P2P Call

-Shared fields for all logs in the call:

-```json

-"time": "2021-07-19T18:46:50.188Z",

-"resourceId": "SUBSCRIPTIONS/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/RESOURCEGROUPS/ACS-TEST-RG/PROVIDERS/MICROSOFT.COMMUNICATION/COMMUNICATIONSERVICES/ACS-PROD-CCTS-TESTS",

-"correlationId": "8d1a8374-344d-4502-b54b-ba2d6daaf0ae",

-```

-#### Call Summary Logs

-Call Summary Logs have shared operation and category information:

-```json

-"operationName": "CallSummary",

-"operationVersion": "1.0",

-"category": "CallSummary",

-```

-Call Summary for VoIP user 1

-```json

-"properties": {

- "identifier": "acs:61fddbe3-0003-4066-97bc-6aaf143bbb84_0000000b-4fee-66cf-ac00-343a0d003158",

- "callStartTime": "2021-07-19T17:54:05.113Z",

- "callDuration": 6,

- "callType": "P2P",

- "teamsThreadId": "null",

- "participantId": "null",

- "participantStartTime": "2021-07-19T17:54:06.758Z",

- "participantDuration": "5",

- "participantEndReason": "0",

- "endpointId": "570ea078-74e9-4430-9c67-464ba1fa5859",

- "endpointType": "VoIP",

- "sdkVersion": "1.0.1.0",

- "osVersion": "Windows 10.0.17763 Arch: x64"

-}

-```

-Call summary for VoIP user 2

-```json

-"properties": {

- "identifier": "acs:7af14122-9ac7-4b81-80a8-4bf3582b42d0_06f9276d-8efe-4bdd-8c22-ebc5434903f0",

- "callStartTime": "2021-07-19T17:54:05.335Z",

- "callDuration": 6,

- "callType": "P2P",

- "teamsThreadId": "null",

- "participantId": "null",

- "participantStartTime": "2021-07-19T17:54:06.335Z",

- "participantDuration": "5",

- "participantEndReason": "0",

- "endpointId": "a5bd82f9-ac38-4f4a-a0fa-bb3467cdcc64",

- "endpointType": "VoIP",

- "sdkVersion": "1.1.0.0",

- "osVersion": "null"

-}

-```

-Call Summary Logs crossed tenants: Call summary for VoIP user 1

-```json

-"properties": {

- "identifier": "1e4c59e1-r1rr-49bc-893d-990dsds8f9f5",

- "callStartTime": "2022-08-14T06:18:27.010Z",

- "callDuration": 520,

- "callType": "P2P",

- "teamsThreadId": "null",

- "participantId": "null",

- "participantTenantId": "02cbdb3c-155a-4b95-b829-6d56a45787ca",

- "participantStartTime": "2022-08-14T06:18:27.010Z",

- "participantDuration": "520",

- "participantEndReason": "0",

- "endpointId": "02cbdb3c-155a-4d98-b829-aaaaa61d44ea",

- "endpointType": "VoIP",

- "sdkVersion": "Redacted",

- "osVersion": "Redacted"

-}

-```

-Call summary for PSTN call (**Please note:** P2P or group call logs emitted will have OS, and SDK version redacted regardless is the participant or botΓÇÖs tenant)

-```json

-"properties": {

- "identifier": "b1999c3e-bbbb-4650-9b23-9999bdabab47",

- "callStartTime": "2022-08-07T13:53:12Z",

- "callDuration": 1470,

- "callType": "Group",

- "teamsThreadId": "19:36ec5177126fff000aaa521670c804a3@thread.v2",

- "participantId": " b25cf111-73df-4e0a-a888-640000abe34d",

- "participantStartTime": "2022-08-07T13:56:45Z",

- "participantDuration": 960,

- "participantEndReason": "0",

- "endpointId": "8731d003-6c1e-4808-8159-effff000aaa2",

- "endpointType": "PSTN",

- "sdkVersion": "Redacted",

- "osVersion": "Redacted"

-}

-```

-#### Call Diagnostic Logs

-Call diagnostics logs share operation information:

-```json

-"operationName": "CallDiagnostics",

-"operationVersion": "1.0",

-"category": "CallDiagnostics",

-```

-Diagnostic log for audio stream from VoIP Endpoint 1 to VoIP Endpoint 2:

-```json

-"properties": {

- "identifier": "acs:61fddbe3-0003-4066-97bc-6aaf143bbb84_0000000b-4fee-66cf-ac00-343a0d003158",

- "participantId": "null",

- "endpointId": "570ea078-74e9-4430-9c67-464ba1fa5859",

- "endpointType": "VoIP",

- "mediaType": "Audio",

- "streamId": "1000",

- "transportType": "UDP",

- "roundTripTimeAvg": "82",

- "roundTripTimeMax": "88",

- "jitterAvg": "1",

- "jitterMax": "1",

- "packetLossRateAvg": "0",

- "packetLossRateMax": "0"

-}

-```

-Diagnostic log for audio stream from VoIP Endpoint 2 to VoIP Endpoint 1:

-```json

-"properties": {

- "identifier": "acs:7af14122-9ac7-4b81-80a8-4bf3582b42d0_06f9276d-8efe-4bdd-8c22-ebc5434903f0",

- "participantId": "null",

- "endpointId": "a5bd82f9-ac38-4f4a-a0fa-bb3467cdcc64",

- "endpointType": "VoIP",

- "mediaType": "Audio",

- "streamId": "1363841599",

- "transportType": "UDP",

- "roundTripTimeAvg": "78",

- "roundTripTimeMax": "84",

- "jitterAvg": "1",

- "jitterMax": "1",

- "packetLossRateAvg": "0",

- "packetLossRateMax": "0"

-}

-```

-Diagnostic log for video stream from VoIP Endpoint 1 to VoIP Endpoint 2:

-```json

-"properties": {

- "identifier": "acs:61fddbe3-0003-4066-97bc-6aaf143bbb84_0000000b-4fee-66cf-ac00-343a0d003158",

- "participantId": "null",

- "endpointId": "570ea078-74e9-4430-9c67-464ba1fa5859",

- "endpointType": "VoIP",

- "mediaType": "Video",

- "streamId": "2804",

- "transportType": "UDP",

- "roundTripTimeAvg": "103",

- "roundTripTimeMax": "143",

- "jitterAvg": "0",

- "jitterMax": "4",

- "packetLossRateAvg": "3.146336E-05",

- "packetLossRateMax": "0.001769911"

-}

-```

-### Group Call

-The data would be generated in three Call Summary Logs and 6 Call Diagnostic Logs. Shared fields for all logs in the Call:

-```json

-"time": "2021-07-05T06:30:06.402Z",

-"resourceId": "SUBSCRIPTIONS/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/RESOURCEGROUPS/ACS-TEST-RG/PROVIDERS/MICROSOFT.COMMUNICATION/COMMUNICATIONSERVICES/ACS-PROD-CCTS-TESTS",

-"correlationId": "341acde7-8aa5-445b-a3da-2ddadca47d22",

-```

-#### Call Summary Logs

-Call Summary Logs have shared operation and category information:

-```json

-"operationName": "CallSummary",

-"operationVersion": "1.0",

-"category": "CallSummary",

-```

-Call summary for VoIP Endpoint 1:

-```json

-"properties": {

- "identifier": "acs:1797dbb3-f982-47b0-b98e-6a76084454f1_0000000b-1531-729f-ac00-343a0d00d975",

- "callStartTime": "2021-07-05T06:16:40.240Z",

- "callDuration": 87,

- "callType": "Group",

- "teamsThreadId": "19:meeting_MjZiOTAyN2YtZWU1Yi00ZTZiLT77777OOOOO99999jgxOTkw@thread.v2",

- "participantId": "04cc26f5-a86d-481c-b9f9-7a40be4d6fba",

- "participantStartTime": "2021-07-05T06:16:44.235Z",

- "participantDuration": "82",

- "participantEndReason": "0",

- "endpointId": "5ebd55df-ffff-ffff-89e6-4f3f0453b1a6",

- "endpointType": "VoIP",

- "sdkVersion": "1.0.0.3",

- "osVersion": "Darwin Kernel Version 18.7.0: Mon Nov 9 15:07:15 PST 2020; root:xnu-4903.272.3~3/RELEASE_ARM64_S5L8960X"

-}

-```

-Call summary for VoIP Endpoint 3:

-```json

-"properties": {

- "identifier": "acs:1797dbb3-f982-47b0-b98e-6a76084454f1_0000000b-1531-57c6-ac00-343a0d00d972",

- "callStartTime": "2021-07-05T06:16:40.240Z",

- "callDuration": 87,

- "callType": "Group",

- "teamsThreadId": "19:meeting_MjZiOTAyN2YtZWU1Yi00ZTZiLTk2ZDUtYTZlM2I2ZjgxOTkw@thread.v2",

- "participantId": "1a9cb3d1-7898-4063-b3d2-26c1630ecf03",

- "participantStartTime": "2021-07-05T06:16:40.240Z",

- "participantDuration": "87",

- "participantEndReason": "0",

- "endpointId": "5ebd55df-ffff-ffff-ab89-19ff584890b7",

- "endpointType": "VoIP",

- "sdkVersion": "1.0.0.3",

- "osVersion": "Android 11.0; Manufacturer: Google; Product: redfin; Model: Pixel 5; Hardware: redfin"

-}

-```

-Call summary for PSTN Endpoint 2:

-```json

-"properties": {

- "identifier": "null",

- "callStartTime": "2021-07-05T06:16:40.240Z",

- "callDuration": 87,

- "callType": "Group",

- "teamsThreadId": "19:meeting_MjZiOTAyN2YtZWU1Yi00ZTZiLT77777OOOOO99999jgxOTkw@thread.v2",

- "participantId": "515650f7-8204-4079-ac9d-d8f4bf07b04c",

- "participantStartTime": "2021-07-05T06:17:10.447Z",

- "participantDuration": "52",

- "participantEndReason": "0",

- "endpointId": "46387150-692a-47be-8c9d-1237efe6c48b",

- "endpointType": "PSTN",

- "sdkVersion": "null",

- "osVersion": "null"

-}

-```

-Call Summary Logs cross-tenant

-```json

-"properties": {

- "identifier": "1e4c59e1-r1rr-49bc-893d-990dsds8f9f5",

- "callStartTime": "2022-08-14T06:18:27.010Z",

- "callDuration": 912,

- "callType": "Group",

- "teamsThreadId": "19:meeting_MjZiOTAyN2YtZWU1Yi00ZTZiLT77777OOOOO99999jgxOTkw@thread.v2",

- "participantId": "aa1dd7da-5922-4bb1-a4fa-e350a111fd9c",

- "participantTenantId": "02cbdb3c-155a-4b95-b829-6d56a45787ca",

- "participantStartTime": "2022-08-14T06:18:27.010Z",

- "participantDuration": "902",

- "participantEndReason": "0",

- "endpointId": "02cbdb3c-155a-4d98-b829-aaaaa61d44ea",

- "endpointType": "VoIP",

- "sdkVersion": "Redacted",

- "osVersion": "Redacted"

-}

-```

-Call summary log crossed tenant with bot as a participant

-Call summary for bot

-```json

-"properties": {

- "identifier": "b1902c3e-b9f7-4650-9b23-9999bdabab47",

- "callStartTime": "2022-08-09T16:00:32Z",

- "callDuration": 1470,

- "callType": "Group",

- "teamsThreadId": "19:meeting_MmQwZDcwYTQtZ000HWE6NzI4LTg1YTAtNXXXXX99999ZZZZZ@thread.v2",

- "participantId": "66e9d9a7-a434-4663-d91d-fb1ea73ff31e",

- "participantStartTime": "2022-08-09T16:14:18Z",

- "participantDuration": 644,

- "participantEndReason": "0",

- "endpointId": "69680ec2-5ac0-4a3c-9574-eaaa77720b82",

- "endpointType": "Bot",

- "sdkVersion": "Redacted",

- "osVersion": "Redacted"

-}

-```

-#### Call Diagnostic Logs

-Call diagnostics logs share operation information:

-```json

-"operationName": "CallDiagnostics",

-"operationVersion": "1.0",

-"category": "CallDiagnostics",

-```

-Diagnostic log for audio stream from VoIP Endpoint 1 to Server Endpoint:

-```json

-"properties": {

- "identifier": "acs:1797dbb3-f982-47b0-b98e-6a76084454f1_0000000b-1531-729f-ac00-343a0d00d975",

- "participantId": "04cc26f5-a86d-481c-b9f9-7a40be4d6fba",

- "endpointId": "5ebd55df-ffff-ffff-89e6-4f3f0453b1a6",

- "endpointType": "VoIP",

- "mediaType": "Audio",

- "streamId": "14884",

- "transportType": "UDP",

- "roundTripTimeAvg": "46",

- "roundTripTimeMax": "48",

- "jitterAvg": "0",

- "jitterMax": "1",

- "packetLossRateAvg": "0",

- "packetLossRateMax": "0"

-}

-```

-Diagnostic log for audio stream from Server Endpoint to VoIP Endpoint 1:

-```json

-"properties": {

- "identifier": null,

- "participantId": "04cc26f5-a86d-481c-b9f9-7a40be4d6fba",

- "endpointId": null,

- "endpointType": "Server",

- "mediaType": "Audio",

- "streamId": "2001",

- "transportType": "UDP",

- "roundTripTimeAvg": "42",

- "roundTripTimeMax": "44",

- "jitterAvg": "1",

- "jitterMax": "1",

- "packetLossRateAvg": "0",

- "packetLossRateMax": "0"

-}

-```

-Diagnostic log for audio stream from VoIP Endpoint 3 to Server Endpoint:

-```json

-"properties": {

- "identifier": "acs:1797dbb3-f982-47b0-b98e-6a76084454f1_0000000b-1531-57c6-ac00-343a0d00d972",

- "participantId": "1a9cb3d1-7898-4063-b3d2-26c1630ecf03",

- "endpointId": "5ebd55df-ffff-ffff-ab89-19ff584890b7",

- "endpointType": "VoIP",

- "mediaType": "Audio",

- "streamId": "13783",

- "transportType": "UDP",

- "roundTripTimeAvg": "45",

- "roundTripTimeMax": "46",

- "jitterAvg": "1",

- "jitterMax": "2",

- "packetLossRateAvg": "0",

- "packetLossRateMax": "0"

-}

-```

-Diagnostic log for audio stream from Server Endpoint to VoIP Endpoint 3:

-```json

-"properties": {

- "identifier": "null",

- "participantId": "1a9cb3d1-7898-4063-b3d2-26c1630ecf03",

- "endpointId": null,

- "endpointType": "Server"

- "mediaType": "Audio",

- "streamId": "1000",

- "transportType": "UDP",

- "roundTripTimeAvg": "45",

- "roundTripTimeMax": "46",

- "jitterAvg": "1",

- "jitterMax": "4",

- "packetLossRateAvg": "0",

-```

-### Error Codes

-The `participantEndReason` will contain a value from the set of Calling SDK error codes. You can refer to these codes to troubleshoot issues during the call, per Endpoint. See [troubleshooting in Azure communication Calling SDK error codes](../troubleshooting-info.md?tabs=csharp%2cios%2cdotnet#calling-sdk-error-codes)

-For your Communications Services logs, we've provided a useful [default query pack](../../../azure-monitor/logs/query-packs.md#default-query-pack) to provide an initial set of insights to quickly analyze and understand your data. These query packs are described here: [Log Analytics for Communications Services](log-analytics.md).

-The user identity is intended to act as a primary key for logs and metrics collected through Azure Monitor. If you'd like to get a view of all of a specific user's calls, for example, you should set up your authentication in a way that maps a specific Azure Communication Services identity (or identities) to a singular user. Learn more about [log analytics](../concepts/analytics/log-analytics.md), and [metrics](../concepts/metrics.md) available to you.

-1. First, you will need to create a storage account for your logs. Go to [Create a storage account](../../storage/common/storage-account-create.md?tabs=azure-portal) for instructions to complete this step. See also [Storage account overview](../../storage/common/storage-account-overview.md) for more information on the types and features of different storage options. If you already have an Azure storage account go to Step 2.

-1. When you've created your storage account, next you need to enable logging by following the instructions in [Enable diagnostic logs in your resource](./logging-and-diagnostics.md#enable-diagnostic-logs-in-your-resource). You will select the check boxes for the logs "CallSummaryPRIVATEPREVIEW" and "CallDiagnosticPRIVATEPREVIEW".

-1. Next, select the "Archive to a storage account" box and then select the storage account for your logs in the drop-down menu below. The "Send to Analytics workspace" option isn't currently available for Private Preview of this feature, but it will be made available when this feature is made public.

-| | [Azure Monitor](../../logging-and-diagnostics.md) | ✔️ |

-| [Azure Monitor](../../logging-and-diagnostics.md) | ✔️ |

-In this article, you will learn which Azure logs, Azure metrics & Teams logs are emitted for Teams external users when joining Teams meetings. Azure Communication Services user joining Teams meeting emits the following metrics: [Authentication API](../../metrics.md) and [Chat API](../../metrics.md). Communication Services resource additionally tracks the following logs: [Call Summary](../../analytics/call-logs-azure-monitor.md) and [Call Diagnostic](../../analytics/call-logs-azure-monitor.md) Log. Teams administrator can use [Teams Admin Center](https://aka.ms/teamsadmincenter) and [Teams Call Quality Dashboard](https://cqd.teams.microsoft.com) to review logs stored for Teams external users joining Teams meetings organized by the tenant.

-If Azure Communication Services resource and Teams meeting organizer tenants are different, then some fields of the logs are redacted. You can find more information in the call summary & diagnostics logs [documentation](../../analytics/call-logs-azure-monitor.md). Bots indicate service logic provided during the meeting. Here is a list of frequently used bots:

-| | [Azure Monitor](../logging-and-diagnostics.md) | ✔️ |

-| | Honor setting "Media bit rate (Kbs)" | ❌ |

-| | [Azure Monitor](../../logging-and-diagnostics.md) | ✔️ |

-|[Allow reactions](/microsoftteams/meeting-policies-in-teams-general#meeting-reactions)|If enabled, Teams users can use reactions in the Teams meeting. Azure Communication Services don't support reactions. |❌|

-| | [Azure Monitor](../../logging-and-diagnostics.md) | ✔️ |

-| | [Azure Communication Services Insights](../../analytics/insights/voice-and-video-insights.md) | ✔️ |

-After a Teams meeting ends, diagnostic information about the meeting is available using the [Communication Services logging and diagnostics](./logging-and-diagnostics.md) and using the [Teams Call Analytics](/MicrosoftTeams/use-call-analytics-to-troubleshoot-poor-call-quality) in the Teams admin center. Communication Services users will appear as "Anonymous" in Call Analytics screens. Communication Services users aren't included in the [Teams real-time Analytics](/microsoftteams/use-real-time-telemetry-to-troubleshoot-poor-meeting-quality).

-description: Learn about logging in Azure Communication Services

-# Communication Services logs

-Azure Communication Services offers logging capabilities that you can use to monitor and debug your Communication Services solution. These capabilities can be configured through the Azure portal.

- >[!IMPORTANT]

- > For Audio/Video/Telephony call data refer to [Call Summary and Call Diagnostic Logs](../concepts/analytics/call-logs-azure-monitor.md)

-## Enable diagnostic logs in your resource

-Logging is turned off by default when a resource is created. To enable logging, navigate to the **Diagnostic settings** tab in the resource menu under the **Monitoring** section. Then select **Add diagnostic setting**.

-Next, select the archive target you want. Currently, we support storage accounts and Log Analytics as archive targets. After selecting the types of logs that you'd like to capture, save the diagnostic settings.

-

-New settings take effect in about 10 minutes. Logs will begin appearing in the configured archival target within the Logs pane of your Communication Services resource.

-For more information about configuring diagnostics, see the overview of [Azure resource logs](../../azure-monitor/essentials/platform-logs-overview.md).

-## Resource log categories

-Communication Services offers the following types of logs that you can enable:

-* **Usage logs** - provides usage data associated with each billed service offering

-* **Chat operational logs** - provides basic information related to the chat service

-* **SMS operational logs** - provides basic information related to the SMS service

-* **Authentication operational logs** - provides basic information related to the Authentication service

-* **Network Traversal operational logs** - provides basic information related to the Network Traversal service

-* **Email Send Mail operational logs** - provides detailed information related to the Email service send mail requests.

-* **Email Status Update operational logs** - provides message and recipient level delivery status updates related to the Email service send mail requests.

-* **Email User Engagement operational logs** - provides information related to 'open' and 'click' user engagement metrics for messages sent from the Email service.

-* **Call Automation operational logs** - provides operational information on Call Automation API requests. These logs can be used to identify failure points, query all requests made in a call (using Correlation ID or Server Call ID) or query all requests made by a specific service application in the call (using Participant ID).

-### Usage logs schema

-| Property | Description |

-| -- | |

-| Timestamp | The timestamp (UTC) of when the log was generated. |

-| Operation Name | The operation associated with log record. |

-| Operation Version | The `api-version` associated with the operation, if the operationName was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| Category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |

-| Correlation ID | The ID for correlated events. Can be used to identify correlated events between multiple tables. |

-| Properties | Other data applicable to various modes of Communication Services. |

-| Record ID | The unique ID for a given usage record. |

-| Usage Type | The mode of usage. (for example, Chat, PSTN, NAT, etc.) |

-| Unit Type | The type of unit that usage is based off for a given mode of usage. (for example, minutes, megabytes, messages, etc.). |

-| Quantity | The number of units used or consumed for this record. |

-### Chat operational logs

-| Property | Description |

-| -- | |

-| TimeGenerated | The timestamp (UTC) of when the log was generated. |

-| OperationName | The operation associated with log record. |

-| CorrelationID | The ID for correlated events. Can be used to identify correlated events between multiple tables. |

-| OperationVersion | The api-version associated with the operation, if the operationName was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| Category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |

-| ResultType | The status of the operation. |

-| ResultSignature | The sub status of the operation. If this operation corresponds to a REST API call, this field is the HTTP status code of the corresponding REST call. |

-| ResultDescription | The static text description of this operation. |

-| DurationMs | The duration of the operation in milliseconds. |

-| CallerIpAddress | The caller IP address, if the operation corresponds to an API call that would come from an entity with a publicly available IP address. |

-| Level | The severity level of the event. |

-| URI | The URI of the request. |

-| UserId | The request sender's user ID. |

-| ChatThreadId | The chat thread ID associated with the request. |

-| ChatMessageId | The chat message ID associated with the request. |

-| SdkType | The Sdk type used in the request. |

-| PlatformType | The platform type used in the request. |

-### SMS operational logs

-| Property | Description |

-| -- | |

-| TimeGenerated | The timestamp (UTC) of when the log was generated. |

-| OperationName | The operation associated with log record. |

-| CorrelationID | The ID for correlated events. Can be used to identify correlated events between multiple tables. |

-| OperationVersion | The api-version associated with the operation, if the operationName was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| Category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |

-| ResultType | The status of the operation. |

-| ResultSignature | The sub status of the operation. If this operation corresponds to a REST API call, this field is the HTTP status code of the corresponding REST call. |

-| ResultDescription | The static text description of this operation. |

-| DurationMs | The duration of the operation in milliseconds. |

-| CallerIpAddress | The caller IP address, if the operation corresponds to an API call that would come from an entity with a publicly available IP address. |

-| Level | The severity level of the event. |

-| URI | The URI of the request. |

-| OutgoingMessageLength | The number of characters in the outgoing message. |

-| IncomingMessageLength | The number of characters in the incoming message. |

-| DeliveryAttempts | The number of attempts made to deliver this message. |

-| PhoneNumber | The phone number the SMS message is being sent from. |

-| SdkType | The SDK type used in the request. |

-| PlatformType | The platform type used in the request. |

-| Method | The method used in the request. |

-|NumberType| The type of number, the SMS message is being sent from. It can be either **LongCodeNumber** or **ShortCodeNumber** |

-### Authentication operational logs

-| Property | Description |

-| -- | |

-| TimeGenerated | The timestamp (UTC) of when the log was generated. |

-| OperationName | The operation associated with log record. |

-| CorrelationID | The ID for correlated events. Can be used to identify correlated events between multiple tables. |

-| OperationVersion | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| Category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |

-| ResultType | The status of the operation. |

-| ResultSignature | The sub-status of the operation. If this operation corresponds to a REST API call, this field is the HTTP status code of the corresponding REST call. |

-| DurationMs | The duration of the operation in milliseconds. |

-| CallerIpAddress | The caller IP address, if the operation corresponds to an API call that would come from an entity with a publicly available IP address. |

-| Level | The severity level of the event. |

-| URI | The URI of the request. |

-| SdkType | The SDK type used in the request. |

-| PlatformType | The platform type used in the request. |

-| Identity | The identity of Azure Communication Services or Teams user related to the operation. |

-| Scopes | The Communication Services scopes present in the access token. |

-### Network Traversal operational logs

-| Dimension | Description |

-||-|

-| TimeGenerated | The timestamp (UTC) of when the log was generated. |

-| OperationName | The operation associated with log record. |

-| CorrelationId | The ID for correlated events. Can be used to identify correlated events between multiple tables. |

-| OperationVersion | The API-version associated with the operation or version of the operation (if there's no API version). |

-| Category | The log category of the event. Logs with the same log category and resource type will have the same properties fields. |

-| ResultType | The status of the operation (for example, Succeeded or Failed). |

-| ResultSignature | The sub status of the operation. If this operation corresponds to a REST API call, this field is the HTTP status code of the corresponding REST call. |

-| DurationMs | The duration of the operation in milliseconds. |

-| Level | The severity level of the operation. |

-| URI | The URI of the request. |

-| Identity | The request sender's identity, if provided. |

-| SdkType | The SDK type being used in the request. |

-| PlatformType | The platform type being used in the request. |

-| RouteType | The routing methodology to where the ICE server will be located from the client (for example, Any or Nearest). |

-### Email Send Mail operational logs

-| Property | Description |

-| -- | |

-| TimeGenerated | The timestamp (UTC) of when the log was generated. |

-| Location | The region where the operation was processed. |

-| OperationName | The operation associated with log record. |

-| OperationVersion | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| Category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |

-| CorrelationID | The ID for correlated events. Can be used to identify correlated events between multiple tables. For all Email operational logs, the CorrelationId is mapped to the MessageId, which is returned from a successful SendMail request. |

-| Size | Represents the total size in megabytes of the email body, subject, headers and attachments. |

-| ToRecipientsCount | The total # of unique email addresses on the To line. |

-| CcRecipientsCount | The total # of unique email addresses on the Cc line. |

-| BccRecipientsCount | The total # of unique email addresses on the Bcc line. |

-| UniqueRecipientsCount | This is the deduplicated total recipient count for the To, Cc and Bcc address fields. |

-| AttachmentsCount | The total # of attachments. |

-### Email Status Update operational logs

-| Property | Description |

-| -- | |

-| TimeGenerated | The timestamp (UTC) of when the log was generated. |

-| Location | The region where the operation was processed. |

-| OperationName | The operation associated with log record. |

-| OperationVersion | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| Category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |

-| CorrelationID | The ID for correlated events. Can be used to identify correlated events between multiple tables. For all Email operational logs, the CorrelationId is mapped to the MessageId, which is returned from a successful SendMail request. |

-| RecipientId | The email address for the targeted recipient. If this is a message-level event, the property will be empty. |

-| DeliveryStatus | The terminal status of the message. |

-### Email User Engagement operational logs

-| Property | Description |

-| -- | |

-| TimeGenerated | The timestamp (UTC) of when the log was generated. |

-| Location | The region where the operation was processed. |

-| OperationName | The operation associated with log record. |

-| OperationVersion | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| Category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |

-| CorrelationID | The ID for correlated events. Can be used to identify correlated events between multiple tables. For all Email operational logs, the CorrelationId is mapped to the MessageId, which is returned from a successful SendMail request. |

-| RecipientId | The email address for the targeted recipient. If this is a message-level event, the property will be empty. |

-| EngagementType | The type of user engagement being tracked. |

-| EngagementContext | The context represents what the user interacted with. |

-| UserAgent | The user agent string from the client. |

-### Call Automation operational logs

-| Property | Description |

-| -- | |

-| TimeGenerated | The timestamp (UTC) of when the log was generated. |

-| OperationName | The operation associated with log record. |

-| CorrelationID | The identifier to identify a call and correlate events for a unique call. |

-| OperationVersion | The `api-version` associated with the operation, if the `operationName` was performed using an API. If there's no API that corresponds to this operation, the version represents the version of that operation in case the properties associated with the operation change in the future. |

-| Category | The log category of the event. Category is the granularity at which you can enable or disable logs on a particular resource. The properties that appear within the properties blob of an event are the same within a particular log category and resource type. |

-| ResultType | The status of the operation. |

-| ResultSignature | The sub status of the operation. If this operation corresponds to a REST API call, this field is the HTTP status code of the corresponding REST call. |

-| DurationMs | The duration of the operation in milliseconds. |

-| CallerIpAddress | The caller IP address, if the operation corresponds to an API call that would come from an entity with a publicly available IP address. |

-| Level | The severity level of the event. |

-| URI | The URI of the request. |

-| CallConnectionId | ID representing the call connection, if available. This ID is different for each participant and is used to identify their connection to the call. |

-| ServerCallId | A unique ID to identify a call. |

-| SDKVersion | SDK version used for the request. |

-| SDKType | The SDK type used for the request. |

-| ParticipantId | ID to identify the call participant that made the request. |

-| SubOperationName | Used to identify the sub type of media operation (play, recognize) |

-| UK | Local | - | - |

-This document will help you troubleshoot issues that you may experience within your Communication Services solution. If you're troubleshooting SMS, you can [enable delivery reporting with Event Grid](../quickstarts/sms/handle-sms-events.md) to capture SMS delivery details.

-We encourage developers to submit questions, suggest features, and report problems as issues. To aid in doing this we have a [dedicated support and help options page](../support.md) which lists your options for support.

-* **Call logs**: These logs contain detailed information that can be used to troubleshoot calling and network issues.

-The following code snippets demonstrate diagnostics configuration. When the SDKs are used with diagnostics enabled, diagnostics details will be emitted to the configured event listener:

-When troubleshooting issues with the Call Automation SDK, like call management or recording problems, you'll need to collect the IDs that help identify the failing call or operation. You can provide either of the two IDs mentioned here.

-When troubleshooting voice or video calls, you may be asked to provide a `call ID`. This can be accessed via the `id` property of the `call` object:

-console.log(result); // your message ID will be in the result

-When troubleshooting send email or email message status requests, you may be asked to provide an `operation ID`. This can be accessed in the response:

-This may be useful if you want to redirect logs to a location other than console.

-This will give you a `xcappdata` file. Right-click on this file and select ΓÇ£Show package contentsΓÇ¥. You'll then see the `.blog` files that you can then attach to your Azure support request.

-On Android Studio, navigate to the Device File Explorer by selecting View > Tool Windows > Device File Explorer from both the simulator and the device. The `.blog` file will be located within your application's directory, which should look something like `/data/data/[app_name_space:com.contoso.com.acsquickstartapp]/files/acs_sdk.blog`. You can attach this file to your support request.

-These can be accessed by looking at where your app is keeping its local data. There are many ways to figure out where a UWP app keeps its local data, the following steps are just one of these ways:

-You can find your current Teams license using [licenseDetails](/graph/api/resources/licensedetails) Microsoft Graph API that returns licenses assigned to a user. Follow the steps below to use the Graph Explorer tool to view licenses assigned to a user:

-| 400 | Recognize Failed | Check the error message. The message will highlight if this is due to timeout being reached or if operation was canceled. For more information about the error codes and messages you can check our how-to guide for [gathering user input](../how-tos/call-automation/recognize-action.md#event-codes).

-* [Get started with log analytics in Azure Communication Service](../../concepts/logging-and-diagnostics.md)

-Because point reads (key/value lookups on the item ID) are the most efficient kind of read, you should make sure your item ID has a meaningful value so you can fetch your items with a point read (instead of a query) when possible.

-The cost to do a point read (fetching a single item by its ID and partition key value) for a 1-KB item is one Request Unit (or one RU). All other database operations are similarly assigned a cost using RUs. No matter which API you use to interact with your Azure Cosmos DB container, RUs measure the actual costs of using that API. Whether the database operation is a write, point read, or query, costs are always measured in RUs.

-Use the following information to create an EA subscription.

-| **PREVIEW - Activity from a risky IP address**<br>(ARM.MCAS_ActivityFromAnonymousIPAddresses) | Users activity from an IP address that has been identified as an anonymous proxy IP address has been detected.<br>These proxies are used by people who want to hide their device's IP address, and can be used for malicious intent. This detection uses a machine learning algorithm that reduces false positives, such as mis-tagged IP addresses that are widely used by users in the organization.<br>Requires an active Microsoft Defender for Cloud Apps license. | - | Medium |

-| **PREVIEW - Activity from infrequent country**<br>(ARM.MCAS_ActivityFromInfrequentCountry) | Activity from a location that wasn't recently or ever visited by any user in the organization has occurred.<br>This detection considers past activity locations to determine new and infrequent locations. The anomaly detection engine stores information about previous locations used by users in the organization.<br>Requires an active Microsoft Defender for Cloud Apps license. | - | Medium |

-| **PREVIEW - Impossible travel activity**<br>(ARM.MCAS_ImpossibleTravelActivity) | Two user activities (in a single or multiple sessions) have occurred, originating from geographically distant locations. This occurs within a time period shorter than the time it would have taken the user to travel from the first location to the second. This indicates that a different user is using the same credentials.<br>This detection uses a machine learning algorithm that ignores obvious false positives contributing to the impossible travel conditions, such as VPNs and locations regularly used by other users in the organization. The detection has an initial learning period of seven days, during which it learns a new user's activity pattern.<br>Requires an active Microsoft Defender for Cloud Apps license. | - | Medium |

-| **PREVIEW - Suspicious creation of compute resources detected**<br>(ARM_SuspiciousComputeCreation) | Microsoft Defender for Resource Manager identified a suspicious creation of compute resources in your subscription utilizing Virtual Machines/Azure Scale Set. The identified operations are designed to allow administrators to efficiently manage their environments by deploying new resources when needed. While this activity may be legitimate, a threat actor might utilize such operations to conduct crypto mining.<br> The activity is deemed suspicious as the compute resources scale is higher than previously observed in the subscription. <br> This can indicate that the principal is compromised and is being used with malicious intent. | Impact | Medium |

-The following tables include the Defender for Servers security alerts [to be deprecated in April, 2023](upcoming-changes.md#deprecation-and-improvement-of-selected-alerts-for-windows-and-linux-servers).

-| Has high severity vulnerabilities | Indicates that a resource has high severity vulnerabilities | Azure VM, AWS EC2, Kubernetes image |

-| Vulnerable to remote code execution | Indicates that a resource has vulnerabilities allowing remote code execution | Azure VM, AWS EC2, Kubernetes image |

-| Is running | Indicates that the source entity is running the target entity as a process | Azure VM, EC2, Kubernetes container | SQL, Arc-Enabled SQL, Hosted MongoDB, Hosted MySQL, Hosted Oracle, Hosted PostgreSQL, Hosted SQL Server, Kubernetes image, Kubernetes pod |

- > If you select the "Microsoft Defender for Cloud built-in Qualys solution" solution, Defender for Cloud enables the following policy: [(Preview) Configure machines to receive a vulnerability assessment provider](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2fproviders%2fMicrosoft.Authorization%2fpolicyDefinitions%2f13ce0167-8ca6-4048-8e6b-f996402e3c1b).

-The optional Defender CSPM plan, provides advanced posture management capabilities such as [Attack path analysis](how-to-manage-attack-path.md), [Cloud security explorer](how-to-manage-cloud-security-explorer.md), advanced threat hunting, [security governance capabilities](concept-regulatory-compliance.md), and also tools to assess your [security compliance](review-security-recommendations.md) with a wide range of benchmarks, regulatory standards, and any custom security policies required in your organization, industry, or region.

-| [Governance](concept-regulatory-compliance.md) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS, GCP, on-premises |

-| Agentless discovery for Kubernetes | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure |

-| Agentless vulnerability assessments for container images, including registry scanning (\* Up to 20 unique images per billable resource) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure |

-# Use Defender for Containers to scan your Azure Container Registry images for vulnerabilities

-This article explains how to use Defender for Containers to scan the container images stored in your Azure Resource Manager-based Azure Container Registry, as part of the protections provided within Microsoft Defender for Cloud.

-To enable scanning of vulnerabilities in containers, you have to [enable Defender for Containers](defender-for-containers-enable.md). When the scanner, powered by Qualys, reports vulnerabilities, Defender for Cloud presents the findings and related information as recommendations. In addition, the findings include related information such as remediation steps, relevant CVEs, CVSS scores, and more. You can view the identified vulnerabilities for one or more subscriptions, or for a specific registry.

-

- >[!NOTE]

- > This feature is charged per image.

- Use the ACR tools to bring images to your registry from Docker Hub or Microsoft Container Registry. When the import completes, the imported images are scanned by the built-in vulnerability assessment solution.

- Learn more in [Import container images to a container registry](../container-registry/container-registry-import-images.md)

- You can also [scan images in Amazon AWS Elastic Container Registry](defender-for-containers-vulnerability-assessment-elastic.md) directly from the Azure portal.

-Make sure you have write (owner/contributor) access to the subscription.

- on:

- When you enable Defender for Containers, you also gain the ability to [query](how-to-manage-cloud-security-explorer.md#build-a-query-with-the-cloud-security-explorer) containers data plane workloads in the security explorer.

-Template Analyzer runs rules on ARM and Bicep templates. You can learn more about [Template Analyzer's rules and remediation details](https://github.com/Azure/template-analyzer/blob/main/docs/built-in-bpa-rules.md#built-in-rules).

-If you've got *any* of the Microsoft Defender plan (except for Defender for Servers Plan 1) enabled on *any* of your Azure resources, you can access Defender for Cloud's regulatory compliance dashboard and all of its data.

-These recommendations replace `Virtual machines should encrypt temp disks, caches, and data flows between Compute and Storage resources` which detected Azure Disk Encryption and the policy `Virtual machines and virtual machine scale sets should have encryption at host enabled` which detected EncryptionAtHost. ADE and EncryptionAtHost provide comparable encryption at rest coverage, and we recommend enabling one of them on every virtual machine. The new recommendations detect whether either ADE or EncryptionAtHost are enabled and only warn if neither are enabled. We also warn if ADE is enabled on some, but not all disks of a VM (this condition isn't applicable to EncryptionAtHost).

-### Changes in the recommendation "Machines should be configured securely"

-No action is required on the customer side, and there's no expected impact on the secure score.

-### New alert in Defender for Resource Manager

-Defender for Resource Manager has the following new alert:

-| Alert (alert type) | Description | MITRE tactics | Severity |

-|||:-:||

-| **PREVIEW - Suspicious creation of compute resources detected**<br>(ARM_SuspiciousComputeCreation) | Microsoft Defender for Resource Manager identified a suspicious creation of compute resources in your subscription utilizing Virtual Machines/Azure Scale Set. The identified operations are designed to allow administrators to efficiently manage their environments by deploying new resources when needed. While this activity may be legitimate, a threat actor might utilize such operations to conduct crypto mining.<br> The activity is deemed suspicious as the compute resources scale is higher than previously observed in the subscription. <br> This can indicate that the principal is compromised and is being used with malicious intent. | Impact | Medium |

-You can see a list of all of the [alerts available for Resource Manager](alerts-reference.md#alerts-resourcemanager).

-Cloud storage plays a key role in the organization and stores large volumes of valuable and sensitive data. Today we are announcing a new Defender for Storage plan. If youΓÇÖre using the previous plan (now renamed to "Defender for Storage (classic)"), you will need to proactively [migrate to the new plan](defender-for-storage-classic-migrate.md) in order to use the new features and benefits.

-These capabilities will enhance the existing Activity Monitoring capability, based on control and data plane log analysis and behavioral modeling to identify early signs of breach.

-We are announcing that Defender CSPM is now Generally Available (GA). Defender CSPM offers all of the services available under the Foundational CSPM capabilities and adds the following benefits:

-This recommendation disables local authentication methods and allows only Azure Active Directory Authentication which improves security by ensuring that Azure SQL Databases can exclusively be accessed by Azure Active Directory identities.

-The Cloud Security Explorer now allows you to run cloud-abstract queries across resources. You can use either the pre-built query templates or use the custom search to apply filters to build your query. Learn [how to manage Cloud Security Explorer](how-to-manage-cloud-security-explorer.md).

-### Recommendation to find vulnerabilities in running container images released for General Availability (GA)

-The [Running container images should have vulnerability findings resolved](defender-for-containers-vulnerability-assessment-azure.md#view-vulnerabilities-for-images-running-on-your-aks-clusters) recommendation for Linux is now GA. The recommendation is used to identify unhealthy resources and is included in the calculations of your secure score.

-We recommend that you use the recommendation to remediate vulnerabilities in your Linux containers. Learn about [recommendation remediation](implement-security-recommendations.md).

-Only built-in recommendations have an impact on the secure score.

-| [Changes in the recommendation "Machines should be configured securely"](#changes-in-the-recommendation-machines-should-be-configured-securely) | March 2023 |

-| [Three alerts in the Defender for Azure Resource Manager plan will be deprecated](#three-alerts-in-the-defender-for-resource-manager-plan-will-be-deprecated) | March 2023 |

-| [Alerts automatic export to Log Analytics workspace will be deprecated](#alerts-automatic-export-to-log-analytics-workspace-will-be-deprecated) | March 2023 |

-| [Deprecation and improvement of selected alerts for Windows and Linux Servers](#deprecation-and-improvement-of-selected-alerts-for-windows-and-linux-servers) | April 2023 |

-| [Multiple changes to identity recommendations](#multiple-changes-to-identity-recommendations) | May 2023 |

-### Changes in the recommendation "Machines should be configured securely"

-**Estimated date for change: March 2023**

-The recommendation `Machines should be configured securely` will be updated. The update will improve the performance and stability of the recommendation and align its experience with the generic behavior of Defender for Cloud's recommendations.

-As part of this update, the recommendation's ID will be changed from `181ac480-f7c4-544b-9865-11b8ffe87f47` to `c476dc48-8110-4139-91af-c8d940896b98`.

-No action is required on the customer side, and there's no expected downtime nor impact on the secure score.

-### Three alerts in the Defender for Resource Manager plan will be deprecated

-**Estimated date for change: March 2023**

-As we continue to improve the quality of our alerts, the following three alerts from the Defender for Resource Manager plan will be deprecated:

-1. `Activity from a risky IP address (ARM.MCAS_ActivityFromAnonymousIPAddresses)`

-1. `Activity from infrequent country (ARM.MCAS_ActivityFromInfrequentCountry)`

-1. `Impossible travel activity (ARM.MCAS_ImpossibleTravelActivity)`

-You can learn more details about each of these alerts from the [alerts reference list](alerts-reference.md#alerts-resourcemanager).

-In the scenario where an activity from a suspicious IP address is detected, one of the following Defenders for Resource Manager plan alerts `Azure Resource Manager operation from suspicious IP address` or `Azure Resource Manager operation from suspicious proxy IP address` will be present.

-### Alerts automatic export to Log Analytics workspace will be deprecated

-**Estimated date for change: March 2023**

-Currently, Defender for Cloud security alerts are automatically exported to a default Log Analytics workspace on the resource level. This causes an indeterministic behavior and therefore, this feature is set to be deprecated.

-You can export your security alerts to a dedicated Log Analytics workspace with the [Continuous Export](continuous-export.md#set-up-a-continuous-export) feature.

-If you have already configured continuous export of your alerts to a Log Analytics workspace, no further action is required.

-### Deprecation and improvement of selected alerts for Windows and Linux Servers

-**Estimated date for change: April 2023**

-The security alert quality improvement process for Defender for Servers includes the deprecation of some alerts for both Windows and Linux servers. The deprecated alerts will now be sourced from and covered by Defender for Endpoint threat alerts.

-If you already have the Defender for Endpoint integration enabled, no further action is required. You may experience a decrease in your alerts volume in April 2023.

-If you don't have the Defender for Endpoint integration enabled in Defender for Servers, you'll need to enable the Defender for Endpoint integration to maintain and improve your alert coverage.

-All Defender for Servers customers, have full access to the Defender for EndpointΓÇÖs integration as a part of the [Defender for Servers plan](plan-defender-for-servers-select-plan.md#plan-features).

-You can learn more about [Microsoft Defender for Endpoint onboarding options](integration-defender-for-endpoint.md#enable-the-microsoft-defender-for-endpoint-integration).

-You can also view the [full list of alerts](alerts-reference.md#defender-for-servers-alerts-to-be-deprecated) that are set to be deprecated.

-Read the [Microsoft Defender for Cloud blog](https://techcommunity.microsoft.com/t5/microsoft-defender-for-cloud/defender-for-servers-security-alerts-improvements/ba-p/3714175).

-We are announcing the full deprecation of support of [`PCI DSS`](/azure/compliance/offerings/offering-pci-dss) standard/initiative in Azure China 21Vianet.

-### Multiple changes to identity recommendations

-**Estimated date for change: May 2023**

-We announced previously the [availability of identity recommendations V2 (preview)](release-notes-archive.md#extra-recommendations-added-to-identity), which included enhanced capabilities.

-As part of these changes, the following recommendations will be released as General Availability (GA) and replace the V1 recommendations that are set to be deprecated.

-#### General Availability (GA) release of identity recommendations V2

-The following security recommendations will be released as GA and replace the V1 recommendations:

-

-|Recommendation | Assessment Key|

-|--|--|

-|Accounts with owner permissions on Azure resources should be MFA enabled | 6240402e-f77c-46fa-9060-a7ce53997754 |

-|Accounts with write permissions on Azure resources should be MFA enabled | c0cb17b2-0607-48a7-b0e0-903ed22de39b |

-| Accounts with read permissions on Azure resources should be MFA enabled | dabc9bc4-b8a8-45bd-9a5a-43000df8aa1c |

-| Guest accounts with owner permissions on Azure resources should be removed | 20606e75-05c4-48c0-9d97-add6daa2109a |

-| Guest accounts with write permissions on Azure resources should be removed | 0354476c-a12a-4fcc-a79d-f0ab7ffffdbb |

-| Guest accounts with read permissions on Azure resources should be removed | fde1c0c9-0fd2-4ecc-87b5-98956cbc1095 |

-| Blocked accounts with owner permissions on Azure resources should be removed | 050ac097-3dda-4d24-ab6d-82568e7a50cf |

-| Blocked accounts with read and write permissions on Azure resources should be removed | 1ff0b4c9-ed56-4de6-be9c-d7ab39645926 |

-We are announcing the full deprecation of support of [`PCI DSS`](/azure/compliance/offerings/offering-pci-dss) standard/initiative in Azure China 21Vianet.

-| Azure Synapse Workspace authentication mode should be Azure Active Directory Only | Azure Active Directory (AAD) only authentication methods improves security by ensuring that Synapse Workspaces exclusively require AAD identities for authentication. Learn more at: https://aka.ms/Synapse | [Synapse Workspaces should use only Azure Active Directory identities for authentication](https://portal.azure.com/#view/Microsoft_Azure_Policy/PolicyDetailBlade/definitionId/%2fproviders%2fMicrosoft.Authorization%2fpolicyDefinitions%2f2158ddbe-fefa-408e-b43f-d4faef8ff3b8) |

-To improve the Defender for DevOps user experience and enable further integration with Defender for Coud's rich set of capabilities, Defender for DevOps will no longer support duplicate instances of a DevOps organization to be onboarded to an Azure tenant.

-If you do not have an instance of a DevOps organization onboarded more than once to your organization, no further action is required. If you do have more than one instance of a DevOps organization onboarded to your tenant, the subscription owner will be notified and will need to delete the DevOps Connector(s) they do not want to keep by navigating to Defender for Cloud Environment Settings.

-Customers will have until June 30, 2023 to resolve this issue. After this date, only the most recent DevOps Connector created where an instance of the DevOps organization exists will remain onboarded to Defender for DevOps.

-For IoT solutions built in Azure, device twins play a key role in both device management and process automation.

-Defender for IoT fully integrates with your existing IoT device management platform. Full integration, enables you to manage your device's security status, and allows you to make use of all existing device control capabilities. Integration is achieved by making use of the IoT Hub twin mechanism.

-Learn more about the concept of [Understand and use device twins in IoT Hub](../../iot-hub/iot-hub-devguide-device-twins.md).

-## Defender-IoT-micro-agent twin

-Defender for IoT uses a Defender-IoT-micro-agent twin for each device. The Defender-IoT-micro-agent twin holds all of the information that is relevant to device security, for each specific device in your solution. Device security properties are configured through a dedicated Defender-IoT-micro-agent twin for safer communication, to enable updates, and maintenance that requires fewer resources.

-## Understanding DefenderIotMicroAgent module twins

-To take full advantage of all Defender for IoT feature's, you need to create, configure, and use the Defender-IoT-micro-agent twins for every device in the service.