The Horizon Cloud pod deployer needs a service principal to access and use your Microsoft Azure subscription's capacity for your Horizon Cloud pods. When you register a Microsoft Azure AD application, the service principal is also created. Also, you must generate an authentication key and assign a role to the service principal at the subscription level. If you are going to use the feature to have the external gateway use its own subscription, separate from the pod's, you must also perform similar steps for a service principal associated with that subscription.

For up-to-date and in-depth details and screenshots for creating a service principal, see the Microsoft Azure documentation's documentation topic How to: Use the portal to create an Azure AD application and service principal that can access resources.

Important: Each service principal that you configure for Horizon Cloud's use must be assigned an appropriate role in that service principal's associated subscription. The role to a service principal must allow the actions that Horizon Cloud needs to operated on the Horizon Cloud managed resources in that service principal's associated Microsoft Azure subscription. The service principal for the pod's subscription needs a role that allows for actions to successfully deploy the pod, to operate on the pod and the pod-managed resources to fulfill the administrator workflows initiated using the Horizon Cloud Administration Console, and to maintain the pod over time. When using a separate subscription for the pod's external Unified Access Gateway configuration, the service principal for that subscription needs a role that allows for actions to successfully deploy the resources needed for that gateway configuration, to operate on those Horizon Cloud-managed resources to fulfill the administrator workflows, and to maintain those gateway-related resources over time.

As described in Operations Required by Horizon Cloud in Your Microsoft Azure Subscriptions, the service principal must be granted access using one of the following methods:

  • At the subscription level, assign the Contributor role. The Contributor role is one of the Microsoft Azure built-in roles. The Contributor role is described in Built-in roles for Azure resources in the Microsoft Azure documentation.
  • At the subscription level, assign a custom role that you have set up to provide the service principal with the minimum set of permitted actions that Horizon Cloud needs for deployment of the pod-related resources and for ongoing administrator-initiated workflows and pod maintenance operations.
  • When using a separate subscription for the external Unified Access Gateway configuration and deploying into an existing resource group, an valid combination is to grant access to the service principal to access that resource group and associated VNet using a role that provides narrow-scope permissions plus grant access for the service principal to access the subscription using the built-in Reader role.

You perform these steps using the Microsoft Azure portal appropriate for your registered account. For example, there are specific portal endpoints for these Microsoft Azure clouds.

  • Microsoft Azure (standard global)
  • Microsoft Azure China
  • Microsoft Azure US Government
Note: When performing these steps, you can collect some of the values that you will need for the deployment wizard, as described in Subscription-Related Information for the Horizon Cloud Pod Deployment Wizard, specifically:
  • Application ID
  • Authentication key
Caution: Even though you can set the secret key's expiration duration to a specific timeframe, if you do that, you must remember to refresh the key before it expires or the associated Horizon Cloud pod will stop working. Horizon Cloud cannot detect or know what duration you set. For smooth operations, set the key's expiration to Never.

If you prefer not to set the expiration to Never and prefer instead to refresh the key before it expires, you must remember to log in to the Horizon Cloud Administration Console before the expiration date and enter the new key value in the associated pod's subscription information. For detailed steps, see the Update the Subscription Information Associated with Deployed Pods topic in the VMware Horizon Cloud Service on Microsoft Azure Administration Guide.

In the steps below, Step 7.a illustrates the service principal being granted access at the subscription level.

Prerequisites

If you want to assign a custom role to the service principal instead of the built-in Contributor role, verify that the custom role exists in your subscription. Verify that the custom role permits the management operations required by Horizon Cloud, as described in Operations Required by Horizon Cloud in Your Microsoft Azure Subscriptions.

Procedure

  1. From the Microsoft Azure portal's left navigation bar, click Microsoft Azure Active Directory menu item in the Microsoft Azure portal's main menu (Azure Active Directory), then click App Registrations menu item in Azure portal's Azure AD submenu (App registrations).
  2. Click New application registration.
  3. Type a descriptive name and select a supported account type.
  4. In the Redirect URI section, select Web, type http://localhost:8000, and click Register.
    Option Description
    Name The name is up to you. The name is a way you can differentiate this service principal used by Horizon Cloud from any other service principals that might exist in this same subscription.
    Redirect URI Ensure Web is selected.

    Type http://localhost:8000 as shown. Microsoft Azure marks this as a required field. Because Horizon Cloud does not need a sign-on URL for the service principal http://localhost:8000 is used to satisfy the Microsoft Azure requirement.

    The newly created app registration is displayed on screen.
  5. Copy the application ID and directory (tenant) ID and save them to a location where you can retrieve them later when you run the deployment wizard.

    Screen of the service principal's details with an arrow pointing to the Application ID.

  6. From the service principal's details screen, create the service principal's authentication secret key.
    1. Click Certificates and secrets menu item in the Microsoft Azure portal (Certificates and secrets).
    2. Click New client secret.
    3. Type a description, select an expiration duration, and click Add.
      The key description must be 16 characters or less, for example Hzn-Cloud-Key1.
      Caution: You can set the expiration duration to Never or to a specific timeframe. However, if you set a specific duration, you must remember to refresh the key before it expires and enter the new key into the pod's subscription information in the Horizon Cloud Administration Console. Otherwise, the associated pod will stop working. Horizon Cloud cannot detect or know what duration you set.

      Keys screen showing new key being added with never expires duration.

      Important: Keep this screen open until you copy the secret value and paste the value into a location where you can retrieve it later. Do not close the screen until you have copied the secret value.

      Authentication key displayed in Client secrets screen with value pixelated out.

    4. Copy the secret value to a location where you can retrieve it later when you run the deployment wizard.
  7. Assign a role to the service principal at the subscription level.
    Caution: If the service principal's assigned role does not permit the operations that the pod deployer requires, according to the options you select in the deployment wizard, the wizard will block you from completing the wizard's steps. For the permissions the assigned role must provide, see Operations Required by Horizon Cloud in Your Microsoft Azure Subscriptions.
    1. Navigate to your subscription's settings screen by clicking All services in the Microsoft Azure portal's main navigation bar, clicking Subscriptions, and then clicking the name of the subscription that you will use with the pod.
      Note: At this point, from the screen, you can copy the subscription ID which you will later need in the deployment wizard.

      Subscription details in the Azure portal with IDs pixelated out and a green arrow pointing to the ID.

    2. Click Access Control (IAM) menu item (Access control (IAM)) and then click Add > Add role assignment to open the Add role assignment screen.
    3. In the Add role assignment screen, for Role, select the role you are assigning, according to the rules described in Operations Required by Horizon Cloud in Your Microsoft Azure Subscriptions.
    4. Use the Select box to search for your service principal by the name you gave it.
      The following screenshot illustrates this step where the Contributor role is selected for the service principal.
      Screenshot of the Azure portal's Add permissions screen with Owner role selected and searching for the service principal.

      Note: Make sure the Assign access to drop-down list is set to Azure AD user, group, or application.
    5. Click your service principal to make it a selected member and then click Save.

      In the Add permissions screen, the service principal added as a selected member of Owner role.

  8. Verify that your subscription has the registered resource providers that the pod requires.
    1. From the Access control (IAM) screen you are on from the previous step, navigate to the subscription's list of resource providers by clicking Resource providers menu choice in the Subscription settings menu (Resource providers) in the subscription's menu.
    2. Verify that the following resource providers have Icon of Registered status in the Azure portal for a resource provider (Registered) status, and if not, register them.
      • Microsoft.Compute
      • microsoft.insights
      • Microsoft.Network
      • Microsoft.Storage
      • Microsoft.KeyVault
      • Microsoft.Authorization
      • Microsoft.Resources
      • Microsoft.ResourceHealth
      • Microsoft.DBforPostgreSQL
      • Microsoft.Sql

      Resource providers screen with a green arrow pointing to one that is unregistered.

Results

At this point, you've created and configured the service provider for the pod, and you have the subscription-related values you need in the first step of the pod deployment wizard. The four subscription-related values are:

  • Subscription ID
  • Azure Active Directory ID
  • Application ID
  • Application key value

What to do next

Verify that you have collected all of the subscription-related information you will enter in the deployment wizard. See Subscription-Related Information for the Horizon Cloud Pod Deployment Wizard.

If you are going to use a separate subscription for deploying the external Unified Access Gateway configuration into an existing resource group, and you want to grant granular, narrow-scope permissions instead of access at the subscription level, see Operations Required by Horizon Cloud in Your Microsoft Azure Subscriptions for details. Ensure the appropriate access is granted to the service principal to meet the Horizon Cloud deployer's requirements.