+ * Create a Conditional Access policy that includes either All guest and external users and then [implement a policy to block access](../conditional-access/concept-conditional-access-cloud-apps.md).

+- Learn about [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md) and [Conditional Access](../conditional-access/overview.md) to help manage your organization's application and resource access.

+ * Block access to the Azure portal. You can make rare necessary exceptions. Create a Conditional Access policy that includes all guests and external users. Then [implement a policy to block access](../conditional-access/concept-conditional-access-cloud-apps.md).

+- [Identity Protection](../identity-protection/overview-identity-protection.md) - Adaptive protection through user and session risk profiling, plus [Leaked credential detection](../identity-protection/concept-identity-protection-risks.md)

+Users access the Microsoft MyApps portal to easily find their BIG-IP published services and for managing their account properties.

+A BIG-IPΓÇÖs role is critical to any business, so deployed BIG-IP instances can be monitored to ensure published services are highly available, both at an SHA level and operationally too.

+Integrating an F5 BIG-IP with Azure AD for SHA has the following pre-requisites:

+ - F5 BIG-IP® Best bundle

+ - F5 BIG-IP Access Policy ManagerΓäó standalone license

+ - F5 BIG-IP Access Policy Manager™ (APM) add-on license on an existing BIG-IP F5 BIG-IP® Local Traffic Manager™ (LTM)

+ - A 90-day BIG-IP Access Policy ManagerΓäó (APM) [trial license](https://www.f5.com/trial/big-ip-trial.php)

+The following tutorials provide detailed guidance on implementing some of the more common patterns for BIG-IP and Azure AD secure hybrid access.

+Version 16.x of the Guided Configuration now offers an Easy Button feature. With **Easy Button**, admins no longer go back and forth between Azure AD and a BIG-IP to enable services for SHA. The end-to-end deployment and policy management is handled directly between the APMΓÇÖs Guided Configuration wizard and Microsoft Graph. This rich integration between BIG-IP APM and Azure AD ensures applications can quickly, easily support identity federation, SSO, and Azure AD Conditional Access, without management overhead of having to do so on a per app basis.

+- [BIG-IP Easy Button for SSO to Oracle EBS (Enterprise Business Suite)](f5-big-ip-oracle-enterprise-business-suite-easy-button.md)

+- [BIG-IP Easy Button for SSO to Oracle JD Edwards](f5-big-ip-oracle-jde-easy-button.md)

+Consider running an SHA Proof of concept (POC) using your existing BIG-IP infrastructure, or by [Deploying a BIG-IP Virtual Edition (VE) VM into Azure](f5-bigip-deployment-guide.md) takes approximately 30 minutes, at which point you'll have:

+- A fully secured platform to model a SHA proof of concept

+- A pre-production instance for testing new BIG-IP system updates and hotfixes

+At the same time, you should identify one or two applications that can be published via the BIG-IP and protected with SHA.

+The below interactive guide walks through the high-level procedure for implementing SHA using a non Easy Button template, and seeing the end-user experience.

+ Title: Configure F5 BIG-IP Easy Button for SSO to Oracle JDE

+description: Learn to implement SHA with header-based SSO to Oracle JD Edwards using F5ΓÇÖs BIG-IP Easy Button guided configuration

+# Tutorial: Configure F5ΓÇÖs BIG-IP Easy Button for SSO to Oracle JDE

+In this article, you'll learn to implement Secure Hybrid Access (SHA) with header-based single sign-on (SSO) to Oracle JD Edwards (JDE) using F5ΓÇÖs BIG-IP Easy Button guided configuration.

+Enabling BIG-IP published services for Azure Active Directory (Azure AD) SSO provides many benefits, including:

+* [Improved Zero Trust governance](https://www.microsoft.com/security/blog/2020/04/02/announcing-microsoft-zero-trust-assessment-tool/) through Azure AD pre-authentication and [Conditional Access](/conditional-access/overview)

+* Full SSO between Azure AD and BIG-IP published services

+* Manage Identities and access from a single control plane, the [Azure portal](https://portal.azure.com/)

+To learn about all the benefits, see the article on [F5 BIG-IP and Azure AD integration](http://f5-aad-integration.md/) and [what is application access and single sign-on with Azure AD](/azure/active-directory/active-directory-appssoaccess-whatis).

+## Scenario description

+For this scenario, use an **Oracle JDE application using HTTP authorization headers** to manage access to protected content.

+Being legacy, the application lacks modern protocols to support a direct integration with Azure AD. The application can be modernized, but it is costly, requires careful planning, and introduces risk of potential downtime. Instead, an F5 BIG-IP Application Delivery Controller is used to bridge the gap between the legacy application and the modern ID control plane, through protocol transitioning.

+Having a BIG-IP in front of the app enables us to overlay the service with Azure AD pre-authentication and header-based SSO, significantly improving the overall security posture of the application.

+## Scenario architecture

+The secure hybrid access solution for this scenario is made up of several components:

+**Oracle JDE Application:** BIG-IP published service to be protected by Azure AD SHA.

+**Azure AD:** Security Assertion Markup Language (SAML) Identity Provider (IdP) responsible for verification of user credentials, Conditional Access (CA), and SSO to the BIG-IP.

+**BIG-IP APM:** Reverse proxy and SAML service provider (SP) to the application, delegating authentication to the SAML IdP before performing header-based SSO to the Oracle service.

+SHA for this scenario supports both SP and IdP initiated flows. The following image illustrates the SP initiated flow.

+

+| Steps| Description |

+| -- |-|

+| 1| User connects to application endpoint (BIG-IP) |

+| 2| BIG-IP APM access policy redirects user to Azure AD (SAML IdP) |

+| 3| Azure AD pre-authenticates user and applies any enforced Conditional Access policies |

+| 4| User is redirected back to BIG-IP (SAML SP) and SSO is performed using issued SAML token |

+| 5| BIG-IP injects Azure AD attributes as headers in request to the application |

+| 6| Application authorizes request and returns payload |

+## Prerequisites

+Prior BIG-IP experience isnΓÇÖt necessary, but you need:

+* An Azure AD free subscription or above

+* An existing BIG-IP or [deploy a BIG-IP Virtual Edition (VE) in Azure](./f5-bigip-deployment-guide.md)

+* Any of the following F5 BIG-IP license SKUs

+ * F5 BIG-IP® Best bundle

+ * F5 BIG-IP Access Policy ManagerΓäó (APM) standalone license

+ * F5 BIG-IP Access Policy Manager™ (APM) add-on license on an existing BIG-IP F5 BIG-IP® Local Traffic Manager™ (LTM)

+ * 90-day BIG-IP full feature [trial license](https://www.f5.com/trial/big-ip-trial.php).

+* User identities [synchronized](../hybrid/how-to-connect-sync-whatis.md) from an on-premises directory to Azure AD or created directly within Azure AD and flowed back to your on-premises directory

+* An account with Azure AD application admin [permissions](/azure/active-directory/users-groups-roles/directory-assign-admin-roles#application-administrator)

+* [SSL certificate](./f5-bigip-deployment-guide.md#ssl-profile) for publishing services over HTTPS

+* An existing Oracle JDE environment

+## BIG-IP configuration methods

+There are many methods to configure BIG-IP for this scenario, including two template-based options and an advanced configuration. This tutorial covers the latest Guided Configuration 16.1 offering an Easy button template. With the Easy Button, admins no longer go back and forth between Azure AD and a BIG-IP to enable services for SHA. The deployment and policy management is handled directly between the APMΓÇÖs Guided Configuration wizard and Microsoft Graph. This rich integration between BIG-IP APM and Azure AD ensures that applications can quickly, easily support identity federation, SSO, and Azure AD Conditional Access, reducing administrative overhead.

+>[!NOTE]

+> All example strings or values referenced throughout this guide should be replaced with those for your actual environment.

+## Register Easy Button

+Before a client or service can access Microsoft Graph, it must be trusted by the [Microsoft identity platform](../develop/quickstart-register-app.md).

+A BIG-IP must also be registered as a client in Azure AD, before it is allowed to establish a trust in between each SAML SP instance of a BIG-IP published application, and Azure AD as the SAML IdP.

+1. Sign in to the [Azure AD portal](https://portal.azure.com/) with Application Administrative rights

+2. From the left navigation pane, select the **Azure Active Directory** service

+3. Under Manage, select **App registrations > New registration**

+4. Enter a display name for your application. For example, F5 BIG-IP Easy Button

+5. Specify who can use the application > **Accounts in this organizational directory only**

+6. Select **Register** to complete the initial app registration

+7. Navigate to **API permissions** and authorize the following Microsoft Graph permissions:

+ * Application.Read.All

+ * Application.ReadWrite.All

+ * Application.ReadWrite.OwnedBy

+ * Directory.Read.All

+ * Group.Read.All

+ * IdentityRiskyUser.Read.All

+ * Policy.Read.All

+ * Policy.ReadWrite.ApplicationConfiguration

+ * Policy.ReadWrite.ConditionalAccess

+ * User.Read.All

+8. Grant admin consent for your organization

+9. Go to **Certificates & Secrets**, generate a new **Client secret** and note it down

+10. Go to **Overview**, note the **Client ID** and **Tenant ID**

+## Configure Easy Button

+Initiate the **Easy Button** configuration to set up a SAML Service Provider (SP) and Azure AD as an Identity Provider (IdP) for your application.

+1. Navigate to **Access > Guided Configuration > Microsoft Integration** and select **Azure AD Application**.

+ 

+2. Review the list of configuration steps and select **Next**

+ 

+3. Follow the sequence of steps required to publish your application.

+ 

+### Configuration Properties

+The **Configuration Properties** tab creates up a new application config and SSO object. Consider **Azure Service Account Details** section to be the client application you registered in your Azure AD tenant earlier. These settings allow a BIG-IP to programmatically register a SAML application directly in your tenant, along with the properties you would normally configure manually. Easy Button does this for every BIG-IP APM service being enabled for SHA.

+Some of these are global settings so can be re-used for publishing more applications, further reducing deployment time and effort.

+1. Provide a unique **Configuration Name** that enables an admin to easily distinguish between Easy Button configurations

+2. Enable **Single Sign-On (SSO) & HTTP Headers**

+3. Enter the **Tenant Id, Client ID**, and **Client Secret** you noted down from your registered application

+4. Before you select **Next**, confirm that BIG-IP can successfully connect to your tenant.

+ 

+

+### Service Provider

+The **Service Provider** settings define the SAML SP properties for the APM instance representing the application protected through SHA.

+1. Enter **Host**. This is the public FQDN of the application being secured. You need a corresponding DNS record for clients to resolve this address, but using a localhost record is fine during testing

+2. Enter **Entity ID**. This is the identifier Azure AD will use to identify the SAML SP requesting a token

+ Screenshot for Service Provider settings](./media/f5-big-ip-easy-button-oracle-jde/service-provider-settings.png)

+ Next, under optional **Security Settings** specify whether Azure AD should encrypt issued SAML assertions. Encrypting assertions between Azure AD and the BIG-IP APM provides assurance that the content tokens canΓÇÖt be intercepted, and personal or corporate data be compromised.

+3. From the **Assertion Decryption Private Key** list, select **Create New**

+ 

+4. Select **OK**. This opens the **Import SSL Certificate and Keys** dialog in a new tab

+5. Select **PKCS 12 (IIS)** to import your certificate and private key. Once provisioned close the browser tab to return to the main tab.

+ 

+6. Check **Enable Encrypted Assertion**

+7. If you have enabled encryption, select your certificate from the **Assertion Decryption Private Key** list. This is the private key for the certificate that BIG-IP APM uses to decrypt Azure AD assertions

+8. If you have enabled encryption, select your certificate from the **Assertion Decryption Certificate** list. This is the certificate that BIG-IP uploads to Azure AD for encrypting the issued SAML assertions.

+ 

+### Azure Active Directory

+This section defines all properties that you would normally use to manually configure a new BIG-IP SAML application within your Azure AD tenant. The Easy Button wizard provides a set of pre-defined application templates for Oracle PeopleSoft, Oracle E-business Suite, Oracle JD Edwards, SAP ERP as well as generic SHA template for any other apps. In this example, select **JD Edwards Protected by F5 BIG-IP > Add**. This adds the template for the Oracle JD Edwards.

+

+#### Azure Configuration

+1. Enter **Display Name** of app that the BIG-IP creates in your Azure AD tenant, and the icon that the users see on MyApps portal

+2. In the **Sign On URL (optional)** enter the public FQDN of the JDE application being secured.

+ Screenshot for Azure configuration add display info](./media/f5-big-ip-easy-button-oracle-jde/azure-configuration-add-display-info.png)

+3. Select the refresh icon next to the **Signing Key** and **Signing Certificate** to locate the certificate you imported earlier

+4. Enter the certificateΓÇÖs password in **Signing Key Passphrase**

+5. Enable **Signing Option** (optional). This ensures that BIG-IP only accepts tokens and claims that are signed by Azure AD

+ 

+6. **User and User Groups** are used to authorize access to the application. They are dynamically added from the tenant. **Add** a user or group that you can use later for testing, otherwise all access will be denied

+ 

+#### User Attributes & Claims

+When a user successfully authenticates, Azure AD issues a SAML token with a default set of claims and attributes uniquely identifying the user. The **User Attributes & Claims** tab shows the default claims to issue for the new application. It also lets you configure more claims.

+

+You can include additional Azure AD attributes if necessary, but the Oracle JDE scenario only requires the default attributes.

+#### Additional User Attributes

+The **Additional User Attributes** tab can support a variety of distributed systems requiring attributes stored in other directories for session augmentation. Attributes fetched from an LDAP source can then be injected as additional SSO headers to further control access based on roles, Partner IDs, etc.

+#### Conditional Access Policy

+Conditional Access policies are enforced post Azure AD pre-authentication, to control access based on device, application, location, and risk signals.

+The **Available Policies** view, by default, will list all Conditional Access policies that do not include user-based actions.

+The **Selected Policies** view, by default, displays all policies targeting All cloud apps. These policies cannot be deselected or moved to the Available Policies list as they are enforced at a tenant level.

+To select a policy to be applied to the application being published:

+1. Select the desired policy in the **Available Policies** list

+2. Select the right arrow and move it to the **Selected Policies** list

+ The selected policies should either have an **Include** or **Exclude** option checked. If both options are checked, the policy is not enforced.

+ 

+> [!NOTE]

+> The policy list is enumerated only once when first switching to this tab. A refresh button is available to manually force the wizard to query your tenant, but this button is displayed only when the application has been deployed.

+### Virtual Server Properties

+A virtual server is a BIG-IP data plane object represented by a virtual IP address listening for client requests to the application. Any received traffic is processed and evaluated against the APM profile associated with the virtual server, before being directed according to the policy results and settings.

+1. Enter **Destination Address**. This is any available IPv4/IPv6 address that the BIG-IP can use to receive client traffic. A corresponding record should also exist in DNS, enabling clients to resolve the external URL of your BIG-IP published application to this IP.

+2. Enter **Service Port** as *443* for HTTPS

+3. Check **Enable Redirect Port** and then enter **Redirect Port**. It redirects incoming HTTP client traffic to HTTPS

+4. Select **Client SSL Profile** to enable the virtual server for HTTPS so that client connections are encrypted over TLS. Select the client SSL profile you created as part of the prerequisites or leave the default if testing

+ 

+### Pool Properties

+The **Application Pool tab** details the services behind a BIG-IP, represented as a pool containing one or more application servers.

+1. Choose from **Select a Pool**. Create a new pool or select an existing one

+2. Choose the **Load Balancing Method** as *Round Robin*

+3. Update the **Pool Servers**. Select an existing node or specify an IP and port for the servers hosting the Oracle JDE application.

+ 

+#### Single Sign-On & HTTP Headers

+The **Easy Button wizard** supports Kerberos, OAuth Bearer, and HTTP authorization headers for SSO to published applications. As the Oracle JDE application expects headers, enable **HTTP Headers** and enter the following properties.

+* **Header Operation:** replace

+* **Header Name:** JDE_SSO_UID

+* **Header Value:** %{session.sso.token.last.username}

+ 

+>[!NOTE]

+>APM session variables defined within curly brackets are CASE sensitive. If you enter OrclGUID when the Azure AD attribute name is being defined as orclguid, it will cause an attribute mapping failure.

+### Session Management

+The BIG-IPs session management settings are used to define the conditions under which user sessions are terminated or allowed to continue, limits for users and IP addresses, and corresponding user info. Consult [F5 documentation](https://support.f5.com/csp/article/K18390492) for details on these settings.

+What isnΓÇÖt covered however is Single Log-Out (SLO) functionality, which ensures all sessions between the IdP, the BIG-IP, and the user agent are terminated as users sign off. When the Easy Button deploys a SAML application to your Azure AD tenant, it also populates the Logout Url with the APMΓÇÖs SLO endpoint. That way IdP initiated sign-outs from the Azure AD MyApps portal also terminate the session between the BIG-IP and a client.

+During deployment, the SAML federation metadata for the published application is imported from your tenant, providing the APM the SAML logout endpoint for Azure AD. This helps SP initiated sign outs terminate the session between a client and Azure AD.

+## Summary

+This last step provides a breakdown of your configurations. Select **Deploy** to commit all settings and verify that the application now exists in your tenants list of Enterprise applications.

+## Next steps

+From a browser, connect to the **Oracle JDE applicationΓÇÖs external URL** or select the applicationΓÇÖs icon in the [Microsoft MyApps portal](https://myapps.microsoft.com/). After authenticating to Azure AD, youΓÇÖll be redirected to the BIG-IP virtual server for the application and automatically signed in through SSO.

+For increased security, organizations using this pattern could also consider blocking all direct access to the application, thereby forcing a strict path through the BIG-IP.

+## Advanced deployment

+There may be cases where the Guided Configuration templates lack the flexibility to achieve more specific requirements. For those scenarios, see [Advanced Configuration for headers-based SSO](./f5-big-ip-header-advanced.md). Alternatively, the BIG-IP gives the option to disable **Guided ConfigurationΓÇÖs strict management mode**. This allows you to manually tweak your configurations, even though bulk of your configurations are automated through the wizard-based templates.

+You can navigate to **Access > Guided Configuration** and select the **small padlock icon** on the far right of the row for your applicationsΓÇÖ configs.

+

+At that point, changes via the wizard UI are no longer possible, but all BIG-IP objects associated with the published instance of the application will be unlocked for direct management.

+> [!NOTE]

+> Re-enabling strict mode and deploying a configuration will overwrite any settings performed outside of the Guided Configuration UI, therefore we recommend the advanced configuration method for production services.

+## Troubleshooting

+There can be many factors leading to failure to access a published application. BIG-IP logging can help quickly isolate all sorts of issues with connectivity, policy violations, or misconfigured variable mappings.

+Start troubleshooting by increasing the log verbosity level.

+1. Navigate to **Access Policy > Overview > Event Logs > Settings**

+2. Select the row for your published application then **Edit > Access System Logs**

+3. Select **Debug** from the SSO list then **OK**

+Reproduce your issue, then inspect the logs, but remember to switch this back when finished as verbose mode generates lots of data. If you see a BIG-IP branded error immediately after successful Azure AD pre-authentication, itΓÇÖs possible the issue relates to SSO from Azure AD to the BIG-IP.

+1. Navigate to **Access > Overview > Access reports**

+2. Run the report for the last hour to see logs provide any clues. The **View session** variables link for your session will also help understand if the APM is receiving the expected claims from Azure AD

+If you donΓÇÖt see a BIG-IP error page, then the issue is probably more related to the backend request or SSO from the BIG-IP to the application.

+1. In which case you should head to **Access Policy > Overview > Active Sessions** and select the link for your active session

+2. The **View Variables** link in this location may also help root cause SSO issues, particularly if the BIG-IP APM fails to obtain the right attributes

+See [BIG-IP APM variable assign examples](https://devcentral.f5.com/s/articles/apm-variable-assign-examples-1107) and [F5 BIG-IP session variables reference](https://techdocs.f5.com/en-us/bigip-15-0-0/big-ip-access-policy-manager-visual-policy-editor/session-variables.html) for more info.

+1. Use [List users](/graph/api/user-list) API to get the user.

+ ```http

+ GET https://graph.microsoft.com/v1.0/users?$filter=userPrincipalName eq 'alice@contoso.com'

+1. Use the [List unifiedRoleDefinitions](/graph/api/rbacapplication-list-roledefinitions) API to get the role you want to assign.

+ ```http

+ GET https://graph.microsoft.com/v1.0/rolemanagement/directory/roleDefinitions?$filter=displayName eq 'Billing Administrator'

+1. Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the role.

+ ```http

+ POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+1. Use [List users](/graph/api/user-list) API to get the user.

+ ```http

+ GET https://graph.microsoft.com/v1.0/users?$filter=userPrincipalName eq 'alice@contoso.com'

+1. Use the [List unifiedRoleDefinitions](/graph/api/rbacapplication-list-roledefinitions) API to get the role you want to assign.

+ ```http

+ GET https://graph.microsoft.com/v1.0/rolemanagement/directory/roleDefinitions?$filter=displayName eq 'User Administrator'

+ ```http

+ GET https://graph.microsoft.com/v1.0/directory/administrativeUnits?$filter=displayName eq 'Seattle Admin Unit'

+1. Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the role.

+ ```http

+ POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+1. Use [List users](/graph/api/user-list) API to get the user.

+ ```http

+ GET https://graph.microsoft.com/v1.0/users?$filter=userPrincipalName eq 'alice@contoso.com'

+1. Use the [List unifiedRoleDefinitions](/graph/api/rbacapplication-list-roledefinitions) API to get the role you want to assign.

+ ```http

+ GET https://graph.microsoft.com/v1.0/rolemanagement/directory/roleDefinitions?$filter=displayName eq 'Application Administrator'

+ ```http

+ GET https://graph.microsoft.com/v1.0/applications?$filter=displayName eq 'f/128 Filter Photos'

+1. Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the role.

+ ```http

+ POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the role.

+### Example 1: Create a role assignment between a user and a role definition

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+```http

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",

+ "directoryScopeId": "/" // Don't use "resourceScope" attribute in Azure AD role assignments. It will be deprecated soon.

+```http

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+```http

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+ "principalId": "2142743c-a5b3-4983-8486-4532ccba12869",

+ "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",

+ "directoryScopeId": "/" //Don't use "resourceScope" attribute in Azure AD role assignments. It will be deprecated soon.

+```http

+### Example 3: Create a role assignment on a single resource scope

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+```http

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+ "principalId": "2142743c-a5b3-4983-8486-4532ccba12869",

+ "roleDefinitionId": "e9b2b976-1dea-4229-a078-b08abd6c4f84", //role template ID of a custom role

+ "directoryScopeId": "/13ff0c50-18e7-4071-8b52-a6f08e17c8cc" //object ID of an application

+```http

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+```http

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "29232cdf-9323-42fd-ade2-1d097af3e4de", //role template ID of Exchange Administrator

+ "directoryScopeId": "/administrativeUnits/13ff0c50-18e7-4071-8b52-a6f08e17c8cc" //object ID of an administrative unit

+```http

+Use the [List unifiedRoleAssignments](/graph/api/rbacapplication-list-roleassignments) API to get the role assignment.

+### Example 5: Get role assignments for a given principal

+```http

+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=principalId+eq+'<object-id-of-principal>'

+```http

+ "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",

+ "directoryScopeId": "/"

+ "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",

+ "directoryScopeId": "/"

+```http

+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=roleDefinitionId+eq+'<object-id-or-template-id-of-role-definition>'

+```http

+ "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",

+ "directoryScopeId": "/"

+```http

+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

+```http

+ "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1",

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",

+ "directoryScopeId": "/"

+```http

+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=directoryScopeId+eq+'/d23998b1-8853-4c87-b95f-be97d6c6b610'

+```http

+ "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",

+ "directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"

+ "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "3671d40a-1aac-426c-a0c1-a3821ebd8218",

+ "directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"

+Use the [Delete unifiedRoleAssignment](/graph/api/unifiedroleassignment-delete) API to delete the role assignment.

+### Example 9: Delete a role assignment between a user and a role definition.

+```http

+DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

+```http

+```http

+DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

+```http

+```http

+DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

+```http

+Use the [Create unifiedRoleDefinition](/graph/api/rbacapplication-post-roledefinitions) API to create a custom role. For more information, see [Create and assign a custom role](custom-create.md) and [Assign custom admin roles using the Microsoft Graph API](custom-assign-graph.md).

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions

+ "description": "Can manage user and group assignments for Applications.",

+ "displayName": "Manage user and group assignments",

+ "isEnabled": true,

+ "allowedResourceActions":

+ [

+ "microsoft.directory/servicePrincipals/appRoleAssignedTo/update"

+ ]

+ "templateId": "<PROVIDE NEW GUID HERE>",

+ "version": "1"

+Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the custom role. The role assignment combines a security principal ID (which can be a user or service principal), a role definition ID, and an Azure AD resource scope. For more information on the elements of a role assignment, see the [custom roles overview](custom-overview.md)

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+ "principalId": "<PROVIDE OBJECTID OF USER TO ASSIGN HERE>",

+ "roleDefinitionId": "<PROVIDE OBJECTID OF ROLE DEFINITION HERE>",

+ "directoryScopeId": "/"

+Use the [Create group](/graph/api/group-post-groups) API to create a group.

+```http

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

+ "description": "This group is assigned to Helpdesk Administrator built-in role of Azure AD.",

+ "displayName": "Contoso_Helpdesk_Administrators",

+ "groupTypes": [

+ "Unified"

+ ],

+ "isAssignableToRole": true,

+ "mailEnabled": true,

+ "mailNickname": "contosohelpdeskadministrators",

+ "securityEnabled": true

+Use the [List unifiedRoleDefinitions](/graph/api/rbacapplication-list-roledefinitions) API to get a role definition.

+```http

+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions?$filter = displayName eq 'Helpdesk Administrator'

+Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the role.

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+ "principalId": "<Object Id of Group>",

+ "roleDefinitionId": "<ID of role definition>",

+ "directoryScopeId": "/"

+Use the [Create group](/graph/api/group-post-groups) API to create a group.

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

+ "description": "This group is assigned to Helpdesk Administrator built-in role of Azure AD",

+ "displayName": "Contoso_Helpdesk_Administrators",

+ "groupTypes": [

+ "Unified"

+ ],

+ "isAssignableToRole": true,

+ "mailEnabled": true,

+ "mailNickname": "contosohelpdeskadministrators",

+ "securityEnabled": true

+Use the [List unifiedRoleDefinitions](/graph/api/rbacapplication-list-roledefinitions) API to get a role definition.

+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions?$filter=displayName+eq+'Helpdesk Administrator'

+Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the role.

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+ "principalId": "{object-id-of-group}",

+ "roleDefinitionId": "{role-definition-id}",

+ "directoryScopeId": "/"

+Use the [Delete unifiedRoleAssignment](/graph/api/unifiedroleassignment-delete) API to delete the role assignment.

+DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/{role-assignment-id}

+Use the [Get group](/graph/api/group-get) API to get a group.

+GET https://graph.microsoft.com/v1.0/groups?$filter=displayName+eq+'Contoso_Helpdesk_Administrator'

+Use the [List unifiedRoleAssignments](/graph/api/rbacapplication-list-roleassignments) API to get the role assignment.

+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=principalId eq

+ $uri = "https://graph.microsoft.com/v1.0/directoryObjects/$userId/microsoft.graph.checkMemberObjects"

+1. Use the [List unifiedRoleAssignments](/graph/api/rbacapplication-list-roleassignments) API to get roles assigned directly to a user. Add following query to the URL and select **Run query**.

+ ```http

+ GET https://graph.microsoft.com/v1.0/rolemanagement/directory/roleAssignments?$filter=principalId eq '55c07278-7109-4a46-ae60-4b644bc83a31'

+ a. Use the [List groups](/graph/api/group-list) API to get the list of all role assignable groups.

+ ```http

+ GET https://graph.microsoft.com/v1.0/groups?$filter=isAssignableToRole eq true

+ b. Pass this list to the [checkMemberObjects](/graph/api/user-checkmemberobjects) API to figure out which of the role assignable groups the user is member of.

+ ```http

+ POST https://graph.microsoft.com/v1.0/users/55c07278-7109-4a46-ae60-4b644bc83a31/checkMemberObjects

+ c. Use the [List unifiedRoleAssignments](/graph/api/rbacapplication-list-roleassignments) API to loop through the groups and get the roles assigned to them.

+ ```http

+ GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=principalId eq '5425a4a0-8998-45ca-b42c-4e00920a6382'

+3. Select the API version to **v1.0**.

+4. Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign roles. Add following details to the URL and Request Body and select **Run query**.

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+4. Use the [Create unifiedRoleEligibilityScheduleRequest](/graph/api/unifiedroleeligibilityschedulerequest-post-unifiedroleeligibilityschedulerequests) API to assign roles using PIM. Add following details to the URL and Request Body and select **Run query**.

+```http

+```http

+To activate the role assignment, use the [Create unifiedRoleAssignmentScheduleRequest](/graph/api/unifiedroleassignmentschedulerequest-post-unifiedroleassignmentschedulerequests) API.

+```http

+Use the [Create unifiedRoleDefinition](/graph/api/rbacapplication-post-roledefinitions) API to create a custom role.

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions

+```http

+ "description": "Can create an unlimited number of application registrations.",

+ "displayName": "Application Registration Creator",

+ "isEnabled": true,

+ "allowedResourceActions":

+ [

+ "microsoft.directory/applications/create"

+ "microsoft.directory/applications/createAsOwner"

+ ]

+ "templateId": "<PROVIDE NEW GUID HERE>",

+ "version": "1"

+Use the [Create unifiedRoleAssignment](/graph/api/rbacapplication-post-roleassignments) API to assign the custom role. The role assignment combines a security principal ID (which can be a user or service principal), a role definition (role) ID, and an Azure AD resource scope.

+```http

+POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

+```http

+ "@odata.type": "#microsoft.graph.unifiedRoleAssignment",

+ "principalId": "<PROVIDE OBJECTID OF USER TO ASSIGN HERE>",

+ "roleDefinitionId": "<PROVIDE OBJECTID OF ROLE DEFINITION HERE>",

+ "directoryScopeId": "/"

+3. Select the API version to **v1.0**.

+4. Add the following query to use the [List unifiedRoleDefinitions](/graph/api/rbacapplication-list-roledefinitions) API.

+ ```http

+ GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions

+ ```http

+ GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions?$filter=DisplayName eq 'Conditional Access Administrator'&$select=rolePermissions

+Use the [List unifiedRoleAssignments](/graph/api/rbacapplication-list-roleassignments) API to get the role assignment for a specified role definition.

+```http

+GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments&$filter=roleDefinitionId eq ΓÇÿ<template-id-of-role-definition>ΓÇÖ

+```http

+ "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1",

+ "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",

+ "roleDefinitionId": "3671d40a-1aac-426c-a0c1-a3821ebd8218",

+ "directoryScopeId": "/"

+1. In the **Operations** section of the menu, select **Publish website**. This operation may take a few minutes.

+## Customization and styling of the managed portal

+Your API Management service includes a built-in, always up-to-date, **managed** developer portal. You can access it from the Azure portal interface.

+Customize and style the managed portal through the built-in, drag-and-drop visual editor:

+* Use the visual editor to modify pages, media, layouts, menus, styles, or website settings.

+* Take advantage of built-in widgets to add text, images, buttons, and other objects that the portal supports out-of-the-box.

+* [Add custom HTML](developer-portal-faq.md#how-do-i-add-custom-html-to-my-developer-portal) - for example, add HTML for a form or to embed a video player. The custom code is rendered in an inline frame (iframe).

+See [this tutorial](api-management-howto-developer-portal-customize.md) for example customizations.

+## <a name="managed-vs-self-hosted"></a> Extensibility

+In some cases you might need functionality beyond the customization and styling options supported in the managed developer portal. If you need to implement custom logic, which isn't supported out-of-the-box, you can modify the portal's codebase, available on [GitHub](https://github.com/Azure/api-management-developer-portal). For example, you could create a new widget to integrate with a third-party support system. When you implement new functionality, you can choose one of the following options:

+Learn more about the developer portal:

+You have the following options:

+* For certain situations, you can [add custom HTML](#how-do-i-add-custom-html-to-my-developer-portal) to add functionality to the portal.

+* Open a feature request in the [GitHub repository](https://github.com/Azure/api-management-developer-portal).

+* [Implement the missing functionality yourself](developer-portal-implement-widgets.md).

+Learn more about developer portal [extensibility](api-management-howto-developer-portal.md#managed-vs-self-hosted).

+Automatically apply the CORS policy by clicking the **Enable CORS** button.

+The call failure may also be caused by an TLS/SSL certificate, which is assigned to a custom domain and is not trusted by the browser. As a mitigation, you can remove the management endpoint custom domain. API Management will fall back to the default endpoint with a trusted certificate.

+## How do I add custom HTML to my developer portal?

+The managed developer portal includes a **Custom HTML code** widget that enables you to insert HTML code for small portal customizations. For example, use custom HTML to embed a video or to add a form. The portal renders the custom widget in an inline frame (iframe).

+

+1. In the administrative interface for the developer portal, go to the page or section where you want to insert the widget.

+1. Select the grey "plus" (**+**) icon that appears when you hover the pointer over the page.

+1. In the **Add widget** window, select **Custom HTML code**.

+

+ :::image type="content" source="media/developer-portal-faq/add-custom-html-code-widget.png" alt-text="Add widget for custom HTML code":::

+1. Select the "pencil" icon to customize the widget.

+1. Enter a **Width** and **Height** (in pixels) for the widget.

+1. To inherit styles from the developer portal (recommended), select **Apply developer portal styling**.

+ > [!NOTE]

+ > If this setting isn't selected, the embedded elements will be plain HTML controls, without the styles of the developer portal.

+

+ :::image type="content" source="media/developer-portal-faq/configure-html-custom-code.png" alt-text="Configure HTML custom code":::

+1. Replace the sample **HTML code** with your custom content.

+1. When configuration is complete, close the window.

+1. Save your changes, and [republish the portal](api-management-howto-developer-portal-customize.md#publish).

+> [!NOTE]

+> Microsoft does not support the HTML code you add in the Custom HTML Code widget.

+Learn more about the developer portal:

+| <font size=5>Acumatica</font>| [**Acumatica**](https://www.acumatica.com/) is a technology provider that develops cloud- and browser-based enterprise resource planning (ERP) software for small and medium-sized businesses (SMBs). To bring expense claims into the modern age, Acumatica incorporated Form Recognizer into its native application. The Form Recognizer's prebuilt-receipt API and machine learning capabilities are used to automatically extract data from receipts. Acumatica's customers can file multiple, error-free claims in a matter of seconds, freeing up more time to focus on other important tasks. | [Customer story](https://customers.microsoft.com/story/762684-acumatica-partner-professional-services-azure) |

+|<font size=5> Arkas Logistics</font> | [**Arkas Logistics**](http://www.arkaslojistik.com.tr/) is operates under the umbrella of Arkas Holding, Turkey's leading holding institution and operating in 23 countries. During the COVID-19 crisis, Arkas Logistics has been able to provide outstanding, complete logistical services thanks to its focus on contactless operation and digitalization steps. Form Recognizer powers a solution that maintains the continuity of the supply chain and allows for uninterrupted service. | [Customer story](https://customers.microsoft.com/story/842149-arkas-logistics-transportation-azure-en-turkey ) |

+|<font size=5>Automation Anywhere</font>| [**Automation Anywhere**](https://www.automationanywhere.com/) is on a singular and unwavering mission to democratize automation by liberating teams from mundane, repetitive tasks, and allowing more time for innovation and creativity with cloud-native robotic process automation (RPA)software. To protect the citizens of the United Kingdom, healthcare providers must process tens of thousands of COVID-19 tests daily, each one accompanied by a form for the World Health Organization (WHO). Manually completing and processing these forms would potentially slow testing and divert resources away from patient care. In response, Automation Anywhere built an AI-powered bot to help a healthcare provider automatically process and submit the COVID-19 test forms at scale. | [Customer story](https://customers.microsoft.com/story/811346-automation-anywhere-partner-professional-services-azure-cognitive-services) |

+|<font size=5>AvidXchange</font>| [**AvidXchange**](https://www.avidxchange.com/) has developed an accounts payable automation solution applying Form Recognizer. AvidXchange partners with Azure Cognitive Services to deliver an accounts payable automation solution for the middle market. Customers benefit from faster invoice processing times and increased accuracy to ensure their suppliers are paid the right amount, at the right time. | [Blog](https://techcommunity.microsoft.com/t5/azure-ai/form-recognizer-now-reads-more-languages-processes-ids-and/ba-p/2179428)|

+|<font size=5>Blue Prism</font>| [**Blue Prism**](https://www.blueprism.com/) Decipher is an AI-powered document processing capability that's directly embedded into the company's connected-RPA platform. Decipher works with Form Recognizer to help organizations process forms faster and with less human effort. One of Blue Prism's customers has been testing the solution to automate invoice handling as part of its procurement process. | [Customer story](https://customers.microsoft.com/story/737482-blue-prism-partner-professional-services-azure) |

+|<font size=5>Chevron</font>| [**Chevron**](https://www.chevron.com//) Canada Business Unit is now using Form Recognizer with UiPath's robotic process automation platform to automate the extraction of data and move it into back-end systems for analysis. Subject matter experts have more time to focus on higher-value activities and information flows more rapidly. Accelerated operational control enables the company to analyze its business with greater speed, accuracy, and depth. | [Customer story](https://customers.microsoft.com/story/chevron-mining-oil-gas-azure-cognitive-services)|

+|<font size=5>Cross Masters</font>|[**Cross Masters**](https://crossmasters.com/), uses cutting-edge AI technologies not only as a passion, but as an essential part of a work culture requiring continuous innovation. One of the latest success stories is automation of manual paperwork required to process thousands of invoices. Cross Masters used Form Recognizer to develop a unique, customized solution, to provide clients with market insights from a large set of collected invoices. Most impressive is the extraction quality and continuous introduction of new features, such as model composing and table labeling. | [Blog](https://techcommunity.microsoft.com/t5/azure-ai/form-recognizer-now-reads-more-languages-processes-ids-and/ba-p/2179428)|

+ |<font size=5>Element</font>| [**Element**](https://www.element.com/) is a global business that provides specialist testing, inspection, and certification services to a diverse range of businesses. Element is one of the fastest growing companies in the global testing, inspection and certification sector having over 6,500 engaged experts working in more than 200 facilities across the globe. When the finance team for the Americas was forced to work from home during the COVID-19 pandemic, it needed to digitalize its paper processes fast. The creativity of the team and its use of Azure Form Recognizer delivered more than business as usualΓÇöit delivered significant efficiencies. The Element team used the tools in Microsoft Azure so the next phase could be expedited. Rather than coding from scratch, they saw the opportunity to use the Azure Form Recognizer. This integration quickly gave them the functionality they needed, together with the agility and security of Microsoft Azure. Microsoft Azure Logic Apps is used to automate the process of extracting the documents from email, storing them, and updating the system with the extracted data. Computer Vision, part of Azure Cognitive Services, partners with Azure Form Recognizer to extract the right data points from the invoice documentsΓÇöwhether they're a pdf or scanned images. | [Customer story](https://customers.microsoft.com/en-us/story/1414941527887021413-element)|

+ |<font size=5>Emaar Properties</font>| [**Emaar Properties**](https://www.emaar.com/en/), operates Dubai Mall, the world's most-visited retail and entertainment destination. Each year, the Dubai Mall draws more than 80 million visitors. To enrich the shopping experience, Emaar Properties offers a unique rewards program through a dedicated mobile app. Loyalty program points are earned via submitted receipts. Emaar Properties uses Microsoft Azure Form Recognizer to process submitted receipts and has achieved 92 percent reading accuracy.| [Customer story](https://customers.microsoft.com/en-us/story/1459754150957690925-emaar-retailers-azure-en-united-arab-emirates)|

+|<font size=5>EY</font>| [**EY**](https://ey.com/) (Ernst & Young Global Limited) is a multinational professional services network that helps to create long-term value for clients and build trust in the capital markets. Enabled by data and technology, diverse EY teams in over 150 countries to help clients grow, transform, and operate. EY teams work across assurance, consulting, law, strategy, tax, and transactions to find solutions for complex issues facing our world today. The EY Technology team collaborated with Microsoft to build a platform that hastens invoice extraction and contract comparison processes. Azure Form Recognizer and Custom Vision partnered to enable EY teams to automate and improve the OCR and document handling processes for its consulting, tax, audit, and transactions services clients. | [Customer story](https://customers.microsoft.com/en-us/story/1404985164224935715-ey-professional-services-azure-form-recognizer)|

+|<font size=5>Financial Fabric</font>| [**Financial Fabric**](https://www.financialfabric.com//), a Microsoft Cloud Solution Provider, delivers data architecture, science, and analytics services to investment managers at hedge funds, family offices, and corporate treasuries. Its daily processes involve extracting and normalizing data from thousands of complex financial documents, such as bank statements and legal agreements. The company then provides custom analytics to help its clients make better investment decisions. Extracting this data previously took days or weeks. By using Form Recognizer, Financial Fabric has reduced the time it takes to go from extraction to analysis to just minutes. | [Customer story](https://customers.microsoft.com/story/financial-fabric-banking-capital-markets-azure)|

+|<font size=5>GEP</font>| [**GEP**](https://www.gep.com/) has developed an invoice processing solution for a client using Form Recognizer. "At GEP, we're seeing AI and automation make a profound impact on procurement and the supply chain. By combining our AI solution with Microsoft Form Recognizer, we automated the processing of 4,000 invoices a day for a client... It saved them tens of thousands of hours of manual effort, while improving accuracy, controls and compliance on a global scale." Sarateudu Sethi, GEP's Vice President of Artificial Intelligence. | [Blog](https://techcommunity.microsoft.com/t5/azure-ai/form-recognizer-now-reads-more-languages-processes-ids-and/ba-p/2179428)|

+|<font size=5>HCA Healthcare</font>| [**HCA Healthcare**](https://hcahealthcare.com/) is one of the nation's leading providers of healthcare with over 180 hospitals and 2,000 sites-of-care located throughout the United States and serving approximately 35 million patients each year. Currently, they're using Azure Form Recognizer to simplify and improve the patient onboarding experience and reducing administrative time spent entering repetitive data into the care center's system. | [Customer story](https://customers.microsoft.com/en-us/story/1404891793134114534-hca-healthcare-healthcare-provider-azure)|

+|<font size=5>Icertis</font>| [**Icertis**](https://www.icertis.com/), is a Software as a Service (SaaS) provider headquartered in Bellevue, Washington. Icertis digitally transforms the contract management process with a cloud-based, AI-powered, contract lifecycle management solution. Azure Form Recognizer enables Icertis Contract Intelligence to take key-value pairs embedded in contracts and create structured data understood and operated upon by machine algorithms. Through these and other powerful Azure Cognitive and AI services, Icertis empowers customers in every industry to improve business in multiple ways: optimized manufacturing operations, added agility to retail strategies, reduced risk in IT services, and faster delivery of life-saving pharmaceutical products. | [Blog](https://cloudblogs.microsoft.com/industry-blog/en-in/unicorn/2022/01/12/how-icertis-built-a-contract-management-solution-using-azure-form-recognizer/)|

+|<font size=5>Instabase</font>| [**Instabase**](https://instabase.com/) is a horizontal application platform that provides best-in-class machine learning processes to help retrieve, organize, identify, and understand complex masses of unorganized data. Instabase then brings this data into business workflows as organized information. The platform provides a repository of integrative applications to orchestrate and harness that information with the means to rapidly extend and enhance them as required. Instabase applications are fully containerized for widespread, infrastructure-agnostic deployment. | [Customer story](https://customers.microsoft.com/en-gb/story/1376278902865681018-instabase-partner-professional-services-azure)|

+|<font size=5>Northern Trust</font>| [**Northern Trust**](https://www.northerntrust.com/) is a leading provider of wealth management, asset servicing, asset management, and banking to corporations, institutions, families, and individuals. As part of its initiative to digitize alternative asset servicing, Northern Trust has launched an AI-powered solution to extract unstructured investment data from alternative asset documents and making it accessible and actionable for asset-owner clients. Microsoft Azure Applied AI services accelerate time-to-value for enterprises building AI solutions. This proprietary solution transforms crucial information such as capital call notices, cash and stock distribution notices, and capital account statements from various unstructured formats into digital, actionable insights for investment teams. | [Customer story](https://www.businesswire.com/news/home/20210914005449/en/Northern-Trust-Automates-Data-Extraction-from-Alternative-Asset-Documentation)|

+ |<font size=5>Standard Bank</font>| [**Standard Bank of South Africa**](https://www.standardbank.co.za/southafrica/personal/home) is Africa's largest bank by assets. Standard Bank is headquartered in Johannesburg, South Africa, and has more than 150 years of trade experience in Africa and beyond. When manual due diligence in cross-border transactions began absorbing too much staff time, the bank decided it needed a new way forward. Standard Bank uses Form Recognizer to significantly reduce its cross-border payments registration and processing time. | [Customer story](https://customers.microsoft.com/en-hk/story/1395059149522299983-standard-bank-of-south-africa-banking-capital-markets-azure-en-south-africa)|

+|<font size=5>WEX</font>| [**WEX**](https://www.wexinc.com/) has developed a tool to process Explanation of Benefits documents using Form Recognizer. "The technology is truly amazing. I was initially worried that this type of solution wouldn't be feasible, but I soon realized that Form Recognizer can read virtually any document with accuracy." Matt Dallahan, Senior Vice President of Product Management and Strategy | [Blog](https://techcommunity.microsoft.com/t5/azure-ai/form-recognizer-now-reads-more-languages-processes-ids-and/ba-p/2179428)|

+|<font size=5>Wilson Allen</font> | [**Wilson Allen**](https://wilsonallen.com/) took advantage of AI container support for Microsoft Azure Cognitive Services and created a powerful AI solution that help firms around the world find unprecedented levels of insight in previously siloed and unstructured data. Its clients can use this data to support business development and foster client relationships. | [Customer story](https://customers.microsoft.com/story/814361-wilson-allen-partner-professional-services-azure)|

+|<font size=5>Zelros</font>| [**Zelros**](http://www.zelros.com/) offers AI-powered software for the insurance industry. Insurers use the Zelros platform to take in forms and seamlessly manage customer enrollment and claims filing. The company combined its technology with Form Recognizer to automatically pull key-value pairs and text out of documents. When insurers use the Zelros platform, they can quickly process paperwork, ensure high accuracy, and redirect thousands of hours previously spent on manual data extraction toward better service. | [Customer story](https://customers.microsoft.com/story/816397-zelros-insurance-azure)|

+You can use a local Kubernetes secret for authentication with a `git` or `bucket` source. The local secret must contain all of the authentication parameters needed for the source and must be created in the same namespace as the Flux configuration.

+For HTTPS authentication, you create a secret with the `username` and `password`:

+For SSH authentication, you create a secret with the `identity` and `known_hosts` fields:

+Learn more about using a local Kubernetes secret with these authentication methods:

+* [Git repository HTTPS authentication](https://fluxcd.io/docs/components/source/gitrepositories/#https-authentication)

+* [Git repository HTTPS self-signed certificates](https://fluxcd.io/docs/components/source/gitrepositories/#https-self-signed-certificates)

+* [Git repository SSH authentication](https://fluxcd.io/docs/components/source/gitrepositories/#ssh-authentication)

+* [Bucket static authentication](https://fluxcd.io/docs/components/source/buckets/#static-authentication)

+> [!NOTE]

+> Not all languages and operating system combinations support in-portal editing. If you're unable to create a proxy in the portal, you can instead manually create a _proxies.json_ file in the root of your function app project folder. To learn more about portal editing support, see [Language support details](functions-create-function-app-portal.md#language-support-details).

+| Guam | Γ£ô | Γ£ô | Γ£ô | Γ£ô | Γ£ô |

+> | components / analyticsItems | No | No |

+> | components / favorites | No | No |

+> | components / myAnalyticsItems | No | No |

+> | components / pricingPlans | No | No |

+> | dataCollectionEndpoints | No | No |

+> | dataCollectionRuleAssociations | No | No |

+> | dataCollectionRules | Yes | Yes |

+> | myWorkbooks | No | No |

+> | components / analyticsItems | No |

+> | components / favorites | No |

+> | components / myAnalyticsItems | No |

+> | components / pricingPlans | No |

+> | dataCollectionEndpoints | No |

+> | dataCollectionRuleAssociations | No |

+> | dataCollectionRules | Yes |

+> | myWorkbooks | No |

+Azure Communication Services capabilities are conceptually organized into discrete areas based on their functional area. Most areas have fully open-sourced SDKs programmed against published REST APIs that you can use directly over the Internet. The Calling SDK uses proprietary network interfaces and is closed-source.

+### SDK platform support details

+#### iOS and Android

+#### .NET

+## REST APIs

+Communication Services APIs are documented alongside other [Azure REST APIs in docs.microsoft.com](/rest/api/azure/). This documentation will tell you how to structure your HTTP messages and offers guidance for using [Postman](../tutorials/postman-tutorial.md). REST interface documentation is also published in Swagger format on [GitHub](https://github.com/Azure/azure-rest-api-specs).

+### REST API Throttles

+Certain REST APIs and corresponding SDK methods have throttle limits you should be mindful of. Exceeding these throttle limits will trigger a`429 - Too Many Requests` error response. These limits can be increased through [a request to Azure Support](../../azure-portal/supportability/how-to-create-azure-support-request.md).

+| API| Throttle|

+|||

+| [All Search Telephone Number Plan APIs](/rest/api/communication/phonenumbers) | 4 requests/day|

+| [Purchase Telephone Number Plan](/rest/api/communication/phonenumbers/purchasephonenumbers) | 1 purchase a month|

+| [Send SMS](/rest/api/communication/sms/send) | 200 requests/minute |

+| **Unusual unauthenticated access to a storage container**<br>(Storage.Blob_AnonymousAccessAnomaly) | This storage account was accessed without authentication, which is a change in the common access pattern. Read access to this container is usually authenticated. This might indicate that a threat actor was able to exploit public read access to storage container(s) in this storage account(s).<br>Applies to: Azure Blob Storage | Collection | Low |

+### Exclude an active Databricks workspace

+Microsoft Defender for Storage can exclude specific active Databricks workspace storage accounts, when the plan is already enabled on a subscription.

+**To exclude an active Databricks workspace**:

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

+1. Navigate to **Azure Databricks** > **`Your Databricks workspace`** > **Tags**.

+1. In the Name field, enter `AzDefenderPlanAutoEnable`.

+1. In the Value field, enter `off`.

+1. Select **Apply**.

+ :::image type="content" source="media/defender-for-storage-exclude/workspace-exclude.png" alt-text="Screenshot showing the location, and how to apply the tag to your Azure Databricks account.":::

+1. Navigate to **Microsoft Defender for Cloud** > **Environment settings** > **`Your subscription`**.

+1. Toggle the Defender for Storage plan to **Off**.

+ :::image type="content" source="media/defender-for-storage-exclude/storage-off.png" alt-text="Screenshot showing how to switch the Defender for Storage plan to off.":::

+1. Select **Save**.

+1. Toggle the Defender for Storage plan to **On**.

+1. Select **Save**.

+The tags will be inherited by the Storage account of the Databricks workspace and prevent Defender for Storage from turning on.

+> [!Note]

+> Tags can't be added directly to the Databricks Storage account, or its Managed Resource Group.

+### Prevent auto-enabling on a new Databricks workspace storage account

+When you create a new Databricks workspace, you have the ability to add a tag that will prevent your Microsoft Defender for Storage account from enabling automatically.

+**To prevent auto-enabling on a new Databricks workspace storage account**:

+ 1. Follow [these steps](/azure/databricks/scenarios/quickstart-create-Databricks-workspace-portal?tabs=azure-portal) to create a new Azure Databricks workspace.

+

+ 1. In the Tags tab, enter a tag named `AzDefenderPlanAutoEnable`.

+

+ 1. Enter the value `off`.

+

+ :::image type="content" source="media/defender-for-storage-exclude/tag-off.png" alt-text="Screenshot that shows how to create a tag in the Databricks workspace.":::

+1. Continue following the instructions to create your new Azure Databricks workspace.

+

+The Microsoft Defender for Storage account will inherit the tag of the Databricks workspace, which will prevent Defender for Storage from turning on automatically.

+| Environment requirements: | Kubernetes v1.14 (or newer) is required<br>No PodSecurityPolicy resource (old PSP model) on the clusters<br>Windows nodes are not supported |

+| **Action** | [Security Reader](../role-based-access-control/built-in-roles.md#security-reader) / <br> [Reader](../role-based-access-control/built-in-roles.md#reader) | [Security Admin](../role-based-access-control/built-in-roles.md#security-admin) | [Contributor](../role-based-access-control/built-in-roles.md#contributor) / [Owner](../role-based-access-control/built-in-roles.md#owner) | [Contributor](../role-based-access-control/built-in-roles.md#contributor) | [Owner](../role-based-access-control/built-in-roles.md#owner) |

+### Secure development environment

+The Horizon ODE enables development of custom or proprietary protocols that cannot be shared outside an organization. For example, because of legal regulations or corporate policies.

+Develop dissector plugins without:

+- revealing any proprietary information about how your protocols are defined.

+- sharing any of your sensitive PCAPs.

+- violating compliance regulations.

+Contact <ms-horizon-support@microsoft.com> for information about developing protocol plugins.

+### Customization and localization

+The SDK supports various customization options, including:

+ - Text for function codes.

+ - Full localization text for alerts, events, and protocol parameters.

+ :::image type="content" source="media/references-horizon-sdk/localization.png" alt-text="View fully localized alerts.":::

+## Horizon architecture

+The architectural model includes three product layers.

+### Defender for IoT platform layer

+Enables immediate integration and real-time monitoring of custom dissector plugins in the Defender for IoT platform, without the need to upgrade the Defender for IoT platform version.

+### Defender for IoT services layer

+Each service is designed as a pipeline, decoupled from a specific protocol, enabling more efficient, independent development.

+Each service is designed as a pipeline, decoupled from a specific protocol. Services listens for traffic on the pipeline. They interact with the plugin data and the traffic captured by the sensors to index deployed protocols and analyze the traffic payload, and enable a more efficient and independent development.

+### Custom dissector layer

+Enables creation of plugins using the Defender for IoT proprietary SDK (including C++ implementation and JSON configuration) to:

+- Define how to identify the protocol

+- Define how to map the fields you want to extract from the traffic, and extract them

+- Define how to integrate with the Defender for IoT services

+ :::image type="content" source="media/references-horizon-sdk/layers.png" alt-text="The built-in layers.":::

+Defender for IoT provides basic dissectors for common protocols. You can build your dissectors on top of these protocols.

+**Microsoft:** Horizon community dissectors, Horizon proprietary dissectors (developed by customers).

+[Customize alert rules](how-to-accelerate-alert-incident-response.md#customize-alert-rules).

+This section describes how to create Attack Vector reports.

+**To create an attack vector simulation:**

+1. Select **Attack vector** from the sensor side menu.

+1. Select **Add simulation**.

+ - **Show in Device map**: Show the attack vector as a group in the Device map.

+3. Select **Save**.

+1. Select the report that is saved from the Attack vector page and review:

+ - network attack paths and insights

+ - a risk score

+ - source and target devices

+ - a graphical representation of attack vectors

+ :::image type="content" source="media/how-to-generate-reports/sample-attack-vectors.png" alt-text="Screen shot of Attack vectors report.":::

+**Secure Devices** are devices with a security score above 90%.

+**Devices Needing Improvement**: Devices with a security score between 70 percent and 89%.

+**Vulnerable Devices** are devices with a security score below 70%.

+The risk assessment score may be negatively impacted if you don't define backup and anti-virus server addresses in your sensor. Adding these addresses improves your score. By default these addresses aren't defined.

+## Create risk assessment reports

+Create a risk assessment report based on detections made by the sensor you are logged into. The report name is automatically generated as risk-assessment-report-1.pdf. The number is updated for each new report you create. The time and day of creation are displayed.

+**To create a report:**

+1. Sign in to the sensor console.

+1. Select **Risk assessment** on the side menu.

+1. Select **Generate report**. The report appears in the Saved Reports section.

+1. Select the report from the Saved Reports section to download it.

+**To import a company logo:**

+1. Select **Import logo**.

+1. Choose a logo to add to the header of your Risk assessment reports.

+Create a risk assessment report based on detections made by sensors that are managed by your on-premises management console.

+**To create a report:**

+**To import a company logo:**

+1. Select **Import logo**.

+1. Choose a logo to add to the header of your Risk assessment reports.

+If validation is enabled and the certificate cannot be verified, communication between Defender for IoT and the server will be halted. The sensor will display an error message indicating the validation failure. If the validation is disabled and the certificate isn't valid, communication will still be carried out.

+**To create a new forwarding rule**:

+1. Select **Create new rule**.

+1. Add a rule name.

+1. Define rule conditions:

+ - Select the severity level. This is the minimum incident to forward, in terms of severity level. For example, if you select **Minor**, minor alerts and any alert above this severity level will be forwarded. Levels are predefined.

+

+ - Select a protocol(s) that should be detected.

+ Information will forwarding if the traffic detected was running selected protocols.

+

+ - Select which engines the rule should apply to.

+ Alert information detected from selected engines will be forwarded

+

+1. Define rule actions by selecting a server.

+ Forwarding rule actions instruct the sensor to forward alert information to selected partner vendors or servers. You can create multiple actions for each forwarding rule.

+1. Select **Save**.

+## Forwarding rule actions

+You can send alert information to the servers described in this section.

+**To define email for the forwarding rule:**

+1. Enter a single email address. If you need to add more than one email, you'll need to create another action for each email address.

+1. Select **Save**.

+This action is available from the on-premises management console.

+You will know the forwarding rule is working if you see the Success notification.

+**To define NetWitness forwarding parameters:**

+1. Select **Save**.

+1. In the Forwarding page, find the rule you need and select the three dots (...) at the end of the row.

+1. In the Forwarding page, find the rule you need and select the three dots (...) at the end of the row.

+1. Select **Edit** and update the rule.

+1. Select **Save**.

+1. In the Forwarding page, find the rule you need and select the three dots (...) at the end of the row.

+1. Select **Delete** and confirm.

+1. Select **Save**.

+# Enable browser connection to DevTest Labs VMs with Azure Bastion

+The dataset consists of about 120 training images each for turkeys and chickens, with 100 validation images for each class. We'll download and extract the dataset as part of our training script `pytorch_train.py`. The images are a subset of the [Open Images v5 Dataset](https://storage.googleapis.com/openimages/web/https://docsupdatetracker.net/index.html).

+Make sure the curated environment includes all the dependencies required by your training script. If not, you'll have to modify the environment to include the missing dependencies. If the environment is modified, you'll have to give it a new name, as the 'AzureML' prefix is reserved for curated environments. If you modified the conda dependencies YAML file, you can create a new environment from it with a new name, for example:

+By default if no base image is specified, Azure ML will use a CPU image `azureml.core.environment.DEFAULT_CPU_IMAGE` as the base image. Since this example runs training on a GPU cluster, you'll need to specify a GPU base image that has the necessary GPU drivers and dependencies. Azure ML maintains a set of base images published on Microsoft Container Registry (MCR) that you can use. For more information, see [AzureML-Containers GitHub repo](https://github.com/Azure/AzureML-Containers).

+A `FileDataset` object references one or multiple files in your workspace datastore or public urls. The files can be of any format, and the class provides you with the ability to download or mount the files to your compute. By creating a `FileDataset`, you create a reference to the data source location. If you applied any transformations to the data set, they'll be stored in the data set as well. The data remains in its existing location, so no extra storage cost is incurred. For more information the `Dataset` package, see the [How to create register datasets article](./how-to-create-register-datasets.md).

+Make sure the curated environment includes all the dependencies required by your training script. If not, you'll have to modify the environment to include the missing dependencies. If the environment is modified, you'll have to give it a new name, as the 'AzureML' prefix is reserved for curated environments. If you modified the conda dependencies YAML file, you can create a new environment from it with a new name, for example:

+By default if no base image is specified, Azure ML will use a CPU image `azureml.core.environment.DEFAULT_CPU_IMAGE` as the base image. Since this example runs training on a GPU cluster, you'll need to specify a GPU base image that has the necessary GPU drivers and dependencies. Azure ML maintains a set of base images published on Microsoft Container Registry (MCR) that you can use, see the [Azure/AzureML-Containers](https://github.com/Azure/AzureML-Containers) GitHub repo for more information.

+Once you've trained the model, you can register it to your workspace. Model registration lets you store and version your models in your workspace to simplify [model management and deployment](concept-model-management-and-deployment.md).

+Optional: by specifying the parameters `model_framework`, `model_framework_version`, and `resource_configuration`, no-code model deployment becomes available. This allows you to directly deploy your model as a web service from the registered model, and the `ResourceConfiguration` object defines the compute resource for the web service.

+Instead of the traditional deployment route, you can also use the no-code deployment feature (preview) for TensorFlow. By registering your model as shown above with the `model_framework`, `model_framework_version`, and `resource_configuration` parameters, you can use the `deploy()` static function to deploy your model.

+The following code uses `mlflow` and your Azure Machine Learning workspace details to construct the unique MLFLow tracking URI associated with your workspace. Then the method [`set_tracking_uri()`](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.set_tracking_uri) points the MLflow tracking URI to that URI.

+| Offers | Added a [Revenue Dashboard](revenue-dashboard.md) to Partner Center, including a revenue report, [sample queries](analytics-sample-queries.md#revenue-report-queries), and [FAQs](/azure/marketplace/analytics-faq#revenue) page. | 2021-12-08 |

+| Policy | The SaaS customer [refund window](/marketplace/refund-policies) is now [72 hours](marketplace-faq-publisher-guide.yml) for all offers. | 2021-09-01 |

+| Offers | We have updated the names of [Dynamics 365](marketplace-dynamics-365.md) offer types: <br><br> - Dynamics 365 for Customer Engagement &amp; PowerApps is now **Dynamics 365 apps on Dataverse and Power Apps** <br> - Dynamics 365 for operations is now **Dynamics 365 Operations Apps** <br> - Dynamics 365 business central is now **Dynamics 365 Business Central** | 2021-12-03 |

+## February 2022

+This release of Azure Database for MySQL - Single Server includes the following updates.

+**Bug fixes**

+The MySQL client version 8.0.27 or later is now compatible with Azure Database for MySQL - Single Server. Now you can connect form the MySQL client version 8.0.27 or later created either via mysql.exe or workbench.

+

+**Known Issues**

+Customers in Japan received two Maintenance Notification emails for this month. The Email notification send for *05-Feb 2022* was send by mistake and no changes will be done to the service on this date. You can safely ignore them. We apologize for the inconvenience.

+| **Incidents** | | |

+| **Hunting** | | |

+| **Domain solution content** | | |

+| - [Microsoft Defender for Cloud](../../sentinel/connect-azure-security-center.md) | GA | GA |

+| - [Microsoft Defender for IoT](../../sentinel/data-connectors-reference.md#microsoft-defender-for-iot) | Public Preview | Not Available |

+| - [Microsoft Insider Risk Management](../../sentinel/sentinel-solutions-catalog.md#domain-solutions) | Public Preview | Not Available |

+| - **[Microsoft Power BI](../../sentinel/data-connectors-reference.md#microsoft-power-bi-preview)** | | |

+| - Office 365 GCC | Public Preview | - |

+| - Office 365 GCC High | - | Not Available |

+| - Office 365 DoD | - | Not Available |

+| - **[Microsoft Project](../../sentinel/data-connectors-reference.md#microsoft-project-preview)** | | |

+| - Office 365 GCC | Public Preview | - |

+| - Office 365 GCC High | - | Not Available |

+| - Office 365 DoD | - | Not Available |

+ Title: Microsoft Sentinel user management normalization schema reference (Public Preview) | Microsoft Docs

+description: This article describes the Microsoft Sentinel user management normalization schema.

+# Microsoft Sentinel user management normalization schema reference (preview)

+The Microsoft Sentinel user management normalization schema is used to describe user management activities, such as creating a user or a group, changing user attribute, or adding a user to a group. Such events are reported, for example, by operating systems, directory services, identity management systems, and any other system reporting on its local user management activity.

+For more information about normalization in Microsoft Sentinel, see [Normalization and the Advanced SIEM Information Model (ASIM)](normalization.md).

+> [!IMPORTANT]

+> The user management normalization schema is currently in *preview*. This feature is provided without a service level agreement. We don't recommend it for production workloads.

+>

+> The [Azure Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

+>

+## Schema overview

+The ASIM user management schema describes user management activities. The activities typically include the following entities:

+- **Actor** - the user performing the management activity.

+- **Acting Process** - the process used by the actor to perform the management activity.

+- **Src** - when the activity is performed over the network, the source device from which the activity was initiated.

+- **Target User** - the user who's account is managed.

+- **Group** the target user is added or removed from, or being modified.

+Some activities, such as **UserCreated**, **GroupCreated**, **UserModified**, and *GroupModified**, set or update user properties. The property set or updated is documented in the following fields:

+- [EventSubType](#eventsubtype) - the name of the value that was set or updated. [UpdatedPropertyName](#updatedpropertyname) is an alias to **EventSubType** when [EventSubType](#eventsubtype) refers to one of the relevant event types.

+- [PreviousPropertyValue](#previouspropertyvalue) - the previous value of the property.

+- [NewPropertyValue](#newpropertyvalue) - the updated value of the property.

+## Schema details

+### Common fields

+> [!IMPORTANT]

+> Fields common to all schemas are described in the [ASIM schema overview](normalization-about-schemas.md#common). The following list mentions only fields that have specific guidelines for user management events.

+>

+| Field | Class | Type | Description |

+||-||--|

+| **EventType** | Mandatory | Enumerated | Describes the operation reported by the record.<br><br> For User Management activity, the supported values are:<br> - `UserCreated`<br> - `UserDeleted`<br> - `UserModified`<br> - `UserLocked`<br> - `UserUnlocked`<br> - `UserDisabled`<br> - `UserEnabled`<br> - `PasswordChanged`<br> - `PasswordReset`<br> - `GroupCreated`<br> - `GroupDeleted`<br> - `GroupModified`<br> - `UserAddedToGroup`<br> - `UserRemovedFromGroup`<br> - `GroupEnumerated`<br> - `UserRead`<br> - `GroupRead`<br> |

+| <a name="eventsubtype"></a>**EventSubType** | Optional | Enumerated | The following sub-types are supported:<br> - `UserRead`: Password, Hash<br> - `UserCreated`, `GroupCreated`, `UserModified`, `GroupModified`. For more information, see [UpdatedPropertyName](#updatedpropertyname) |

+| **EventResult** | Mandatory | Enumerated | While failure is possible, most systems report only successful user management events. The expected value for successful events is `Success`. |

+| **EventResultDetails** | Optional | Enumerated | The valid values are `NotAuthorized` and `Other`. |

+| **EventSeverity** | Mandatory | Enumerated | While any valid severity value is allowed, the severity of user management events is typically `Informational`. |

+| **EventSchema** | Mandatory | String | The name of the schema documented here is `UserManagement`. |

+| **EventSchemaVersion** | Mandatory | String | The version of the schema. The version of the schema documented here is `0.1.1`. |

+| **Dvc** fields| | | For user management events, device fields refer to the system reporting the event. This is usually the system on which the user is managed. |

+| | | | |

+### Updated property fields

+| Field | Class | Type | Description |

+|-|-||-|

+| <a name="updatedpropertyname"></a>**UpdatedPropertyName** | Alias | | Alias to [EventSubType](#eventsubtype) when the Event Type is `UserCreated`, `GroupCreated`, `UserModified`, or `GroupModified`.<br><br>Supported values are:<br>- `MultipleProperties`: Used when the activity updates multiple properties<br>- `Previous<PropertyName>`, where `<PropertyName>` is one of the supported values for `UpdatedPropertyName`. <br>- `New<PropertyName>`, where `<PropertyName>` is one of the supported values for `UpdatedPropertyName`. |

+| <a name="previouspropertyvalue"></a>**PreviousPropertyValue** | Optional | String | The previous value that was stored in the specified property. |

+| <a name="newpropertyvalue"></a>**NewPropertyValue** | Optional | String | The new value stored in the specified property. |

+|||||

+### Target user fields

+| Field | Class | Type | Description |

+|-|-||-|

+| <a name="targetuserid"></a>**TargetUserId** | Optional | String | A machine-readable, alphanumeric, unique representation of the target user. <br><br>Supported formats and types include:<br>- **SID** (Windows): `S-1-5-21-1377283216-344919071-3415362939-500`<br>- **UID** (Linux): `4578`<br>- **AADID** (Azure Active Directory): `9267d02c-5f76-40a9-a9eb-b686f3ca47aa`<br>- **OktaId**: `00urjk4znu3BcncfY0h7`<br>- **AWSId**: `72643944673`<br><br>Store the ID type in the [TargetUserIdType](#targetuseridtype) field. If other IDs are available, we recommend that you normalize the field names to **TargetUserSid**, **TargetUserUid**, **TargetUserAADID**, **TargetUserOktaId**, and **TargetUserAwsId**, respectively. For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: `S-1-12` |

+| <a name="targetuseridtype"></a>**TargetUserIdType** | Optional | Enumerated | The type of the ID stored in the [TargetUserId](#targetuserid) field. <br><br>Supported values are `SID`, `UID`, `AADID`, `OktaId`, and `AWSId`. |

+| <a name="targetusername"></a>**TargetUsername** | Optional | String | The target username, including domain information when available. <br><br>Use one of the following formats and in the following order of priority:<br>- **Upn/Email**: `johndow@contoso.com`<br>- **Windows**: `Contoso\johndow`<br>- **DN**: `CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=COM`<br>- **Simple**: `johndow`. Use the Simple form only if domain information isn't available.<br><br>Store the Username type in the [TargetUsernameType](#targetusernametype) field. If other IDs are available, we recommend that you normalize the field names to **TargetUserUpn**, **TargetUserWindows**, and **TargetUserDn**. For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: `AlbertE` |

+| <a name="targetusernametype"></a>**TargetUsernameType** | Optional | Enumerated | Specifies the type of the username stored in the [TargetUsername](#targetusername) field. Supported values include `UPN`, `Windows`, `DN`, and `Simple`. For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: `Windows` |

+| **TargetUserType** | Optional | Enumerated | The type of target user. Supported values include:<br>- `Regular`<br>- `Machine`<br>- `Admin`<br>- `System`<br>- `Application`<br>- `Service Principal`<br>- `Other`<br><br>**Note**: The value might be provided in the source record by using different terms, which should be normalized to these values. Store the original value in the [TargetOriginalUserType](#targetoriginalusertype) field. |

+| <a name="targetoriginalusertype"></a>**TargetOriginalUserType** | Optional | String | The original destination user type, if provided by the source. |

+|||||

+### Actor fields

+| Field | Class | Type | Description |

+|-|-||-|

+| <a name="actoruserid"></a>**ActorUserId** | Optional | String | A machine-readable, alphanumeric, unique representation of the Actor. <br><br>Supported formats and types include:<br>- **SID** (Windows): `S-1-5-21-1377283216-344919071-3415362939-500`<br>- **UID** (Linux): `4578`<br>- **AADID** (Azure Active Directory): `9267d02c-5f76-40a9-a9eb-b686f3ca47aa`<br>- **OktaId**: `00urjk4znu3BcncfY0h7`<br>- **AWSId**: `72643944673`<br><br>Store the ID type in the [ActorUserIdType](#actoruseridtype) field. If other IDs are available, we recommend that you normalize the field names to **ActorUserSid**, **ActorUserUid**, **ActorUserAadId**, **ActorUserOktaId**, and **ActorAwsId**, respectively. For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: S-1-12 |

+| <a name="actoruseridtype"></a>**ActroUserIdType** | Optional | Enumerated | The type of the ID stored in the [ActorUserId](#actoruserid) field. Supported values include `SID`, `UID`, `AADID`, `OktaId`, and `AWSId`. |

+| <a name="actorusername"></a>**ActorUsername** | Mandatory | String | The Actor username, including domain information when available. <br><br>Use one of the following formats and in the following order of priority:<br>- **Upn/Email**: `johndow@contoso.com`<br>- **Windows**: `Contoso\johndow`<br>- **DN**: `CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=COM`<br>- **Simple**: `johndow`. Use the Simple form only if domain information isn't available.<br><br>Store the Username type in the [ActorUsernameType](#actorusernametype) field. If other IDs are available, we recommend that you normalize the field names to **ActorUserUpn**, **ActorUserWindows**, and **ActorUserDn**.<br><br>For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: `AlbertE` |

+| <a name="user"></a>**User** | Alias | | Alias to [ActorUsername](#actorusername). |

+| <a name="actorusernametype"></a>**ActorUsernameType** | Mandatory | Enumerated | Specifies the type of the username stored in the [ActorUsername](#actorusername) field. Supported values are `UPN`, `Windows`, `DN`, and `Simple`. For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: `Windows` |

+| **ActorUserType** | Optional | Enumerated | The type of the Actor. Allowed values are:<br>- `Regular`<br>- `Machine`<br>- `Admin`<br>- `System`<br>- `Application`<br>- `Service Principal`<br>- `Other`<br><br>**Note**: The value might be provided in the source record by using different terms, which should be normalized to these values. Store the original value in the [ActorOriginalUserType](#actororiginalusertype) field. |

+| <a name="actororiginalusertype"></a>**ActorOriginalUserType** | | | The original actor user type, if provided by the source. |

+| **ActorSessionId** | Optional | String | The unique ID of the login session of the Actor. <br><br>Example: `999`<br><br>**Note**: The type is defined as *string* to support varying systems, but on Windows this value must be numeric. <br><br>If you are using a Windows machine and used a different type, make sure to convert the values. For example, if you used a hexadecimal value, convert it to a decimal value. |

+|||||

+### Group fields

+| Field | Class | Type | Description |

+|-|-||-|

+| <a name="groupid"></a>**GroupId** | Optional | String | A machine-readable, alphanumeric, unique representation of the group, for activities involving a group. <br><br>Supported formats and types include:<br>- **SID** (Windows): `S-1-5-21-1377283216-344919071-3415362939-500`<br>- **UID** (Linux): `4578`<br><br>Store the ID type in the [GroupIdType](#groupidtype) field. If other IDs are available, we recommend that you normalize the field names to **GroupSid** or **GroupUid**, respectively. For more information, see [The User entity](normalization-about-schemas.md#the-user-entity).<br><br>Example: `S-1-12` |

+| <a name="groupidtype"></a>**GroupIdType** | Optional | Enumerated | The type of the ID stored in the [GroupId](#groupid) field. <br><br>Supported values are `SID`, and `UID`. |

+| <a name="groupname"></a>**GroupName** | Optional | String | The group name, including domain information when available, for activities involving a group. <br><br>Use one of the following formats and in the following order of priority:<br>- **Upn/Email**: `grp@contoso.com`<br>- **Windows**: `Contoso\grp`<br>- **DN**: `CN=grp,OU=Sales,DC=Fabrikam,DC=COM`<br>- **Simple**: `grp`. Use the Simple form only if domain information isn't available.<br><br>Store the group name type in the [GroupNameType](#groupnametype) field. If other IDs are available, we recommend that you normalize the field names to **GroupUpn**, **GorupNameWindows**, and **GroupDn**.<br><br>Example: `Contoso\Finance` |

+| <a name="groupnametype"></a>**GroupNameType** | Optional | Enumerated | Specifies the type of the group name stored in the [GroupName](#groupname) field. Supported values include `UPN`, `Windows`, `DN`, and `Simple`.<br><br>Example: `Windows` |

+| **GroupType** | Optional | Enumerated | The type of the group, for activities involving a group. Supported values include:<br>- `Local Distribution`<br>- `Local Security Enabled`<br>- `Global Distribution`<br>- `Global Security Enabled`<br>- `Universal Distribution`<br>- `Universal Security Enabled`<br>- `Other`<br><br>**Note**: The value might be provided in the source record by using different terms, which should be normalized to these values. Store the original value in the [GroupOriginalType](#grouporiginaltype) field. |

+| <a name="grouporiginaltype"></a>**GroupOriginalType** | Optional | String | The original group type, if provided by the source. |

+|||||

+### Source fields

+| Field | Class | Type | Description |

+|-|-||-|

+| <a name="src"></a>**Src** | Recommended | String | A unique identifier of the source device. <br><br>This field might alias the [SrcDvcId](#srcdvcid), [SrcHostname](#srchostname), or [SrcIpAddr](#srcipaddr) fields. <br><br>Example: `192.168.12.1` |

+| <a name="srcipaddr"></a>**SrcIpAddr** | Recommended | IP address | The IP address of the source device. This value is mandatory if **SrcHostname** is specified.<br><br>Example: `77.138.103.108` |

+| <a name="ipaddr"></a>**IpAddr** | Alias | | Alias to [SrcIpAddr](#srcipaddr). |

+| <a name="srchostname"></a> **SrcHostname** | Recommended | String | The source device hostname, excluding domain information.<br><br>Example: `DESKTOP-1282V4D` |

+|<a name="srcdomain"></a> **SrcDomain** | Recommended | String | The domain of the source device.<br><br>Example: `Contoso` |

+| <a name="srcdomaintype"></a>**SrcDomainType** | Recommended | Enumerated | The type of [SrcDomain](#srcdomain), if known. Possible values include:<br>- `Windows` (such as `contoso`)<br>- `FQDN` (such as `microsoft.com`)<br><br>Required if [SrcDomain](#srcdomain) is used. |

+| **SrcFQDN** | Optional | String | The source device hostname, including domain information when available. <br><br>**Note**: This field supports both traditional FQDN format and Windows domain\hostname format. The [SrcDomainType](#srcdomaintype) field reflects the format used. <br><br>Example: `Contoso\DESKTOP-1282V4D` |

+| <a name="srcdvcid"></a>**SrcDvcId** | Optional | String | The ID of the source device as reported in the record.<br><br>Example: `ac7e9755-8eae-4ffc-8a02-50ed7a2216c3` |

+| **SrcDvcIdType** | Optional | Enumerated | The type of [SrcDvcId](#srcdvcid), if known. Possible values include:<br> - `AzureResourceId`<br>- `MDEid`<br><br>If multiple IDs are available, use the first one from the preceding list, and store the others in **SrcDvcAzureResourceId** and **SrcDvcMDEid**, respectively.<br><br>**Note**: This field is required if [SrcDvcId](#srcdvcid) is used. |

+| **SrcDeviceType** | Optional | Enumerated | The type of the source device. Possible values include:<br>- `Computer`<br>- `Mobile Device`<br>- `IOT Device`<br>- `Other` |

+| **SrcGeoCountry** | Optional | Country | The country associated with the source IP address.<br><br>Example: `USA` |

+| **SrcGeoRegion** | Optional | Region | The region within a country associated with the source IP address.<br><br>Example: `Vermont` |

+| **SrcGeoCity** | Optional | City | The city associated with the source IP address.<br><br>Example: `Burlington` |

+| **SrcGeoLatitude** | Optional | Latitude | The latitude of the geographical coordinate associated with the source IP address.<br><br>Example: `44.475833` |

+| **SrcGeoLongitude** | Optional | Longitude | The longitude of the geographical coordinate associated with the source IP address.<br><br>Example: `73.211944` |

+| | | | |

+### Acting Application

+| Field | Class | Type | Description |

+|-|-||-|

+| **ActingAppId** | Optional | String | The ID of the application used by the actor to perform the activity, including a process, browser, or service. <br><br>For example: `0x12ae8` |

+| **ActiveAppName** | Optional | String | The name of the application used by the actor to perform the activity, including a process, browser, or service. <br><br>For example: `C:\Windows\System32\svchost.exe` |

+| **ActingAppType** | Optional | Enumerated | The type of acting application. Supported values include: <br>- `Process` <br>- `Browser` <br>- `Resource` <br>- `Other` |

+| **HttpUserAgent** | Optional | String | When authentication is performed over HTTP or HTTPS, this field's value is the user_agent HTTP header provided by the acting application when performing the authentication.<br><br>For example: `Mozilla/5.0 (iPhone; CPU iPhone OS 12_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1` |

+|||||

+### Additional fields and aliases

+| Field | Class | Type | Description |

+|-|-||-|

+| <a name="hostname"></a>**Hostname** | Alias | | Alias to [DvcHostname](normalization-about-schemas.md#dvchostname). |

+|||||

+## Next steps

+For more information, see:

+- Watch the [ASIM Webinar](https://www.youtube.com/watch?v=WoGD-JeC7ng) or review the [slides](https://1drv.ms/b/s!AnEPjr8tHcNmjDY1cro08Fk3KUj-?e=murYHG)

+- [Advanced SIEM Information Model (ASIM) overview](normalization.md)

+- [Advanced SIEM Information Model (ASIM) schemas](normalization-about-schemas.md)

+- [Advanced SIEM Information Model (ASIM) parsers](normalization-parsers-overview.md)

+- [Advanced SIEM Information Model (ASIM) content](normalization-content.md)

+In this how-to article, you learn to use the Azure CLI with Bash to work with container objects.

+storageAccount="<storage-account>"

+ --account-name $storageAccount \

+for value in {2..5}

+ --account-name $storageAccount \

+containerList="${containerPrefix}6 ${containerPrefix}7 ${containerPrefix}8"

+ --account-name $storageAccount \

+storageAccount="<storage-account>"

+numResults="3"

+ --account-name $storageAccount \

+ --account-name $storageAccount \

+ --account-name $storageAccount \

+storageAccount="<storage-account>"

+ --account-name $storageAccount \

+ --account-name $storageAccount \

+for row in $containerList

+ tmpRow=$(echo $row | sed -e 's/\r//g')

+ az storage container show --name $tmpRow --account-name $storageAccount --auth-mode login

+The first example below updates and then retrieves a named container's metadata. The second example iterates the list of containers matching the `-prefix` value. Containers with names containing even numbers have their metadata set with values contained in the *metadata* variable.

+storageAccount="<storage-account>"

+containerName="demo-container-1"

+containerPrefix="demo-container-"

+# Update named container metadata

+ --account-name $storageAccount \

+ --account-name $storageAccount \

+# Get list of containers

+containerList=$(az storage container list \

+ --query "[].name" \

+ --prefix $containerPrefix \

+ --account-name $storageAccount \

+ --auth-mode login \

+ --output tsv)

+# Update and display metadata

+for row in $containerList

+do

+ #Get the container's number

+ tmpName=$(echo $row | sed -e 's/\r//g')

+ if [ `expr ${tmpName: ${#containerPrefix}} % 2` == 0 ]

+ then

+ az storage container metadata update \

+ --name $tmpName \

+ --metadata $metadata \

+ --account-name $storageAccount \

+ --auth-mode login

+

+ echo $tmpName

+ az storage container metadata show \

+ --name $tmpName \

+ --account-name $storageAccount \

+ --auth-mode login

+ fi

+done

+storageAccount="<storage-account>"

+ --account-name $storageAccount \

+ --account-name $storageAccount \

+ --auth-mode login \

+for row in $list

+ tmpName=$(echo $row | sed -e 's/\r//g')

+ --name $tmpName \

+ --account-name $storageAccount \

+If you have container soft delete enabled for your storage account, then it's possible to retrieve containers that have been deleted. If your storage account's soft delete data protection option is enabled, the `--include-deleted` parameter will return containers deleted within the associated retention period. The `--include-deleted` parameter can only be used to return containers when used with the `--prefix` parameter. To learn more about soft delete, refer to the [Soft delete for containers](soft-delete-container-overview.md) article.

+#!/bin/bash

+storageAccount="<storage-account>"

+containerPrefix="demo-container-"

+ --prefix $containerPrefix \

+ --account-name $storageAccount\

+The following examples explain how to restore a soft-deleted container with the `az storage container restore` command. You'll need to supply values for the `--name` and `--version` parameters to ensure that the correct version of the container is restored. If you don't know the version number, you can use the `az storage container list` command to retrieve it as shown in the first example. The second example finds and restores all deleted containers within a specific storage account.

+storageAccount="<storage-account>"

+ --account-name $storageAccount \

+ --include-deleted | sed -e 's/\r//g')

+ --account-name $storageAccount \

+# Restore a list of deleted containers

+containerList=$(az storage container list \

+ --account-name $storageAccount \

+ --include-deleted \

+ --auth-mode login \

+ --query "[?deleted].{name:name,version:version}" \

+ -o json)

+for row in $(echo "${containerList}" | jq -c '.[]' )

+do

+ tmpName=$(echo $row | jq -r '.name')

+ tmpVersion=$(echo $row | jq -r '.version')

+ az storage container restore \

+ --account-name $storageAccount \

+ --name $tmpName \

+ --deleted-version $tmpVersion \

+ --auth-mode login

+done

+The following example illustrates the process of configuring a service SAS for a specific container using the `az storage container generate-sas` command. Because it's generating a service SAS, the example first retrieves the storage account key to pass as the `--account-key` value.

+Copy and paste the Blob SAS token value in a secure location. It will only be displayed once and canΓÇÖt be retrieved once Bash is closed. To construct the SAS URL, append the SAS token (URI) to the URL for the storage service.

+storageAccount="<storage-account>"

+ --account-key $accountKey \

+ --account-name $storageAccount

+description: Learn how to mount a container in Blob Storage from an Azure virtual machine (VM) or a client that runs on-premises by using the NFS 3.0 protocol.

+# Mount Blob Storage by using the Network File System (NFS) 3.0 protocol

+This article provides guidance on how to mount a container in Azure Blob Storage from a Linux-based Azure virtual machine (VM) or a Linux system that runs on-premises by using the Network File System (NFS) 3.0 protocol. To learn more about NFS 3.0 protocol support in Blob Storage, see [Network File System (NFS) 3.0 protocol support in Azure Blob Storage](network-file-system-protocol-support.md).

+## Step 1: Create an Azure virtual network

+Your storage account must be contained within a virtual network. A virtual network enables clients to connect securely to your storage account. To learn more about Azure Virtual Network, and how to create a virtual network, see the [Virtual Network documentation](../../virtual-network/index.yml).

+> Clients in the same virtual network can mount containers in your account. You can also mount a container from a client that runs in an on-premises network, but you'll have to first connect your on-premises network to your virtual network. See [Supported network connections](network-file-system-protocol-support.md#supported-network-connections).

+Currently, the only way to secure the data in your storage account is by using a virtual network and other network security settings. Any other tools used to secure data, including account key authorization, Azure Active Directory (Azure AD) security, and access control lists (ACLs), are not yet supported in accounts that have the NFS 3.0 protocol support enabled on them.

+To mount a container by using NFS 3.0, you must create a storage account. You can't enable existing accounts.

+The NFS 3.0 protocol is supported for standard general-purpose v2 storage accounts and for premium block blob storage accounts. For more information on these types of storage accounts, see [Storage account overview](../common/storage-account-overview.md).

+To configure the account, choose these values:

+> By default, the root squash option of a new container is **No Root Squash**. But you can change that to **Root Squash** or **All Squash**. For information about these squash options, see your operating system documentation.

+> 

+Create a directory on your Linux system, and then mount the container in the storage account.

+1. On your Linux system, create a directory:

+2. Mount the container by using the following command:

+|Error | Cause/resolution|

+|`Access denied by server while mounting`|Ensure that your client is running within a supported subnet. See [Supported network locations](network-file-system-protocol-support.md#supported-network-connections).|

+|`No such file or directory`| Make sure to type, rather than copy and paste, the mount command and its parameters directly into the terminal. If you copy and paste any part of this command into the terminal from another application, hidden characters in the pasted information might cause this error to appear. This error also might appear if the account isn't enabled for NFS 3.0.|

+|`Permission denied`| The default mode of a newly created NFS 3.0 container is 0750. Non-root users don't have access to the volume. If access from non-root users is required, root users must change the mode to 0755. Sample command: `sudo chmod 0755 /mnt/<newcontainer>`|

+|`EINVAL ("Invalid argument"`) |This error can appear when a client attempts to:<li>Write to a blob that was created from a blob endpoint.<li>Delete a blob that has a snapshot or is in a container that has an active WORM (write once, read many) policy.|

+|`EROFS ("Read-only file system"`) |This error can appear when a client attempts to:<li>Write to a blob or delete a blob that has an active lease.<li>Write to a blob or delete a blob in a container that has an active WORM policy. |

+|`OperationNotSupportedOnSymLink` error| This error can be returned during a write operation via a Blob Storage or Azure Data Lake Storage Gen2 API. Using these APIs to write or delete symbolic links that are created by using NFS 3.0 is not allowed. Make sure to use the NFS 3.0 endpoint to work with symbolic links. |

+|`mount: /mnt/test: bad option;`| Install the NFS helper program by using `sudo apt install nfs-common`.|

+1. Once deployed, additional permissions are required.

+- In the Azure portal, assign other users of the workspace to the **Contributor** role in the workspace. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+- Assign other users the appropriate **[Synapse RBAC roles](security/synapse-workspace-synapse-rbac-roles.md)** using Synapse Studio.

+- A member of the **Owner** role of the Azure Storage account must assign the **Storage Blob Data Contributor** role to the Azure Synapse workspace MSI and other users.

+Azure PowerShell is a set of cmdlets for managing Azure resources directly from PowerShell. You can use it in your browser with Azure Cloud Shell. You can also install it on macOS, Linux, or Windows.

+If you don't have an Azure subscription, create a [free](https://azure.microsoft.com/free/) account before you begin.

+If you choose to use Cloud Shell, see [Overview of Azure Cloud Shell](../cloud-shell/overview.md) for more information.

+If you choose to use PowerShell locally, this article requires that you install the Az PowerShell module and connect to your Azure account using the [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) cmdlet. For more information about installing the Az PowerShell module, see [Install Azure PowerShell](/powershell/azure/install-az-ps).

+> While the **Az.Synapse** PowerShell module is in preview, you must install it separately using the `Install-Module` cmdlet. After this PowerShell module becomes generally available, it will be part of future Az PowerShell module releases and available by default from within Azure Cloud Shell.

+1. Once deployed, additional permissions are required.

+- In the Azure portal, assign other users of the workspace to the **Contributor** role in the workspace. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+- Assign other users the appropriate **[Synapse RBAC roles](security/synapse-workspace-synapse-rbac-roles.md)** using Synapse Studio.

+- A member of the **Owner** role of the Azure Storage account must assign the **Storage Blob Data Contributor** role to the Azure Synapse workspace MSI and other users.

+Next, you can [create SQL pools](quickstart-create-sql-pool-studio.md) or [create Apache Spark pools](quickstart-create-apache-spark-pool-studio.md) to start analyzing and exploring your data.

+* [Use serverless SQL pool](quickstart-sql-on-demand.md)

+This Azure Resource Manager (ARM) template will create an Azure Synapse workspace with underlying Data Lake Storage. The Azure Synapse workspace is a securable collaboration boundary for analytics processes in Azure Synapse Analytics.

+To create an Azure Synapse workspace, a user must have **Azure Contributor** role and **User Access Administrator** permissions, or the **Owner** role in the subscription. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+1. Once deployed, additional permissions are required.

+- In the Azure portal, assign other users of the workspace to the **Contributor** role in the workspace. For detailed steps, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md).

+- Assign other users the appropriate **[Synapse RBAC roles](security/synapse-workspace-synapse-rbac-roles.md)** using Synapse Studio.

+- A member of the **Owner** role of the Azure Storage account must assign the **Storage Blob Data Contributor** role to the Azure Synapse workspace MSI and other users.

+To learn more about Azure Synapse Analytics and Azure Resource Manager,

+Next, you can [create SQL pools](quickstart-create-sql-pool-studio.md) or [create Apache Spark pools](quickstart-create-apache-spark-pool-studio.md) to start analyzing and exploring your data.

+ Title: Azure Hybrid Benefit for BYOS Linux VMs

+description: Learn how Azure Hybrid Benefit can help get updates from Azure infrastructure for Linux machines on Azure.

+documentationcenter: ''

+# How Azure Hybrid Benefit for BYOS VMs (AHB BYOS) applies for Linux virtual machines

+>[!IMPORTANT]

+>The below article is scoped to Azure Hybrid Benefit for BYOS VMs (AHB BYOS) which caters to conversion of custom on-prem image VMs and RHEL or SLES BYOS VMs. For conversion of RHEL PAYG or SLES PAYG VMs, refer to [Azure Hybrid Benefit for PAYG VMs here](./azure-hybrid-benefit-linux.md).

+>[!NOTE]

+>Azure Hybrid Benefit for BYOS VMs is planned for Preview from **30 March 2022**. You can [sign up for the preview here.](https://aka.ms/ahb-linux-form) You will receive a mail from Microsoft once your subscriptions are enabled for Preview.

+Azure Hybrid Benefit for BYOS VMs is a licensing benefit that helps you to get software updates and integrated support for Red Hat Enterprise Linux (RHEL) and SUSE Linux Enterprise Server (SLES) virtual machines (VMs) directly from Azure infrastructure. This benefit is available to RHEL and SLES custom on-prem image VMs (VMs generated from o- prem images), and to RHEL and SLES Marketplace bring-your-own-subscription (BYOS) VMs.

+## Benefit description

+Before AHB BYOS, RHEL and SLES customers who migrated their on-prem machines to Azure by creating images of on-prem systems and migrating them as VMs on Azure did not have the flexibility to get software updates directly from Azure similar to Marketplace PAYG VMs. Hence, you needed to still buy cloud access licenses from the Enterprise Linux distributors to get security support as well as software updates. With Azure Hybrid Benefit for BYOS VMs, we will allow you to get software updates and support for on-prem custom image VMs as well as RHEL and SLES BYOS VMs similar to PAYG VMs by paying the same software fees as charged to PAYG VMs. In addition, these conversions can happen without any redeployment, so you can avoid any downtime risk.

+After you enable the AHB for BYOS VMs benefit on RHEL or SLES VM, you will be charged for the additional software fee typically incurred on a PAYG VM and you will also start getting software updates typically provided to a PAYG VM.

+You can also choose to convert a VM that has had the benefit enabled on it back to a BYOS billing model which will stop software billing and software updates from Azure infrastructure.

+## Scope of Azure Hybrid Benefit for BYOS VMs eligibility for Linux VMs

+**Azure Hybrid Benefit for BYOS VMs** is available for all RHEL and SLES custom on-prem image VMs as well as RHEL and SLES Marketplace BYOS VMs. For RHEL and SLES PAYG Marketplace VMs, [refer to AHB for PAYG VMs here](./azure-hybrid-benefit-linux.md)

+Azure Dedicated Host instances, and SQL hybrid benefits are not eligible for Azure Hybrid Benefit for BYOS VMs if you're already using the benefit with Linux VMs. Virtual Machine Scale Sets (VMSS) are Reserved Instances (RIs) are not in scope for AHB BYOS.

+## Get started

+### Red Hat customers

+To start using the benefit for Red Hat:

+1. Install the 'AHBForRHEL' extension on the virtual machine on which you wish to apply the AHB BYOS benefit. This is a prerequisite before moving to next step. You can do this via the portal or use Azure CLI.

+

+1. Depending on the software updates you want, change the license type to relevant value. Here are the available license type values and the software updates associated with them:

+ | License Type | Software Updates | Allowed VMs|

+ ||||

+ | RHEL_BASE | Installs Red Hat regular/base repositories into your virtual machine. | RHEL BYOS VMs, RHEL custom on-prem image VMs|

+ | RHEL_EUS | Installs Red Hat Extended Update Support (EUS) repositories into your virtual machine. | RHEL BYOS VMs, RHEL custom on-prem image VMs|

+ | RHEL_SAPAPPS | Installs RHEL for SAP Business Apps repositories into your virtual machine. | RHEL BYOS VMs, RHEL custom on-prem image VMs|

+ | RHEL_SAPHA | Installs RHEL for SAP with HA repositories into your virtual machine. | RHEL BYOS VMs, RHEL custom on-prem image VMs|

+ | RHEL_BASESAPAPPS | Installs RHEL regular/base SAP Business Apps repositories into your virtual machine. | RHEL BYOS VMs, RHEL custom on-prem image VMs|

+ | RHEL_BASESAPHA | Installs regular/base RHEL for SAP with HA repositories into your virtual machine.| RHEL BYOS VMs, RHEL custom on-prem image VMs|

+1. Wait for one hour for the extension to read the license type value and install the repositories.

+1. You should now be connected to Azure Red Hat Update Infrastructure and the relevant repositories will be installed in your machine.

+1. In case the extension is not running by itself, you can run it on demand as well.

+1. In case you want to switch back to the bring-your-own-subscription model, just change the license type to 'None' and run the extension. This will remove all RHUI repositories from your virtual machine and stop the billing.

+>[!Note]

+> In the unlikely event that extension is not able to install repositories or there are any issues, please change the license type back to empty and reach out to support for help. This will ensure you are not getting billed for software updates.

+### SUSE customers

+To start using the benefit for SUSE:

+1. Install the Azure Hybrid Benefit for BYOS VMs extension on the virtual machine on which you wish to apply the AHB BYOS benefit. This is a prerequisite before moving to next step.

+1. Depending on the software updates you want, change the license type to relevant value. Here are the available license type values and the software updates associated with them:

+ | License Type | Software Updates | Allowed VMs|

+ ||||

+ | SLES_STANDARD | Installs SLES standard repositories into your virtual machine. | SLES BYOS VMs, SLES custom on-prem image VMs|

+ | SLES_SAP | Installs SLES SAP repositories into your virtual machine. | SLES SAP BYOS VMs, SLES custom on-prem image VMs|

+ | SLES_HPC | Installs SLES High Performance Compute related repositories into your virtual machine. | SLES HPC BYOS VMs, SLES custom on-prem image VMs|

+1. Wait for 5 minutes for the extension to read the license type value and install the repositories.

+1. You should now be connected to Azure SLES Update Infrastructure and the relevant repositories will be installed in your machine.

+1. In case the extension is not running by itself, you can run it on demand as well.

+1. In case you want to switch back to the bring-your-own-subscription model, just change the license type to 'None' and run the extension. This will remove all repositories from your virtual machine and stop the billing.

+## Enable and disable the benefit for RHEL

+You can install the `AHBForRHEL` extension to install the extension. After successfully installing the extension,

+you can use the `az vm update` command to update existing license type on running VMs. For SLES VMs, run the command and set `--license-type` parameter to one of the following: `RHEL_BASE`, `RHEL_EUS`, `RHEL_SAPHA`, `RHEL_SAPAPPS`, `RHEL_BASESAPAPPS` or `RHEL_BASESAPHA`.

+### CLI example to enable the benefit for RHEL

+1. Install the Azure Hybrid Benefit extension on running VM using the portal or via Azure CLI using the command below:

+ ```azurecli

+ az vm extension set -n AHBForRHEL --publisher Microsoft.Azure.AzureHybridBenefit --vm-name myVMName --resource-group myResourceGroup

+ ```

+1. Once, the extension is installed successfully, change the license type based on your requirements:

+ ```azurecli

+ # This will enable the benefit to fetch software updates for RHEL base/regular repositories

+ az vm update -g myResourceGroup -n myVmName --license-type RHEL_BASE

+

+ # This will enable the benefit to fetch software updates for RHEL EUS repositories

+ az vm update -g myResourceGroup -n myVmName --license-type RHEL_EUS

+

+ # This will enable the benefit to fetch software updates for RHEL SAP APPS repositories

+ az vm update -g myResourceGroup -n myVmName --license-type RHEL_SAPAPPS

+

+ # This will enable the benefit to fetch software updates for RHEL SAP HA repositories

+ az vm update -g myResourceGroup -n myVmName --license-type RHEL_SAPHA

+

+ # This will enable the benefit to fetch software updates for RHEL BASE SAP APPS repositories

+ az vm update -g myResourceGroup -n myVmName --license-type RHEL_BASESAPAPPS

+

+ # This will enable the benefit to fetch software updates for RHEL BASE SAP HA repositories

+ az vm update -g myResourceGroup -n myVmName --license-type RHEL_BASESAPHA

+ ```

+1. Wait for 5 minutes for the extension to read the license type value and install the repositories.

+1. You should now be connected to Azure Red Hat Update Infrastructure and the relevant repositories will be installed in your machine. You can check the same by performing the command below on your VM which outputs installed repository packages on your VM:

+ ```bash

+ yum repolist

+ ```

+ 1. In case the extension is not running by itself, you can try the below command on the VM using:

+ ```bash

+

+ ```

+## Enable and disable the benefit for SLES

+You can install the `AHBForSLES` extension to install the extension. After successfully installing the extension,

+you can use the `az vm update` command to update existing license type on running VMs. For SLES VMs, run the command and set `--license-type` parameter to one of the following: `SLES_STANDARD`,`SLES_SAP` or `SLES_HPC`.

+### CLI example to enable the benefit for SLES

+1. Install the Azure Hybrid Benefit extension on running VM using the portal or via Azure CLI using the command below:

+ ```azurecli

+ az vm extension set -n AHBForSLES --publisher publisherName --vm-name myVMName --resource-group myResourceGroup

+ ```

+1. Once, the extension is installed successfully, change the license type based on your requirements:

+ ```azurecli

+ # This will enable the benefit to fetch software updates for SLES STANDARD repositories

+ az vm update -g myResourceGroup -n myVmName --license-type SLES_STANDARD

+ # This will enable the benefit to fetch software updates for SLES SAP repositories

+ az vm update -g myResourceGroup -n myVmName --license-type SLES_SAP

+ # This will enable the benefit to fetch software updates for SLES HPC repositories

+ az vm update -g myResourceGroup -n myVmName --license-type SLES_HPC

+ ```

+1. Wait for 5 minutes for the extension to read the license type value and install the repositories.

+1. You should now be connected to Azure SLES Update Infrastructure and the relevant repositories will be installed in your machine. You can check the same by performing the command below on your VM which outputs installed repository packages on your VM:

+ ```bash

+ zypper repos

+ ```

+

+### CLI example to disable the benefit

+1. Ensure that the Azure Hybrid Benefit extension is installed on your VM.

+1. To disable the benefit, follow below command:

+ ```azurecli

+ # This will disable the benefit on a VM

+ az vm update -g myResourceGroup -n myVmName --license-type None

+ ```

+## Check the AHB BYOS status of a VM

+To check the status of Azure Hybrid Benefit for BYOS VM status

+1. Ensure that the Azure Hybrid Benefit extension is installed:

+1. You can view the Azure Hybrid Benefit status of a VM by using the Azure CLI or by using Azure Instance Metadata Service.

+ You can use the below command for this purpose. Look for a `licenseType` field in the response. If the `licenseType` field exists and the value is one of the below, your VM has the benefit enabled:

+ `RHEL_BASE`, `RHEL_EUS`, `RHEL_BASESAPAPPS`, `RHEL_SAPHA`, `RHEL_BASESAPAPPS`, `RHEL_BASESAPHA`, `SLES_STANDARD`, `SLES_SAP`, `SLES_`

+ ```azurecli

+ az vm get-instance-view -g MyResourceGroup -n MyVm

+ ```

+## Compliance

+### Red Hat

+Customers who use Azure Hybrid Benefit for BYOS VMs for RHEL agree to the standard [legal terms](http://www.redhat.com/licenses/cloud_CSSA/Red_Hat_Cloud_Software_Subscription_Agreement_for_Microsoft_Azure.pdf) and [privacy statement](http://www.redhat.com/licenses/cloud_CSSA/Red_Hat_Privacy_Statement_for_Microsoft_Azure.pdf) associated with the Azure Marketplace RHEL offerings.

+### SUSE

+To use Azure Hybrid Benefit for BYOS VMs for your SLES VMs, and for information about moving from SLES PAYG to BYOS or moving from SLES BYOS to PAYG, see [SUSE Linux Enterprise and Azure Hybrid Benefit](https://aka.ms/suse-ahb).

+## Frequently asked questions

+*Q: What are the additional licensing cost I pay with AHB for BYOS VMs?*

+A: On using AHB for BYOS VMs, you will essentially convert your bring your own subscription (BYOS) billing model to pay as you go (PAYG) billing model. Hence, you will be paying similar to PAYG VMs for software subscription cost. The table below maps the PAYG flavors available on Azure and links to pricing page to help you understand the cost associated with AHB for BYOS VMs.

+| License type | Relevant PAYG VM image & Pricing Link (Keep the AHB for PAYG filter off) |

+||||

+| RHEL_BASE | [Red Hat Enterprise Linux](https://azure.microsoft.com/pricing/details/virtual-machines/red-hat/) |

+| RHEL_SAPAPPS | [RHEL for SAP Business Applications](https://azure.microsoft.com/pricing/details/virtual-machines/rhel-sap-business/) |

+| RHEL_SAPHA | [RHEL for SAP with HA](https://azure.microsoft.com/pricing/details/virtual-machines/rhel-sap-ha/) |

+| RHEL_BASESAPAPPS [RHEL for SAP Business Applications](https://azure.microsoft.com/pricing/details/virtual-machines/rhel-sap-business/) |

+| RHEL_BASESAPHA | [RHEL for SAP with HA](https://azure.microsoft.com/pricing/details/virtual-machines/rhel-sap-ha/) |

+| RHEL_EUS | [Red Hat Enterprise Linux](https://azure.microsoft.com/pricing/details/virtual-machines/red-hat/) |

+| SLES_ STANDARD | [SLES Standard](https://azure.microsoft.com/pricing/details/virtual-machines/sles-standard/) |

+| SLES_SAP | [SLES SAP](https://azure.microsoft.com/pricing/details/virtual-machines/sles-sap/) |

+| SLES_HPC | [SLES HPC](https://azure.microsoft.com/pricing/details/virtual-machines/sles-hpc-standard/) |

+*Q: Can I use a license type designated for RHEL (such as `RHEL_BASE`) with a SLES image, or vice versa?*

+A: No, you can't. Trying to enter a license type that incorrectly matches the distribution running on your VM will fail and you might end uo getting billed incorrectly. However, if you accidentally enter the wrong license type, either changing the license type to empty will remove the billing or updating your VM again to the correct license type will still enable the benefit.

+*Q: I've uploaded my own RHEL or SLES image from on-premises (via Azure Migrate, Azure Site Recovery, or otherwise) to Azure. Can I convert the billing on these images from BYOS to PAYG?*

+A: Yes, this is the capability AHB for BYOS VMs supports. Please [follow steps shared here](#get-started).

+*Q: Can I use Azure Hybrid Benefit for BYOS VMs on RHEL and SLES PAYG Marketplace VMs?*

+A: No, as these VMs are already pay-as-you-go (PAYG). However, with AHB v1 and v2 you can use the license type of `RHEL_BYOS` for RHEL VMs and `SLES_BYOS` for conversions of RHEL and SLES PAYG Marketplace VMs. You can read more on [AHB for PAYG VMs here.](./azure-hybrid-benefit-linux.md)

+*Q: Can I use Azure Hybrid Benefit for BYOS VMs on virtual machine scale sets for RHEL and SLES?*

+A: No, Azure Hybrid Benefit for BYOS VMs is not available for virtual machine scale sets currently.

+*Q: Can I use Azure Hybrid Benefit for BYOS VMs on a virtual machine deployed for SQL Server on RHEL images?*

+A: No, you can't. There is no plan for supporting these virtual machines.

+*Q: Can I use Azure Hybrid Benefit for BYOS VMs on my RHEL Virtual Data Center subscription?*

+A: No, you cannot. VDC is not supported on Azure at all, including AHB.

+

+## Next steps

+* [Learn how to convert RHEL and SLES PAYG VMs to BYOS using AHB for PAYG VMs](./azure-hybrid-benefit-linux.md)

+* [Learn how to create and update VMs and add license types (RHEL_BYOS, SLES_BYOS) for Azure Hybrid Benefit by using the Azure CLI](/cli/azure/vm)

+ Title: Azure Hybrid Benefit for PAYG Linux VMs

+# How Azure Hybrid Benefit for PAYG Marketplace VMs applies for Linux virtual machines

+>[!IMPORTANT]

+>The below article is scoped to Azure Hybrid Benefit for PAYG Marketplace VMs which caters to conversion of RHEL PAYG or SLES PAYG VMs to BYOS billing model. For, conversion of custom on-prem image VMs and RHEL or SLES BYOS VMs to PAYG billing model, refer to [Azure Hybrid Benefit for BYOS VMs here](./azure-hybrid-benefit-byos-linux.md).

+Azure Hybrid Benefit for PAYG VMs is a licensing benefit that helps you to significantly reduce the costs of running your Red Hat Enterprise Linux (RHEL) and SUSE Linux Enterprise Server (SLES) virtual machines (VMs) in the cloud. With this benefit, you pay for only the infrastructure costs of your VM because your RHEL or SLES subscription covers the software fee. The benefit is available for all RHEL and SLES Marketplace pay-as-you-go (PAYG) images.

+Through Azure Hybrid Benefit for PAYG VMs, you can migrate your on-premises RHEL and SLES servers to Azure by converting existing RHEL and SLES PAYG VMs on Azure to bring-your-own-subscription (BYOS) billing. Typically, VMs deployed from PAYG images on Azure will charge both an infrastructure fee and a software fee. With Azure Hybrid Benefit, PAYG VMs can be converted to a BYOS billing model without a redeployment, so you can avoid any downtime risk.

+## Scope of Azure Hybrid Benefit for PAYG VMs

+**Azure Hybrid Benefit for PAYG VMs** is available for all RHEL and SLES PAYG images from Azure Marketplace.

+**Azure Hybrid Benefit for BYOS VMs** is available for RHEL or SLES BYOS images or custom images from Azure Marketplace. You can [read more about AHB for BYOS VMs here.](./azure-hybrid-benefit-byos-linux.md)

+Azure Hybrid Benefit for PAYG VMs for RHEL is available to Red Hat customers who meet both of these criteria:

+1. Apply Azure Hybrid Benefit for PAYG VMs to any of your existing RHEL PAYG VMs and any new RHEL VMs that you deploy from Azure Marketplace PAYG images. You can use Azure portal or Azure CLI for enabling the benefit.

+Azure Hybrid Benefit for PAYG VMs for SUSE is available to customers who have:

+## Apply the Azure Hybrid Benefit for PAYG VMs at VM create time

+In addition to applying the Azure Hybrid Benefit for PAYG VMs to existing pay-as-you-go VMs, you can invoke it at the time of VM creation. The benefits of doing so are threefold:

+## Check the Azure Hybrid Benefit for PAYG VMs status of a VM

+You can view the Azure Hybrid Benefit for PAYG VMs status of a VM by using the Azure CLI or by using Azure Instance Metadata Service.

+Customers who use Azure Hybrid Benefit for PAYG RHEL VMs agree to the standard [legal terms](http://www.redhat.com/licenses/cloud_CSSA/Red_Hat_Cloud_Software_Subscription_Agreement_for_Microsoft_Azure.pdf) and [privacy statement](http://www.redhat.com/licenses/cloud_CSSA/Red_Hat_Privacy_Statement_for_Microsoft_Azure.pdf) associated with the Azure Marketplace RHEL offerings.

+Customers who use Azure Hybrid Benefit for PAYG RHEL VMs have three options for providing software updates and patches to those VMs:

+Customers who choose the RHUI option can continue to use RHUI as the main update source for their Azure Hybrid Benefit for PAYG RHEL VMs without attaching RHEL subscriptions to those VMs. Customers who choose the RHUI option are responsible for ensuring RHEL subscription compliance.

+Customers who choose either Red Hat Satellite Server or Red Hat Subscription Manager should remove the RHUI configuration and then attach a Cloud Access enabled RHEL subscription to their Azure Hybrid Benefit for PAYG RHEL VMs.

+For more information about Red Hat subscription compliance, software updates, and sources for Azure Hybrid Benefit for PAYG RHEL VMs, see the [Red Hat article about using RHEL subscriptions with Azure Hybrid Benefit](https://access.redhat.com/articles/5419341).

+To use Azure Hybrid Benefit for PAYG SLES VMs, and for information about moving from SLES PAYG to BYOS or moving from SLES BYOS to PAYG, see [SUSE Linux Enterprise and Azure Hybrid Benefit](https://aka.ms/suse-ahb).

+Customers who use Azure Hybrid Benefit for PAYG SLES VMs need to move the Cloud Update Infrastructure to one of three options that provide software updates and patches to those VMs:

+## Azure Hybrid Benefit for PAYG VMs on Reserved Instances

+Azure Reservations (Azure Reserved Virtual Machine Instances) help you save money by committing to one-year or three-year plans for multiple products. You can learn more about [Reserved instances here](../../cost-management-billing/reservations/save-compute-costs-reservations.md). The Azure Hybrid Benefit for PAYG VMs is available for [Reserved Virtual Machine Instance(RIs)](../../cost-management-billing/reservations/save-compute-costs-reservations.md#charges-covered-by-reservation).

+>If you have already purchased reservations for RHEL or SUSE PAYG software on Azure Marketplace, please wait for the reservation tenure to complete before using the Azure Hybrid Benefit for PAYG VMs.

+A: Yes, you can use the Azure Hybrid Benefit for BYOS VMs capability to do this. You can [learn more about this capability here.](./azure-hybrid-benefit-byos-linux.md)

+A: Yes, you can use the Azure Hybrid Benefit for BYOS VMs capability to do this. You can [learn more about this capability here.](./azure-hybrid-benefit-byos-linux.md)

+*Q: Can I use Azure Hybrid Benefit for PAYG VMs for Azure Marketplace RHEL and SLES SAP images?*

+*Q: Can I use Azure Hybrid Benefit for PAYG VMs on virtual machine scale sets for RHEL and SLES?*

+*Q: Can I use Azure Hybrid Benefit for PAYG VMs on reserved instances for RHEL and SLES?*

+A: Yes, Azure Hybrid Benefit for PAYG VMs on reserved instance for RHEL and SLES is available to all users. You can [learn more about this benefit and how to use it here](#azure-hybrid-benefit-for-payg-vms-on-reserved-instances).

+*Q: Can I use Azure Hybrid Benefit for PAYG VMs on a virtual machine deployed for SQL Server on RHEL images?*