+ "total": 50000000

+You can request to increase the quota size by [contacting support](find-help-open-support-ticket.md)

+[powershell-gallery]: https://www.powershellgallery.com/

+<!-- EXTERNAL LINKS -->

+[naming-prefix]: /windows-server/identity/ad-ds/plan/selecting-the-forest-root-domain#selecting-a-prefix

+> When a directory extension attribute in Azure AD doesn't show up automatically in your attribute mapping drop-down, you can manually add it to the "Azure AD attribute list". When manually adding Azure AD directory extension attributes to your provisioning app, note that directory extension attribute names are case-sensitive. For example: If you have a directory extension attribute named `extension_53c9e2c0exxxxxxxxxxxxxxxx_acmeCostCenter`, make sure you enter it in the same format as defined in the directory. Provisioning multi-valued directory extension attributes is not supported.

+Your users won't notice anything different when they sign in to use your corporate applications. They can still work from anywhere on any device. The Application Proxy connectors direct remote traffic to all apps without regard to their authentication type, so they'll still balance loads automatically.

+This article is for people to publish an application with this scenario for the first time. Besides detailing the publishing steps, it guides you in getting started with both Application Proxy and PingAccess. If you've already configured both services but want a refresher on the publishing steps, skip to the [Add your application to Azure AD with Application Proxy](#add-your-application-to-azure-ad-with-application-proxy) section.

+ 1. **Internal URL**: Normally you provide the URL that takes you to the app's sign-in page when you're on the corporate network. For this scenario, the connector needs to treat the PingAccess proxy as the front page of the application. Use this format: `https://<host name of your PingAccess server>:<port>`. The port is 3000 by default, but you can configure it in PingAccess.

+ > If this is your first application, use port 3000 to start and come back to update this setting if you change your PingAccess configuration. For subsequent applications, the port will need to match the Listener you've configured in PingAccess. Learn more about [listeners in PingAccess](https://docs.pingidentity.com/access/sources/dita/topic?category=pingaccess&Releasestatus_ce=Current&resourceid=pa_assigning_key_pairs_to_https_listeners).

+1. From the **App registrations** sidebar for your application, select **API permissions** > **Add a permission** > **Microsoft APIs** > **Microsoft Graph**. The **Request API permissions** page for **Microsoft Graph** appears, which contains the permissions for Microsoft Graph.

+It might sound alarming to not ask for a user to sign back in, though any violation of IT policies revokes the session. Some examples include a password change, an incompliant device, or an account disable operation. You can also explicitly [revoke users' sessions by using Microsoft Graph PowerShell](/powershell/module/microsoft.graph.users.actions/revoke-mgusersigninsession).

+| **Challenge requested in Authentication Ext for User** | Organizations using a RADIUS protocol other than PAP will observe user VPN authorization failing with these events appearing in the AuthZOptCh event log of the NPS Extension server. You can configure the NPS Server to support PAP. If PAP is not an option, you can set OVERRIDE_NUMBER_MATCHING_WITH_OTP = FALSE to fall back to Approve/Deny push notifications. For further help, please check [Number matching using NPS Extension](how-to-mfa-number-match.md#nps-extension). |

+- [Securing workload identities with Azure AD Identity Protection](../identity-protection/concept-workload-identity-risk.md)

+This article describes how to configure and set up a custom claims provider with the [token issuance start event](custom-claims-provider-overview.md#token-issuance-start-event-listener) type. This event is triggered right before the token is issued, and allows you to call a REST API to add claims to the token.

+Register an application to authenticate your custom authentication extension to your Azure Function.

+1. Sign in to [Graph Explorer](https://aka.ms/ge) using an account whose home tenant is the tenant you wish to manage your custom authentication extension in. The account must have the privileges to create and manage an application registration in the tenant.

+2. Run the following request.

+ # [HTTP](#tab/http)

+ ```http

+ POST https://graph.microsoft.com/v1.0/applications

+ Content-type: application/json

+

+ "displayName": "authenticationeventsAPI"

+ # [C#](#tab/csharp)

+ [!INCLUDE [sample-code](~/microsoft-graph/includes/snippets/csharp/v1/tutorial-application-basics-create-app-csharp-snippets.md)]

+

+ # [Go](#tab/go)

+ [!INCLUDE [sample-code](~/microsoft-graph/includes/snippets/go/v1/tutorial-application-basics-create-app-go-snippets.md)]

+

+ # [Java](#tab/java)

+ [!INCLUDE [sample-code](~/microsoft-graph/includes/snippets/jav)]

+

+ # [JavaScript](#tab/javascript)

+ [!INCLUDE [sample-code](~/microsoft-graph/includes/snippets/javascript/v1/tutorial-application-basics-create-app-javascript-snippets.md)]

+

+ # [PHP](#tab/php)

+ Snippet not available.

+

+ # [PowerShell](#tab/powershell)

+ [!INCLUDE [sample-code](~/microsoft-graph/includes/snippets/powershell/v1/tutorial-application-basics-create-app-powershell-snippets.md)]

+

+ # [Python](#tab/python)

+ [!INCLUDE [sample-code](~/microsoft-graph/includes/snippets/python/v1/tutorial-application-basics-create-app-python-snippets.md)]

+

+

+3. From the response, record the value of **id** and **appId** of the newly created app registration. These values will be referenced in this article as `{authenticationeventsAPI_ObjectId}` and `{authenticationeventsAPI_AppId}` respectively.

+Create a service principal in the tenant for the authenticationeventsAPI app registration.

+Still in Graph Explorer, run the following request. Replace `{authenticationeventsAPI_AppId}` with the value of **appId** that you recorded from the previous step.

+```http

+POST https://graph.microsoft.com/v1.0/servicePrincipals

+Content-type: application/json

+

+{

+ "appId": "{authenticationeventsAPI_AppId}"

+}

+```

+In Graph Explorer, run the following request.

+ - Set the application ID URI value in the *identifierUris* property. Replace `{Function_Url_Hostname}` with the hostname of the `{Function_Url}` you recorded earlier.

+ - Set the `{authenticationeventsAPI_AppId}` value with the **appId** that you recorded earlier.

+ - An example value is `api://authenticationeventsAPI.azurewebsites.net/f4a70782-3191-45b4-b7e5-dd415885dd80`. Take note of this value as you'll use it later in this article in place of `{functionApp_IdentifierUri}`.

+```http

+POST https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}

+Content-type: application/json

+{

+"identifierUris": [

+ "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"

+],

+"api": {

+ "requestedAccessTokenVersion": 2,

+ "acceptMappedClaims": null,

+ "knownClientApplications": [],

+ "oauth2PermissionScopes": [],

+ "preAuthorizedApplications": []

+},

+"requiredResourceAccess": [

+ "resourceAppId": "00000003-0000-0000-c000-000000000000",

+ "resourceAccess": [

+ "id": "214e810f-fda8-4fd7-a475-29461495eb00",

+ "type": "Role"

+]

+}

+```

+Next, you register the custom authentication extension. You register the custom authentication extension by associating it with the app registration for the Azure Function, and your Azure Function endpoint `{Function_Url}`.

+1. In Graph Explorer, run the following request. Replace `{Function_Url}` with the hostname of your Azure Function app. Replace `{functionApp_IdentifierUri}` with the identifierUri used in the previous step.

+ - You'll need the *CustomAuthenticationExtension.ReadWrite.All* delegated permission.

+ # [HTTP](#tab/http)

+ ```http

+ POST https://graph.microsoft.com/beta/identity/customAuthenticationExtensions

+ Content-type: application/json

+ # [C#](#tab/csharp)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [Go](#tab/go)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [Java](#tab/java)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [JavaScript](#tab/javascript)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [PHP](#tab/php)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [PowerShell](#tab/powershell)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [Python](#tab/python)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+1. Record the **id** value of the created custom claims provider object. You'll use the value later in this tutorial in place of `{customExtensionObjectId}`.

+After your custom authentication extension is created, open the **Overview** tab of the new custom authentication extension.

+In your app registration, under **Overview**, copy the **Application (client) ID**. The app ID is referred to as the `{App_to_enrich_ID}` in later steps. In Microsoft Graph, it's referenced by the **appId** propety.

+First create an event listener to trigger a custom authentication extension for the *My Test application* using the token issuance start event.

+1. Sign in to [Graph Explorer](https://aka.ms/ge) using an account whose home tenant is the tenant you wish to manage your custom authentication extension in.

+1. Run the following request. Replace `{App_to_enrich_ID}` with the app ID of *My Test application* recorded earlier. Replace `{customExtensionObjectId}` with the custom authentication extension ID recorded earlier.

+ - You'll need the *EventListener.ReadWrite.All* delegated permission.

+ # [HTTP](#tab/http)

+ ```http

+ POST https://graph.microsoft.com/beta/identity/authenticationEventListeners

+ Content-type: application/json

+

+ # [C#](#tab/csharp)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [Go](#tab/go)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [Java](#tab/java)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [JavaScript](#tab/javascript)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [PHP](#tab/php)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [PowerShell](#tab/powershell)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+ # [Python](#tab/python)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/bet)]

+

+

+Next, create the claims mapping policy, which describes which claims can be issued to an application from a custom claims provider.

+1. Still in Graph Explorer, run the following request. You'll need the *Policy.ReadWrite.ApplicationConfiguration* delegated permission.

+ # [HTTP](#tab/http)

+ ```http

+ POST https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies

+ Content-type: application/json

+ # [C#](#tab/csharp)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/csharp/create-claimsmappingpolicy-from-claimsmappingpolicies-csharp-snippets.md)]

+

+ # [Go](#tab/go)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/go/create-claimsmappingpolicy-from-claimsmappingpolicies-go-snippets.md)]

+

+ # [Java](#tab/java)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/jav)]

+

+ # [JavaScript](#tab/javascript)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/javascript/create-claimsmappingpolicy-from-claimsmappingpolicies-javascript-snippets.md)]

+

+ # [PHP](#tab/php)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/php/create-claimsmappingpolicy-from-claimsmappingpolicies-php-snippets.md)]

+

+ # [PowerShell](#tab/powershell)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/powershell/create-claimsmappingpolicy-from-claimsmappingpolicies-powershell-snippets.md)]

+

+ # [Python](#tab/python)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/python/create-claimsmappingpolicy-from-claimsmappingpolicies-python-snippets.md)]

+

+

+2. Record the `ID` generated in the response, later it's referred to as `{claims_mapping_policy_ID}`.

+Get the service principal object ID:

+1. Run the following request in Graph Explorer. Replace `{App_to_enrich_ID}` with the **appId** of *My Test Application*.

+ ```http

+ GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='{App_to_enrich_ID}')

+ ```

+Record the value of **id**.

+Assign the claims mapping policy to the service principal of *My Test Application*.

+1. Run the following request in Graph Explorer. You'll need the *Policy.ReadWrite.ApplicationConfiguration* and *Application.ReadWrite.All* delegated permission.

+ # [HTTP](#tab/http)

+ ```http

+ POST https://graph.microsoft.com/v1.0/servicePrincipals/{test_App_Service_Principal_ObjectId}/claimsMappingPolicies/$ref

+ Content-type: application/json

+ # [C#](#tab/csharp)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/csharp/create-claimsmappingpolicy-from-serviceprincipal-csharp-snippets.md)]

+

+ # [Go](#tab/go)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/go/create-claimsmappingpolicy-from-serviceprincipal-go-snippets.md)]

+

+ # [Java](#tab/java)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/jav)]

+

+ # [JavaScript](#tab/javascript)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/javascript/create-claimsmappingpolicy-from-serviceprincipal-javascript-snippets.md)]

+

+ # [PHP](#tab/php)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/php/create-claimsmappingpolicy-from-serviceprincipal-php-snippets.md)]

+

+ # [PowerShell](#tab/powershell)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/powershell/create-claimsmappingpolicy-from-serviceprincipal-powershell-snippets.md)]

+

+ # [Python](#tab/python)

+ [!INCLUDE [sample-code](~/microsoft-graph/api-reference/v1.0/includes/snippets/python/create-claimsmappingpolicy-from-serviceprincipal-python-snippets.md)]

+

+

+By adding Azure AD roles to the local administrators group, you can update the users that can manage a device anytime in Azure AD without modifying anything on the device. Azure AD also adds the Azure AD joined device local administrator role to the local administrators group to support the principle of least privilege (PoLP). In addition to users with the Global Administrator role, you can also enable users that have been *only* assigned the Azure AD Joined Device Local Administrator role to manage a device.

+## Manage the Global Administrator role

+To view and update the membership of the [Global Administrator](/azure/active-directory/roles/permissions-reference#global-administrator) role, see:

+## Manage the Azure AD Joined Device Local Administrator role

+In the Azure portal, you can manage the [Azure AD Joined Device Local Administrator](/azure/active-directory/roles/permissions-reference#azure-ad-joined-device-local-administrator) role from **Device settings**.

+To modify the Azure AD Joined Device Local Administrator role, configure **Additional local administrators on all Azure AD joined devices**.

+Azure AD Joined Device Local Administrators are assigned to all Azure AD joined devices. You canΓÇÖt scope this role to a specific set of devices. Updating the Azure AD Joined Device Local Administrator role doesn't necessarily have an immediate impact on the affected users. On devices where a user is already signed into, the privilege elevation takes place when *both* the below actions happen:

+Users aren't directly listed in the local administrator group, the permissions are received through the Primary Refresh Token.

+Starting with Windows 10 version 20H2, you can use Azure AD groups to manage administrator privileges on Azure AD joined devices with the [Local Users and Groups](/windows/client-management/mdm/policy-csp-localusersandgroups) MDM policy. This policy allows you to assign individual users or Azure AD groups to the local administrators group on an Azure AD joined device, providing you with the granularity to configure distinct administrators for different groups of devices.

+- Adding Azure AD groups through the policy requires the group's SID that can be obtained by executing the [Microsoft Graph API for Groups](/graph/api/resources/group). The SID equates to the property `securityIdentifier` in the API response.

+- [Bulk enrollment](/intune/windows-bulk-enroll) - An Azure AD join that is performed in the context of a bulk enrollment happens in the context of an autocreated user. Users signing in after a device has been joined aren't added to the administrators group.

+- You can only assign role based groups to the Azure AD Joined Device Local Administrator role.

+- The Azure AD Joined Device Local Administrator role is assigned to all Azure AD Joined devices. This role can't be scoped to a specific set of devices.

+- When you remove users from the Azure AD Joined Device Local Administrator role, changes aren't instant. Users still have local administrator privilege on a device as long as they're signed in to it. The privilege is revoked during their next sign-in when a new primary refresh token is issued. This revocation, similar to the privilege elevation, could take upto 4 hours.

+#Customer intent: As an IT admin, I want to understand how I can get rid of stale devices, so that I can I can cleanup my device registration data.

+# Customer intent: As a tenant administrator, I want to send B2B invitations to multiple external users at the same time so that I can avoid having to send individual invitations to each user.

+- [Customize the branding for customer sign-in experiences](how-to-customize-branding-customers.md)

+- [Customize the branding for customer sign-in experiences](how-to-customize-branding-customers.md)

+# Customer intent: As a tenant administrator, I want to customize the invitation process with the API.

+# Customer intent: As a tenant administrator, I want to set up Facebook as an identity provider for guest user login.

+# Customer intent: As a tenant administrator, I want to learn about B2B collaboration guest user properties and states before and after invitation redemption.

+ - Default sync rule ΓÇ£In from AD ΓÇô User CommonΓÇ¥ was updated to flow the employeeType attribute.

+## Privileged Identity Management and app provisioning (Public Preview)

+If the group is configured for [app provisioning](../app-provisioning/index.yml), activation of group membership will trigger provisioning of group membership (and user account itself if it wasnΓÇÖt provisioned previously) to the application using SCIM protocol.

+In Public Preview we have a functionality that triggers provisioning right after group membership is activated in PIM.

+Provisioning configuration depends on the application. Generally, we recommend having at least two groups assigned to the application. Depending on the number of roles in your application, you may choose to define additional ΓÇ£privileged groups.ΓÇ¥:

+|Group|Purpose|Members|Group membership|Role assigned in the application|

+|--|--|--|--|--|

+|All users group|Ensure that all users that need access to the application are constantly provisioned to the application.|All users that need to access application.|Active|None, or low-privileged role|

+|Privileged group|Provide just-in-time access to privileged role in the application.|Users that need to have just-in-time access to privileged role in the application.|Eligible|Privileged role|

+> - For information about delays activating the Azure AD Joined Device Local Administrator role, see [How to manage the local administrators group on Azure AD joined devices](../devices/assign-local-admin.md#manage-the-azure-ad-joined-device-local-administrator-role).

+ Title: Logs available for streaming to endpoints from Azure Active Directory

+description: Learn about the Azure Active Directory logs available for streaming to an endpoint for storage, analysis, or monitoring.

+# Learn about the identity logs you can stream to an endpoint

+Using Diagnostic settings in Azure Active Directory (Azure AD), you can route activity logs to several endpoints for long term retention and data insights. You select the logs you want to route, then select the endpoint.

+This article describes the logs that you can route to an endpoint from Azure AD Diagnostic settings.

+## Prerequisites

+Setting up an endpoint, such as an event hub or storage account, may require different roles and licenses. To create or edit a new Diagnostic setting, you need a user who's a **Security Administrator** or **Global Administrator** for the Azure AD tenant.

+To help decide which log routing option is best for you, see [How to access activity logs](howto-access-activity-logs.md). The overall process and requirements for each endpoint type are covered in the following articles.

+- [Send logs to a Log Analytics workspace to integrate with Azure Monitor logs](howto-integrate-activity-logs-with-azure-monitor-logs.md)

+- [Archive logs to a storage account](howto-archive-logs-to-storage-account.md)

+- [Stream logs to an event hub](howto-stream-logs-to-event-hub.md)

+- [Send to a partner solution](../../partner-solutions/overview.md)

+## Activity log options

+The following logs can be sent to an endpoint. Some logs may be in public preview but still visible in the portal.

+### Audit logs

+The `AuditLogs` report capture changes to applications, groups, users, and licenses in your Azure AD tenant. Once you've routed your audit logs, you can filter or analyze by date/time, the service that logged the event, and who made the change. For more information, see [Audit logs](concept-audit-logs.md).

+### Sign-in logs

+The `SignInLogs` send the interactive sign-in logs, which are logs generated by your users signing in. Sign-in logs are generated by users providing their username and password on an Azure AD sign-in screen or passing an MFA challenge. For more information, see [Interactive user sign-ins](concept-all-sign-ins.md#interactive-user-sign-ins).

+### Non-interactive sign-in logs

+The `NonInteractiveUserSIgnInLogs` are sign-ins done on behalf of a user, such as by a client app. The device or client uses a token or code to authenticate or access a resource on behalf of a user. For more information, see [Non-interactive user sign-ins](concept-all-sign-ins.md#non-interactive-user-sign-ins).

+### Service principal sign-in logs

+If you need to review sign-in activity for apps or service principals, the `ServicePrincipalSignInLogs` may be a good option. In these scenarios, certificates or client secrets are used for authentication. For more information, see [Service principal sign-ins](concept-all-sign-ins.md#service-principal-sign-ins).

+### Managed identity sign-in logs

+The `ManagedIdentitySignInLogs` provide similar insights as the service principal sign-in logs, but for managed identities, where Azure manages the secrets. For more information, see [Managed identity sign-ins](concept-all-sign-ins.md#managed-identity-for-azure-resources-sign-ins).

+### Provisioning logs

+If your organization provisions users through a third-party application such as Workday or ServiceNow, you may want to export the `ProvisioningLogs` reports. For more information, see [Provisioning logs](concept-provisioning-logs.md).

+### AD FS sign-in logs

+Sign-in activity for Active Directory Federated Services (AD FS) applications are captured in this Usage and insight reports. You can export the `ADFSSignInLogs` report to monitor sign-in activity for AD FS applications. For more information, see [AD FS sign-in logs](concept-usage-insights-report.md#ad-fs-application-activity).

+### Risky users

+The `RiskyUsers` logs identify users who are at risk based on their sign-in activity. This report is part of Azure AD Identity Protection and uses sign-in data from Azure AD. For more information, see [What is Azure AD Identity Protection?](../identity-protection/overview-identity-protection.md).

+### User risk events

+The `UserRiskEvents` logs are part of Azure AD Identity Protection. These logs capture details about risky sign-in events. For more information, see [How to investigate risk](../identity-protection/howto-identity-protection-investigate-risk.md#risky-sign-ins).

+### Risky service principals

+The `RiskyServicePrincipals` logs provide information about service principals that Azure AD Identity Protection detected as risky. Service principal risk represents the probability that an identity or account is compromised. These risks are calculated asynchronously using data and patterns from Microsoft's internal and external threat intelligence sources. These sources may include security researchers, law enforcement professionals, and security teams at Microsoft. For more information, see [Securing workload identities](../identity-protection/concept-workload-identity-risk.md)

+### Service principal risk events

+The `ServicePrincipalRiskEvents` logs provide details around the risky sign-in events for service principals. These logs may include any identified suspicious events related to the service principal accounts. For more information, see [Securing workload identities](../identity-protection/concept-workload-identity-risk.md)

+### Enriched Microsoft 365 audit logs

+The `EnrichedOffice365AuditLogs` logs are associated with the enriched logs you can enable for Microsoft Entra Internet Access. Selecting this option doesn't add new logs to your workspace unless your organization is using Microsoft Entra Internet to secure access to your Microsoft 365 traffic *and* you enabled the enriched logs. For more information, see [How to use the Global Secure Access enriched Microsoft 365 logs](../../global-secure-access/how-to-view-enriched-logs.md).

+### Microsoft Graph activity logs

+The `MicrosoftGraphActivityLogs` logs are associated with a feature that is still in preview. The logs are visible in Azure AD, but selecting these options won't add new logs to your workspace unless your organization was included in the preview.

+### Network access traffic logs

+The `NetworkAccessTrafficLogs` logs are associated with Microsoft Entra Internet Access and Microsoft Entra Private Access. The logs are visible in Azure AD, but selecting this option doesn't add new logs to your workspace unless your organization is using Microsoft Entra Internet Access and Microsoft Entra Private Access to secure access to your corporate resources. For more information, see [What is Global Secure Access?](../../global-secure-access/overview-what-is-global-secure-access.md).

+## Next steps

+- [Learn about the sign-ins logs](concept-all-sign-ins.md)

+- [Explore how to access the activity logs](howto-access-activity-logs.md)

+ Title: Azure Active Directory activity log integration options and considerations

+description: Introduction to the options and considerations for integrating Azure Active Directory activity logs with storage and analysis tools.

+# Azure AD activity log integrations

+Using **Diagnostic settings** in Azure Active Directory (Azure AD), you can route activity logs to several endpoints for long term data retention and insights. You can archive logs for storage, route to Security Information and Event Management (SIEM) tools, and integrate logs with Azure Monitor logs.

+With these integrations, you can enable rich visualizations, monitoring, and alerting on the connected data. This article describes the recommended uses for each integration type or access method. Cost considerations for sending Azure AD activity logs to various endpoints are also covered.

+## Supported reports

+The following logs can be integrated with one of many endpoints:

+* The [**audit logs activity report**](concept-audit-logs.md) gives you access to the history of every task that's performed in your tenant.

+* With the [**sign-in activity report**](concept-sign-ins.md), you can see when users attempt to sign in to your applications or troubleshoot sign-in errors.

+* With the [**provisioning logs**](../app-provisioning/application-provisioning-log-analytics.md), you can monitor which users have been created, updated, and deleted in all your third-party applications.

+* The [**risky users logs**](../identity-protection/howto-identity-protection-investigate-risk.md#risky-users) helps you monitor changes in user risk level and remediation activity.

+* With the [**risk detections logs**](../identity-protection/howto-identity-protection-investigate-risk.md#risk-detections), you can monitor user's risk detections and analyze trends in risk activity detected in your organization.

+## Integration options

+To help choose the right method for integrating Azure AD activity logs for storage or analysis, think about the overall task you're trying to accomplish. We've grouped the options into three main categories:

+- Troubleshooting

+- Long-term storage

+- Analysis and monitoring

+### Troubleshooting

+If you're performing troubleshooting tasks but you don't need to retain the logs for more than 30 days, we recommend using the Azure portal or Microsoft Graph to access activity logs. You can filter the logs for your scenario and export or download them as needed.

+If you're performing troubleshooting tasks *and* you need to retain the logs for more than 30 days, take a look at the long-term storage options.

+### Long-term storage

+If you're performing troubleshooting tasks *and* you need to retain the logs for more than 30 days, you can export your logs to an Azure storage account. This option is ideal of you don't plan on querying that data often.

+If you need to query the data that you're retaining for more than 30 days, take a look at the analysis and monitoring options.

+### Analysis and monitoring

+If your scenario requires that you retain data for more than 30 days *and* you plan on querying that data regularly, you've got a few options to integrate your data with SIEM tools for analysis and monitoring.

+If you have a third party SIEM tool, we recommend setting up an Event Hubs namespace and event hub that you can stream your data through. With an event hub, you can stream logs to one of the supported SIEM tools.

+If you don't plan on using a third-party SIEM tool, we recommend sending your Azure AD activity logs to Azure Monitor logs. With this integration, you can query your activity logs with Log Analytics. In Addition to Azure Monitor logs, Microsoft Sentinel provides near real-time security detection and threat hunting. If you decide to integrate with SIEM tools later, you can stream your Azure AD activity logs along with your other Azure data through an event hub.

+## Cost considerations

+There's a cost for sending data to a Log Analytics workspace, archiving data in a storage account, or streaming logs to an event hub. The amount of data and the cost incurred can vary significantly depending on the tenant size, the number of policies in use, and even the time of day.

+Because the size and cost for sending logs to an endpoint is difficult to predict, the most accurate way to determine your expected costs is to route your logs to an endpoint for day or two. With this snapshot, you can get an accurate prediction for your expected costs. You can also get an estimate of your costs by downloading a sample of your logs and multiplying accordingly to get an estimate for one day.

+Other considerations for sending Azure AD logs to Azure Monitor logs are covered in the following Azure Monitor cost details articles:

+- [Azure Monitor logs cost calculations and options](../../azure-monitor/logs/cost-logs.md)

+- [Azure Monitor cost and usage](../../azure-monitor/usage-estimated-costs.md)

+- [Optimize costs in Azure Monitor](../../azure-monitor/best-practices-cost.md)

+Azure Monitor provides the option to exclude whole events, fields, or parts of fields when ingesting logs from Azure AD. Learn more about this cost saving feature in [Data collection transformation in Azure Monitor](../../azure-monitor/essentials/data-collection-transformations.md).

+## Estimate your costs

+To estimate the costs for your organization, you can estimate either the daily log size or the daily cost for integrating your logs with an endpoint.

+The following factors could affect costs for your organization:

+- Audit log events use around 2 KB of data storage

+- Sign-in log events use on average 11.5 KB of data storage

+- A tenant of about 100,000 users could incur about 1.5 million events per day

+- Events are batched into about 5-minute intervals and sent as a single message that contains all the events within that time frame

+### Daily log size

+To estimate the daily log size, gather a sample of your logs, adjust the sample to reflect your tenant size and settings, then apply that sample to the [Azure pricing calculator](https://azure.microsoft.com/pricing/calculator/).

+If you haven't downloaded logs from the Azure portal, review the [How to download logs in Azure AD](howto-download-logs.md) article. Depending on the size of your organization, you may need to choose a different sample size to start your estimation. The following sample sizes are a good place to start:

+- 1000 records

+- For large tenants, 15 minutes of sign-ins

+- For small to medium tenants, 1 hour of sign-ins

+You should also consider the geographic distribution and peak hours of your users when you capture your data sample. If your organization is based in one region, it's likely that sign-ins peak around the same time. Adjust your sample size and when you capture the sample accordingly.

+With the data sample captured, multiply accordingly to find out how large the file would be for one day.

+### Estimate the daily cost

+To get an idea of how much a log integration could cost for your organization, you can enable an integration for a day or two. Use this option if your budget allows for the temporary increase.

+To enable a log integration, follow the steps in the [Integrate activity logs with Azure Monitor logs](howto-integrate-activity-logs-with-log-analytics.md) article. If possible, create a new resource group for the logs and endpoint you want to try out. Having a devoted resource group makes it easy to view the cost analysis and then delete it when you're done.

+With the integration enabled, navigate to **Azure portal** > **Cost Management** > **Cost analysis**. There are several ways to analyze costs. This [Cost Management quickstart](../../cost-management-billing/costs/quick-acm-cost-analysis.md) should help you get started. The figures in the following screenshot are used for example purposes and are not intended to reflect actual amounts.

+

+Make sure you're using your new resource group as the scope. Explore the daily costs and forecasts to get an idea of how much your log integration could cost.

+## Calculate estimated costs

+From the [Azure pricing calculator](https://azure.microsoft.com/pricing/calculator/) landing page, you can estimate the costs for various products.

+- [Azure Monitor](https://azure.microsoft.com/pricing/details/monitor/)

+- [Azure storage](https://azure.microsoft.com/pricing/details/storage/blobs/)

+- [Azure Event Hubs](https://azure.microsoft.com/pricing/details/event-hubs/)

+- [Microsoft Sentinel](https://azure.microsoft.com/pricing/details/microsoft-sentinel/)

+Once you have an estimate for the GB/day that will be sent to an endpoint, enter that value in the [Azure pricing calculator](https://azure.microsoft.com/pricing/calculator/). The figures in the following screenshot are used for example purposes and are not intended to reflect actual prices.

+

+## Next steps

+* [Create a storage account](../../storage/common/storage-account-create.md)

+* [Archive activity logs to a storage account](quickstart-azure-monitor-route-logs-to-storage-account.md)

+* [Route activity logs to an event hub](./tutorial-azure-monitor-stream-logs-to-event-hub.md)

+* [Integrate activity logs with Azure Monitor](howto-integrate-activity-logs-with-log-analytics.md)

+description: Learn how to choose the right method for accessing the activity logs in Azure Active Directory.

+# How to access activity logs in Azure AD

+The data collected in your Azure Active Directory (Azure AD) logs enables you to assess many aspects of your Azure AD tenant. To cover a broad range of scenarios, Azure AD provides you with several options to access your activity log data. As an IT administrator, you need to understand the intended uses cases for these options, so that you can select the right access method for your scenario.

+The required roles and licenses may vary based on the report. Global Administrators can access all reports, but we recommend using a role with least privilege access to align with the [Zero Trust guidance](/security/zero-trust/zero-trust-overview).

+*The level of access and capabilities for Identity Protection vary with the role and license. For more information, see the [license requirements for Identity Protection](../identity-protection/overview-identity-protection.md#license-requirements).

+The Microsoft Graph API provides a unified programmability model that you can use to access data for your Azure AD Premium tenants. It doesn't require an administrator or developer to set up extra infrastructure to support your script or app.

+#### Archive activity logs to a storage account

+ Title: How to archive activity logs to a storage account

+description: Learn how to archive Azure Active Directory logs to a storage account

+# Customer intent: As an IT administrator, I want to learn how to archive Azure AD logs to an Azure storage account so I can retain it for longer than the default retention period.

+# How to archive Azure AD logs to an Azure storage account

+If you need to store Azure Active Directory (Azure AD) activity logs for longer than the [default retention period](reference-reports-data-retention.md), you can archive your logs to a storage account.

+## Prerequisites

+To use this feature, you need:

+* An Azure subscription with an Azure storage account. If you don't have an Azure subscription, you can [sign up for a free trial](https://azure.microsoft.com/free/).

+* A user who's a *Security Administrator* or *Global Administrator* for the Azure AD tenant.

+## Archive logs to an Azure storage account

+6. Under **Destination Details** select the **Archive to a storage account** check box.

+7. Select the appropriate **Subscription** and **Storage account** from the menus.

+ 

+8. After the categories have been selected, in the **Retention days** field, type in the number of days of retention you need of your log data. By default, this value is *0*, which means that logs are retained in the storage account indefinitely. If you set a different value, events older than the number of days selected are automatically cleaned up.

+ > [!NOTE]

+ > The Diagnostic settings storage retention feature is being deprecated. For details on this change, see [**Migrate from diagnostic settings storage retention to Azure Storage lifecycle management**](../../azure-monitor/essentials/migrate-to-azure-storage-lifecycle-policy.md).

+

+9. Select **Save** to save the setting.

+10. Close the window to return to the Diagnostic settings pane.

+## Next steps

+- [Learn about other ways to access activity logs](howto-access-activity-logs.md)

+- [Manually download activity logs](howto-download-logs.md)

+- [Integrate activity logs with Azure Monitor logs](howto-integrate-activity-logs-with-azure-monitor-logs.md)

+- [Stream logs to an event hub](howto-stream-logs-to-event-hub.md)

+The Azure Active Directory (Azure AD) [reporting APIs](/graph/api/resources/azure-ad-auditlog-overview) provide you with programmatic access to the data through a set of REST APIs. You can call these APIs from many programming languages and tools. The reporting API uses [OAuth](../../api-management/api-management-howto-protect-backend-with-aad.md) to authorize access to the web APIs. The Microsoft Graph API is **not** designed for pulling large amounts of activity data. Pulling large amounts of activity data using the API may lead to issues with pagination and performance.

+In order to access the sign-in reports for a tenant, an Azure AD tenant must have associated Azure AD Premium P1 or P2 license. If the directory type is Azure AD B2C, the sign-in reports are accessible through the API without any additional license requirement.

+# How to download logs in Azure Active Directory

+ Title: Integrate Azure Active Directory logs with Azure Monitor logs

+description: Learn how to integrate Azure Active Directory logs with Azure Monitor logs for querying and analysis.

+# Integrate Azure AD logs with Azure Monitor logs

+Using **Diagnostic settings** in Azure Active Directory (Azure AD), you can integrate logs with Azure Monitor so your sign-in activity and the audit trail of changes within your tenant can be analyzed along with other Azure data.

+This article provides the steps to integrate Azure Active Directory (Azure AD) logs with Azure Monitor.

+Use the integration of Azure AD activity logs and Azure Monitor to perform the following tasks:

+- Compare your Azure AD sign-in logs against security logs published by Microsoft Defender for Cloud.

+- Troubleshoot performance bottlenecks on your applicationΓÇÖs sign-in page by correlating application performance data from Azure Application Insights.

+- Analyze the Identity Protection risky users and risk detections logs to detect threats in your environment.

+- Identify sign-ins from applications still using the Active Directory Authentication Library (ADAL) for authentication. [Learn about the ADAL end-of-support plan.](../develop/msal-migration.md)

+> [!NOTE]

+> Integrating Azure Active Directory logs with Azure Monitor automatically enables the Azure Active Directory data connector within Microsoft Sentinel.

+## How do I access it?

+To use this feature, you need:

+* An Azure subscription. If you don't have an Azure subscription, you can [sign up for a free trial](https://azure.microsoft.com/free/).

+* An Azure AD Premium P1 or P2 tenant.

+* **Global Administrator** or **Security Administrator** access for the Azure AD tenant.

+* A **Log Analytics workspace** in your Azure subscription. Learn how to [create a Log Analytics workspace](../../azure-monitor/logs/quick-create-workspace.md).

+* Permission to access data in a Log Analytics workspace. See [Manage access to log data and workspaces in Azure Monitor](../../azure-monitor/logs/manage-access.md) for information on the different permission options and how to configure permissions.

+## Create a Log Analytics workspace

+A Log Analytics workspace allows you to collect data based on a variety or requirements, such as geographic location of the data, subscription boundaries, or access to resources. Learn how to [create a Log Analytics workspace](../../azure-monitor/logs/quick-create-workspace.md).

+Looking for how to set up a Log Analytics workspace for Azure resources outside of Azure AD? Check out the [Collect and view resource logs for Azure Monitor](../../azure-monitor/essentials/diagnostic-settings.md) article.

+## Send logs to Azure Monitor

+Follow the steps below to send logs from Azure Active Directory to Azure Monitor logs. Looking for how to set up Log Analytics workspace for Azure resources outside of Azure AD? Check out the [Collect and view resource logs for Azure Monitor](../../azure-monitor/essentials/diagnostic-settings.md) article.

+6. Under **Destination Details** select the **Send to Log Analytics workspace** check box.

+7. Select the appropriate **Subscription** and **Log Analytics workspace** from the menus.

+8. Select the **Save** button.

+ 

+If you do not see logs appearing in the selected destination after 15 minutes, sign out and back into Azure to refresh the logs.

+## Next steps

+* [Analyze Azure AD activity logs with Azure Monitor logs](howto-analyze-activity-logs-log-analytics.md)

+* [Learn about the data sources you can analyze with Azure Monitor](../../azure-monitor/data-sources.md)

+* [Automate creating diagnostic settings with Azure Policy](../../azure-monitor/essentials/diagnostic-settings-policy.md)

+ Title: Stream Azure Active Directory logs to an event hub

+description: Learn how to stream Azure Active Directory logs to an event hub for SIEM tool integration.

+# How to stream activity logs to an event hub

+Your Azure Active Directory (Azure AD) tenant produces large amounts of data every second. Sign-in activity and logs of changes made in your tenant add up to a lot of data that can be hard to analyze. Integrating with Security Information and Event Management (SIEM) tools can help you gain insights into your environment.

+This article shows how you can stream your logs to an event hub, to integrate with one of several SIEM tools.

+## Prerequisites

+To stream logs to a SIEM tool, you first need to create an **Azure event hub**.

+Once you have an event hub that contains Azure AD activity logs, you can set up the SIEM tool integration using the **Azure AD Diagnostics Settings**.

+## Stream logs to an event hub

+6. Select the **Stream to an event hub** check box.

+7. Select the Azure subscription, Event Hubs namespace, and optional event hub where you want to route the logs.

+The subscription and Event Hubs namespace must both be associated with the Azure AD tenant from where you're streaming the logs.

+Once you have the Azure event hub ready, navigate to the SIEM tool you want to integrate with the activity logs. You'll finish the process in the SIEM tool.

+We currently support Splunk, SumoLogic, and ArcSight. Select a tab below to get started. Refer to the tool's documentation.

+# [Splunk](#tab/splunk)

+To use this feature, you need the [Splunk Add-on for Microsoft Cloud Services](https://splunkbase.splunk.com/app/3110/#/details).

+### Integrate Azure AD logs with Splunk

+1. Open your Splunk instance and select **Data Summary**.

+ 

+1. Select the **Sourcetypes** tab, and then select **mscs:azure:eventhub**

+ 

+Append **body.records.category=AuditLogs** to the search. The Azure AD activity logs are shown in the following figure:

+ 

+If you cannot install an add-on in your Splunk instance (for example, if you're using a proxy or running on Splunk Cloud), you can forward these events to the Splunk HTTP Event Collector. To do so, use this [Azure function](https://github.com/splunk/azure-functions-splunk), which is triggered by new messages in the event hub.

+# [SumoLogic](#tab/SumoLogic)

+To use this feature, you need a SumoLogic single sign-on enabled subscription.

+### Integrate Azure AD logs with SumoLogic

+1. Configure your SumoLogic instance to [collect logs for Azure Active Directory](https://help.sumologic.com/docs/integrations/microsoft-azure/active-directory-azure#collecting-logs-for-azure-active-directory).

+1. [Install the Azure AD SumoLogic app](https://help.sumologic.com/docs/integrations/microsoft-azure/active-directory-azure#viewing-azure-active-directory-dashboards) to use the pre-configured dashboards that provide real-time analysis of your environment.

+ 

+# [ArcSight](#tab/ArcSight)

+To use this feature, you need a configured instance of ArcSight Syslog NG Daemon SmartConnector (SmartConnector) or ArcSight Load Balancer. If the events are sent to ArcSight Load Balancer, they're sent to the SmartConnector by the Load Balancer.

+Download and open the [configuration guide for ArcSight SmartConnector for Azure Monitor Event Hubs](https://software.microfocus.com/products/siem-security-information-event-management/overview). This guide contains the steps you need to install and configure the ArcSight SmartConnector for Azure Monitor.

+## Integrate Azure AD logs with ArcSight

+1. Complete the steps in the **Prerequisites** section of the ArcSight configuration guide. This section includes the following steps:

+ * Set user permissions in Azure to ensure there's a user with the **owner** role to deploy and configure the connector.

+ * Open ports on the server with Syslog NG Daemon SmartConnector so it's accessible from Azure.

+ * The deployment runs a Windows PowerShell script, so you must enable PowerShell to run scripts on the machine where you want to deploy the connector.

+1. Follow the steps in the **Deploying the Connector** section of the ArcSight configuration guide to deploy the connector. This section walks you through how to download and extract the connector, configure application properties and run the deployment script from the extracted folder.

+1. Use the steps in the **Verifying the Deployment in Azure** to make sure the connector is set up and functions correctly. Verify the following prerequisites:

+ * The requisite Azure functions are created in your Azure subscription.

+ * The Azure AD logs are streamed to the correct destination.

+ * The application settings from your deployment are persisted in the Application Settings in Azure Function Apps.

+ * A new resource group for ArcSight is created in Azure, with an Azure AD application for the ArcSight connector and storage accounts containing the mapped files in CEF format.

+1. Complete the post-deployment steps in the **Post-Deployment Configurations** of the ArcSight configuration guide. This section explains how to perform another configuration if you are on an App Service Plan to prevent the function apps from going idle after a timeout period, configure streaming of resource logs from the event hub, and update the SysLog NG Daemon SmartConnector keystore certificate to associate it with the newly created storage account.

+1. The configuration guide also explains how to customize the connector properties in Azure, and how to upgrade and uninstall the connector. There's also a section on performance improvements, including upgrading to an [Azure Consumption plan](https://azure.microsoft.com/pricing/details/functions) and configuring an ArcSight Load Balancer if the event load is greater than what a single Syslog NG Daemon SmartConnector can handle.

+## Activity log integration options and considerations

+If your current SIEM isn't supported in Azure Monitor diagnostics yet, you can set up **custom tooling** by using the Event Hubs API. To learn more, see the [Getting started receiving messages from an event hub](../../event-hubs/event-hubs-dotnet-standard-getstarted-send.md).

+**IBM QRadar** is another option for integrating with Azure AD activity logs. The DSM and Azure Event Hubs Protocol are available for download at [IBM support](https://www.ibm.com/support). For more information about integration with Azure, go to the [IBM QRadar Security Intelligence Platform 7.3.0](https://www.ibm.com/support/knowledgecenter/SS42VS_DSM/c_dsm_guide_microsoft_azure_overview.html?cp=SS42VS_7.3.0) site.

+Some sign-in categories contain large amounts of log data, depending on your tenantΓÇÖs configuration. In general, the non-interactive user sign-ins and service principal sign-ins can be 5 to 10 times larger than the interactive user sign-ins.

+## Next steps

+- [Analyze Azure AD activity logs with Azure Monitor logs](howto-analyze-activity-logs-log-analytics.md)

+- [Use Microsoft Graph to access Azure AD activity logs](quickstart-access-log-with-graph-api.md)

+# How to use Azure Active Directory Recommendations

+ Title: Azure Monitor workbooks for Azure Active Directory

+description: Learn how to use Azure Monitor workbooks for Azure Active Directory reports.

+# How to use Azure Active Directory Workbooks

+Workbooks are found in Azure AD and in Azure Monitor. The concepts, processes, and best practices are the same for both types of workbooks, however, workbooks for Azure Active Directory (AD) cover only those identity management scenarios that are associated with Azure AD.

+When using workbooks, you can either start with an empty workbook, or use an existing template. Workbook templates enable you to quickly get started using workbooks without needing to build from scratch.

+- **Public templates** published to a [gallery](../../azure-monitor/visualize/workbooks-overview.md#the-gallery) are a good starting point when you're just getting started with workbooks.

+- **Private templates** are helpful when you start building your own workbooks and want to save one as a template to serve as the foundation for multiple workbooks in your tenant.

+## Prerequisites

+To use Azure Workbooks for Azure AD, you need:

+- An Azure AD tenant with a [Premium P1 license](../fundamentals/get-started-premium.md)

+- A Log Analytics workspace *and* access to that workspace

+- The appropriate roles for Azure Monitor *and* Azure AD

+### Log Analytics workspace

+You must create a [Log Analytics workspace](../../azure-monitor/logs/quick-create-workspace.md) *before* you can use Azure AD Workbooks. There are a combination of factors that determine access to Log Analytics workspaces. You need the right roles for the workspace *and* the resources sending the data.

+For more information, see [Manage access to Log Analytics workspaces](../../azure-monitor/logs/manage-access.md).

+### Azure Monitor roles

+Azure Monitor provides [two built-in roles](../../azure-monitor/roles-permissions-security.md#monitoring-reader) for viewing monitoring data and editing monitoring settings. Azure role-based access control (RBAC) also provides two Log Analytics built-in roles that grant similar access.

+- **View**:

+ - Monitoring Reader

+ - Log Analytics Reader

+- **View and modify settings**:

+ - Monitoring Contributor

+ - Log Analytics Contributor

+For more information on the Azure Monitor built-in roles, see [Roles, permissions, and security in Azure Monitor](../../azure-monitor/roles-permissions-security.md#monitoring-reader).

+For more information on the Log Analytics RBAC roles, see [Azure built-in roles](../../role-based-access-control/built-in-roles.md#log-analytics-contributor)

+### Azure AD roles

+Read only access allows you to view Azure AD log data inside a workbook, query data from Log Analytics, or read logs in the Azure AD portal. Update access adds the ability to create and edit diagnostic settings to send Azure AD data to a Log Analytics workspace.

+- **Read**:

+ - Reports Reader

+ - Security Reader

+ - Global Reader

+- **Update**:

+ - Security Administrator

+For more information on Azure AD built-in roles, see [Azure AD built-in roles](../roles/permissions-reference.md).

+## How to access Azure Workbooks for Azure AD

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

+1. Navigate to **Azure Active Directory** > **Monitoring** > **Workbooks**.

+ - **Workbooks**: All workbooks created in your tenant

+ - **Public Templates**: Prebuilt workbooks for common or high priority scenarios

+ - **My Templates**: Templates you've created

+1. Select a report or template from the list. Workbooks may take a few moments to populate.

+ - Search for a template by name.

+ - Select the **Browse across galleries** to view templates that aren't specific to Azure AD.

+ 

+## Create a new workbook

+Workbooks can be created from scratch or from a template. When creating a new workbook, you can add elements as you go or use the **Advanced Editor** option to paste in the JSON representation of a workbook, copied from the [workbooks GitHub repository](https://github.com/Microsoft/Application-Insights-Workbooks/blob/master/schema/workbook.json).

+**To create a new workbook from scratch**:

+1. Navigate to **Azure AD** > **Monitoring** > **Workbooks**.

+1. Select **+ New**.

+1. Select an element from the **+ Add** menu.

+ For more information on the available elements, see [Creating an Azure Workbook](../../azure-monitor/visualize/workbooks-create-workbook.md).

+ 

+**To create a new workbook from a template**:

+1. Navigate to **Azure AD** > **Monitoring** > **Workbooks**.

+1. Select a workbook template from the Gallery.

+1. Select **Edit** from the top of the page.

+ - Each element of the workbook has its own **Edit** button.

+ - For more information on editing workbook elements, see [Azure Workbooks Templates](../../azure-monitor/visualize/workbooks-templates.md)

+1. Select the **Edit** button for any element. Make your changes and select **Done editing**.

+ 

+1. When you're done editing the workbook, select the **Save As** to save your workbook with a new name.

+1. In the **Save As** window:

+ - Provide a **Title**, **Subscription**, **Resource Group** (you must have the ability to save a workbook for the selected Resource Group), and **Location**.

+ - Optionally choose to save your workbook content to an [Azure Storage Account](../../azure-monitor/visualize/workbooks-bring-your-own-storage.md).

+1. Select the **Apply** button.

+## Next steps

+* [Create interactive reports by using Monitor workbooks](../../azure-monitor/visualize/workbooks-overview.md).

+* [Create custom Azure Monitor queries using Azure PowerShell](../governance/entitlement-management-logs-and-reporting.md).

+ Title: What is Azure Active Directory monitoring and health?

+description: Provides a general overview of Azure Active Directory monitoring and health.

+# What is Azure Active Directory monitoring and health?

+The features of Azure Active Directory (Azure AD) Monitoring and health provide a comprehensive view of identity related activity in your environment. This data enables you to:

+- Determine how your users utilize your apps and services.

+- Detect potential risks affecting the health of your environment.

+- Troubleshoot issues preventing your users from getting their work done.

+Sign-in and audit logs comprise the activity logs behind many Azure AD reports, which can be used to analyze, monitor, and troubleshoot activity in your tenant. Routing your activity logs to an analysis and monitoring solution provides greater insights into your tenant's health and security.

+This article describes the types of activity logs available in Azure AD, the reports that use the logs, and the monitoring services available to help you analyze the data.

+## Identity activity logs

+Activity logs help you understand the behavior of users in your organization. There are three types of activity logs in Azure AD:

+- [**Audit logs**](concept-audit-logs.md) include the history of every task performed in your tenant.

+- [**Sign-in logs**](concept-all-sign-ins.md) capture the sign-in attempts of your users and client applications.

+- [**Provisioning logs**](concept-provisioning-logs.md) provide information around users provisioned in your tenant through a third party service.

+The activity logs can be viewed in the Azure portal or using the Microsoft Graph API. Activity logs can also be routed to various endpoints for storage or analysis. To learn about all of the options for viewing the activity logs, see [How to access activity logs](howto-access-activity-logs.md).

+### Audit logs

+Audit logs provide you with records of system activities for compliance. This data enables you to address common scenarios such as:

+- Someone in my tenant got access to an admin group. Who gave them access?

+- I want to know the list of users signing into a specific app because I recently onboarded the app and want to know if itΓÇÖs doing well.

+- I want to know how many password resets are happening in my tenant.

+### Sign-in logs

+The sign-ins logs enable you to find answers to questions such as:

+- What is the sign-in pattern of a user?

+- How many users have users signed in over a week?

+- WhatΓÇÖs the status of these sign-ins?

+### Provisioning logs

+You can use the provisioning logs to find answers to questions like:

+- What groups were successfully created in ServiceNow?

+- What users were successfully removed from Adobe?

+- What users from Workday were successfully created in Active Directory?

+## Identity reports

+Reviewing the data in the Azure AD activity logs can provide helpful information for IT administrators. To streamline the process of reviewing data on key scenarios, we've created several reports on common scenarios that use the activity logs.

+- [Identity Protection](../identity-protection/overview-identity-protection.md) uses sign-in data to create reports on risky users and sign-in activities.

+- Activity related to your applications, such as service principal and app credential activity, are used to create reports in [Usage and insights](concept-usage-insights-report.md).

+- [Azure AD workbooks](overview-workbooks.md) provide a customizable way to view and analyze the activity logs.

+- [Monitor the status of Azure AD recommendations to improve your tenant's security.](overview-recommendations.md)

+## Identity monitoring and tenant health

+Reviewing Azure AD activity logs is the first step in maintaining and improving the health and security of your tenant. You need to analyze the data, monitor on risky scenarios, and determine where you can make improvements. Azure AD monitoring provides the necessary tools to help you make informed decisions.

+Monitoring Azure AD activity logs requires routing the log data to a monitoring and analysis solution. Endpoints include Azure Monitor logs, Microsoft Sentinel, or a third-party solution third-party Security Information and Event Management (SIEM) tool.

+- [Stream logs to an event hub to integrate with third-party SIEM tools.](howto-stream-logs-to-event-hub.md)

+- [Integrate logs with Azure Monitor logs.](howto-integrate-activity-logs-with-log-analytics.md)

+- [Analyze logs with Azure Monitor logs and Log Analytics.](howto-analyze-activity-logs-log-analytics.md)

+For an overview of how to access, store, and analyze activity logs, see [How to access activity logs](howto-access-activity-logs.md).

+## Next steps

+- [Learn about the sign-ins logs](concept-all-sign-ins.md)

+- [Learn about the audit logs](concept-audit-logs.md)

+- [Use Microsoft Graph to access activity logs](quickstart-access-log-with-graph-api.md)

+- [Integrate activity logs with SIEM tools](howto-stream-logs-to-event-hub.md)

+ Title: Migrate from ADAL to MSAL recommendation

+The first step to migrating your apps from ADAL to MSAL is to identify all applications in your tenant that are currently using ADAL. You can identify your apps programmatically with the Microsoft Graph API or the Microsoft Graph PowerShell SDK. The steps for the Microsoft Graph PowerShell SDK are provided in the Recommendation details in the Azure Active Directory portal.

+1. Sign in to [Graph Explorer](https://aka.ms/ge).

+1. Select **GET** as the HTTP method from the dropdown.

+1. Set the API version to **beta**.

+1. Run the following query in Microsoft Graph, replacing the `<TENANT_ID>` placeholder with your tenant ID. This query returns a list of the impacted resources in your tenant.

+The [Azure AD sign-ins workbook](../develop/howto-get-list-of-all-auth-library-apps.md) was an alternative method to identify these apps. The workbook is still available to you, but using the workbook requires streaming sign-in logs to Azure Monitor first. The ADAL to MSAL recommendation works out of the box. Plus, the sign-ins workbook doesn't capture Service Principal sign-ins, while the recommendation does.

+ Title: Configure a log analytics workspace in Azure AD

+description: Learn how to configure Log Analytics workspace and run KQL queries on your identity data.

+#Customer intent: As an IT admin, I want to set up log analytics so I can analyze the health of my environment.

+# Tutorial: Configure a log analytics workspace

+In this tutorial, you learn how to:

+> [!div class="checklist"]

+> * Configure a log analytics workspace for your audit and sign-in logs

+> * Run queries using the Kusto Query Language (KQL)

+> * Create an alert rule that sends alerts when a specific account is used

+> * Create a custom workbook using the quickstart template

+> * Add a query to an existing workbook template

+## Prerequisites

+- An Azure subscription with at least one P1 licensed admin. If you don't have an Azure subscription, you can [sign up for a free trial](https://azure.microsoft.com/free/).

+- An Azure Active Directory (Azure AD) tenant.

+- A user who's a Global Administrator or Security Administrator for the Azure AD tenant.

+Familiarize yourself with these articles:

+- [Tutorial: Collect and analyze resource logs from an Azure resource](../../azure-monitor/essentials/tutorial-resource-logs.md)

+- [How to integrate activity logs with Log Analytics](./howto-integrate-activity-logs-with-log-analytics.md)

+- [Manage emergency access account in Azure AD](../roles/security-emergency-access.md)

+- [KQL quick reference](/azure/data-explorer/kql-quick-reference)

+- [Azure Monitor Workbooks](../../azure-monitor/visualize/workbooks-overview.md)

+## Configure a workspace

+This procedure outlines how to configure a log analytics workspace for your audit and sign-in logs.

+Configuring a log analytics workspace consists of two main steps:

+

+1. Creating a log analytics workspace

+2. Setting diagnostic settings

+**To configure a workspace:**

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

+2. Search for **log analytics workspaces**.

+ 

+3. On the log analytics workspaces page, click **Add**.

+ 

+4. On the **Create Log Analytics workspace** page, perform the following steps:

+ 

+ 1. Select your subscription.

+ 2. Select a resource group.

+

+ 3. In the **Name** textbox, type a name (e.g.: MytestWorkspace1).

+ 4. Select your region.

+5. Click **Review + Create**.

+ 

+6. Click **Create** and wait for the deployment to be succeeded. You may need to refresh the page to see the new workspace.

+ 

+7. Search for **Azure Active Directory**.

+ 

+8. In **Monitoring** section, click **Diagnostic setting**.

+ 

+9. On the **Diagnostic settings** page, click **Add diagnostic setting**.

+ 

+10. On the **Diagnostic setting** page, perform the following steps:

+ 

+ 1. Under **Category details**, select **AuditLogs** and **SigninLogs**.

+ 2. Under **Destination details**, select **Send to Log Analytics**, and then select your new log analytics workspace.

+

+ 3. Click **Save**.

+## Run queries

+This procedure shows how to run queries using the **Kusto Query Language (KQL)**.

+**To run a query:**

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

+2. Search for **Azure Active Directory**.

+ 

+3. In the **Monitoring** section, click **Logs**.

+4. On the **Logs** page, click **Get Started**.

+5. In the **Search* textbox, type your query.

+6. Click **Run**.

+### KQL query examples

+Take 10 random entries from the input data:

+`SigninLogs | take 10`

+Look at the sign-ins where the Conditional Access was a success

+`SigninLogs | where ConditionalAccessStatus == "success" | project UserDisplayName, ConditionalAccessStatus`

+Count how many successes there have been

+`SigninLogs | where ConditionalAccessStatus == "success" | project UserDisplayName, ConditionalAccessStatus | count`

+Aggregate count of successful sign-ins by user by day:

+`SigninLogs | where ConditionalAccessStatus == "success" | summarize SuccessfulSign-ins = count() by UserDisplayName, bin(TimeGenerated, 1d)`

+View how many times a user does a certain operation in specific time period:

+`AuditLogs | where TimeGenerated > ago(30d) | where OperationName contains "Add member to role" | summarize count() by OperationName, Identity`

+Pivot the results on operation name

+`AuditLogs | where TimeGenerated > ago(30d) | where OperationName contains "Add member to role" | project OperationName, Identity | evaluate pivot(OperationName)`

+Merge together Audit and Sign in Logs using an inner join:

+`AuditLogs |where OperationName contains "Add User" |extend UserPrincipalName = tostring(TargetResources[0].userPrincipalName) | |project TimeGenerated, UserPrincipalName |join kind = inner (SigninLogs) on UserPrincipalName |summarize arg_min(TimeGenerated, *) by UserPrincipalName |extend SigninDate = TimeGenerated`

+View number of signs ins by client app type:

+`SigninLogs | summarize count() by ClientAppUsed`

+Count the sign ins by day:

+`SigninLogs | summarize NumberOfEntries=count() by bin(TimeGenerated, 1d)`

+Take 5 random entries and project the columns you wish to see in the results:

+`SigninLogs | take 5 | project ClientAppUsed, Identity, ConditionalAccessStatus, Status, TimeGenerated `

+Take the top 5 in descending order and project the columns you wish to see

+`SigninLogs | take 5 | project ClientAppUsed, Identity, ConditionalAccessStatus, Status, TimeGenerated `

+Create a new column by combining the values to two other columns:

+`SigninLogs | limit 10 | extend RiskUser = strcat(RiskDetail, "-", Identity) | project RiskUser, ClientAppUsed`

+## Create an alert rule

+This procedure shows how to send alerts when the breakglass account is used.

+**To create an alert rule:**

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

+2. Search for **Azure Active Directory**.

+ 

+3. In the **Monitoring** section, click **Logs**.

+4. On the **Logs** page, click **Get Started**.

+5. In the **Search** textbox, type: `SigninLogs |where UserDisplayName contains "BreakGlass" | project UserDisplayName`

+6. Click **Run**.

+7. In the toolbar, click **New alert rule**.

+ 

+8. On the **Create alert rule** page, verify that the scope is correct.

+9. Under **Condition**, click: **Whenever the average custom log search is greater than `logic undefined` count**

+ 

+10. On the **Configure signal logic** page, in the **Alert logic** section, perform the following steps:

+ 

+ 1. As **Based on**, select **Number of results**.

+ 2. As **Operator**, select **Greater than**.

+ 3. As **Threshold value**, select **0**.

+11. On the **Configure signal logic** page, in the **Evaluated based on** section, perform the following steps:

+ 

+ 1. As **Period (in minutes)**, select **5**.

+ 2. As **Frequency (in minutes)**, select **5**.

+ 3. Click **Done**.

+12. Under **Action group**, click **Select action group**.

+ 

+13. On the **Select an action group to attach to this alert rule**, click **Create action group**.

+ 

+14. On the **Create action group** page, perform the following steps:

+ 

+ 1. In the **Action group name** textbox, type **My action group**.

+ 2. In the **Display name** textbox, type **My action**.

+ 3. Click **Review + create**.

+ 4. Click **Create**.

+15. Under **Customize action**, perform the following steps:

+ 

+ 1. Select **Email subject**.

+ 2. In the **Subject line** textbox, type: `Breakglass account has been used`

+16. Under **Alert rule details**, perform the following steps:

+ 

+ 1. In the **Alert rule name** textbox, type: `Breakglass account`

+ 2. In the **Description** textbox, type: `Your emergency access account has been used`

+17. Click **Create alert rule**.

+## Create a custom workbook

+This procedure shows how to create a new workbook using the quickstart template.

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

+2. Search for **Azure Active Directory**.

+ 

+3. In the **Monitoring** section, click **Workbooks**.

+ 

+4. In the **Quickstart** section, click **Empty**.

+ 

+5. Click **Add**.

+ 

+6. Click **Add text**.

+ 

+7. In the textbox, type: `# Client apps used in the past week`, and then click **Done Editing**.

+ 

+8. In the new workbook, click **Add**, and then click **Add query**.

+ 

+9. In the query textbox, type: `SigninLogs | where TimeGenerated > ago(7d) | project TimeGenerated, UserDisplayName, ClientAppUsed | summarize count() by ClientAppUsed`

+10. Click **Run Query**.

+ 

+11. In the toolbar, under **Visualization**, click **Pie chart**.

+ 

+12. Click **Done Editing**.

+ 

+## Add a query to a workbook template

+This procedure shows how to add a query to an existing workbook template. The example is based on a query that shows the distribution of conditional access success to failures.

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

+2. Search for **Azure Active Directory**.

+ 

+3. In the **Monitoring** section, click **Workbooks**.

+ 

+4. In the **conditional access** section, click **Conditional Access Insights and Reporting**.

+ 

+5. In the toolbar, click **Edit**.

+ 

+6. In the toolbar, click the three dots, then **Add**, and then **Add query**.

+ 

+7. In the query textbox, type: `SigninLogs | where TimeGenerated > ago(20d) | where ConditionalAccessPolicies != "[]" | summarize dcount(UserDisplayName) by bin(TimeGenerated, 1d), ConditionalAccessStatus`

+8. Click **Run Query**.

+ 

+9. Click **Time Range**, and then select **Set in query**.

+10. Click **Visualization**, and then select **Bar chart**.

+11. Click **Advanced Settings**, as chart title, type `Conditional Access status over the last 20 days`, and then click **Done Editing**.

+ 

+## Next steps

+Advance to the next article to learn how to manage device identities by using the Azure portal.

+> [!div class="nextstepaction"]

+> [Monitoring](overview-monitoring.md)

+ Title: 'Tutorial: Configure Canva for automatic user provisioning with Azure Active Directory'

+description: Learn how to automatically provision and de-provision user accounts from Azure AD to Canva.

+writer: twimmers

+ms.assetid: 9bf62920-d9e0-4ed4-a4f6-860cb9563b00

+# Tutorial: Configure Canva for automatic user provisioning

+This tutorial describes the steps you need to perform in both Canva and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and de-provisions users and groups to [Canva](https://www.canva.com/) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

+## Supported capabilities

+> [!div class="checklist"]

+> * Create users in Canva.

+> * Remove users in Canva when they do not require access anymore.

+> * Keep user attributes synchronized between Azure AD and Canva.

+> * Provision groups and group memberships in Canva.

+> * [Single sign-on](canva-tutorial.md) to Canva (recommended).

+## Prerequisites

+The scenario outlined in this tutorial assumes that you already have the following prerequisites:

+* [An Azure AD tenant](../develop/quickstart-create-new-tenant.md).

+* A user account in Azure AD with [permission](../roles/permissions-reference.md) to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).

+* An Canva tenant.

+* A user account in Canva with Admin permissions.

+## Step 1. Plan your provisioning deployment

+1. Learn about [how the provisioning service works](../app-provisioning/user-provisioning.md).

+1. Determine who will be in [scope for provisioning](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. Determine what data to [map between Azure AD and Canva](../app-provisioning/customize-application-attributes.md).

+## Step 2. Configure Canva to support provisioning with Azure AD

+Contact Canva support to configure Canva to support provisioning with Azure AD.

+## Step 3. Add Canva from the Azure AD application gallery

+Add Canva from the Azure AD application gallery to start managing provisioning to Canva. If you have previously setup Canva for SSO you can use the same application. However it's recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery [here](../manage-apps/add-application-portal.md).

+## Step 4. Define who will be in scope for provisioning

+The Azure AD provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user / group. If you choose to scope who will be provisioned to your app based on assignment, you can use the following [steps](../manage-apps/assign-user-or-group-access-portal.md) to assign users and groups to the application. If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described [here](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* Start small. Test with a small set of users and groups before rolling out to everyone. When scope for provisioning is set to assigned users and groups, you can control this by assigning one or two users or groups to the app. When scope is set to all users and groups, you can specify an [attribute based scoping filter](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* If you need more roles, you can [update the application manifest](../develop/howto-add-app-roles-in-azure-ad-apps.md) to add new roles.

+## Step 5. Configure automatic user provisioning to Canva

+This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users and/or groups in TestApp based on user and/or group assignments in Azure AD.

+### To configure automatic user provisioning for Canva in Azure AD:

+1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise Applications**, then select **All applications**.

+ 

+1. In the applications list, select **Canva**.

+ 

+1. Select the **Provisioning** tab.

+ 

+1. Set the **Provisioning Mode** to **Automatic**.

+ 

+1. Under the **Admin Credentials** section, input your Canva Tenant URL and Secret Token. Click **Test Connection** to ensure Azure AD can connect to Canva. If the connection fails, ensure your Canva account has Admin permissions and try again.

+ 

+1. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box.

+ 

+1. Select **Save**.

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Canva**.

+1. Review the user attributes that are synchronized from Azure AD to Canva in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Canva for update operations. If you choose to change the [matching target attribute](../app-provisioning/customize-application-attributes.md), you'll need to ensure that the Canva API supports filtering users based on that attribute. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Canva|

+ |||||

+ |userName|String|&check;|&check;

+ |active|Boolean||

+ |externalId|String||

+ |emails[type eq "work"].value|String||&check;

+ |name.givenName|String||

+ |name.familyName|String||

+ |displayName|String||

+

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Groups to Canva**.

+1. Review the group attributes that are synchronized from Azure AD to Canva in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the groups in Canva for update operations. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Canva|

+ |||||

+ |displayName|String|&check;|&check;

+ |members|Reference||

+

+1. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. To enable the Azure AD provisioning service for Canva, change the **Provisioning Status** to **On** in the **Settings** section.

+ 

+1. Define the users and/or groups that you would like to provision to Canva by choosing the desired values in **Scope** in the **Settings** section.

+ 

+1. When you're ready to provision, click **Save**.

+ 

+This operation starts the initial synchronization cycle of all users and groups defined in **Scope** in the **Settings** section. The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.

+## Step 6. Monitor your deployment

+Once you've configured provisioning, use the following resources to monitor your deployment:

+* Use the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md) to determine which users have been provisioned successfully or unsuccessfully

+* Check the [progress bar](../app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user.md) to see the status of the provisioning cycle and how close it's to completion

+* If the provisioning configuration seems to be in an unhealthy state, the application goes into quarantine. Learn more about quarantine states [here](../app-provisioning/application-provisioning-quarantine-status.md).

+## More resources

+* [Managing user account provisioning for Enterprise Apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)

+* [What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+## Next steps

+* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)

+ Title: 'Tutorial: Configure Forcepoint Cloud Security Gateway - User Authentication for automatic user provisioning with Azure Active Directory'

+description: Learn how to automatically provision and de-provision user accounts from Azure AD to Forcepoint Cloud Security Gateway - User Authentication.

+writer: twimmers

+ms.assetid: 415b2ba3-a9a5-439a-963a-7c2c0254ced1

+# Tutorial: Configure Forcepoint Cloud Security Gateway - User Authentication for automatic user provisioning

+This tutorial describes the steps you need to perform in both Forcepoint Cloud Security Gateway - User Authentication and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and de-provisions users and groups to [Forcepoint Cloud Security Gateway - User Authentication](https://admin.forcepoint.net) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

+## Supported capabilities

+> [!div class="checklist"]

+> * Create users in Forcepoint Cloud Security Gateway - User Authentication.

+> * Remove users in Forcepoint Cloud Security Gateway - User Authentication when they do not require access anymore.

+> * Keep user attributes synchronized between Azure AD and Forcepoint Cloud Security Gateway - User Authentication.

+> * Provision groups and group memberships in Forcepoint Cloud Security Gateway - User Authentication.

+> * [Single sign-on](forcepoint-cloud-security-gateway-tutorial.md) to Forcepoint Cloud Security Gateway - User Authentication (recommended).

+## Prerequisites

+The scenario outlined in this tutorial assumes that you already have the following prerequisites:

+* [An Azure AD tenant](../develop/quickstart-create-new-tenant.md).

+* A user account in Azure AD with [permission](../roles/permissions-reference.md) to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).

+* An Forcepoint Cloud Security Gateway - User Authentication tenant.

+* A user account in Forcepoint Cloud Security Gateway - User Authentication with Admin permissions.

+## Step 1. Plan your provisioning deployment

+1. Learn about [how the provisioning service works](../app-provisioning/user-provisioning.md).

+1. Determine who will be in [scope for provisioning](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. Determine what data to [map between Azure AD and Forcepoint Cloud Security Gateway - User Authentication](../app-provisioning/customize-application-attributes.md).

+## Step 2. Configure Forcepoint Cloud Security Gateway - User Authentication to support provisioning with Azure AD

+Contact Forcepoint Cloud Security Gateway - User Authentication support to configure Forcepoint Cloud Security Gateway - User Authentication to support provisioning with Azure AD.

+## Step 3. Add Forcepoint Cloud Security Gateway - User Authentication from the Azure AD application gallery

+Add Forcepoint Cloud Security Gateway - User Authentication from the Azure AD application gallery to start managing provisioning to Forcepoint Cloud Security Gateway - User Authentication. If you have previously setup Forcepoint Cloud Security Gateway - User Authentication for SSO you can use the same application. However it's recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery [here](../manage-apps/add-application-portal.md).

+## Step 4. Define who will be in scope for provisioning

+The Azure AD provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user / group. If you choose to scope who will be provisioned to your app based on assignment, you can use the following [steps](../manage-apps/assign-user-or-group-access-portal.md) to assign users and groups to the application. If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described [here](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* Start small. Test with a small set of users and groups before rolling out to everyone. When scope for provisioning is set to assigned users and groups, you can control this by assigning one or two users or groups to the app. When scope is set to all users and groups, you can specify an [attribute based scoping filter](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* If you need more roles, you can [update the application manifest](../develop/howto-add-app-roles-in-azure-ad-apps.md) to add new roles.

+## Step 5. Configure automatic user provisioning to Forcepoint Cloud Security Gateway - User Authentication

+This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users and/or groups in TestApp based on user and/or group assignments in Azure AD.

+### To configure automatic user provisioning for Forcepoint Cloud Security Gateway - User Authentication in Azure AD:

+1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise Applications**, then select **All applications**.

+ 

+1. In the applications list, select **Forcepoint Cloud Security Gateway - User Authentication**.

+ 

+1. Select the **Provisioning** tab.

+ 

+1. Set the **Provisioning Mode** to **Automatic**.

+ 

+1. Under the **Admin Credentials** section, input your Forcepoint Cloud Security Gateway - User Authentication Tenant URL and Secret Token. Click **Test Connection** to ensure Azure AD can connect to Forcepoint Cloud Security Gateway - User Authentication. If the connection fails, ensure your Forcepoint Cloud Security Gateway - User Authentication account has Admin permissions and try again.

+ 

+1. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box.

+ 

+1. Select **Save**.

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Forcepoint Cloud Security Gateway - User Authentication**.

+1. Review the user attributes that are synchronized from Azure AD to Forcepoint Cloud Security Gateway - User Authentication in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Forcepoint Cloud Security Gateway - User Authentication for update operations. If you choose to change the [matching target attribute](../app-provisioning/customize-application-attributes.md), you'll need to ensure that the Forcepoint Cloud Security Gateway - User Authentication API supports filtering users based on that attribute. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Forcepoint Cloud Security Gateway - User Authentication|

+ |||||

+ |userName|String|&check;|&check;

+ |externalId|String||&check;

+ |displayName|String||&check;

+ |urn:ietf:params:scim:schemas:extension:forcepoint:2.0:User:ntlmId|String||

+

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Groups to Forcepoint Cloud Security Gateway - User Authentication**.

+1. Review the group attributes that are synchronized from Azure AD to Forcepoint Cloud Security Gateway - User Authentication in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the groups in Forcepoint Cloud Security Gateway - User Authentication for update operations. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Forcepoint Cloud Security Gateway - User Authentication|

+ |||||

+ |displayName|String|&check;|&check;

+ |externalId|String||

+ |members|Reference||

+

+1. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. To enable the Azure AD provisioning service for Forcepoint Cloud Security Gateway - User Authentication, change the **Provisioning Status** to **On** in the **Settings** section.

+ 

+1. Define the users and/or groups that you would like to provision to Forcepoint Cloud Security Gateway - User Authentication by choosing the desired values in **Scope** in the **Settings** section.

+ 

+1. When you're ready to provision, click **Save**.

+ 

+This operation starts the initial synchronization cycle of all users and groups defined in **Scope** in the **Settings** section. The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.

+## Step 6. Monitor your deployment

+Once you've configured provisioning, use the following resources to monitor your deployment:

+* Use the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md) to determine which users have been provisioned successfully or unsuccessfully

+* Check the [progress bar](../app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user.md) to see the status of the provisioning cycle and how close it's to completion

+* If the provisioning configuration seems to be in an unhealthy state, the application goes into quarantine. Learn more about quarantine states [here](../app-provisioning/application-provisioning-quarantine-status.md).

+## More resources

+* [Managing user account provisioning for Enterprise Apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)

+* [What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+## Next steps

+* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)

+ Title: 'Tutorial: Configure Hypervault for automatic user provisioning with Azure Active Directory'

+description: Learn how to automatically provision and deprovision user accounts from Azure AD to Hypervault.

+writer: twimmers

+ms.assetid: eca2ff9e-a09d-4bb4-88f6-6021a93d2c9d

+# Tutorial: Configure Hypervault for automatic user provisioning

+This tutorial describes the steps you need to perform in both Hypervault and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and deprovisions users to [Hypervault](https://hypervault.com) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

+## Supported capabilities

+> [!div class="checklist"]

+> * Create users in Hypervault.

+> * Remove users in Hypervault when they do not require access anymore.

+> * Keep user attributes synchronized between Azure AD and Hypervault.

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

+## Prerequisites

+The scenario outlined in this tutorial assumes that you already have the following prerequisites:

+* [An Azure AD tenant](../develop/quickstart-create-new-tenant.md)

+* A user account in Azure AD with [permission](../roles/permissions-reference.md) to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).

+* A user account in Hypervault with Admin permissions.

+## Step 1. Plan your provisioning deployment

+1. Learn about [how the provisioning service works](../app-provisioning/user-provisioning.md).

+1. Determine who is in [scope for provisioning](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. Determine what data to [map between Azure AD and Hypervault](../app-provisioning/customize-application-attributes.md).

+## Step 2. Configure Hypervault to support provisioning with Azure AD

+Contact Hypervault support to configure Hypervault to support provisioning with Azure AD.

+## Step 3. Add Hypervault from the Azure AD application gallery

+Add Hypervault from the Azure AD application gallery to start managing provisioning to Hypervault. If you have previously setup Hypervault for SSO, you can use the same application. However it's recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery [here](../manage-apps/add-application-portal.md).

+## Step 4. Define who is in scope for provisioning

+The Azure AD provisioning service allows you to scope who is provisioned based on assignment to the application and/or based on attributes of the user. If you choose to scope who is provisioned to your app based on assignment, you can use the following [steps](../manage-apps/assign-user-or-group-access-portal.md) to assign users to the application. If you choose to scope who is provisioned based solely on attributes of the user, you can use a scoping filter as described [here](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* Start small. Test with a small set of users before rolling out to everyone. When scope for provisioning is set to assigned users, you can control this by assigning one or two users to the app. When scope is set to all users, you can specify an [attribute based scoping filter](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* If you need more roles, you can [update the application manifest](../develop/howto-add-app-roles-in-azure-ad-apps.md) to add new roles.

+## Step 5. Configure automatic user provisioning to Hypervault

+This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users in TestApp based on user assignments in Azure AD.

+### To configure automatic user provisioning for Hypervault in Azure AD:

+1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise Applications**, then select **All applications**.

+ 

+1. In the applications list, select **Hypervault**.

+ 

+1. Select the **Provisioning** tab.

+ 

+1. Set the **Provisioning Mode** to **Automatic**.

+ 

+1. Under the **Admin Credentials** section, input your Hypervault Tenant URL and Secret Token. Click **Test Connection** to ensure Azure AD can connect to Hypervault. If the connection fails, ensure your Hypervault account has Admin permissions and try again.

+ 

+1. In the **Notification Email** field, enter the email address of a person who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box.

+ 

+1. Select **Save**.

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Hypervault**.

+1. Review the user attributes that are synchronized from Azure AD to Hypervault in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Hypervault for update operations. If you choose to change the [matching target attribute](../app-provisioning/customize-application-attributes.md), you need to ensure that the Hypervault API supports filtering users based on that attribute. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Hypervault|

+ |||||

+ |userName|String|&check;|&check;

+ |active|Boolean||&check;

+ |displayName|String||&check;

+ |name.givenName|String||&check;

+ |name.familyName|String||&check;

+ |emails[type eq "work"].value|String||&check;

+1. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. To enable the Azure AD provisioning service for Hypervault, change the **Provisioning Status** to **On** in the **Settings** section.

+ 

+1. Define the users that you would like to provision to Hypervault by choosing the desired values in **Scope** in the **Settings** section.

+ 

+1. When you're ready to provision, click **Save**.

+ 

+This operation starts the initial synchronization cycle of all users defined in **Scope** in the **Settings** section. The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.

+## Step 6. Monitor your deployment

+Once you've configured provisioning, use the following resources to monitor your deployment:

+* Use the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md) to determine which users have been provisioned successfully or unsuccessfully

+* Check the [progress bar](../app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user.md) to see the status of the provisioning cycle and how close it's to completion

+* If the provisioning configuration seems to be in an unhealthy state, the application goes into quarantine. Learn more about quarantine states [here](../app-provisioning/application-provisioning-quarantine-status.md).

+## More resources

+* [Managing user account provisioning for Enterprise Apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)

+* [What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+## Next steps

+* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)

+ Title: 'Tutorial: Configure Oneflow for automatic user provisioning with Azure Active Directory'

+description: Learn how to automatically provision and de-provision user accounts from Azure AD to Oneflow.

+writer: twimmers

+ms.assetid: 6af89cdd-956c-4cc2-9a61-98afe7814470

+# Tutorial: Configure Oneflow for automatic user provisioning

+This tutorial describes the steps you need to perform in both Oneflow and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and de-provisions users and groups to [Oneflow](https://oneflow.com) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

+## Supported capabilities

+> [!div class="checklist"]

+> * Create users in Oneflow.

+> * Remove users in Oneflow when they do not require access anymore.

+> * Keep user attributes synchronized between Azure AD and Oneflow.

+> * Provision groups and group memberships in Oneflow.

+> * [Single sign-on](oneflow-tutorial.md) to Oneflow (recommended).

+## Prerequisites

+The scenario outlined in this tutorial assumes that you already have the following prerequisites:

+* [An Azure AD tenant](../develop/quickstart-create-new-tenant.md).

+* A user account in Azure AD with [permission](../roles/permissions-reference.md) to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).

+* An Oneflow tenant.

+* A user account in Oneflow with Admin permissions.

+## Step 1. Plan your provisioning deployment

+1. Learn about [how the provisioning service works](../app-provisioning/user-provisioning.md).

+1. Determine who will be in [scope for provisioning](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. Determine what data to [map between Azure AD and Oneflow](../app-provisioning/customize-application-attributes.md).

+## Step 2. Configure Oneflow to support provisioning with Azure AD

+Contact Oneflow support to configure Oneflow to support provisioning with Azure AD.

+## Step 3. Add Oneflow from the Azure AD application gallery

+Add Oneflow from the Azure AD application gallery to start managing provisioning to Oneflow. If you have previously setup Oneflow for SSO you can use the same application. However it's recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery [here](../manage-apps/add-application-portal.md).

+## Step 4. Define who will be in scope for provisioning

+The Azure AD provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user / group. If you choose to scope who will be provisioned to your app based on assignment, you can use the following [steps](../manage-apps/assign-user-or-group-access-portal.md) to assign users and groups to the application. If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described [here](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* Start small. Test with a small set of users and groups before rolling out to everyone. When scope for provisioning is set to assigned users and groups, you can control this by assigning one or two users or groups to the app. When scope is set to all users and groups, you can specify an [attribute based scoping filter](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* If you need more roles, you can [update the application manifest](../develop/howto-add-app-roles-in-azure-ad-apps.md) to add new roles.

+## Step 5. Configure automatic user provisioning to Oneflow

+This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users and/or groups in TestApp based on user and/or group assignments in Azure AD.

+### To configure automatic user provisioning for Oneflow in Azure AD:

+1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise Applications**, then select **All applications**.

+ 

+1. In the applications list, select **Oneflow**.

+ 

+1. Select the **Provisioning** tab.

+ 

+1. Set the **Provisioning Mode** to **Automatic**.

+ 

+1. Under the **Admin Credentials** section, input your Oneflow Tenant URL and Secret Token. Click **Test Connection** to ensure Azure AD can connect to Oneflow. If the connection fails, ensure your Oneflow account has Admin permissions and try again.

+ 

+1. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box.

+ 

+1. Select **Save**.

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Oneflow**.

+1. Review the user attributes that are synchronized from Azure AD to Oneflow in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Oneflow for update operations. If you choose to change the [matching target attribute](../app-provisioning/customize-application-attributes.md), you'll need to ensure that the Oneflow API supports filtering users based on that attribute. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Oneflow|

+ |||||

+ |userName|String|&check;|&check;

+ |active|Boolean||&check;

+ |externalId|String||

+ |emails[type eq "work"].value|String||

+ |name.givenName|String||

+ |name.familyName|String||

+ |phoneNumbers[type eq \"work\"].value|String||

+ |urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department|String||

+ |urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber|String||

+ |nickName|String||

+ |title|String||

+ |profileUrl|String||

+ |displayName|String||

+ |addresses[type eq \"work\"].streetAddress|String||

+ |addresses[type eq \"work\"].locality|String||

+ |addresses[type eq \"work\"].region|String||

+ |addresses[type eq \"work\"].postalCode|String||

+ |addresses[type eq \"work\"].country|String||

+ |urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter|String||

+ |urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division|String||

+ |urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:adSourceAnchor|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:customAttribute1|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:customAttribute2|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:customAttribute3|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:customAttribute4|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:customAttribute5|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:distinguishedName|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:domain|String||

+ |urn:ietf:params:scim:schemas:extension:ws1b:2.0:User:userPrincipalName|String||

+

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Groups to Oneflow**.

+1. Review the group attributes that are synchronized from Azure AD to Oneflow in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the groups in Oneflow for update operations. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Oneflow|

+ |||||

+ |displayName|String|&check;|&check;

+ |externalId|String|&check;|&check;

+ |members|Reference||

+

+1. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. To enable the Azure AD provisioning service for Oneflow, change the **Provisioning Status** to **On** in the **Settings** section.

+ 

+1. Define the users and/or groups that you would like to provision to Oneflow by choosing the desired values in **Scope** in the **Settings** section.

+ 

+1. When you're ready to provision, click **Save**.

+ 

+This operation starts the initial synchronization cycle of all users and groups defined in **Scope** in the **Settings** section. The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.

+## Step 6. Monitor your deployment

+Once you've configured provisioning, use the following resources to monitor your deployment:

+* Use the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md) to determine which users have been provisioned successfully or unsuccessfully

+* Check the [progress bar](../app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user.md) to see the status of the provisioning cycle and how close it's to completion

+* If the provisioning configuration seems to be in an unhealthy state, the application goes into quarantine. Learn more about quarantine states [here](../app-provisioning/application-provisioning-quarantine-status.md).

+## More resources

+* [Managing user account provisioning for Enterprise Apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)

+* [What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+## Next steps

+* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)

+ Title: 'Tutorial: Configure Postman for automatic user provisioning with Azure Active Directory'

+description: Learn how to automatically provision and de-provision user accounts from Azure AD to Postman.

+writer: twimmers

+ms.assetid: f3687101-9bec-4f18-9884-61833f4f58c3

+# Tutorial: Configure Postman for automatic user provisioning

+This tutorial describes the steps you need to perform in both Postman and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and de-provisions users and groups to [Postman](https://www.postman.com/) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

+## Supported capabilities

+> [!div class="checklist"]

+> * Create users in Postman.

+> * Remove users in Postman when they do not require access anymore.

+> * Keep user attributes synchronized between Azure AD and Postman.

+> * Provision groups and group memberships in Postman.

+> * [Single sign-on](postman-tutorial.md) to Postman (recommended).

+## Prerequisites

+The scenario outlined in this tutorial assumes that you already have the following prerequisites:

+* [An Azure AD tenant](../develop/quickstart-create-new-tenant.md).

+* A user account in Azure AD with [permission](../roles/permissions-reference.md) to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).

+* An Postman tenant.

+* A user account in Postman with Admin permissions.

+## Step 1. Plan your provisioning deployment

+1. Learn about [how the provisioning service works](../app-provisioning/user-provisioning.md).

+1. Determine who will be in [scope for provisioning](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. Determine what data to [map between Azure AD and Postman](../app-provisioning/customize-application-attributes.md).

+## Step 2. Configure Postman to support provisioning with Azure AD

+Contact Postman support to configure Postman to support provisioning with Azure AD.

+## Step 3. Add Postman from the Azure AD application gallery

+Add Postman from the Azure AD application gallery to start managing provisioning to Postman. If you have previously setup Postman for SSO you can use the same application. However it's recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery [here](../manage-apps/add-application-portal.md).

+## Step 4. Define who will be in scope for provisioning

+The Azure AD provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user / group. If you choose to scope who will be provisioned to your app based on assignment, you can use the following [steps](../manage-apps/assign-user-or-group-access-portal.md) to assign users and groups to the application. If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described [here](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* Start small. Test with a small set of users and groups before rolling out to everyone. When scope for provisioning is set to assigned users and groups, you can control this by assigning one or two users or groups to the app. When scope is set to all users and groups, you can specify an [attribute based scoping filter](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* If you need more roles, you can [update the application manifest](../develop/howto-add-app-roles-in-azure-ad-apps.md) to add new roles.

+## Step 5. Configure automatic user provisioning to Postman

+This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users and/or groups in TestApp based on user and/or group assignments in Azure AD.

+### To configure automatic user provisioning for Postman in Azure AD:

+1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise Applications**, then select **All applications**.

+ 

+1. In the applications list, select **Postman**.

+ 

+1. Select the **Provisioning** tab.

+ 

+1. Set the **Provisioning Mode** to **Automatic**.

+ 

+1. Under the **Admin Credentials** section, input your Postman Tenant URL and Secret Token. Click **Test Connection** to ensure Azure AD can connect to Postman. If the connection fails, ensure your Postman account has Admin permissions and try again.

+ 

+1. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box.

+ 

+1. Select **Save**.

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Postman**.

+1. Review the user attributes that are synchronized from Azure AD to Postman in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Postman for update operations. If you choose to change the [matching target attribute](../app-provisioning/customize-application-attributes.md), you'll need to ensure that the Postman API supports filtering users based on that attribute. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Postman|

+ |||||

+ |userName|String|&check;|&check;

+ |active|Boolean||&check;

+ |externalId|String||&check;

+ |name.givenName|String||&check;

+ |name.familyName|String||&check;

+

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Groups to Postman**.

+1. Review the group attributes that are synchronized from Azure AD to Postman in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the groups in Postman for update operations. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Postman|

+ |||||

+ |displayName|String|&check;|&check;

+ |externalId|String||&check;

+ |members|Reference||

+

+1. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. To enable the Azure AD provisioning service for Postman, change the **Provisioning Status** to **On** in the **Settings** section.

+ 

+1. Define the users and/or groups that you would like to provision to Postman by choosing the desired values in **Scope** in the **Settings** section.

+ 

+1. When you're ready to provision, click **Save**.

+ 

+This operation starts the initial synchronization cycle of all users and groups defined in **Scope** in the **Settings** section. The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.

+## Step 6. Monitor your deployment

+Once you've configured provisioning, use the following resources to monitor your deployment:

+* Use the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md) to determine which users have been provisioned successfully or unsuccessfully

+* Check the [progress bar](../app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user.md) to see the status of the provisioning cycle and how close it's to completion

+* If the provisioning configuration seems to be in an unhealthy state, the application goes into quarantine. Learn more about quarantine states [here](../app-provisioning/application-provisioning-quarantine-status.md).

+## More resources

+* [Managing user account provisioning for Enterprise Apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)

+* [What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+## Next steps

+* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)

+ Title: 'Tutorial: Configure Servicely for automatic user provisioning with Azure Active Directory'

+description: Learn how to automatically provision and deprovision user accounts from Azure AD to Servicely.

+writer: twimmers

+ms.assetid: be3af02b-da77-4a88-bec3-e634e2af38b3

+# Tutorial: Configure Servicely for automatic user provisioning

+This tutorial describes the steps you need to perform in both Servicely and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and deprovisions users and groups to [Servicely](https://servicely.ai/) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

+## Supported capabilities

+> [!div class="checklist"]

+> * Create users in Servicely.

+> * Remove users in Servicely when they do not require access anymore.

+> * Keep user attributes synchronized between Azure AD and Servicely.

+> * Provision groups and group memberships in Servicely.

+## Prerequisites

+The scenario outlined in this tutorial assumes that you already have the following prerequisites:

+* [An Azure AD tenant](../develop/quickstart-create-new-tenant.md).

+* A user account in Azure AD with [permission](../roles/permissions-reference.md) to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).

+* An Servicely tenant.

+* A user account in Servicely with Admin permissions.

+## Step 1. Plan your provisioning deployment

+1. Learn about [how the provisioning service works](../app-provisioning/user-provisioning.md).

+1. Determine who is in [scope for provisioning](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. Determine what data to [map between Azure AD and Servicely](../app-provisioning/customize-application-attributes.md).

+## Step 2. Configure Servicely to support provisioning with Azure AD

+Contact Servicely support to configure Servicely to support provisioning with Azure AD.

+## Step 3. Add Servicely from the Azure AD application gallery

+Add Servicely from the Azure AD application gallery to start managing provisioning to Servicely. Learn more about adding an application from the gallery [here](../manage-apps/add-application-portal.md).

+## Step 4. Define who is in scope for provisioning

+The Azure AD provisioning service allows you to scope who is provisioned based on assignment to the application and/or based on attributes of the user. If you choose to scope who is provisioned to your app based on assignment, you can use the following [steps](../manage-apps/assign-user-or-group-access-portal.md) to assign users and groups to the application. If you choose to scope who is provisioned based solely on attributes of the user or group, you can use a scoping filter as described [here](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* Start small. Test with a small set of users and groups before rolling out to everyone. When scope for provisioning is set to assigned users and groups, you can control this by assigning one or two users or groups to the app. When scope is set to all users and groups, you can specify an [attribute based scoping filter](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* If you need more roles, you can [update the application manifest](../develop/howto-add-app-roles-in-azure-ad-apps.md) to add new roles.

+## Step 5. Configure automatic user provisioning to Servicely

+This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users and/or groups in TestApp based on user and/or group assignments in Azure AD.

+### To configure automatic user provisioning for Servicely in Azure AD:

+1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise Applications**, then select **All applications**.

+ 

+1. In the applications list, select **Servicely**.

+ 

+1. Select the **Provisioning** tab.

+ 

+1. Set the **Provisioning Mode** to **Automatic**.

+ 

+1. Under the **Admin Credentials** section, input your Servicely Tenant URL and Secret Token. Click **Test Connection** to ensure Azure AD can connect to Servicely. If the connection fails, ensure your Servicely account has Admin permissions and try again.

+ 

+1. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box.

+ 

+1. Select **Save**.

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Servicely**.

+1. Review the user attributes that are synchronized from Azure AD to Servicely in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Servicely for update operations. If you choose to change the [matching target attribute](../app-provisioning/customize-application-attributes.md), you need to ensure that the Servicely API supports filtering users based on that attribute. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Servicely|

+ |||||

+ |userName|String|&check;|&check;

+ |active|Boolean||

+ |externalId|String||

+ |emails[type eq "work"].value|String||

+ |name.givenName|String||

+ |name.familyName|String||

+ |title|String||

+ |preferredLanguage|String||

+ |phoneNumbers[type eq "work"].value|String||

+ |phoneNumbers[type eq "mobile"].value|String||

+ |timezone|String||

+ |urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber|String||

+ |urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager|String||

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Groups to Servicely**.

+1. Review the group attributes that are synchronized from Azure AD to Servicely in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the groups in Servicely for update operations. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Servicely|

+ |||||

+ |displayName|String|&check;|&check;

+ |externalId|String|&check;|&check;

+ |members|Reference||

+

+1. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. To enable the Azure AD provisioning service for Servicely, change the **Provisioning Status** to **On** in the **Settings** section.

+ 

+1. Define the users and/or groups that you would like to provision to Servicely by choosing the desired values in **Scope** in the **Settings** section.

+ 

+1. When you're ready to provision, click **Save**.

+ 

+This operation starts the initial synchronization cycle of all users and groups defined in **Scope** in the **Settings** section. The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.

+## Step 6. Monitor your deployment

+Once you've configured provisioning, use the following resources to monitor your deployment:

+* Use the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md) to determine which users have been provisioned successfully or unsuccessfully

+* Check the [progress bar](../app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user.md) to see the status of the provisioning cycle and how close it's to completion

+* If the provisioning configuration seems to be in an unhealthy state, the application goes into quarantine. Learn more about quarantine states [here](../app-provisioning/application-provisioning-quarantine-status.md).

+## More resources

+* [Managing user account provisioning for Enterprise Apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)

+* [What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+## Next steps

+* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)

+Microsoft Entra Verified ID implements the [W3C StatusList2021](https://github.com/w3c/vc-status-list-2021/tree/343b8b59cddba4525e1ef355356ae760fc75904e). When presentation to the Request Service API happens, the API will do the revocation check for you. The revocation check happens over an anonymous API call to Identity Hub and does not contain any data who is checking if the verifiable credential is still valid or revoked. With the **statusList2021**, Microsoft Entra Verified ID just keeps a flag by the hashed value of the indexed claim to keep track of the revocation status.

+Azure AI services provide a layered security model. This model enables you to secure your Azure AI services accounts to a specific subset of networksΓÇï. When network rules are configured, only applications that request data over the specified set of networks can access the account. You can limit access to your resources with *request filtering*, which allows requests that originate only from specified IP addresses, IP ranges, or from a list of subnets in [Azure Virtual Networks](../virtual-network/virtual-networks-overview.md).

+> Turning on firewall rules for your Azure AI services account blocks incoming requests for data by default. To allow requests through, one of the following conditions needs to be met:

+> - The request originates from a service that operates within an Azure Virtual Network on the allowed subnet list of the target Azure AI services account. The endpoint request that originated from the virtual network needs to be set as the [custom subdomain](cognitive-services-custom-subdomains.md) of your Azure AI services account.

+> - The request originates from an allowed list of IP addresses.

+> Requests that are blocked include those from other Azure services, from the Azure portal, and from logging and metrics services.

+To secure your Azure AI services resource, you should first configure a rule to deny access to traffic from all networks, including internet traffic, by default. Then, configure rules that grant access to traffic from specific virtual networks. This configuration enables you to build a secure network boundary for your applications. You can also configure rules to grant access to traffic from select public internet IP address ranges and enable connections from specific internet or on-premises clients.

+Network rules are enforced on all network protocols to Azure AI services, including REST and WebSocket. To access data by using tools such as the Azure test consoles, explicit network rules must be configured. You can apply network rules to existing Azure AI services resources, or when you create new Azure AI services resources. After network rules are applied, they're enforced for all requests.

+Virtual networks are supported in [regions where Azure AI services are available](https://azure.microsoft.com/global-infrastructure/services/). Azure AI services support service tags for network rules configuration. The services listed here are included in the `CognitiveServicesManagement` service tag.

+> - Anomaly Detector

+> - Azure OpenAI

+> - Content Moderator

+> - Custom Vision

+> - Face

+> - Language Understanding (LUIS)

+> - Personalizer

+> - Speech service

+> - Language

+> - QnA Maker

+> - Translator

+> If you use Azure OpenAI, LUIS, Speech Services, or Language services, the `CognitiveServicesManagement` tag only enables you to use the service by using the SDK or REST API. To access and use Azure OpenAI Studio, LUIS portal, Speech Studio, or Language Studio from a virtual network, you need to use the following tags:

+> - `AzureActiveDirectory`

+> - `AzureFrontDoor.Frontend`

+> - `AzureResourceManager`

+> - `CognitiveServicesManagement`

+> - `CognitiveServicesFrontEnd`

+> Making changes to network rules can impact your applications' ability to connect to Azure AI services. Setting the default network rule to *deny* blocks all access to the data unless specific network rules that *grant* access are also applied.

+>

+> Before you change the default rule to deny access, be sure to grant access to any allowed networks by using network rules. If you allow listing for the IP addresses for your on-premises network, be sure to add all possible outgoing public IP addresses from your on-premises network.

+### Manage default network access rules

+1. Select **Resource Management** to expand it, then select **Networking**.

+ :::image type="content" source="media/vnet/virtual-network-blade.png" alt-text="Screenshot shows the Networking page with Selected Networks and Private Endpoints selected." lightbox="media/vnet/virtual-network-blade.png":::

+1. To deny access by default, under **Firewalls and virtual networks**, select **Selected Networks and Private Endpoints**.

+ With this setting alone, unaccompanied by configured virtual networks or address ranges, all access is effectively denied. When all access is denied, requests that attempt to consume the Azure AI services resource aren't permitted. The Azure portal, Azure PowerShell, or the Azure CLI can still be used to configure the Azure AI services resource.

+1. To allow traffic from all networks, select **All networks**.

+ :::image type="content" source="media/vnet/virtual-network-deny.png" alt-text="Screenshot shows the Networking page with All networks selected." lightbox="media/vnet/virtual-network-deny.png":::

+1. Install the [Azure PowerShell](/powershell/azure/install-azure-powershell) and [sign in](/powershell/azure/authenticate-azureps), or select **Open Cloudshell**.

+ ```azurepowershell-interactive

+ $parameters = @{

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ }

+ (Get-AzCognitiveServicesAccountNetworkRuleSet @parameters).DefaultAction

+ ```

+ You can get values for your resource group `myresourcegroup` and the name of your Azure services resource `myaccount` from the Azure portal.

+1. Set the default rule to deny network access.

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ "DefaultAction" = "Deny"

+1. Set the default rule to allow network access.

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ "DefaultAction" = "Allow"

+1. Install the [Azure CLI](/cli/azure/install-azure-cli) and [sign in](/cli/azure/authenticate-azure-cli), or select **Open Cloudshell**.

+ --resource-group "myresourcegroup" --name "myaccount" \

+ --query properties.networkAcls.defaultAction

+1. Get the resource ID for use in the later steps.

+ ```azurecli-interactive

+ resourceId=$(az cognitiveservices account show

+ --resource-group "myresourcegroup" \

+ --name "myaccount" --query id --output tsv)

+ ```

+ --ids $resourceId \

+ --ids $resourceId \

+You can configure Azure AI services resources to allow access from specific subnets only. The allowed subnets might belong to a virtual network in the same subscription or in a different subscription. The other subscription can belong to a different Azure AD tenant.

+Enable a *service endpoint* for Azure AI services within the virtual network. The service endpoint routes traffic from the virtual network through an optimal path to the Azure AI services service. For more information, see [Virtual Network service endpoints](../virtual-network/virtual-network-service-endpoints-overview.md).

+The identities of the subnet and the virtual network are also transmitted with each request. Administrators can then configure network rules for the Azure AI services resource to allow requests from specific subnets in a virtual network. Clients granted access by these network rules must continue to meet the authorization requirements of the Azure AI services resource to access the data.

+Each Azure AI services resource supports up to 100 virtual network rules, which can be combined with IP network rules. For more information, see [Grant access from an internet IP range](#grant-access-from-an-internet-ip-range) later in this article.

+### Set required permissions

+To apply a virtual network rule to an Azure AI services resource, you need the appropriate permissions for the subnets to add. The required permission is the default *Contributor* role or the *Cognitive Services Contributor* role. Required permissions can also be added to custom role definitions.

+The Azure AI services resource and the virtual networks that are granted access might be in different subscriptions, including subscriptions that are part of a different Azure AD tenant.

+> Configuration of rules that grant access to subnets in virtual networks that are a part of a different Azure AD tenant are currently supported only through PowerShell, the Azure CLI, and the REST APIs. You can view these rules in the Azure portal, but you can't configure them.

+### Configure virtual network rules

+To grant access to a virtual network with an existing network rule:

+1. Select **Resource Management** to expand it, then select **Networking**.

+1. Confirm that you selected **Selected Networks and Private Endpoints**.

+1. Under **Allow access from**, select **Add existing virtual network**.

+ :::image type="content" source="media/vnet/virtual-network-add-existing.png" alt-text="Screenshot shows the Networking page with Selected Networks and Private Endpoints selected and Add existing virtual network highlighted." lightbox="media/vnet/virtual-network-add-existing.png":::

+ :::image type="content" source="media/vnet/virtual-network-add-existing-details.png" alt-text="Screenshot shows the Add networks dialog box where you can enter a virtual network and subnet.":::

+ > [!NOTE]

+ > If a service endpoint for Azure AI services wasn't previously configured for the selected virtual network and subnets, you can configure it as part of this operation.

+ >

+ > Currently, only virtual networks that belong to the same Azure AD tenant are available for selection during rule creation. To grant access to a subnet in a virtual network that belongs to another tenant, use PowerShell, the Azure CLI, or the REST APIs.

+1. Select **Save** to apply your changes.

+To create a new virtual network and grant it access:

+1. On the same page as the previous procedure, select **Add new virtual network**.

+ :::image type="content" source="media/vnet/virtual-network-add-new.png" alt-text="Screenshot shows the Networking page with Selected Networks and Private Endpoints selected and Add new virtual network highlighted." lightbox="media/vnet/virtual-network-add-new.png":::

+ :::image type="content" source="media/vnet/virtual-network-create.png" alt-text="Screenshot shows the Create virtual network dialog box.":::

+1. Select **Save** to apply your changes.

+To remove a virtual network or subnet rule:

+1. On the same page as the previous procedures, select **...(More options)** to open the context menu for the virtual network or subnet, and select **Remove**.

+ :::image type="content" source="media/vnet/virtual-network-remove.png" alt-text="Screenshot shows the option to remove a virtual network." lightbox="media/vnet/virtual-network-remove.png":::

+1. Install the [Azure PowerShell](/powershell/azure/install-azure-powershell) and [sign in](/powershell/azure/authenticate-azureps), or select **Open Cloudshell**.

+1. List the configured virtual network rules.

+ $parameters = @{

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ }

+1. Enable a service endpoint for Azure AI services on an existing virtual network and subnet.

+ -AddressPrefix "CIDR" `

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myvnet"

+ > To add a network rule for a subnet in a virtual network that belongs to another Azure AD tenant, use a fully-qualified `VirtualNetworkResourceId` parameter in the form `/subscriptions/subscription-ID/resourceGroups/resourceGroup-Name/providers/Microsoft.Network/virtualNetworks/vNet-name/subnets/subnet-name`.

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myvnet"

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ "VirtualNetworkResourceId" = $subnet.Id

+1. Install the [Azure CLI](/cli/azure/install-azure-cli) and [sign in](/cli/azure/authenticate-azure-cli), or select **Open Cloudshell**.

+1. List the configured virtual network rules.

+ --resource-group "myresourcegroup" --name "myaccount" \

+1. Enable a service endpoint for Azure AI services on an existing virtual network and subnet.

+ az network vnet subnet update --resource-group "myresourcegroup" --name "mysubnet" \

+ subnetid=$(az network vnet subnet show \

+ --resource-group "myresourcegroup" --name "mysubnet" --vnet-name "myvnet" \

+ --resource-group "myresourcegroup" --name "myaccount" \

+ > To add a rule for a subnet in a virtual network that belongs to another Azure AD tenant, use a fully-qualified subnet ID in the form `/subscriptions/subscription-ID/resourceGroups/resourceGroup-Name/providers/Microsoft.Network/virtualNetworks/vNet-name/subnets/subnet-name`.

+ > You can use the `--subscription` parameter to retrieve the subnet ID for a virtual network that belongs to another Azure AD tenant.

+ --resource-group "myresourcegroup" --name "mysubnet" --vnet-name "myvnet" \

+ --resource-group "myresourcegroup" --name "myaccount" \

+> Be sure to [set the default rule](#change-the-default-network-access-rule) to *deny*, or network rules have no effect.

+You can configure Azure AI services resources to allow access from specific public internet IP address ranges. This configuration grants access to specific services and on-premises networks, which effectively block general internet traffic.

+You can specify the allowed internet address ranges by using [CIDR format (RFC 4632)](https://tools.ietf.org/html/rfc4632) in the form `192.168.0.0/16` or as individual IP addresses like `192.168.0.1`.

+ > Small address ranges that use `/31` or `/32` prefix sizes aren't supported. Configure these ranges by using individual IP address rules.

+IP network rules are only allowed for *public internet* IP addresses. IP address ranges reserved for private networks aren't allowed in IP rules. Private networks include addresses that start with `10.*`, `172.16.*` - `172.31.*`, and `192.168.*`. For more information, see [Private Address Space (RFC 1918)](https://tools.ietf.org/html/rfc1918#section-3).

+Currently, only IPv4 addresses are supported. Each Azure AI services resource supports up to 100 IP network rules, which can be combined with [virtual network rules](#grant-access-from-a-virtual-network).

+### Configure access from on-premises networks

+To grant access from your on-premises networks to your Azure AI services resource with an IP network rule, identify the internet-facing IP addresses used by your network. Contact your network administrator for help.

+If you use Azure ExpressRoute on-premises for public peering or Microsoft peering, you need to identify the NAT IP addresses. For more information, see [What is Azure ExpressRoute](../expressroute/expressroute-introduction.md).

+For public peering, each ExpressRoute circuit by default uses two NAT IP addresses. Each is applied to Azure service traffic when the traffic enters the Microsoft Azure network backbone. For Microsoft peering, the NAT IP addresses that are used are either customer provided or supplied by the service provider. To allow access to your service resources, you must allow these public IP addresses in the resource IP firewall setting.

+To find your public peering ExpressRoute circuit IP addresses, [open a support ticket with ExpressRoute](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/overview) use the Azure portal. For more information, see [NAT requirements for Azure public peering](../expressroute/expressroute-nat.md#nat-requirements-for-azure-public-peering).

+1. Select **Resource Management** to expand it, then select **Networking**.

+1. Confirm that you selected **Selected Networks and Private Endpoints**.

+1. Under **Firewalls and virtual networks**, locate the **Address range** option. To grant access to an internet IP range, enter the IP address or address range (in [CIDR format](https://tools.ietf.org/html/rfc4632)). Only valid public IP (nonreserved) addresses are accepted.

+ :::image type="content" source="media/vnet/virtual-network-add-ip-range.png" alt-text="Screenshot shows the Networking page with Selected Networks and Private Endpoints selected and the Address range highlighted." lightbox="media/vnet/virtual-network-add-ip-range.png":::

+ To remove an IP network rule, select the trash can <span class="docon docon-delete x-hidden-focus"></span> icon next to the address range.

+1. Install the [Azure PowerShell](/powershell/azure/install-azure-powershell) and [sign in](/powershell/azure/authenticate-azureps), or select **Open Cloudshell**.

+1. List the configured IP network rules.

+ ```azurepowershell-interactive

+ $parameters = @{

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ }

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ "IPAddressOrRange" = "ipaddress"

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ "IPAddressOrRange" = "CIDR"

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ "IPAddressOrRange" = "ipaddress"

+ "ResourceGroupName" = "myresourcegroup"

+ "Name" = "myaccount"

+ "IPAddressOrRange" = "CIDR"

+1. Install the [Azure CLI](/cli/azure/install-azure-cli) and [sign in](/cli/azure/authenticate-azure-cli), or select **Open Cloudshell**.

+1. List the configured IP network rules.

+ --resource-group "myresourcegroup" --name "myaccount" --query ipRules

+ --resource-group "myresourcegroup" --name "myaccount" \

+ --ip-address "ipaddress"

+ --resource-group "myresourcegroup" --name "myaccount" \

+ --ip-address "CIDR"

+ --resource-group "myresourcegroup" --name "myaccount" \

+ --ip-address "ipaddress"

+ --resource-group "myresourcegroup" --name "myaccount" \

+ --ip-address "CIDR"

+> Be sure to [set the default rule](#change-the-default-network-access-rule) to *deny*, or network rules have no effect.

+You can use [private endpoints](../private-link/private-endpoint-overview.md) for your Azure AI services resources to allow clients on a virtual network to securely access data over [Azure Private Link](../private-link/private-link-overview.md). The private endpoint uses an IP address from the virtual network address space for your Azure AI services resource. Network traffic between the clients on the virtual network and the resource traverses the virtual network and a private link on the Microsoft Azure backbone network, which eliminates exposure from the public internet.

+- Secure your Azure AI services resource by configuring the firewall to block all connections on the public endpoint for the Azure AI services service.

+- Increase security for the virtual network, by enabling you to block exfiltration of data from the virtual network.

+- Securely connect to Azure AI services resources from on-premises networks that connect to the virtual network by using [Azure VPN Gateway](../vpn-gateway/vpn-gateway-about-vpngateways.md) or [ExpressRoutes](../expressroute/expressroute-locations.md) with private-peering.

+### Understand private endpoints

+A private endpoint is a special network interface for an Azure resource in your [virtual network](../virtual-network/virtual-networks-overview.md). Creating a private endpoint for your Azure AI services resource provides secure connectivity between clients in your virtual network and your resource. The private endpoint is assigned an IP address from the IP address range of your virtual network. The connection between the private endpoint and the Azure AI services service uses a secure private link.

+Applications in the virtual network can connect to the service over the private endpoint seamlessly. Connections use the same connection strings and authorization mechanisms that they would use otherwise. The exception is Speech Services, which require a separate endpoint. For more information, see [Private endpoints with the Speech Services](#use-private-endpoints-with-the-speech-service) in this article. Private endpoints can be used with all protocols supported by the Azure AI services resource, including REST.

+Private endpoints can be created in subnets that use service endpoints. Clients in a subnet can connect to one Azure AI services resource using private endpoint, while using service endpoints to access others. For more information, see [Virtual Network service endpoints](../virtual-network/virtual-network-service-endpoints-overview.md).

+When you create a private endpoint for an Azure AI services resource in your virtual network, Azure sends a consent request for approval to the Azure AI services resource owner. If the user who requests the creation of the private endpoint is also an owner of the resource, this consent request is automatically approved.

+Azure AI services resource owners can manage consent requests and the private endpoints through the **Private endpoint connection** tab for the Azure AI services resource in the [Azure portal](https://portal.azure.com).

+### Specify private endpoints

+When you create a private endpoint, specify the Azure AI services resource that it connects to. For more information on creating a private endpoint, see:

+- [Create a private endpoint by using the Azure portal](../private-link/create-private-endpoint-portal.md)

+- [Create a private endpoint by using Azure PowerShell](../private-link/create-private-endpoint-powershell.md)

+- [Create a private endpoint by using the Azure CLI](../private-link/create-private-endpoint-cli.md)

+### Connect to private endpoints

+> Azure OpenAI Service uses a different private DNS zone and public DNS zone forwarder than other Azure AI services. For the correct zone and forwarder names, see [Azure services DNS zone configuration](../private-link/private-endpoint-dns.md#azure-services-dns-zone-configuration).

+Clients on a virtual network that use the private endpoint use the same connection string for the Azure AI services resource as clients connecting to the public endpoint. The exception is the Speech service, which requires a separate endpoint. For more information, see [Use private endpoints with the Speech service](#use-private-endpoints-with-the-speech-service) in this article. DNS resolution automatically routes the connections from the virtual network to the Azure AI services resource over a private link.

+By default, Azure creates a [private DNS zone](../dns/private-dns-overview.md) attached to the virtual network with the necessary updates for the private endpoints. If you use your own DNS server, you might need to make more changes to your DNS configuration. For updates that might be required for private endpoints, see [Apply DNS changes for private endpoints](#apply-dns-changes-for-private-endpoints) in this article.

+### Use private endpoints with the Speech service

+See [Use Speech service through a private endpoint](Speech-Service/speech-services-private-link.md).

+### Apply DNS changes for private endpoints

+When you create a private endpoint, the DNS `CNAME` resource record for the Azure AI services resource is updated to an alias in a subdomain with the prefix `privatelink`. By default, Azure also creates a private DNS zone that corresponds to the `privatelink` subdomain, with the DNS A resource records for the private endpoints. For more information, see [What is Azure Private DNS](../dns/private-dns-overview.md).

+When you resolve the endpoint URL from outside the virtual network with the private endpoint, it resolves to the public endpoint of the Azure AI services resource. When it's resolved from the virtual network hosting the private endpoint, the endpoint URL resolves to the private endpoint's IP address.

+This approach enables access to the Azure AI services resource using the same connection string for clients in the virtual network that hosts the private endpoints and clients outside the virtual network.

+If you use a custom DNS server on your network, clients must be able to resolve the fully qualified domain name (FQDN) for the Azure AI services resource endpoint to the private endpoint IP address. Configure your DNS server to delegate your private link subdomain to the private DNS zone for the virtual network.

+> When you use a custom or on-premises DNS server, you should configure your DNS server to resolve the Azure AI services resource name in the `privatelink` subdomain to the private endpoint IP address. Delegate the `privatelink` subdomain to the private DNS zone of the virtual network. Alternatively, configure the DNS zone on your DNS server and add the DNS A records.

+For more information on configuring your own DNS server to support private endpoints, see the following resources:

+- [Name resolution that uses your own DNS server](../virtual-network/virtual-networks-name-resolution-for-vms-and-role-instances.md#name-resolution-that-uses-your-own-dns-server)

+- [DNS configuration](../private-link/private-endpoint-overview.md#dns-configuration)

+- Explore the various [Azure AI services](./what-are-ai-services.md)

+- Learn more about [Virtual Network service endpoints](../virtual-network/virtual-network-service-endpoints-overview.md)

+- Grant access to [on-premises network](../../../cognitive-services-virtual-networks.md?tabs=portal#configure-access-from-on-premises-networks).

+- Grant access to [on-premises network](../../cognitive-services-virtual-networks.md?tabs=portal#configure-access-from-on-premises-networks).

+You can store the results of a batch transcription to a writable Azure Blob storage container using option `destinationContainerUrl` in the [batch transcription creation request](#create-a-transcription-job). Note however that this option is only using [ad hoc SAS](batch-transcription-audio-data.md#sas-url-for-batch-transcription) URI and doesn't support [Trusted Azure services security mechanism](batch-transcription-audio-data.md#trusted-azure-services-security-mechanism). This option also doesn't support Access policy based SAS. The Storage account resource of the destination container must allow all external traffic.

+zone_pivot_groups: programming-languages-speech-services

+- [Diarization](get-started-stt-diarization.md)

+- [Pronunciation assessment](how-to-pronunciation-assessment.md)

+**DNS for private endpoints:** Review the general principles of [DNS for private endpoints in Azure AI services resources](../cognitive-services-virtual-networks.md#apply-dns-changes-for-private-endpoints). Then confirm that your DNS configuration is working correctly by performing the checks described in the following sections.

+| Max number of simultaneous model trainings | N/A | 4 |

+ Title: Deploy a user-managed glossary in Translator container

+description: How to deploy a user-managed glossary in the Translator container environment.

+recommendations: false

+<!-- markdownlint-disable MD036 -->

+<!-- markdownlint-disable MD046 -->

+# Deploy a user-managed glossary

+Microsoft Translator containers enable you to run several features of the Translator service in your own environment and are great for specific security and data governance requirements.

+There may be times when you're running a container with a multi-layered ingestion process when you discover that you need to implement an update to sentence and/or phrase files. Since the standard phrase and sentence files are encrypted and read directly into memory at runtime, you need to implement a quick-fix engineering solution to implement a dynamic update. This update can be implemented using our user-managed glossary feature:

+* To deploy the **phrase&#8203;fix** solution, you need to create a **phrase&#8203;fix** glossary file to specify that a listed phrase is translated in a specified way.

+* To deploy the **sent&#8203;fix** solution, you need to create a **sent&#8203;fix** glossary file to specify an exact target translation for a source sentence.

+* The **phrase&#8203;fix** and **sent&#8203;fix** files are then included with your translation request and read directly into memory at runtime.

+## Managed glossary workflow

+ > [!IMPORTANT]

+ > **UTF-16 LE** is the only accepted file format for the managed-glossary folders. For more information about encoding your files, *see* [Encoding](/powershell/module/microsoft.powershell.management/set-content?view=powershell-7.2#-encoding&preserve-view=true)

+1. To get started manually creating the folder structure, you need to create and name your folder. The managed-glossary folder is encoded in **UTF-16 LE BOM** format and nests **phrase&#8203;fix** or **sent&#8203;fix** source and target language files. Let's name our folder `customhotfix`. Each folder can have **phrase&#8203;fix** and **sent&#8203;fix** files. You provide the source (`src`) and target (`tgt`) language codes with the following naming convention:

+ |Glossary file name format|Example file name |

+ |--|--|

+ |{`src`}.{`tgt`}.{container-glossary}.{phrase&#8203;fix}.src.snt|en.es.container-glossary.phrasefix.src.snt|

+ |{`src`}.{`tgt`}.{container-glossary}.{phrase&#8203;fix}.tgt.snt|en.es.container-glossary.phrasefix.tgt.snt|

+ |{`src`}.{`tgt`}.{container-glossary}.{sent&#8203;fix}.src.snt|en.es.container-glossary.sentfix.src.snt|

+ |{`src`}.{`tgt`}.{container-glossary}.{sent&#8203;fix}.tgt.snt|en.es.container-glossary.sentfix.tgt.snt|

+ > [!NOTE]

+ >

+ > * The **phrase&#8203;fix** solution is an exact find-and-replace operation. Any word or phrase listed is translated in the way specified.

+ > * The **sent&#8203;fix** solution is more precise and allows you to specify an exact target translation for a source sentence. For a sentence match to occur, the entire submitted sentence must match the **sent&#8203;fix** entry. If only a portion of the sentence matches, the entry won't match.

+ > * If you're hesitant about making sweeping find-and-replace changes, we recommend, at the outset, solely using the **sent&#8203;fix** solution.

+1. Next, to dynamically reload glossary entry updates, create a `version.json` file within the `customhotfix` folder. The `version.json` file should contain the following parameters: **VersionId**. An integer value.

+ ***Sample version.json file***

+ ```json

+ {

+ "VersionId": 5

+ }

+ ```

+ > [!TIP]

+ >

+ > Reload can be controlled by setting the following environmental variables when starting the container:

+ >

+ > * **HotfixReloadInterval=**. Default value is 5 minutes.

+ > * **HotfixReloadEnabled=**. Default value is true.

+1. Use the **docker run** command

+ **Docker run command required options**

+ ```dockerfile

+ docker run --rm -it -p 5000:5000 \

+ -e eula=accept \

+ -e billing={ENDPOINT_URI} \

+ -e apikey={API_KEY} \

+ -e Languages={LANGUAGES_LIST} \

+ -e HotfixDataFolder={path to glossary folder}

+ {image}

+ ```

+ **Example docker run command**

+ ```dockerfile

+ docker run -rm -it -p 5000:5000 \

+ -v /mnt/d/models:/usr/local/models -v /mnt/d /customerhotfix:/usr/local/customhotfix \

+ -e EULA=accept \

+ -e billing={ENDPOINT_URI} \

+ -e apikey={API_Key} \

+ -e Languages=en,es \

+ -e HotfixDataFolder=/usr/local/customhotfix\

+ mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

+ ```

+## Learn more

+> [!div class="nextstepaction"]

+> [Create a dynamic dictionary](../dynamic-dictionary.md) [Use a custom dictionary](../custom-translator/concepts/dictionaries.md)

+Containers enable you to run several features of the Translator service in your own environment. Containers are great for specific security and data governance requirements. In this article you learn how to download, install, and run a Translator container.

+> * To use the Translator container, you must submit an online request and have it approved. For more information, _see_ [Request approval to run container](#request-approval-to-run-container).

+> * Translator container supports limited features compared to the cloud offerings. For more information, _see_ [**Container translate methods**](translator-container-supported-parameters.md).

+To get started, you need an active [**Azure account**](https://azure.microsoft.com/free/cognitive-services/). If you don't have one, you can [**create a free account**](https://azure.microsoft.com/free/).

+You also need:

+| Familiarity with Docker | <ul><li>You should have a basic understanding of Docker concepts like registries, repositories, containers, and container images, as well as knowledge of basic `docker` [terminology and commands](/dotnet/architecture/microservices/container-docker-introduction/docker-terminology).</li></ul> |

+| Translator resource | <ul><li>An Azure [Translator](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) regional resource (not `global`) with an associated API key and endpoint URI. Both values are required to start the container and can be found on the resource overview page.</li></ul>|

+* The container provides a homepage at `/` as a visual validation that the container is running.

+* You can open your favorite web browser and navigate to the external IP address and exposed port of the container in question. Use the following request URLs to validate the container is running. The example request URLs listed point to `http://localhost:5000`, but your specific container may vary. Keep in mind that you're navigating to your container's **External IP address** and exposed port.

+> The feature described in this document, Azure AD Integration (legacy) was **deprecated on June 1st, 2023**. At this time, no new clusters can be created with Azure AD Integration (legacy). All Azure AD Integration (legacy) AKS clusters will be migrated to AKS-managed Azure AD automatically starting from December 1st, 2023.

+|networkEndpointType| Specify network endpoint type for the storage account created by driver. If privateEndpoint is specified, a [private endpoint][storage-account-private-endpoint] is created for the storage account. For other cases, a service endpoint will be created for NFS protocol.¹ | `privateEndpoint` | No | For an AKS cluster, add the AKS cluster name to the Contributor role in the resource group hosting the VNET.|

+¹ If the storage account is created by the driver, then you only need to specify `networkEndpointType: privateEndpoint` parameter in storage class. The CSI driver creates the private endpoint together with the account. If you bring your own storage account, then you need to [create the private endpoint][storage-account-private-endpoint] for the storage account.

+When you create an Azure Blob storage resource for use with AKS, you can create the resource in the node resource group. This approach allows the AKS cluster to access and manage the blob storage resource.

+[storage-account-private-endpoint]: ../storage/common/storage-private-endpoints.md

+ containers:

+ - name: mypod

+ image: mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine

+ resources:

+ requests:

+ cpu: 100m

+ memory: 128Mi

+ limits:

+ cpu: 250m

+ memory: 256Mi

+ volumeMounts:

+ - mountPath: /mnt/azure

+ name: volume

+ volumes:

+ - name: volume

+ persistentVolumeClaim:

+ claimName: my-azurefile

+* The **cluster autoscaler** watches for pods that can't be scheduled on nodes because of resource constraints. The cluster then automatically increases the number of nodes. For more information, see [How does scale-up work?](https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/FAQ.md#how-does-scale-up-work)

+> --network-plugin kubenet \

+> --network-policy calico \

+ --name azlinuxpool \

+> * Inbound, external traffic flows from the load balancer to the virtual network for your AKS cluster. The virtual network has a network security group (NSG) which allows all inbound traffic from the load balancer. This NSG uses a [service tag][service-tags] of type *LoadBalancer* to allow traffic from the load balancer.

+> * Pod CIDR should be added to loadBalancerSourceRanges if there are Pods needing to access the service's LoadBalancer IP for clusters with version v1.25 or above.

+> The open source Azure AD pod-managed identity (preview) in Azure Kubernetes Service has been deprecated as of 10/24/2022, and the project will be archived in Sept. 2023. For more information, see the [deprecation notice](https://github.com/Azure/aad-pod-identity#-announcement). The AKS Managed add-on begins deprecation in Sept. 2024.

+ * Australia East

+ * Central India

+ * East US

+ * UK South

+ * West Europe

+

+- API Management only performs cache lookup for HTTP GET requests.

+- API Management only caches responses to HTTP GET requests.

+If you want, you can run a custom command at the container start-up time, by running the following command in the [Cloud Shell](https://shell.azure.com):

+The default PHP image for App Service uses Nginx, and you change the site root by [configuring the Nginx server with the `root` directive](https://docs.nginx.com/nginx/admin-guide/web-server/serving-static-content/). This [example configuration file](https://github.com/Azure-Samples/laravel-tasks/blob/main/default) contains the following snippets that changes the `root` directive:

+server {

+ #proxy_cache cache;

+ #proxy_cache_valid 200 1s;

+ listen 8080;

+ listen [::]:8080;

+ root /home/site/wwwroot/public; # Changed for Laravel

+ location / {

+ index index.php https://docsupdatetracker.net/index.html index.htm hostingstart.html;

+ try_files $uri $uri/ /index.php?$args; # Changed for Laravel

+ }

+ ...

+```

+The default container uses the configuration file found at */etc/nginx/sites-available/default*. Keep in mind that any edit you make to this file is erased when the app restarts. To make a change that is effective across app restarts, [add a custom start-up command](#customize-start-up) like this example:

+```

+cp /home/site/wwwroot/default /etc/nginx/sites-available/default && service nginx reload

+This command replaces the default Nginx configuration file with a file named *default* in your repository root and restarts Nginx.

+To customize PHP_INI_SYSTEM directives (see [php.ini directives](https://www.php.net/manual/ini.list.php)), use the `PHP_INI_SCAN_DIR` app setting.

+The deployment process used by the steps here places the package on the app's content share with the right naming convention and directory structure (see [Kudu publish API reference](#kudu-publish-api-reference)), and it's the recommended approach. If you deploy WAR/JAR/EAR packages using [FTP](deploy-ftp.md) or WebDeploy instead, you may see unkown failures due to mistakes in the naming or structure.

+The steps you follow for your project depends on whether you're using [Entity Framework Core](/ef/core/) (default for ASP.NET Core) or [Entity Framework](/ef/ef6/) (default for ASP.NET).

+# [Entity Framework Core](#tab/efcore)

+1. In Visual Studio, open the Package Manager Console and add the NuGet package [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient):

+ ```powershell

+ Install-Package Microsoft.Data.SqlClient -Version 5.1.0

+ ```

+1. In the [ASP.NET Core and SQL Database tutorial](tutorial-dotnetcore-sqldb-app.md), the `MyDbConnection` connection string in *appsettings.json* isn't used at all yet. The local environment and the Azure environment both get connection strings from their respective environment variables in order to keep connection secrets out of the source file. But now with Active Directory authentication, there are no more secrets. In *appsettings.json*, replace the value of the `MyDbConnection` connection string with:

+ ```json

+ "Server=tcp:<server-name>.database.windows.net;Authentication=Active Directory Default; Database=<database-name>;"

+ ```

+ > [!NOTE]

+ > The [Active Directory Default](/sql/connect/ado-net/sql/azure-active-directory-authentication#using-active-directory-default-authentication) authentication type can be used both on your local machine and in Azure App Service. The driver attempts to acquire a token from Azure Active Directory using various means. If the app is deployed, it gets a token from the app's managed identity. If the app is running locally, it tries to get a token from Visual Studio, Visual Studio Code, and Azure CLI.

+ >

+ That's everything you need to connect to SQL Database. When you debug in Visual Studio, your code uses the Azure AD user you configured in [2. Set up your dev environment](#2-set-up-your-dev-environment). You'll set up SQL Database later to allow connection from the managed identity of your App Service app. The `DefaultAzureCredential` class caches the token in memory and retrieves it from Azure AD just before expiration. You don't need any custom code to refresh the token.

+1. Type `Ctrl+F5` to run the app again. The same CRUD app in your browser is now connecting to the Azure SQL Database directly, using Azure AD authentication. This setup lets you run database migrations from Visual Studio.

+* For PowerShell details, see [PowerShell Docs](/powershell/scripting/overview).

+- CLUSTER - Cluster write commands are disabled, but read-only cluster commands are permitted.

+- REPLCONF - Azure cache for Redis instances don't allow customers to add external replicas. This [command](https://redis.io/commands/replconf/) is normally only sent by servers.

+⁴ Service SDK types include types from the [Azure SDK for .NET](/dotnet/azure/sdk/azure-sdk-for-dotnet) such as [BlobClient](/dotnet/api/azure.storage.blobs.blobclient). For the isolated process model, Service Bus triggers do not yet support message settlement scenarios.

+|[Microsoft.Azure.Functions.Worker]| 1.18.0 or later |

+|[Microsoft.Azure.Functions.Worker.Sdk]| 1.13.0 or later |

+| [Azure Tables][tables-sdk-types] | _Trigger does not exist_ | **Generally Available** | _SDK types not recommended.¹_ |

+dotnet add package Microsoft.Azure.Functions.Worker.ApplicationInsights

+## Convert a C# script app to a C# project

+The easiest way to convert an application using C# script to a C# project is to start with a new project and migrate the code and configuration from your .csx and function.json files.

+If you are using C# scripting for portal editing, you may wish to start by [downloading the app content to your local machine](./deployment-zip-push.md#download-your-function-app-files). Choose the "Site content" option instead of "Content and Visual Studio project". The project that the portal provides isn't needed because in the later steps of this section, you will be creating a new Visual Studio project. Similarly, do not include app settings in the download. You are defining a new development environment, and this environment should not have the same permissions as your hosted app environment.

+Once you have your C# script code ready, you can begin creating the new project:

+1. Follow the instructions to create a new function project [using Visual Studio](./functions-create-your-first-function-visual-studio.md), using [Visual Studio Code](./create-first-function-vs-code-csharp.md), or [using the command line](./create-first-function-cli-csharp.md). You don't need to publish the project yet.

+1. If your C# script code included an `extensions.csproj` file or any `function.proj` files, copy the package references from these files, and add them to the new project's `.csproj` file alongside it's core dependencies.

+ The conversion activity a good opportunity to update to the latest versions of your dependencies. Doing so may require additional code changes in a later step.

+1. Copy the contents of the C# scripting `host.json` file into the project `host.json` file. If you are combining this with any other migration activities, note that the [`host.json`](./functions-host-json.md) schema depends on the version you are targeting. The contents of the `extensions` section are also informed by the versions of triggers and bindings that you are using. Refer to the reference for each extension to identify the right properties to configure.

+1. For any [shared files referenced by a `#load` directive](#reusing-csx-code), create new `.cs` files for their contents. You can structure this in any way you prefer. For most apps, it is simplest to create a new `.cs` file for each class that you defined. For any static methods created without a class, you'll need to define a new class or classes that they can be defined in.

+1. Migrate each function to a `.cs` file. This file will combine the `run.csx` and the `function.json` for that function. For example, if you had a function named `HelloWorld`, in C# script this would be represented with `HelloWorld/run.csx` and `HelloWorld/function.json`. For the new project, you would create a `HelloWorld.cs`. Perform the following steps for each function:

+ 1. Create a new file named `<FUNCTION_NAME>.cs`, replacing `<FUNCTION_NAME>` with the name of the folder that defined your C# script function. It is often easiest to start by creating a new function in the project model, which will cover some of the later steps. From the CLI, you can use the command `func new --name <FUNCTION_NAME>` making a similar substitution, and selecting the target template when prompted.

+ 1. Copy the `using` statements from your `run.csx` file and add them to the new file. You do not need any `#r` directives.

+ 1. For any `#load` statement in your `run.csx` file, add a new `using` statement for the namespace you used for the shared code.

+ 1. In the new file, define a class for your function under the namespace you are using for the project.

+ 1. Create a new method named `RunHandler` or something similar. This new method will serve as the new entry point for the function.

+ 1. Copy the static method that represents your function, along with any functions it calls, from `run.csx` into your new class as a second method. From the new method you created in the previous step, call into this static method. This indirection step is helpful for navigating any differences as you continue the upgrade. You can keep the original method exactly the same and simply control its inputs from the new context. You may need to create parameters on the new method which you then pass into the static method call. After you have confirmed that the migration has worked as intended, you can remove this extra level of indirection.

+ 1. For each binding in the `function.json` file, add the corresponding attribute to your new method. This may require you to add additional package dependencies. Consult the reference for each binding for specific requirements in the new model.

+

+1. Verify that your project runs locally.

+1. Republish the app to Azure.

+

+### Example function conversion

+This section shows an example of the migration for a single function.

+The original function in C# scripting has two files:

+- `HelloWorld/function.json`

+- `HelloWorld/run.csx`

+The contents of `HelloWorld/function.json` are:

+```json

+{

+ "bindings": [

+ {

+ "authLevel": "FUNCTION",

+ "name": "req",

+ "type": "httpTrigger",

+ "direction": "in",

+ "methods": [

+ "get",

+ "post"

+ ]

+ },

+ {

+ "name": "$return",

+ "type": "http",

+ "direction": "out"

+ }

+ ]

+}

+```

+The contents of `HelloWorld/run.csx` are:

+```csharp

+#r "Newtonsoft.Json"

+using System.Net;

+using Microsoft.AspNetCore.Mvc;

+using Microsoft.Extensions.Primitives;

+using Newtonsoft.Json;

+public static async Task<IActionResult> Run(HttpRequest req, ILogger log)

+{

+ log.LogInformation("C# HTTP trigger function processed a request.");

+ string name = req.Query["name"];

+ string requestBody = await new StreamReader(req.Body).ReadToEndAsync();

+ dynamic data = JsonConvert.DeserializeObject(requestBody);

+ name = name ?? data?.name;

+ string responseMessage = string.IsNullOrEmpty(name)

+ ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."

+ : $"Hello, {name}. This HTTP triggered function executed successfully.";

+ return new OkObjectResult(responseMessage);

+}

+```

+After migrating to the isolated worker model with ASP.NET Core integration, these are replaced by a single `HelloWorld.cs`:

+```csharp

+using System.Net;

+using Microsoft.Azure.Functions.Worker;

+using Microsoft.AspNetCore.Http;

+using Microsoft.AspNetCore.Mvc;

+using Microsoft.Extensions.Logging;

+using Microsoft.AspNetCore.Routing;

+using Microsoft.Extensions.Primitives;

+using Newtonsoft.Json;

+namespace MyFunctionApp

+{

+ public class HelloWorld

+ {

+ private readonly ILogger _logger;

+ public HelloWorld(ILoggerFactory loggerFactory)

+ {

+ _logger = loggerFactory.CreateLogger<HelloWorld>();

+ }

+ [Function("HelloWorld")]

+ public async Task<IActionResult> RunHandler([HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)

+ {

+ return await Run(req, _logger);

+ }

+ // From run.csx

+ public static async Task<IActionResult> Run(HttpRequest req, ILogger log)

+ {

+ log.LogInformation("C# HTTP trigger function processed a request.");

+ string name = req.Query["name"];

+ string requestBody = await new StreamReader(req.Body).ReadToEndAsync();

+ dynamic data = JsonConvert.DeserializeObject(requestBody);

+ name = name ?? data?.name;

+ string responseMessage = string.IsNullOrEmpty(name)

+ ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."

+ : $"Hello, {name}. This HTTP triggered function executed successfully.";

+ return new OkObjectResult(responseMessage);

+ }

+ }

+}

+```

+When running on Linux, the Node.js version is set by the [linuxfxversion](./functions-app-settings.md#linuxfxversion) site setting. This setting can be updated using the Azure CLI.

+The section outlines the various changes that you need to make to your local project to move it to the isolated worker model. Some of the steps change based on your target version of .NET. Use the tabs to select the instructions which match your desired version. These steps assume a local C# project, and if your app is instead using C# script (`.csx` files), you should [convert to the project model](./functions-reference-csharp.md#convert-a-c-script-app-to-a-c-project) before continuing.

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js" />

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css">

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css">

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+## v3 (latest)

+### [3.0.0] (August 18, 2023)

+#### Bug fixes (3.0.0)

+- Fixed zoom control to take into account the `maxBounds` [CameraOptions].

+- Fixed an issue that mouse positions are shifted after a css scale transform on the map container.

+#### Other changes (3.0.0)

+- Phased out the style definition version `2022-08-05` and switched the default `styleDefinitionsVersion` to `2023-01-01`.

+- Added the `mvc` parameter to encompass the map control version in both definitions and style requests.

+#### Installation (3.0.0)

+The version is available on [npm][3.0.0] and CDN.

+- **NPM:** Refer to the instructions at [azure-maps-control@3.0.0][3.0.0]

+- **CDN:** Reference the following CSS and JavaScript in the `<head>` element of an HTML file:

+ ```html

+ <link href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3.0/atlas.min.css" rel="stylesheet" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3.0/atlas.min.js"></script>

+ ```

+## v2

+[3.0.0]: https://www.npmjs.com/package/azure-maps-control/v/3.0.0

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css">

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css">

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css">

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+ <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />

+ <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

+To add a community library, use the `ConfigureOpenTelemetryMeterProvider` or `ConfigureOpenTelemetryTracerProvider` methods.

+builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>

+{

+ o.SamplingRatio = 0.1F;

+});

+> - March 31, 2023 ΓÇô The Diagnostic Settings Storage Retention feature will no longer be available to configure new retention rules for log data. This includes using the portal, CLI PowerShell, and ARM and Bicep templates. If you have configured retention settings, you'll still be able to see and change them in the portal.

+> - September 30, 2023 ΓÇô You will no longer be able to use the API (CLI, Powershell, or templates), or Azure portal to configure retention setting unless you're changing them to *0*. Existing retention rules will still be respected.

+1. On the **Filters** tab, under **Blob prefix** set path or prefix to the container or logs you want the retention rule to apply to. The path or prefix can be at any level within the container and will apply to all blobs under that path or prefix.

+For example, for *all* insight activity logs, use the container *insights-activity-logs* to set the retention for all of the log in that container logs.

+To set the rule for a specific webapp app, use *insights-activity-logs/ResourceId=/SUBSCRIPTIONS/\<your subscription Id\>/RESOURCEGROUPS/\<your resource group\>/PROVIDERS/MICROSOFT.WEB/SITES/\<your webapp name\>*.

+ Use the Storage browser to help you find the path or prefix.

+ The example below shows the prefix for a specific web app: **insights-activity-logs/ResourceId=/SUBSCRIPTIONS/d05145d-4a5d-4a5d-4a5d-5267eae1bbc7/RESOURCEGROUPS/rg-001/PROVIDERS/MICROSOFT.WEB/SITES/appfromdocker1*.

+ To set the rule for all resources in the resource group, use *insights-activity-logs/ResourceId=/SUBSCRIPTIONS/d05145d-4a5d-4a5d-4a5d-5267eae1bbc7/RESOURCEGROUPS/rg-001*.

+ :::image type="content" source="./media/retention-migration/blob-prefix.png" alt-text="A screenshot showing the Storage browser and resource path." lightbox="./media/retention-migration/blob-prefix.png":::

+> This tutorial uses ARM templates to configure the components required to support the Logs ingestion API. See [Tutorial: Send data to Azure Monitor Logs with Logs ingestion API (Azure portal)](tutorial-logs-ingestion-portal.md) for a similar tutorial that uses the Azure portal UI to configure these components.

+* [SAP on Azure NetApp Files Sizing Best Practices](https://techcommunity.microsoft.com/t5/running-sap-applications-on-the/sap-on-azure-netapp-files-sizing-best-practices/ba-p/3895300)

+* In a [cross-region replication](cross-region-replication-introduction.md) (CRR) or [cross-zone replication](cross-zone-replication-introduction.md) (CZR) setting, Azure NetApp Files backup can be configured on a source volume only. Azure NetApp Files backup isn't supported on a CRR or CZR *destination* volume.

+1. Select **Resource groups**.

+1. Select **Create**.

+ :::image type="content" source="./media/manage-resource-groups-portal/manage-resource-groups-add-group.png" alt-text="Screenshot of the Azure portal with 'Resource groups' and 'Add' highlighted." lightbox="./media/manage-resource-groups-portal/manage-resource-groups-add-group.png":::

+1. Enter the following values:

+ - **Subscription**: Select your Azure subscription.

+ - **Resource group**: Enter a new resource group name.

+ :::image type="content" source="./media/manage-resource-groups-portal/manage-resource-groups-create-group.png" alt-text="Screenshot of the Create Resource Group form in the Azure portal with fields for Subscription, Resource group, and Region." lightbox="./media/manage-resource-groups-portal/manage-resource-groups-create-group.png":::

+1. Select **Review + Create**

+1. Select **Create**. It takes a few seconds to create a resource group.

+1. Select **Refresh** from the top menu to refresh the resource group list, and then select the newly created resource group to open it. Or select **Notification**(the bell icon) from the top, and then select **Go to resource group** to open the newly created resource group

+ :::image type="content" source="./media/manage-resource-groups-portal/manage-resource-groups-add-group-go-to-resource-group.png" alt-text="Screenshot of the Azure portal with the 'Go to resource group' button in the Notifications panel." lightbox="./media/manage-resource-groups-portal/manage-resource-groups-add-group-go-to-resource-group.png":::

+1. To list the resource groups, select **Resource groups**

+1. To customize the information displayed for the resource groups, configure the filters. The following screenshot shows the additional columns you could add to the display:

+ :::image type="content" source="./media/manage-resource-groups-portal/manage-resource-groups-list-groups.png" alt-text="Screenshot of the Azure portal displaying a list of resource groups." lightbox="./media/manage-resource-groups-portal/manage-resource-groups-list-groups.png":::

+1. Select **Resource groups**.

+1. Select the resource group you want to open.

+1. Select **Delete resource group**.

+ :::image type="content" source="./media/manage-resource-groups-portal/delete-group.png" alt-text="Screenshot of the Azure portal with the Delete resource group button highlighted in a specific resource group." lightbox="./media/manage-resource-groups-portal/delete-group.png":::

+Locking prevents other users in your organization from accidentally deleting or modifying critical resources, such as Azure subscription, resource group, or resource.

+1. In the left pane, select **Locks**.

+1. To add a lock to the resource group, select **Add**.

+1. Enter **Lock name**, **Lock type**, and **Notes**. The lock types include **Read-only**, and **Delete**.

+ :::image type="content" source="./media/manage-resource-groups-portal/manage-resource-groups-add-lock.png" alt-text="Screenshot of the Add Lock form in the Azure portal with fields for Lock name, Lock type, and Notes." lightbox="./media/manage-resource-groups-portal/manage-resource-groups-add-lock.png":::

+## Microsoft.AzureArcData

+* SqlServerInstances

+## Microsoft.Cdn

+* profiles - By default, limited to 800 instances. That limit can be increased by [registering the following features](preview-features.md) - Microsoft.Resources/ARMDisableResourcesPerRGLimit

+* profiles/networkpolicies - By default, limited to 800 instances. That limit can be increased by [registering the following features](preview-features.md) - Microsoft.Resources/ARMDisableResourcesPerRGLimit

+* diskEncryptionSets

+* bootstrapConfigurations

+## Microsoft.Fabric

+* capacities - By default, limited to 800 instances. That limit can be increased by [registering the following features](preview-features.md) - Microsoft.Fabric/UnlimitedResourceGroupQuota

+* machines/runcommands

+## Microsoft.NetworkCloud

+* volumes

+## Microsoft.NetworkFunction

+* vpnBranches - By default, limited to 800 instances. That limit can be increased by [registering the following features](preview-features.md) - Microsoft.NetworkFunction/AllowNaasVpnAccess

+* securityConnectors/devops

+* accounts/secrets

+* certificates - By default, limited to 800 instances. That limit can be increased by [registering the following features](preview-features.md) - Microsoft.Web/DisableResourcesPerRGLimitForAPIMinWebApp

+- West Europe (on AV36, and AV36P)

+In this article, you'll rotate the cloudadmin credentials (vCenter Server and NSX-T *CloudAdmin* credentials) for your Azure VMware Solution private cloud. Although the password for this account doesn't expire, you can generate a new one at any time.

+>If you use your cloudadmin credentials to connect services to vCenter Server or NSX-T in your private cloud, those connections will stop working once you rotate your password. Those connections will also lock out the cloudadmin account unless you stop those services before rotating the password.

+Consider and determine which services connect to vCenter Server as *cloudadmin@vsphere.local* or NSX-T as cloudadmin before you rotate the password. These services may include VMware services such as HCX, vRealize Orchestrator, vRealize Operations Manager, VMware Horizon, or other third-party tools used for monitoring or provisioning.

+Instead of using the cloudadmin user to connect services to vCenter Server or NSX-T, we recommend individual accounts for each service. For more information about setting up separate accounts for connected services, see [Access and Identity Concepts](./concepts-identity.md).

+1. Select **Generate new password** under vCenter Server credentials.

+### Update HCX Connector

+## Reset your NSX-T manager credentials

+1. In your Azure VMware Solution private cloud, select **VMWare credentials**.

+1. Select **Generate new password** under NSX-T Manager credentials.

+1. Select the confirmation checkbox and then select **Generate password**.

+Now that you've covered resetting your vCenter Server and NSX-T credentials for Azure VMware Solution, you may want to learn about:

+description: This article provides information on authorizing access to Azure Web PubSub Service resources using Azure Active Directory.

+_[1] security principal: a user/resource group, an application, or a service principal such as system-assigned identities and user-assigned identities._

+- **An individual resource.**

+- **A resource group.**

+- **A management group.**

+ Full access to data-plane permissions, including read/write REST APIs and Auth APIs.

+ This role is the most common used for building an upstream server.

+ Use to grant read-only REST APIs permissions to Web PubSub resources.

+ It's used when you'd like to write a monitoring tool that calling **ONLY** Web PubSub data-plane **READONLY** REST APIs.

+To learn more about roles and role assignments, see

+To learn how to create custom roles, see

+- [Disable local authentication](./howto-disable-local-auth.md)

+description: Learn about Azure Web PubSub Service internals, the architecture, the connections and how data is transmitted.

+# Azure Web PubSub service internals

+- **Service**: Azure Web PubSub Service.

+1. A _client_ connects to the service `/client` endpoint using WebSocket transport. Service forward every WebSocket frame to the configured upstream(server). The WebSocket connection can connect with any custom subprotocol for the server to handle, or it can connect with the service-supported subprotocol `json.webpubsub.azure.v1`, which empowers the clients to do pub/sub directly. Details are described in [client protocol](#client-protocol).

+var client1 = new WebSocket("wss://test.webpubsub.azure.com/client/hubs/hub1");

+var client2 = new WebSocket(

+ "wss://test.webpubsub.azure.com/client/hubs/hub1",

+ "custom.subprotocol"

+);

+var pubsub = new WebSocket(

+ "wss://test.webpubsub.azure.com/client/hubs/hub1",

+ "json.webpubsub.azure.v1"

+);

+- Join a group, for example:

+ ```json

+ {

+ "type": "joinGroup",

+ "group": "<group_name>"

+ }

+ ```

+- Leave a group, for example:

+ ```json

+ {

+ "type": "leaveGroup",

+ "group": "<group_name>"

+ }

+ ```

+- Publish messages to a group, for example:

+ ```json

+ {

+ "type": "sendToGroup",

+ "group": "<group_name>",

+ "data": { "hello": "world" }

+ }

+ ```

+- Send custom events to the upstream server, for example:

+ ```json

+ {

+ "type": "event",

+ "event": "<event_name>",

+ "data": { "hello": "world" }

+ }

+ ```

+You may have noticed that for a [simple WebSocket client](#the-simple-websocket-client), the _server_ is a **must have** role to receive the `message` events from clients. A simple WebSocket connection always triggers a `message` event when it sends messages, and always relies on the server-side to process messages and do other operations. With the help of the `json.webpubsub.azure.v1` subprotocol, an authorized client can join a group and publish messages to a group directly. It can also route messages to different event handlers / event listeners by customizing the _event_ the message belongs.

+var client1 = new WebSocket(

+ "wss://xxx.webpubsub.azure.com/client/hubs/hub1",

+ "json.webpubsub.azure.v1"

+);

+client1.onmessage = (e) => {

+ if (e.data) {

+ var message = JSON.parse(e.data);

+ if (message.type === "message" && message.group === "Group1") {

+ // Only print messages from Group1

+ console.log(message.data);

+ }

+client1.onopen = (e) => {

+ client1.send(

+ JSON.stringify({

+ type: "joinGroup",

+ group: "Group1",

+ })

+ );

+- Synchronous events (blocking)

+ Synchronous events block the client workflow.

+ - `connect`: This event is for event handler only. When the client starts a WebSocket handshake, the event is triggered and developers can use `connect` event handler to handle the WebSocket handshake, determine the subprotocol to use, authenticate the client, and join the client to groups.

+ - `message`: This event is triggered when a client sends a message.

+- Asynchronous events (non-blocking)

+ Asynchronous events don't block the client workflow, it acts as some notification to server. When such an event trigger fails, the service logs the error detail.

+ - `connected`: This event is triggered when a client connects to the service successfully.

+ - `disconnected`: This event is triggered when a client disconnected with the service.

+As you may have noticed when we describe the PubSub WebSocket clients, that a client can publish to other clients only when it's _authorized_ to. The `role`s of the client determines the _initial_ permissions the client have:

+| Role | Permission |

+| - | |

+| Not specified | The client can send events. |

+| `webpubsub.joinLeaveGroup` | The client can join/leave any group. |

+| `webpubsub.sendToGroup` | The client can publish messages to any group. |

+| `webpubsub.joinLeaveGroup.<group>` | The client can join/leave group `<group>`. |

+| `webpubsub.sendToGroup.<group>` | The client can publish messages to group `<group>`. |

+ - Step1: Enable Identity for the Web PubSub service

+ - Step2: Select from existing Azure AD application that stands for your webhook web app

+The server is by nature an authorized user. With the help of the _event handler role_, the server knows the metadata of the clients, for example, `connectionId` and `userId`, so it can:

+- Close a client connection

+- Send messages to a client

+- Send messages to clients that belong to the same user

+- Add a client to a group

+- Add clients authenticated as the same user to a group

+- Remove a client from a group

+- Remove clients authenticated as the same user from a group

+- Publish messages to a group

+- Grant publish/join permissions to some specific group or to all groups

+- Revoke publish/join permissions for some specific group or for all groups

+- Check if the client has permission to join or publish to some specific group or to all groups

+You may have noticed that the _event handler role_ handles communication from the service to the server while _the manager role_ handles communication from the server to the service. After combining the two roles, the data flow between service and server looks similar to the following diagram using HTTP protocol.

+Azure Web PubSub Service supports Azure Active Directory (Azure AD) authorizing requests from [Azure applications](../active-directory/develop/app-objects-and-service-principals.md).

+ 

+ 

+1. Copy the value of the **client secret** and then paste it to a secure location.

+ > [!NOTE]

+ > The secret will display only once.

+This sample shows how to assign a `Web PubSub Service Owner` role to a service principal (application) over a Web PubSub resource.

+1. Search for and select the application that you would like to assign the role to.

+1. Click **Next**.

+1. Click **Review + assign** to confirm the change.

+> To learn more about how to assign and manage Azure role assignments, see these articles:

+ 1. Select **x-www-form-urlencoded**.

+ 2. Add `grant_type` key, and type `client_credentials` for the value.

+ 3. Add `client_id` key, and paste the value of **Application (client) ID** in the **Overview** tab of the application you created earlier.

+ 4. Add `client_secret` key, and paste the value of client secret you noted down earlier.

+ 5. Add `resource` key, and type `https://webpubsub.azure.com` for the value.

+6. Select **Send** to send the request to get the token. You see the token in the `access_token` field.

+- [Disable local authentication](./howto-disable-local-auth.md)

+Azure Web PubSub Service supports Azure Active Directory (Azure AD) authorizing requests from [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md).

+## Add role assignments on Azure portal

+This sample shows how to assign a `Web PubSub Service Owner` role to a system-assigned identity over a Web PubSub resource.

+1. Click **Next**.

+1. Click **Review + assign** to confirm the change.

+> To learn more about how to assign and manage Azure role assignments, see these articles:

+- [Disable local authentication](./howto-disable-local-auth.md)

+ ```java

+ package com.webpubsub.tutorial;

+ import com.azure.core.credential.TokenCredential;

+ import com.azure.identity.DefaultAzureCredentialBuilder;

+ public class App {

+ public static void main(String[] args) {

+ TokenCredential credential = new DefaultAzureCredentialBuilder().build();

+ }

+ }

+ ```

+ `credential` can be any class that inherits from `TokenCredential` class.

+ - EnvironmentCredential

+ - ClientSecretCredential

+ - ClientCertificateCredential

+ - ManagedIdentityCredential

+ - VisualStudioCredential

+ - VisualStudioCodeCredential

+ - AzureCliCredential

+ To learn more, see [Azure Identity client library for Java](/java/api/overview/azure/identity-readme)

+2. Then create a `client` with `endpoint`, `hub`, and `credential`.

+ ```Java

+ package com.webpubsub.tutorial;

+ import com.azure.core.credential.TokenCredential;

+ import com.azure.identity.DefaultAzureCredentialBuilder;

+ import com.azure.messaging.webpubsub.WebPubSubServiceClient;

+ import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;

+ public class App {

+ public static void main(String[] args) {

+ TokenCredential credential = new DefaultAzureCredentialBuilder().build();

+ // create the service client

+ WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()

+ .endpoint("<endpoint>")

+ .credential(credential)

+ .hub("<hub>")

+ .buildClient();

+ }

+ }

+ ```

+ Learn how to use this client, see [Azure Web PubSub service client library for Java](/java/api/overview/azure/messaging-webpubsub-readme)

+ ```javascript

+ const { DefaultAzureCredential } = require("@azure/identity");

+ let credential = new DefaultAzureCredential();

+ ```

+ `credential` can be any class that inherits from `TokenCredential` class.

+ - EnvironmentCredential

+ - ClientSecretCredential

+ - ClientCertificateCredential

+ - ManagedIdentityCredential

+ - VisualStudioCredential

+ - VisualStudioCodeCredential

+ - AzureCliCredential

+ To learn more, see [Azure Identity client library for JavaScript](/javascript/api/overview/azure/identity-readme)

+2. Then create a `client` with `endpoint`, `hub`, and `credential`.

+ ```javascript

+ const { DefaultAzureCredential } = require("@azure/identity");

+ let credential = new DefaultAzureCredential();

+ let serviceClient = new WebPubSubServiceClient(

+ "<endpoint>",

+ credential,

+ "<hub>"

+ );

+ ```

+ Learn how to use this client, see [Azure Web PubSub service client library for JavaScript](/javascript/api/overview/azure/web-pubsub-readme)

+ Install-Package Azure.Messaging.WebPubSub

+ ```C#

+ using Azure.Identity;

+ namespace chatapp

+ {

+ public class Program

+ {

+ public static void Main(string[] args)

+ {

+ var credential = new DefaultAzureCredential();

+ }

+ }

+ }

+ ```

+ `credential` can be any class that inherits from `TokenCredential` class.

+ - EnvironmentCredential

+ - ClientSecretCredential

+ - ClientCertificateCredential

+ - ManagedIdentityCredential

+ - VisualStudioCredential

+ - VisualStudioCodeCredential

+ - AzureCliCredential

+ To learn more, see [Azure Identity client library for .NET](/dotnet/api/overview/azure/identity-readme)

+2. Then create a `client` with `endpoint`, `hub`, and `credential`.

+ ```C#

+ using Azure.Identity;

+ using Azure.Messaging.WebPubSub;

+ public class Program

+ {

+ public static void Main(string[] args)

+ {

+ var credential = new DefaultAzureCredential();

+ var client = new WebPubSubServiceClient(new Uri("<endpoint>"), "<hub>", credential);

+ }

+ }

+ ```

+ Or inject it into `IServiceCollections` with our `BuilderExtensions`.

+ ```C#

+ using System;

+ using Azure.Identity;

+ using Microsoft.Extensions.Azure;

+ using Microsoft.Extensions.Configuration;

+ using Microsoft.Extensions.DependencyInjection;

+ namespace chatapp

+ {

+ public class Startup

+ {

+ public Startup(IConfiguration configuration)

+ {

+ Configuration = configuration;

+ }

+ public IConfiguration Configuration { get; }

+ public void ConfigureServices(IServiceCollection services)

+ {

+ services.AddAzureClients(builder =>

+ {

+ var credential = new DefaultAzureCredential();

+ builder.AddWebPubSubServiceClient(new Uri("<endpoint>"), "<hub>", credential);

+ });

+ }

+ }

+ }

+ ```

+ Learn how to use this client, see [Azure Web PubSub service client library for .NET](/dotnet/api/overview/azure/messaging.webpubsub-readme)

+ ```python

+ from azure.identity import DefaultAzureCredential

+ credential = DefaultAzureCredential()

+ ```

+ `credential` can be any class that inherits from `TokenCredential` class.

+ - EnvironmentCredential

+ - ClientSecretCredential

+ - ClientCertificateCredential

+ - ManagedIdentityCredential

+ - VisualStudioCredential

+ - VisualStudioCodeCredential

+ - AzureCliCredential

+ To learn more, see [Azure Identity client library for Python](/python/api/overview/azure/identity-readme)

+2. Then create a `client` with `endpoint`, `hub`, and `credential`.

+ ```python

+ from azure.identity import DefaultAzureCredential

+ credential = DefaultAzureCredential()

+ client = WebPubSubServiceClient(hub="<hub>", endpoint="<endpoint>", credential=credential)

+ ```

+ Learn how to use this client, see [Azure Web PubSub service client library for Python](/python/api/overview/azure/messaging-webpubsubservice-readme)

+description: Quickstart showing how to create a Web PubSub resource from Azure portal, using Azure CLI and a Bicep template

+>

+> - An Azure account with an active subscription. [Create a free Azure account](https://azure.microsoft.com/free/), if don't have one already.

+1. Select the New button found on the upper left-hand corner of the Azure portal. In the New screen, type **Web PubSub** in the search box and press enter.

+ :::image type="content" source="./media/create-instance-portal/search-web-pubsub-in-portal.png" alt-text="Screenshot of searching the Azure Web PubSub in portal.":::

+ | Setting | Suggested value | Description |

+ | -- | -- | |

+ | **Resource name** | Globally unique name | The globally unique Name that identifies your new Web PubSub service instance. Valid characters are `a-z`, `A-Z`, `0-9`, and `-`. |

+ | **Subscription** | Your subscription | The Azure subscription under which this new Web PubSub service instance is created. |

+ | **[Resource Group]** | myResourceGroup | Name for the new resource group in which to create your Web PubSub service instance. |

+ | **Location** | West US | Choose a [region](https://azure.microsoft.com/regions/) near you. |

+ | **Pricing tier** | Free | You can first try Azure Web PubSub service for free. Learn more details about [Azure Web PubSub service pricing tiers](https://azure.microsoft.com/pricing/details/web-pubsub/) |

+ | **Unit count** | - | Unit count specifies how many connections your Web PubSub service instance can accept. Each unit supports 1,000 concurrent connections at most. It is only configurable in the Standard tier. |

+ :::image type="content" source="./media/howto-develop-create-instance/create-web-pubsub-instance-in-portal.png" alt-text="Screenshot of creating the Azure Web PubSub instance in portal.":::

+ ::: zone-end

+The [Azure CLI](/cli/azure) is a set of commands used to create and manage Azure resources. The Azure CLI is available across Azure services and is designed to get you working quickly with Azure, with an emphasis on automation.

+ # [CLI](#tab/CLI)

+ ```azurecli

+ az group create --name exampleRG --location eastus

+ az deployment group create --resource-group exampleRG --template-file main.bicep

+ ```

+ # [PowerShell](#tab/PowerShell)

+ ```azurepowershell

+ New-AzResourceGroup -Name exampleRG -Location eastus

+ New-AzResourceGroupDeployment -ResourceGroupName exampleRG -TemplateFile ./main.bicep

+ ```

+ ***

+ When the deployment finishes, you should see a message indicating the deployment succeeded.

+> [!div class="nextstepaction"]

+- [Send client events to Event Hubs](#send-client-events-to-event-hubs)

+ - [Overview](#overview)

+ - [Configure an event listener](#configure-an-event-listener)

+ - [Add a managed identity to your Web PubSub service](#add-a-managed-identity-to-your-web-pubsub-service)

+ - [Grant the managed identity an `Azure Event Hubs Data sender` role](#grant-the-managed-identity-an-azure-event-hubs-data-sender-role)

+ - [Add an event listener rule to your service settings](#add-an-event-listener-rule-to-your-service-settings)

+ - [Test your configuration with live demo](#test-your-configuration-with-live-demo)

+ - [Next steps](#next-steps)

+1. Find your service from **Azure portal**. Navigate to **Settings**. Then select **Add** to configure your event listener. For an existing hub configuration, select **...** on right side will navigate to the same editing page.

+ :::image type="content" source="media/howto-develop-event-listener/eventhub-consumer-connected-event.png" alt-text="Screenshot of a printed connected event in the Event Hubs consumer client app.":::

+ :::image type="content" source="media/howto-develop-event-listener/web-pubsub-client-specify-event-name.png" alt-text="Screenshot showing the area of the WebSocket client app to generate a user event.":::

+> [!div class="nextstepaction"]

+<!--TODO: Add demo-->

+The event handler handles the incoming client events. Event handlers are registered and configured in the service through the Azure portal or Azure CLI. When a client event is triggered, the service can send the event to the appropriate event handler. The Web PubSub service now supports the event handler as the server-side, which exposes the publicly accessible endpoint for the service to invoke when the event is triggered. In other words, it acts as a **webhook**.

+For every event, the service formulates an HTTP POST request to the registered upstream endpoint and expects an HTTP response.

+- Azure Active Directory(Azure AD) authentication. For more information, see [Use a managed identity in client events](howto-use-managed-identity.md#use-a-managed-identity-in-client-events-scenarios).

+1. Go to your Azure Web PubSub service page in the **Azure portal**.

+1. Select **Settings** from the menu.

+1. In the event handler page, configure the following fields: 1. Enter the server webhook URL in the **URL Template** field. 1. Select the **System events** that you want to subscribe to. 1. Select the **User events** that you want to subscribe to. 1. Select **Authentication** method to authenticate upstream requests. 1. Select **Confirm**.

+ :::image type="content" source="media/howto-develop-eventhandler/configure-event-handler.png" alt-text="Screenshot of Azure Web PubSub Configure Event Handler.":::

+| Commands | Description |

+| -- | -- |

+| `create` | Create hub settings for WebPubSub Service. |

+| `delete` | Delete hub settings for WebPubSub Service. |

+| `list` | List all hub settings for WebPubSub Service. |

+| `show` | Show hub settings for WebPubSub Service. |

+| `update` | Update hub settings for WebPubSub Service. |

+ ```js

+ var pubsub = new WebSocket(

+ "wss://test.webpubsub.azure.com/client/hubs/hub1",

+ "json.reliable.webpubsub.azure.v1"

+ );

+ ```

+ ```js

+ var pubsub = new WebSocket(

+ "wss://test.webpubsub.azure.com/client/hubs/hub1",

+ "protobuf.reliable.webpubsub.azure.v1"

+ );

+ ```

+Websocket connections rely on TCP. When the connection doesn't drop, messages are lossless and delivered in order. To prevent message loss over dropped connections, the Web PubSub service retains the connection status information, including group and message information. This information is used to restore the client on connection recovery

+When the client reconnects to the service using reliable subprotocols, the client will receive a `Connected` message containing the `connectionId` and `reconnectionToken`. The `connectionId` identifies the session of the connection in the service.

+ "type": "system",

+ "event": "connected",

+ "connectionId": "<connection_id>",

+ "reconnectionToken": "<reconnection_token>"

+Clients that send events to event handlers or publish messages to other clients are called publishers. Publishers should set `ackId` in the message to receive an acknowledgment from the Web PubSub service that publishing the message was successful or not.

+The `ackId` is the identifier of the message, each new message should use a unique ID. The original `ackId` should be used when resending a message.

+ "type": "sendToGroup",

+ "group": "group1",

+ "dataType": "text",

+ "data": "text data",

+ "ackId": 1

+ "type": "ack",

+ "ackId": 1,

+ "success": true

+When the service experiences a transient internal error and the message can't be sent to subscriber, the publisher will receive an ack with `success: false`. The publisher should read the error to determine whether or not to resend the message. If the message is resent, the same `ackId` should be used.

+ "type": "ack",

+ "ackId": 1,

+ "success": false,

+ "error": {

+ "name": "InternalServerError",

+ "message": "Internal server error"

+ }

+If the service's ack response is lost because the WebSocket connection dropped, the publisher should resend the message with the same `ackId` after recovery. When the message was previously processed by the service, it will send an ack containing a `Duplicate` error. The publisher should stop resending this message.

+ "type": "ack",

+ "ackId": 1,

+ "success": false,

+ "error": {

+ "name": "Duplicate",

+ "message": "Message with ack-id: 1 has been processed"

+ }

+ "type": "sequenceAck",

+ "sequenceId": 1

+>

+> - The current set of access keys will be permanently deleted.

+> - Tokens signed with current set of access keys will become unavailable.

+> - Signature will **NOT** be attached in the upstream request header. Please visit _[how to validate access token](./howto-use-managed-identity.md#validate-access-tokens)_ to learn how to validate requests via Azure AD token.

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

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "resource_name": {

+ "defaultValue": "test-for-disable-aad",

+ "type": "String"

+ }

+ },

+ "variables": {},

+ "resources": [

+ {

+ "type": "Microsoft.SignalRService/WebPubSub",

+ "apiVersion": "2022-08-01-preview",

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

+ "location": "eastus",

+ "sku": {

+ "name": "Premium_P1",

+ "tier": "Premium",

+ "size": "P1",

+ "capacity": 1

+ },

+ "properties": {

+ "tls": {

+ "clientCertEnabled": false

+ },

+ "networkACLs": {

+ "defaultAction": "Deny",

+ "publicNetwork": {

+ "allow": [

+ "ServerConnection",

+ "ClientConnection",

+ "RESTAPI",

+ "Trace"

+ ]

+ },

+ "privateEndpoints": []

+ },

+ "publicNetworkAccess": "Enabled",

+ "disableLocalAuth": true,

+ "disableAadAuth": false

+ }

+ }

+ ]

+A client, be it a browser 💻, a mobile app 📱, or an IoT device 💡, uses a **Client Access URL** to connect and authenticate with your resource. This URL follows a pattern of `wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>`. This article shows you several ways to get the Client Access URL.

+ - Configure user ID

+ ```js

+ let token = await serviceClient.getClientAccessToken({ userId: "user1" });

+ ```

+ - Configure the lifetime of the token

+ ```js

+ let token = await serviceClient.getClientAccessToken({

+ expirationTimeInMinutes: 5,

+ });

+ ```

+ - Configure a role that can join group `group1` directly when it connects using this Client Access URL

+ ```js

+ let token = await serviceClient.getClientAccessToken({

+ roles: ["webpubsub.joinLeaveGroup.group1"],

+ });

+ ```

+ - Configure a role that the client can send messages to group `group1` directly when it connects using this Client Access URL

+ ```js

+ let token = await serviceClient.getClientAccessToken({

+ roles: ["webpubsub.sendToGroup.group1"],

+ });

+ ```

+ - Configure a group `group1` that the client joins once it connects using this Client Access URL

+ ```js

+ let token = await serviceClient.getClientAccessToken({

+ groups: ["group1"],

+ });

+ ```

+ - Configure user ID

+ ```csharp

+ var url = service.GetClientAccessUri(userId: "user1");

+ ```

+ - Configure the lifetime of the token

+ ```csharp

+ var url = service.GetClientAccessUri(expiresAfter: TimeSpan.FromMinutes(5));

+ ```

+ - Configure a role that can join group `group1` directly when it connects using this Client Access URL

+ ```csharp

+ var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1" });

+ ```

+ - Configure a role that the client can send messages to group `group1` directly when it connects using this Client Access URL

+ ```csharp

+ var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.sendToGroup.group1" });

+ ```

+ - Configure a group `group1` that the client joins once it connects using this Client Access URL

+ ```csharp

+ var url = service.GetClientAccessUri(groups: new string[] { "group1" });

+ ```

+ - Configure user ID

+ ```python

+ token = service.get_client_access_token(user_id="user1")

+ ```

+ - Configure the lifetime of the token

+ ```python

+ token = service.get_client_access_token(minutes_to_expire=5)

+ ```

+ - Configure a role that can join group `group1` directly when it connects using this Client Access URL

+ ```python

+ token = service.get_client_access_token(roles=["webpubsub.joinLeaveGroup.group1"])

+ ```

+ - Configure a role that the client can send messages to group `group1` directly when it connects using this Client Access URL

+ ```python

+ token = service.get_client_access_token(roles=["webpubsub.sendToGroup.group1"])

+ ```

+ - Configure a group `group1` that the client joins once it connects using this Client Access URL

+ ```python

+ token = service.get_client_access_token(groups=["group1"])

+ ```

+ - Configure user ID

+ ```java

+ GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();

+ option.setUserId(id);

+ WebPubSubClientAccessToken token = service.getClientAccessToken(option);

+ ```

+ - Configure the lifetime of the token

+ ```java

+ GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();

+ option.setExpiresAfter(Duration.ofDays(1));

+ WebPubSubClientAccessToken token = service.getClientAccessToken(option);

+ ```

+ - Configure a role that can join group `group1` directly when it connects using this Client Access URL

+ ```java

+ GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();

+ option.addRole("webpubsub.joinLeaveGroup.group1");

+ WebPubSubClientAccessToken token = service.getClientAccessToken(option);

+ ```

+ - Configure a role that the client can send messages to group `group1` directly when it connects using this Client Access URL

+ ```java

+ GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();

+ option.addRole("webpubsub.sendToGroup.group1");

+ WebPubSubClientAccessToken token = service.getClientAccessToken(option);

+ ```

+ - Configure a group `group1` that the client joins once it connects using this Client Access URL

+ ```java

+ GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();

+ option.setGroups(Arrays.asList("group1")),

+ WebPubSubClientAccessToken token = service.getClientAccessToken(option);

+ ```

+ 1. For the URI, enter `https://{Endpoint}/api/hubs/{hub}/:generateToken?api-version=2022-11-01`

+ 2. On the **Auth** tab, select **Bearer Token** and paste the Azure AD token fetched in the previous step

+ 3. Select **Send** and you see the Client Access Token in the response:

+ ```json

+ {

+ "token": "ABCDEFG.ABC.ABC"

+ }

+ ```

+This article describes the built-in policies for Azure Web PubSub Service.

+- You can assign policy definitions using the [Azure portal](../governance/policy/assign-policy-portal.md), [Azure CLI](../governance/policy/assign-policy-azurecli.md), a [Resource Manager template](../governance/policy/assign-policy-template.md), or the Azure Policy SDKs.

+- Policy assignments can be scoped to a resource group, a subscription, or an [Azure management group](../governance/management-groups/overview.md).

+- You can enable or disable [policy enforcement](../governance/policy/concepts/assignment-structure.md#enforcement-mode) at any time.

+- Web PubSub policy assignments apply to existing and new Web PubSub resources within the scope.

+1. Use the filters to display by **Scope**, **Type** or **Compliance state**. Use search list by name or

+ ID.

+ [  ](./media/howto-monitor-azure-policy/azure-policy-compliance.png#lightbox)

+1. Select a policy to review aggregate compliance details and events.

+- Learn more about Azure Policy [definitions](../governance/policy/concepts/definition-structure.md) and [effects](../governance/policy/concepts/effects.md)

+- Create a [custom policy definition](../governance/policy/tutorials/create-custom-policy-definition.md)

+- Learn more about [governance capabilities](../governance/index.yml) in Azure

+[terms-of-use]: https://azure.microsoft.com/support/legal/preview-supplemental-terms/

+This how-to guide provides an overview of Azure Web PubSub resource logs and some tips for using the logs to troubleshoot certain problems. Logs can be used for issue identification, connection tracking, message tracing, HTTP request tracing, and analysis.

+## What are resource logs?

+There are three types of resource logs: _Connectivity_, _Messaging_, and _HTTP requests_.

+>

+> - The real-time resource logs captured by live trace tool will be billed as messages (outbound traffic).

+> - The live trace tool does not currently support Azure Active Directory authentication. You must enable access keys to use live trace. Under **Settings**, select **Keys**, and then enable **Access Key**.

+> - The Azure Web PubSub service Free Tier instance has a daily limit of 20,000 messages (outbound traffic). Live trace can cause you to unexpectedly reach the daily limit.

+ :::image type="content" source="./media/howto-troubleshoot-diagnostic-logs/diagnostic-logs-with-live-trace-tool.png" alt-text="Screenshot of launching the live trace tool.":::

+- **Capture**: Begin to capture the real-time resource logs from Azure Web PubSub.

+- **Clear**: Clear the captured real-time resource logs.

+- **Log filter**: The live trace tool lets you filter the captured real-time resource logs with one specific key word. The common separators (for example, space, comma, semicolon, and so on) will be treated as part of the key word.

+- **Status**: The status shows whether the live trace tool is connected or disconnected with the specific instance.

+The real-time resource logs captured by live trace tool contain detailed information for troubleshooting.

+| Name | Description |

+| -- | -- |

+| Time | Log event time |

+| Log Level | Log event level, can be [Trace \| Debug \| Informational \| Warning \| Error] |

+| Event Name | Operation name of the event |

+| Message | Detailed message for the event |

+| Exception | The run-time exception of Azure Web PubSub service |

+| Hub | User-defined hub name |

+| Connection ID | Identity of the connection |

+| User ID | User identity |

+| IP | Client IP address |

+| Route Template | The route template of the API |

+| Http Method | The Http method (POST/GET/PUT/DELETE) |

+| URL | The uniform resource locator |

+| Trace ID | The unique identifier to the invocation |

+| Status Code | The Http response code |

+| Duration | The duration between receiving the request and processing the request |

+| Headers | The additional information passed by the client and the server with an HTTP request or response |

+ :::image type="content" source="./media/howto-troubleshoot-diagnostic-logs/diagnostic-settings-list.png" alt-text="Screenshot of viewing diagnostic settings and create a new one.":::

+ :::image type="content" source="./media/howto-troubleshoot-diagnostic-logs/diagnostic-settings-details.png" alt-text="Screenshot of configuring diagnostic setting detail":::

+ > [!NOTE]

+ > The storage account should be in the same region as Azure Web PubSub service.

+| Name | Description |

+| | - |

+| time | Log event time |

+| level | Log event level |

+| resourceId | Resource ID of your Azure SignalR Service |

+| location | Location of your Azure SignalR Service |

+| category | Category of the log event |

+| operationName | Operation name of the event |

+| callerIpAddress | IP address of your server or client |

+| properties | Detailed properties related to this log event. For more detail, see the properties table below |

+| Name | Description |

+| - | -- |

+| collection | Collection of the log event. Allowed values are: `Connection`, `Authorization` and `Throttling` |

+| connectionId | Identity of the connection |

+| userId | Identity of the user |

+| message | Detailed message of log event |

+| hub | User-defined Hub Name |

+| routeTemplate | The route template of the API |

+| httpMethod | The Http method (POST/GET/PUT/DELETE) |

+| url | The uniform resource locator |

+| traceId | The unique identifier to the invocation |

+| statusCode | The Http response code |

+| duration | The duration between the request is received and processed |

+| headers | The additional information passed by the client and the server with an HTTP request or response |

+1. On the **Diagnostic setting** page, under **Destination details**, select \*\*Send to Log Analytics workspace.

+ :::image type="content" alt-text="Screenshot showing the Log Analytics menu item." source="./media/howto-troubleshoot-diagnostic-logs/log-analytics-menu-item.png" lightbox="./media/howto-troubleshoot-diagnostic-logs/log-analytics-menu-item.png":::

+ :::image type="content" alt-text="Screenshot showing the Query log in Log Analytics." source="./media/howto-troubleshoot-diagnostic-logs/query-log-in-log-analytics.png" lightbox="./media/howto-troubleshoot-diagnostic-logs/query-log-in-log-analytics.png":::

+ :::image type="content" alt-text="Screenshot showing the sample query in Log Analytics." source="./media/howto-troubleshoot-diagnostic-logs/log-analytics-sample-query.png" lightbox="./media/howto-troubleshoot-diagnostic-logs/log-analytics-sample-query.png":::

+| Name | Description |

+| | - |

+| TimeGenerated | Log event time |

+| Collection | Collection of the log event. Allowed values are: `Connection`, `Authorization` and `Throttling` |

+| OperationName | Operation name of the event |

+| Location | Location of your Azure SignalR Service |

+| Level | Log event level |

+| CallerIpAddress | IP address of your server/client |

+| Message | Detailed message of log event |

+| UserId | Identity of the user |

+| ConnectionId | Identity of the connection |

+| ConnectionType | Type of the connection. Allowed values are: `Server` \| `Client`. `Server`: connection from server side; `Client`: connection from client side |

+| TransportType | Transport type of the connection. Allowed values are: `Websockets` \| `ServerSentEvents` \| `LongPolling` |

+| Reason | Description |

+| - | - |

+| Connection count reaches limit | Connection count reaches limit of your current price tier. Consider scale up service unit |

+| Service reloading, reconnect | Azure Web PubSub service is reloading. You need to implement your own reconnect mechanism or manually reconnect to Azure Web PubSub service |

+| Internal server transient error | Transient error occurs in Azure Web PubSub service, should be auto recovered |

+If you find that you can't establish client connections to Azure Web PubSub service, check your resource logs. If you see `Connection count reaches limit` in the resource log, you established too many connections to Azure Web PubSub service and reached the connection count limit. Consider scaling up your Azure Web PubSub service instance. If you see `Message count reaches limit` in the resource log and you're using the Free tier, it means you used up the quota of messages. If you want to send more messages, consider changing your Azure Web PubSub service instance to Standard tier. For more information, see [Azure Web PubSub service Pricing](https://azure.microsoft.com/pricing/details/web-pubsub/).

+> [!Important]

+> Azure Web PubSub Service can support only one managed identity. That means you can add either a system-assigned identity or a user-assigned identity.

+3. On the **System assigned** tab, switch **Status** to **On**. Select **Save**.

+ :::image type="content" source="media/howto-use-managed-identity/system-identity-portal.png" alt-text="Screenshot showing Add a system-assigned identity in the portal.":::

+ :::image type="content" source="media/howto-use-managed-identity/user-identity-portal.png" alt-text="Screenshot showing Add a user-assigned identity in the portal.":::

+ :::image type="content" source="media/howto-use-managed-identity/msi-settings.png" alt-text="Screenshot showing the msi-setting.":::

+ - Use default AAD application.

+ - Select from existing AAD applications. The application ID of the one you choose will be used.

+ - Specify an AAD application. The value should be [Resource ID of an Azure service](../active-directory/managed-identities-azure-resources/services-support-managed-identities.md#azure-services-that-support-azure-ad-authentication)

+ > [!NOTE]

+ > If you validate an access token by yourself in your service, you can choose any one of the resource formats. If you use Azure role-based access control (Azure RBAC) for a data plane, you must use the resource that the service provider requests.

+>

+> - Build a serverless real-time chat app

+> - Work with Web PubSub function trigger bindings and output bindings

+> - Deploy the function to Azure Function App

+> - Configure Azure Authentication

+> - Configure Web PubSub Event Handler to route events and messages to the application

+- A code editor, such as [Visual Studio Code](https://code.visualstudio.com/)

+- [Node.js](https://nodejs.org/en/download/), version 10.x.

+ > [!NOTE]

+ > For more information about the supported versions of Node.js, see [Azure Functions runtime versions documentation](../azure-functions/functions-versions.md#languages).

+- [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools#installing) (v4 or higher preferred) to run Azure Function apps locally and deploy to Azure.

+- The [Azure CLI](/cli/azure) to manage Azure resources.

+- A code editor, such as [Visual Studio Code](https://code.visualstudio.com/).

+- [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools#installing) (v4 or higher preferred) to run Azure Function apps locally and deploy to Azure.

+- The [Azure CLI](/cli/azure) to manage Azure resources.

+- A code editor, such as [Visual Studio Code](https://code.visualstudio.com/).

+- [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools#installing) (v4 or higher preferred) to run Azure Function apps locally and deploy to Azure.

+- The [Azure CLI](/cli/azure) to manage Azure resources.

+ # [JavaScript](#tab/javascript)

+ ```bash

+ func init --worker-runtime javascript

+ ```

+ # [C# in-process](#tab/csharp-in-process)

+ ```bash

+ func init --worker-runtime dotnet

+ ```

+ # [C# isolated process](#tab/csharp-isolated-process)

+ ```bash

+ func init --worker-runtime dotnet-isolated

+ ```

+ # [JavaScript](#tab/javascript)

+ Update `host.json`'s extensionBundle to version _3.3.0_ or later to get Web PubSub support.

+ ```json

+ {

+ "version": "2.0",

+ "extensionBundle": {

+ "id": "Microsoft.Azure.Functions.ExtensionBundle",

+ "version": "[3.3.*, 4.0.0)"

+ }

+ }

+ ```

+ # [C# in-process](#tab/csharp-in-process)

+ ```bash

+ dotnet add package Microsoft.Azure.WebJobs.Extensions.WebPubSub

+ ```

+ # [C# isolated process](#tab/csharp-isolated-process)

+ ```bash

+ dotnet add package Microsoft.Azure.Functions.Worker.Extensions.WebPubSub --prerelease

+ ```

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

+ }

+ ]

+ }

+ ```

+ ```js

+ var fs = require("fs");

+ var path = require("path");

+ module.exports = function (context, req) {

+ var index =

+ context.executionContext.functionDirectory + "/../https://docsupdatetracker.net/index.html";

+ context.log("https://docsupdatetracker.net/index.html path: " + index);

+ fs.readFile(index, "utf8", function (err, data) {

+ if (err) {

+ console.log(err);

+ context.done(err);

+ }

+ context.res = {

+ status: 200,

+ headers: {

+ "Content-Type": "text/html",

+ },

+ body: data,

+ };

+ context.done();

+ });

+ };

+ ```

+ ```csharp

+ [FunctionName("index")]

+ public static IActionResult Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req, ExecutionContext context, ILogger log)

+ {

+ var indexFile = Path.Combine(context.FunctionAppDirectory, "https://docsupdatetracker.net/index.html");

+ log.LogInformation($"https://docsupdatetracker.net/index.html path: {indexFile}.");

+ return new ContentResult

+ {

+ Content = File.ReadAllText(indexFile),

+ ContentType = "text/html",

+ };

+ }

+ ```

+ # [C# isolated process](#tab/csharp-isolated-process)

+ ```csharp

+ [Function("index")]

+ public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req, FunctionContext context)

+ {

+ var path = Path.Combine(context.FunctionDefinition.PathToAssembly, "../https://docsupdatetracker.net/index.html");

+ _logger.LogInformation($"https://docsupdatetracker.net/index.html path: {path}.");

+ var response = req.CreateResponse();

+ response.WriteString(File.ReadAllText(path));

+ response.Headers.Add("Content-Type", "text/html");

+ return response;

+ }

+ ```

+ ```bash

+ func new -n negotiate -t HttpTrigger

+ ```

+ > [!NOTE]

+ > In this sample, we use [AAD](../app-service/configure-authentication-user-identities.md) user identity header `x-ms-client-principal-name` to retrieve `userId`. And this won't work in a local function. You can make it empty or change to other ways to get or generate `userId` when playing in local. For example, let client type a user name and pass it in query like `?user={$username}` when call `negotiate` function to get service connection url. And in the `negotiate` function, set `userId` with value `{query.user}`.

+ # [JavaScript](#tab/javascript)

+ - Update `negotiate/function.json` and copy following json codes.

+ ```json

+ {

+ "bindings": [

+ {

+ "authLevel": "anonymous",

+ "type": "httpTrigger",

+ "direction": "in",

+ "name": "req"

+ },

+ {

+ "type": "http",

+ "direction": "out",

+ "name": "res"

+ },

+ {

+ "type": "webPubSubConnection",

+ "name": "connection",

+ "hub": "simplechat",

+ "userId": "{headers.x-ms-client-principal-name}",

+ "direction": "in"

+ }

+ ]

+ }

+ ```

+ - Update `negotiate/index.js` and copy following codes.

+ ```js

+ module.exports = function (context, req, connection) {

+ context.res = { body: connection };

+ context.done();

+ };

+ ```

+ # [C# in-process](#tab/csharp-in-process)

+ - Update `negotiate.cs` and replace `Run` function with following codes.

+ ```csharp

+ [FunctionName("negotiate")]

+ public static WebPubSubConnection Run(

+ [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,

+ [WebPubSubConnection(Hub = "simplechat", UserId = "{headers.x-ms-client-principal-name}")] WebPubSubConnection connection,

+ ILogger log)

+ {

+ log.LogInformation("Connecting...");

+ return connection;

+ }

+ ```

+ - Add `using` statements in header to resolve required dependencies.

+ ```csharp

+ using Microsoft.Azure.WebJobs.Extensions.WebPubSub;

+ ```

+ # [C# isolated process](#tab/csharp-isolated-process)

+ - Update `negotiate.cs` and replace `Run` function with following codes.

+ ```csharp

+ [Function("negotiate")]

+ public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,

+ [WebPubSubConnectionInput(Hub = "simplechat", UserId = "{headers.x-ms-client-principal-name}")] WebPubSubConnection connectionInfo)

+ {

+ var response = req.CreateResponse(HttpStatusCode.OK);

+ response.WriteAsJsonAsync(connectionInfo);

+ return response;

+ }

+ ```

+ ```json

+ {

+ "bindings": [

+ {

+ "type": "webPubSubTrigger",

+ "direction": "in",

+ "name": "data",

+ "hub": "simplechat",

+ "eventName": "message",

+ "eventType": "user"

+ },

+ {

+ "type": "webPubSub",

+ "name": "actions",

+ "hub": "simplechat",

+ "direction": "out"

+ }

+ ]

+ }

+ ```

+ ```js

+ module.exports = async function (context, data) {

+ context.bindings.actions = {

+ actionName: "sendToAll",

+ data: `[${context.bindingData.request.connectionContext.userId}] ${data}`,

+ dataType: context.bindingData.dataType,

+ };

+ // UserEventResponse directly return to caller

+ var response = {

+ data: "[SYSTEM] ack.",

+ dataType: "text",

+ };

+ return response;

+ };

+ ```

+ # [C# in-process](#tab/csharp-in-process)

+ - Update `message.cs` and replace `Run` function with following codes.

+ ```csharp

+ [FunctionName("message")]

+ public static async Task<UserEventResponse> Run(

+ [WebPubSubTrigger("simplechat", WebPubSubEventType.User, "message")] UserEventRequest request,

+ BinaryData data,

+ WebPubSubDataType dataType,

+ [WebPubSub(Hub = "simplechat")] IAsyncCollector<WebPubSubAction> actions)

+ {

+ await actions.AddAsync(WebPubSubAction.CreateSendToAllAction(

+ BinaryData.FromString($"[{request.ConnectionContext.UserId}] {data.ToString()}"),

+ dataType));

+ return new UserEventResponse

+ {

+ Data = BinaryData.FromString("[SYSTEM] ack"),

+ DataType = WebPubSubDataType.Text

+ };

+ }

+ ```

+ - Add `using` statements in header to resolve required dependencies.

+ ```csharp

+ using Microsoft.Azure.WebJobs.Extensions.WebPubSub;

+ using Microsoft.Azure.WebPubSub.Common;

+ ```

+ # [C# isolated process](#tab/csharp-isolated-process)

+ - Update `message.cs` and replace `Run` function with following codes.

+ ```csharp

+ [Function("message")]

+ [WebPubSubOutput(Hub = "simplechat")]

+ public SendToAllAction Run(

+ [WebPubSubTrigger("simplechat", WebPubSubEventType.User, "message")] UserEventRequest request)

+ {

+ return new SendToAllAction

+ {

+ Data = BinaryData.FromString($"[{request.ConnectionContext.UserId}] {request.Data.ToString()}"),

+ DataType = request.DataType

+ };

+ }

+ ```

+ ```html

+ <html>

+ <body>

+ <h1>Azure Web PubSub Serverless Chat App</h1>

+ <div id="login"></div>

+ <p></p>

+ <input id="message" placeholder="Type to chat..." />

+ <div id="messages"></div>

+ <script>

+ (async function () {

+ let authenticated = window.location.href.includes(

+ "?authenticated=true"

+ );

+ if (!authenticated) {

+ // auth

+ let login = document.querySelector("#login");

+ let link = document.createElement("a");

+ link.href = `${window.location.origin}/.auth/login/aad?post_login_redirect_url=/api/index?authenticated=true`;

+ link.text = "login";

+ login.appendChild(link);

+ } else {

+ // negotiate

+ let messages = document.querySelector("#messages");

+ let res = await fetch(`${window.location.origin}/api/negotiate`, {

+ credentials: "include",

+ });

+ let url = await res.json();

+ // connect

+ let ws = new WebSocket(url.url);

+ ws.onopen = () => console.log("connected");

+ ws.onmessage = (event) => {

+ let m = document.createElement("p");

+ m.innerText = event.data;

+ messages.appendChild(m);

+ };

+ let message = document.querySelector("#message");

+ message.addEventListener("keypress", (e) => {

+ if (e.charCode !== 13) return;

+ ws.send(message.value);

+ message.value = "";

+ });

+ }

+ })();

+ </script>

+ </body>

+ </html>

+ ```

+ # [JavaScript](#tab/javascript)

+ # [C# in-process](#tab/csharp-in-process)

+ Since C# project compiles files to a different output folder, you need to update your `*.csproj` to make the content page go with it.

+ ```xml

+ <ItemGroup>

+ <None Update="https://docsupdatetracker.net/index.html">

+ <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>

+ </None>

+ </ItemGroup>

+ ```

+ # [C# isolated process](#tab/csharp-isolated-process)

+ Since C# project compiles files to a different output folder, you need to update your `*.csproj` to make the content page go with it.

+ ```xml

+ <ItemGroup>

+ <None Update="https://docsupdatetracker.net/index.html">

+ <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>

+ </None>

+ </ItemGroup>

+ ```

+- A resource group, which is a logical container for related resources.

+- A storage account, which is used to maintain state and other information about your functions.

+- A function app, which provides the environment for executing your function code. A function app maps to your local function project and lets you group functions as a logical unit for easier management, deployment and sharing of resources.

+Use the following commands to create these items.

+ ```azurecli

+ az login

+ ```

+ ```azurecli

+ az group create -n WebPubSubFunction -l <REGION>

+ ```

+ ```azurecli

+ az storage account create -n <STORAGE_NAME> -l <REGION> -g WebPubSubFunction

+ ```

+ # [JavaScript](#tab/javascript)

+ ```azurecli

+ az functionapp create --resource-group WebPubSubFunction --consumption-plan-location <REGION> --runtime node --runtime-version 14 --functions-version 4 --name <FUNCIONAPP_NAME> --storage-account <STORAGE_NAME>

+ ```

+ > [!NOTE]

+ > Check [Azure Functions runtime versions documentation](../azure-functions/functions-versions.md#languages) to set `--runtime-version` parameter to supported value.

+ # [C# in-process](#tab/csharp-in-process)

+ ```azurecli

+ az functionapp create --resource-group WebPubSubFunction --consumption-plan-location <REGION> --runtime dotnet --functions-version 4 --name <FUNCIONAPP_NAME> --storage-account <STORAGE_NAME>

+ ```

+ # [C# isolated process](#tab/csharp-isolated-process)

+ ```azurecli

+ az functionapp create --resource-group WebPubSubFunction --consumption-plan-location <REGION> --runtime dotnet-isolated --functions-version 4 --name <FUNCIONAPP_NAME> --storage-account <STORAGE_NAME>

+ ```

+ After you have successfully created your function app in Azure, you're now ready to deploy your local functions project by using the [func azure functionapp publish](./../azure-functions/functions-run-local.md) command.

+ ```bash

+ func azure functionapp publish <FUNCIONAPP_NAME>

+ ```

+- Hub Name: `simplechat`

+- URL Template: **https://<FUNCTIONAPP_NAME>.azurewebsites.NET/runtime/webhooks/webpubsub?code=<APP_KEY>**

+- User Event Pattern: \*

+- System Events: -(No need to configure in this sample)

+- [Microsoft(Azure AD)](../app-service/configure-authentication-provider-aad.md)

+- [Facebook](../app-service/configure-authentication-provider-facebook.md)

+- [Google](../app-service/configure-authentication-provider-google.md)

+- [Twitter](../app-service/configure-authentication-provider-twitter.md)

+In this quickstart, you learned how to run a serverless chat application. Now, you could start to build your own application.

+> [!div class="nextstepaction"]

+> [!div class="nextstepaction"]

+> [!div class="nextstepaction"]

+> [Explore more Azure Web PubSub samples](https://github.com/Azure/azure-webpubsub/tree/main/samples)

+| Claim Type | Is Required | Description |

+| - | -- | - |

+| `aud` | true | Should be the **SAME** as your HTTP request url. For example, a broadcast request's audience looks like: `https://example.webpubsub.azure.com/api/hubs/myhub/:send?api-version=2022-11-01`. |

+| `exp` | true | Epoch time when this token will be expired. |

+ audience: request.url,

+ expiresIn: "1h",

+ algorithm: "HS256",

+});

+Like using `AccessKey`, a [JSON Web Token (JWT)](https://en.wikipedia.org/wiki/JSON_Web_Token) is also required to authenticate the HTTP request.

+**The difference is**, in this scenario, JWT Token is generated by Azure Active Directory.

+## APIs

+| Operation Group | Description |

+| -- | |

+| [Service Status](/rest/api/webpubsub/dataplane/health-api) | Provides operations to check the service status |

+| [Hub Operations](/rest/api/webpubsub/dataplane/web-pub-sub) | Provides operations to manage the connections and send messages to them. |

+- Send messages to hubs and groups.

+- [Azure Web PubSub client library Java SDK][source_code]

+- [Azure Web PubSub client library reference documentation][api]

+[//]: # "{x-version-update-start;com.azure:azure-messaging-webpubsub;current}"

+[//]: # "{x-version-update-end}"

+better performance compared to the default SSL implementation within the JDK. For more information, including how to reduce the dependency size, see [performance tuning][https://github.com/Azure/azure-sdk-for-java/wiki/Performance-Tuning].

+const serviceClient = new WebPubSubServiceClient(

+ "<ConnectionString>",

+ "<hubName>"

+);

+const {

+ WebPubSubServiceClient,

+ AzureKeyCredential,

+} = require("@azure/web-pubsub");

+const serviceClient = new WebPubSubServiceClient(

+ "<Endpoint>",

+ key,

+ "<hubName>"

+);

+const {

+ WebPubSubServiceClient,

+ AzureKeyCredential,

+} = require("@azure/web-pubsub");

+const serviceClient = new WebPubSubServiceClient(

+ "<Endpoint>",

+ key,

+ "<hubName>"

+);

+const serviceClient = new WebPubSubServiceClient(

+ "<ConnectionString>",

+ "<hubName>"

+);

+const serviceClient = new WebPubSubServiceClient(

+ "<ConnectionString>",

+ "<hubName>"

+);

+const serviceClient = new WebPubSubServiceClient(

+ "<ConnectionString>",

+ "<hubName>"

+);

+const serviceClient = new WebPubSubServiceClient(

+ "<ConnectionString>",

+ "<hubName>"

+);

+await serviceClient.sendToUser("user1", "Hi there!", {

+ contentType: "text/plain",

+});

+const serviceClient = new WebPubSubServiceClient(

+ "<ConnectionString>",

+ "<hubName>"

+);

+const serviceClient = new WebPubSubServiceClient(

+ "<ConnectionString>",

+ "<hubName>"

+);

+ console.log(

+ `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`

+ )

+ userId: "<userId>",

+ allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"],

+ console.log(

+ `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`

+ )

+ "https://<yourAllowedService2>.webpubsub.azure.com",

+ ],

+ console.log(

+ `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`

+ )

+ path: "/customPath1",

+ console.log(

+ `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`

+ )

+ },

+ console.log(

+ `Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`

+ )

+ ```python

+ >>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

+ >>> from azure.identity import DefaultAzureCredential

+ >>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=DefaultAzureCredential())

+ ```

+description: A list of code samples showing how to authenticate and connect to Web PubSub resource(s)

+The client can be a browser, a mobile app, an IoT device or even an EV charging point as long as it supports WebSocket. A client is limited to publishing and subscribing to messages.

+While the client's role is often limited, the application server's role goes beyond simply receiving and publishing messages. Before a client tries to connect with your Web PubSub resource, it goes to the application server for a Client Access Token first. The token is used to establish a persistent WebSocket connection with your Web PubSub resource.

+| Use case | Description |

+| [Using connection string](https://github.com/Azure/azure-webpubsub/blob/main/samples/csharp/chatapp/Startup.cs#L29) | Applies to application server only.

+| [Using Client Access Token](https://github.com/Azure/azure-webpubsub/blob/main/samples/csharp/chatapp/wwwroot/https://docsupdatetracker.net/index.html#L13) | Applies to client only. Client Access Token is generated on the application server.

+| [Anonymous connection](https://github.com/Azure/azure-webpubsub/blob/main/samples/csharp/clientWithCert/client/Program.cs#L15) | Anonymous connection allows clients to connect with Azure Web PubSub directly without going to an application server for a Client Access Token first. This is useful for clients that have limited networking capabilities, like an EV charging point.

+| Use case | Description |

+| Use case | Description |

+| Use case | Description |

+

+3. Locate in your server-side code where Socket.IO server is created and wrap it with `useAzureSocketIO()`:

+ const io = require("socket.io")();

+ useAzureSocketIO(io, {

+ });

+ >[!IMPORTANT]

+ > `useAzureSocketIO` is an asynchronous method and it does initialization steps to connect to Web PubSub. You can `await useAzureSocketIO(...)` or use `useAzureSocketIO(...).then(...)` to make sure your app server starts to serve requests after the initialization succeeds.

+4. If you use the following server APIs, add `async` before using them as they're asynchronous with Web PubSub for Socket.IO.

+* [Back up Windows Servers](backup-windows-with-mars-agent.md)

+### <a name="shareable-links-passwords"></a>Is Reset Password available for local users connecting via shareable link?

+No. Some organizations have company policies that require a password reset when a user logs into a local account for the first time. When using shareable links, the user can't change the password, even though a "Reset Password" button may appear.

+For more information, see [What is Azure Bastion](bastion-overview.md).

+- [Prepare for live traffic with Azure Communications Gateway](prepare-for-live-traffic.md)

+- [Create an Azure Communications Gateway resource](deploy.md)

+ a. Obtain the VCEK certificate by running the following command ΓÇô it obtains the cert from a well-known [Azure Instance Metadata Service](/azure/virtual-machines/instance-metadata-service) (IMDS) endpoint:

+ LOG_ANALYTICS_KEY=$(az monitor log-analytics workspace get-shared-keys \

+ LOG_ANALYTICS_KEY_ENC=$(printf %s $LOG_ANALYTICS_KEY | base64 -w0) # Needed for the next step

+ $LOG_ANALYTICS_KEY=$(az monitor log-analytics workspace get-shared-keys `

+ $LOG_ANALYTICS_KEY_ENC=[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($LOG_ANALYTICS_KEY))

+ --configuration-protected-settings "logProcessor.appLogs.logAnalyticsConfig.sharedKey=${LOG_ANALYTICS_KEY_ENC}"

+ --configuration-protected-settings "logProcessor.appLogs.logAnalyticsConfig.sharedKey=${LOG_ANALYTICS_KEY_ENC}"

+ --servers "$ACI_IP" \

+> If you are using subnet IP range /29 to have only 3 IP addresses. we recommend always to go one range above (never below). For example, use subnet IP range /28 so you can have at least 1 or more IP buffer per container group. By doing this, you can avoid containers in stuck, not able to start, restart or even not able to stop states.

+## Next steps

+See [Ratify on Azure: Allow only signed images to be deployed on AKS with Notation and Ratify](https://github.com/deislabs/ratify/blob/main/docs/quickstarts/ratify-on-azure.md).

+## Azure Key Vault Resource not found

+You see this error when the Azure Key Vault or specified Key are not found.

+## Residency requirements for analytical store

+Analytical store is resident by default as it is stored in either locally redundant or zone redundant storage. To learn more, see the [analytical store](analytical-store-introduction.md) article.

+To get started with intra-account offline container copy for Azure Cosmos DB for MongoDB accounts, register for the **Intra-account offline collection copy (MongoDB)** preview feature flag in [Preview Features](access-previews.md) in the Azure portal. Once the registration is complete, the preview is effective for all API for MongoDB accounts in the subscription.

+- **Query vulnerability information via subassessment API** - You can get scan results via [REST API](subassessment-rest-api.md).

+| Internet exposed VM has high severity vulnerabilities and has insecure secret that is used to authenticate to storage account | An Azure virtual machine is reachable from the internet, has high severity vulnerabilities and has secret that can authenticate to an Azure storage account |

+### GCP VM Instances

+| Attack path display name | Attack path description |

+|--|--|

+| Internet exposed VM instance has high severity vulnerabilities | GCP VM instance '[VMInstanceName]' is reachable from the internet and has high severity vulnerabilities [Remote Code Execution]. |

+| Internet exposed VM instance with high severity vulnerabilities has read permissions to a data store | GCP VM instance '[VMInstanceName]' is reachable from the internet, has high severity vulnerabilities[Remote Code Execution] and has read permissions to a data store. |

+| Internet exposed VM instance with high severity vulnerabilities has read permissions to a data store with sensitive data | GCP VM instance '[VMInstanceName]' is reachable from the internet, has high severity vulnerabilities allowing remote code execution on the machine and assigned with Service Account with read permission to GCP Storage bucket '[BucketName]' containing sensitive data. |

+| Internet exposed VM instance has high severity vulnerabilities and high permission to a project | GCP VM instance '[VMInstanceName]' is reachable from the internet, has high severity vulnerabilities[Remote Code Execution] and has '[Permissions]' permission to project '[ProjectName]'. |

+| Internet exposed VM instance with high severity vulnerabilities has read permissions to a Secret Manager | GCP VM instance '[VMInstanceName]' is reachable from the internet, has high severity vulnerabilities[Remote Code Execution] and has read permissions through IAM policy to GCP Secret Manager's secret '[SecretName]'. |

+| Internet exposed VM instance has high severity vulnerabilities and a hosted database installed | GCP VM instance '[VMInstanceName]' with a hosted [DatabaseType] database is reachable from the internet and has high severity vulnerabilities. |

+| Internet exposed VM with high severity vulnerabilities has plaintext SSH private key | GCP VM instance '[MachineName]' is reachable from the internet, has high severity vulnerabilities [Remote Code Execution] and has plaintext SSH private key [SSHPrivateKey]. |

+| VM instance with high severity vulnerabilities has read permissions to a data store | GCP VM instance '[VMInstanceName]' has high severity vulnerabilities[Remote Code Execution] and has read permissions to a data store. |

+| VM instance with high severity vulnerabilities has read permissions to a data store with sensitive data | GCP VM instance '[VMInstanceName]' has high severity vulnerabilities [Remote Code Execution] and has read permissions to GCP Storage bucket '[BucketName]' containing sensitive data. |

+| VM instance has high severity vulnerabilities and high permission to a project | GCP VM instance '[VMInstanceName]' has high severity vulnerabilities[Remote Code Execution] and has '[Permissions]' permission to project '[ProjectName]'.|

+| VM instance with high severity vulnerabilities has read permissions to a Secret Manager | GCP VM instance '[VMInstanceName]' has high severity vulnerabilities[Remote Code Execution] and has read permissions through IAM policy to GCP Secret Manager's secret '[SecretName]'. |

+| VM instance with high severity vulnerabilities has plaintext SSH private key | GCP VM instance to align with all other attack paths. Virtual machine '[MachineName]' has high severity vulnerabilities [Remote Code Execution] and has plaintext SSH private key [SSHPrivateKey]. |

+### GCP Data

+| Attack path display name | Attack path description |

+|--|--|

+| GCP Storage Bucket with sensitive data is publicly accessible | GCP Storage Bucket [BucketName] with sensitive data allows public read access without authorization required. |

+| Exposed to the internet | Indicates that a resource is exposed to the internet. Supports port filtering. [Learn more](concept-data-security-posture-prepare.md#exposed-to-the-internetallows-public-access) | Azure virtual machine, AWS EC2, Azure storage account, Azure SQL server, Azure Cosmos DB, AWS S3, Kubernetes pod, Azure SQL Managed Instance, Azure MySQL Single Server, Azure MySQL Flexible Server, Azure PostgreSQL Single Server, Azure PostgreSQL Flexible Server, Azure MariaDB Single Server, Synapse Workspace, RDS Instance, GCP VM instance, GCP SQL admin instance |

+| Contains sensitive data <br/> <br/> Prerequisite: [Enable data-aware security for storage accounts in Defender CSPM](data-security-posture-enable.md), or [leverage Microsoft Purview Data Catalog to protect sensitive data](information-protection.md). | Indicates that a resource contains sensitive data. | Azure Storage Account, Azure Storage Account Container, AWS S3 bucket, Azure SQL Server, Azure SQL Database, Azure Data Lake Storage Gen2, Azure Database for PostgreSQL, Azure Database for MySQL, Azure Synapse Analytics, Azure Cosmos DB accounts, GCP cloud storage bucket |

+| Has tags | Lists the resource tags of the cloud resource | All Azure, AWS, and GCP resources |

+| Allows public access | Indicates that a public read access is allowed to the resource with no authorization required. [Learn more](concept-data-security-posture-prepare.md#exposed-to-the-internetallows-public-access) | Azure storage account, AWS S3 bucket, GitHub repository, GCP cloud storage bucket |

+| Has high severity vulnerabilities | Indicates that a resource has high severity vulnerabilities | Azure VM, AWS EC2, Container image, GCP VM instance |

+| Vulnerable to remote code execution | Indicates that a resource has vulnerabilities allowing remote code execution | Azure VM, AWS EC2, Container image, GCP VM instance |

+| Contains | Indicates that the source entity contains the target entity | Azure subscription, Azure resource group, AWS account, Kubernetes namespace, Kubernetes pod, Kubernetes cluster, GitHub owner, Azure DevOps project, Azure DevOps organization, Azure SQL server, GCP project, GCP Folder, GCP Organization | All Azure, AWS, and GCP resources, All Kubernetes entities, All DevOps entities, Azure SQL database |

+| Routes traffic to | Indicates that the source entity can route network traffic to the target entity | Public IP, Load Balancer, VNET, Subnet, VPC, Internet Gateway, Kubernetes service, Kubernetes pod| Azure VM, Azure VMSS, AWS EC2, Subnet, Load Balancer, Internet gateway, Kubernetes pod, Kubernetes service, GCP VM instance, GCP instance group |

+| Clouds: | :::image type="icon" source="./media/icons/yes-icon.png"::: Azure Commercial clouds<br> :::image type="icon" source="./media/icons/no-icon.png"::: Azure Government<br>:::image type="icon" source="./media/icons/no-icon.png"::: Microsoft Azure operated by 21Vianet<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Connected AWS accounts<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Connected GCP projects |

+| Instance and disk types: | **Azure**<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Standard VMs<br>:::image type="icon" source="./media/icons/no-icon.png"::: Unmanaged disks<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Virtual machine scale set - Flex<br>:::image type="icon" source="./media/icons/no-icon.png"::: Virtual machine scale set - Uniform<br><br>**AWS**<br>:::image type="icon" source="./media/icons/yes-icon.png"::: EC2<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Auto Scale instances<br>:::image type="icon" source="./media/icons/no-icon.png"::: Instances with a ProductCode (Paid AMIs)<br><br>**GCP**<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Compute instances<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Instance groups (managed and unmanaged) |

+| Encryption: | **Azure**<br>:::image type="icon" source="./medi) with platform-managed keys (PMK)<br>:::image type="icon" source="./media/icons/no-icon.png"::: Encrypted ΓÇô other scenarios using platform-managed keys (PMK)<br>:::image type="icon" source="./media/icons/no-icon.png"::: Encrypted ΓÇô customer-managed keys (CMK)<br><br>**AWS**<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Unencrypted<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Encrypted - PMK<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Encrypted - CMK<br><br>**GCP**<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Google-managed encryption key<br>:::image type="icon" source="./media/icons/yes-icon.png"::: Customer-managed encryption key (CMEK)<br>:::image type="icon" source="./media/icons/no-icon.png"::: Customer-supplied encryption key (CSEK) |

+> - This price includes free vulnerability assessments for 20 unique images per charged resource, whereby the count will be based on the previous month's consumption. Every subsequent scan will be charged at $0.29 per image digest. The majority of customers are not expected to incur any additional image scan charges. For subscriptions that are both under the Defender CSPM and Defender for Containers plans, free vulnerability assessment will be calculated based on free image scans provided via the Defender for Containers plan, as specified [in the Microsoft Defender for Cloud pricing page](https://azure.microsoft.com/pricing/details/defender-for-cloud/).

+| Microsoft Cloud Security Benchmark | :::image type="icon" source="./media/icons/yes-icon.png"::: | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS, GCP |

+| [Cloud security explorer](how-to-manage-cloud-security-explorer.md) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS, GCP |

+| [Attack path analysis](how-to-manage-attack-path.md) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS, GCP |

+| [Agentless scanning for machines](concept-agentless-data-collection.md) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS, GCP |

+| [Data aware security posture](concept-data-security-posture.md) | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS, GCP |

+| EASM insights in network exposure | - | :::image type="icon" source="./media/icons/yes-icon.png"::: | Azure, AWS, GCP |

+|What GCP data resources can I discover? | GCP storage buckets<br/> Standard Class<br/> Geo: region, dual region, multi region |

+|What permissions do I need for discovery? | Storage account: Subscription Owner<br/> **or**<br/> Microsoft.Authorization/roleAssignments/* (read, write, delete) **and** Microsoft.Security/pricings/* (read, write, delete) **and** Microsoft.Security/pricings/SecurityOperators (read, write)<br/><br/> Amazon S3 buckets: AWS account permission to run Cloud Formation (to create a role).<br/><br/>GCP storage buckets: Google account permission to run script (to create a role).|

+|What GCP regions are supported? | europe-west1, us-east1, us-west1, us-central1, us-east4, asia-south1, northamerica-northeast1|

+| What permissions do I need to perform onboarding? | You need one of these Azure Active directory roles: Security Admin, Contributor, Owner on the subscription level (where the GCP project/s reside in). For consuming the security findings: Security Reader, Security Admin,Reader, Contributor, Owner on the subscription level (where the GCP project/s reside). |

+- A new AWS S3 bucket or GCP storage bucket that's added to an already discovered AWS account or Google account is discovered within 48 hours or less.

+### Discovering GCP storage buckets

+In order to protect GCP resources in Defender for Cloud, you can set up a Google connector using a script template to onboard the GCP account.

+- To discover GCP storage buckets, Defender for Cloud updates the script template.

+- The script template creates a new role in the Google account to allow permission for the Defender for Cloud scanner to access data in the GCP storage buckets.

+- To connect Google accounts, you need Administrator permissions on the account.

+**State** | **Azure storage accounts** | **AWS S3 Buckets** | **GCP Storage Buckets** |

+ | | |

+**Exposed to the internet** | An Azure storage account is considered exposed to the internet if either of these settings enabled:<br/><br/> Storage_account_name > **Networking** > **Public network access** > **Enabled from all networks**<br/><br/> or<br/><br/> Storage_account_name > **Networking** > **Public network access** > **Enable from selected virtual networks and IP addresses**. | An AWS S3 bucket is considered exposed to the internet if the AWS account/AWS S3 bucket policies don't have a condition set for IP addresses. | All GCP storage buckets are exposed to the internet by default. |

+**Allows public access** | An Azure storage account container is considered as allowing public access if these settings are enabled on the storage account:<br/><br/> Storage_account_name > **Configuration** > **Allow blob public access** > **Enabled**.<br/><br/>and **either** of these settings:<br/><br/> Storage_account_name > **Containers** > container_name > **Public access level** set to **Blob (anonymous read access for blobs only)**<br/><br/> Or, storage_account_name > **Containers** > container_name > **Public access level** set to **Container (anonymous read access for containers and blobs)**. | An AWS S3 bucket is considered to allow public access if both the AWS account and the AWS S3 bucket have **Block all public access** set to **Off**, and **either** of these settings is set:<br/><br/> In the policy, **RestrictPublicBuckets** isn't enabled, and the **Principal** setting is set to * and **Effect** is set to **Allow**.<br/><br/> Or, in the access control list, **IgnorePublicAcl** isn't enabled, and permission is allowed for **Everyone**, or for **Authenticated users**. | A GCP storage bucket is considered to allow public access if: it has an IAM (Identity and Access Management) role that meets these criteria: <br/><br/> The role is granted to the principal **allUsers** or **allAuthenticatedUsers**. <br/><br/>The role has at least one storage permission that *isn't* **storage.buckets.create** or **storage.buckets.list**. Public access in GCP is called ΓÇ£Public to internetΓÇ£.

+## Enable agentless scanning in GCP

+1. From Defender for Cloud's menu, select **Environment settings**.

+1. Select the relevant project or organization.

+1. For either the Defender Cloud Security Posture Management (CSPM) or Defender for Servers P2 plan, selectΓÇ» **Settings**.

+ :::image type="content" source="media/enable-agentless-scanning-vms/gcp-select-plan.png" alt-text="Screenshot that shows where to select the plan for GCP projects." lightbox="media/enable-agentless-scanning-vms/gcp-select-plan.png":::

+1. In the settings pane, turn on ΓÇ»**Agentless scanning**.

+ :::image type="content" source="media/enable-agentless-scanning-vms/gcp-select-agentless.png" alt-text="Screenshot that shows where to select agentless scanning." lightbox="media/enable-agentless-scanning-vms/gcp-select-agentless.png":::

+1. SelectΓÇ»**Save and Next: Configure Access**.

+1. Copy the onboarding script.

+1. Run the onboarding script in the GCP organization/project scope (GCP portal or gcloud CLI).

+1. Select ΓÇ»**Next: Review and generate**.

+1. Select ΓÇ»**Update**.

+| Release state | GA (General Availability) for Azure, AWS <Br> Preview for GCP |

+| Clouds: | :::image type="icon" source="./media/icons/yes-icon.png"::: Commercial clouds (Azure, AWS, GCP) <br>:::image type="icon" source="./media/icons/no-icon.png"::: National (Azure Government, Azure China 21Vianet) |

+With the cloud security explorer, you can query all of your security issues and environment context such as assets inventory, exposure to internet, permissions, and lateral movement between resources and across multiple clouds (Azure AWS, and GCP).

+| Clouds: | :::image type="icon" source="./media/icons/yes-icon.png"::: Commercial clouds (Azure, AWS) <br>:::image type="icon" source="./media/icons/yes-icon.png"::: Commercial clouds - GCP (Preview) <br>:::image type="icon" source="./media/icons/no-icon.png"::: National (Azure Government, Microsoft Azure operated by 21Vianet) |

+| August 15 | [Preview release of GCP support in Defender CSPM](#preview-release-of-gcp-support-in-defender-cspm)|

+### Preview release of GCP support in Defender CSPM