The service principal used by Horizon Cloud to perform operations in your Microsoft Azure subscription and resource groups needs an assigned role that specifies the permitted operations that service principal can perform in that subscription and its resource groups. Even though using the Microsoft Azure built-in Contributor role provides for all of the operations needed by Horizon Cloud, it does that by granting the broadest number of permissions. Instead of using that Microsoft Azure built-in Contributor role at the subscription level, you can create a custom role with the minimum set of permissions — scoped to the minimum set of operations that Horizon Cloud requires in the associated subscription — and assign that custom role to the service principal at the subscription level. If you adopt the approach to have a separate subscription for the pod's external Unified Access Gateway configuration and select to have the gateway resources deployed into a resource group that you create and maintain, you have the option of assigning the service principal more granular, narrow-scope permissions within that separate subscription.

The overarching concept is that Horizon Cloud needs to perform certain operations in your subscription and its resource groups to successfully create and maintain the resources needed to have a pod and its gateway configurations. As a simple example, because the pod and gateway architecture require virtual machines with NICs, Horizon Cloud needs the ability to create virtual machines and NICs in your subscription and attach those NICs to subnets in the subscription's VNet. Some of the options you choose for your pod and gateway deployments determine the specific set of operations that Horizon Cloud needs to perform. You can restrict Horizon Cloud's abilities in your subscription to the minimum operations required, by following the rules described below, according to the options you are adopting for deploying a pod and for its external gateway configuration.

For details about custom roles in Microsoft Azure and the steps you take to create a custom role, see the Microsoft Azure documentation topic Custom roles for Azure resources. For details about how a role works, its structure, and the structure of the management operations, see Understand role definitions for Azure resources in the Microsoft Azure documentation. As described in that documentation topic, a role definition is a collection of permissions. This role definition is called the role for short. The role lists the management operations that can be performed, as well as operations that cannot be performed, by the service principal to which that role is assigned. A management operation is a combination of the resource and action performed on that resource.

Overview of the Available Use Cases

When discussing Horizon Cloud required operations in your Microsoft Azure subscriptions and resource groups, there are these use cases.

Note: The role for the service principal created for the subscription that is specified for the rest of the pod resources in the two-subscription use case must follow the same rules as needed for the single-subscription use case.
Use Case Description
A single subscription used by Horizon Cloud for pods and their external Unified Access Gateway configurations.

In this case, access must be granted to the service principal at the subscription level. The role assigned to the service principal at that level must allow the actions that Horizon Cloud needs to perform in your subscription to successfully create in that subscription the required resources and operate on those resources over time. As an example, in this case, the role must provide the ability to create the default resource groups, network security groups, virtual machines, and so on.

Two subscriptions, and you want Horizon Cloud to auto-create the gateway's required resource groups and resources in the external gateway's specified subscription, same as it does in the subscription for the rest of the pod resources.
  • One subscription specified to use for the external Unified Access Gateway configuration's resources
  • One subscription for the rest of the pod resources

When using this option, the service principal for each subscription must be granted access at the subscription level, with permissions that allow actions same as those for the single subscription use case described above.

Two subscriptions as above, but instead of having Horizon Cloud auto-create the external gateway's required resource groups and resources, you create a resource group in advance in that external gateway's specified subscription, and want Horizon Cloud to deploy the external gateway's resources into that existing resource group.

Two options for granting access to the service principal used for deploying the external gateway:

  • Grant access at the subscription level, same as in the above case.
  • Use the following combination:
    • At the subscription level, grant access using the built-in Reader role.
    • At the level of the named resource group, grant access using permissions defined in a custom role. The permissions granted at the resource-group level must provide for the operations that Horizon Cloud requires to perform in the resource group to deploy and configure the external gateway's resources there.

      In addition to the permissions on the resource group, Horizon Cloud needs the permissions to perform the following actions, depending on your deployment plans:

      • If this deployment will use subnets that you create in advance on that subscription's VNet, Horizon Cloud needs the ability to create NICs and network security groups (NSGs) on those subnets. The permissions required on the VNet that the subnet belongs to are Microsoft.Network/virtualNetworks/subnets/* and Microsoft.Network/networkSecurityGroups/*
      • If this deployment will have Horizon Cloud generate the subnets, in addition to the above Microsoft.Network/virtualNetworks/subnets/* and Microsoft.Network/networkSecurityGroups/* permissions, Horizon Cloud needs the ability to create the subnets. The permission required on the VNet is Microsoft.Network/virtualNetworks/write
      • If your external gateway deployment will specify using a public IP address, Horizon Cloud needs the ability to create public IP addresses in the named resource group. The permission required on the named resource group is Microsoft.Network/publicIPAddresses

When Using a Single Subscription for the Pod and Its Gateway Configurations or Using a Separate Subscription for the External Unified Access Gateway Configuration with Permissions Set at the Subscription Level

For these use cases, the permissions are assigned at the subscription level. For the custom role set on the service principal that you specify in the Subscription step in the Horizon Cloud workflows, the following actions are required in the custom role definition. The * (wild card character) grants access to all operations that match the string within the listed resource provider operation. For the descriptions of the operations, see the Microsoft Azure documentation at the links listed below.

Note: As of the July 2021 service release, when all of your Horizon Cloud pods are of manifest 2632 or later and your tenant is configured to use Universal Broker, the features of the Horizon Image Management Service and multi-pod image management are available to you. Those features requires the permissions listed in this table associated with the Azure Shared Image Gallery. For details of the additional requirements, see Horizon Image Management Service System Requirements in the Managing Horizon Images from the Cloud guide.
Table 1. Microsoft Azure Resource Operations that Must Be Permitted in the Custom Role When Assigning Permissions at the Subscription Level
Operation Description in the Microsoft Azure Documentation
Microsoft.Authorization/*/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftauthorization
Microsoft.Compute/*/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/availabilitySets/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/disks/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/images/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/locations/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/snapshots/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/virtualMachines/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/virtualMachineScaleSets/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.DBforPostgreSQL/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftdbforpostgresql
Microsoft.KeyVault/*/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftkeyvault
Microsoft.KeyVault/vaults/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftkeyvault
Microsoft.KeyVault/vaults/secrets/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftkeyvault
Microsoft.Network/loadBalancers/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/networkInterfaces/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/networkSecurityGroups/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/publicIPAddresses/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/virtualNetworks/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/virtualNetworks/write https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/virtualNetworks/checkIpAddressAvailability/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/virtualNetworks/subnets/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/virtualNetworks/virtualNetworkPeerings/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.ResourceHealth/availabilityStatuses/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftresourcehealth
Microsoft.Resources/subscriptions/resourceGroups/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftresources
Microsoft.Resources/deployments/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftresources
Microsoft.Storage/*/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftstorage
Microsoft.Storage/storageAccounts/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftstorage
Microsoft.Compute/galleries/read
Microsoft.Compute/galleries/write
Microsoft.Compute/galleries/delete
Microsoft.Compute/galleries/images/*
Microsoft.Compute/galleries/images/versions/*
https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/read
Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/write
https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftmarketplaceordering

The following JSON code block is an example to illustrate what a custom role definition named Horizon Cloud Pod might look like when it has the set of preceding operations. For a description of the properties and usage information, see the Custom role properties section in the Microsoft Azure documentation topic Custom roles for Azure resources. The ID is the unique ID of the custom role. When you create the custom role using Azure PowerShell or Azure CLI, this ID is automatically generated when you create a new role. As described in the Tutorial: Create a custom role for Azure resources using Azure CLI, mysubscriptionId1 is the ID of your own subscription.

Table 2. Sample JSON for a Role Permitting the Horizon Cloud Required Operations When Assigning Permissions at the Subscription Level
{
"Name": "Horizon Cloud Pod",
"Id": "uuid",
"IsCustom": true,
"Description": "Minimum set of Horizon Cloud pod required operations",
"Actions": [
  "Microsoft.Authorization/*/read"
  "Microsoft.Compute/*/read"
  "Microsoft.Compute/availabilitySets/*"
  "Microsoft.Compute/disks/*"
  "Microsoft.Compute/images/*"
  "Microsoft.Compute/locations/*"
  "Microsoft.Compute/virtualMachines/*"
  "Microsoft.Compute/virtualMachineScaleSets/*"
  "Microsoft.Compute/snapshots/*"
  "Microsoft.DBforPostgreSQL/*"
  "Microsoft.KeyVault/*/read"
  "Microsoft.KeyVault/vaults/*"
  "Microsoft.KeyVault/vaults/secrets/*"
  "Microsoft.Network/loadBalancers/*"
  "Microsoft.Network/networkInterfaces/*"
  "Microsoft.Network/networkSecurityGroups/*"
  "Microsoft.Network/publicIPAddresses/*"
  "Microsoft.Network/virtualNetworks/read"
  "Microsoft.Network/virtualNetworks/write"
  "Microsoft.Network/virtualNetworks/checkIpAddressAvailability/read"
  "Microsoft.Network/virtualNetworks/subnets/*"
  "Microsoft.Network/virtualNetworks/virtualNetworkPeerings/read"
  "Microsoft.Resources/subscriptions/resourceGroups/*"
  "Microsoft.ResourceHealth/availabilityStatuses/read"
  "Microsoft.Resources/deployments/*"
  "Microsoft.Storage/*/read"
  "Microsoft.Storage/storageAccounts/*"
  "Microsoft.Compute/galleries/read"
  "Microsoft.Compute/galleries/write"
  "Microsoft.Compute/galleries/delete"
  "Microsoft.Compute/galleries/images/*"
  "Microsoft.Compute/galleries/images/versions/*"
  "Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/read"
  "Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/write"
  ],
"NotActions": [],
"DataActions": [],
"NotDataActions": [],
"AssignableScopes": [
  "/subscriptions/mysubscriptionId1"
  ]
}

When Using a Separate Subscription for the External Unified Access Gateway Configuration, Deploying into a Custom Resource Group, with Reader Role at the Subscription Level and Additional Required Permissions Assigned at Granular Levels

For this use case, you can assign the built-in Reader role to the service principal at the subscription level, and then grant access at the level of the named resource group using a custom role that specifies the permissions in the following table. Some additional permissions on subnets and on the VNet are required, depending on your planned deployment options:

  • If this external gateway deployment will use subnets that you create in advance, Horizon Cloud needs the ability to create NICs and network security groups (NSGs) on those subnets. The permissions required on the VNet that the subnet belongs to are Microsoft.Network/virtualNetworks/subnets/* and Microsoft.Network/networkSecurityGroups/*
  • If this external gateway deployment will have Horizon Cloud generate the subnets, in addition to the above Microsoft.Network/virtualNetworks/subnets/* and Microsoft.Network/networkSecurityGroups/* permissions, Horizon Cloud needs the ability to create the subnets. The permission required on the subscription's VNet is Microsoft.Network/virtualNetworks/write
  • If your deployment will specify using a public IP address for the external gateway configuration, Horizon Cloud needs the ability to create public IP addresses in the named resource group. The permission required on the named resource group is Microsoft.Network/publicIPAddresses

The following permitted operations are required in the named resource group. The * (wild card character) grants access to all operations that match the string within the listed resource provider operation. For the descriptions of the operations, see the Microsoft Azure documentation at the links listed below.

Table 3. Microsoft Azure Resource Operations that Must Be Permitted on the Specified Resource Group
Operation Description in the Microsoft Azure Documentation
Microsoft.Authorization/*/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftauthorization
Microsoft.Compute/*/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/availabilitySets/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/disks/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/images/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/locations/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/snapshots/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/virtualMachines/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.Compute/virtualMachineScaleSets/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftcompute
Microsoft.DBforPostgreSQL/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftdbforpostgresql
Microsoft.KeyVault/*/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftkeyvault
Microsoft.KeyVault/vaults/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftkeyvault
Microsoft.KeyVault/vaults/secrets/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftkeyvault
Microsoft.Network/loadBalancers/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/networkInterfaces/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/publicIPAddresses/*, if your deployment will specify using a public IP address for the external gateway deployment. https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/virtualNetworks/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/virtualNetworks/checkIpAddressAvailability/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.Network/virtualNetworks/virtualNetworkPeerings/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftnetwork
Microsoft.ResourceHealth/availabilityStatuses/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftresourcehealth
Microsoft.Resources/subscriptions/resourceGroups/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftresources
Microsoft.Resources/deployments/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftresources
Microsoft.Storage/*/read https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftstorage
Microsoft.Storage/storageAccounts/* https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftstorage
Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/read
Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/write
https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftmarketplaceordering