For first-gen Horizon Cloud Service on Microsoft Azure deployments, the service uses API calls to deploy the pod into a Microsoft Azure subscription and manage that pod and the pod-provisioned VDI desktops and farms. To provide the ability for first-gen Horizon Cloud to use its API calls in the pod's subscription, you create an app registration.

Important: Use this page solely when you have access to a first-gen tenant environment in the first-gen control plane. As described in KB-92424, the first-gen control plane has reached end of availability (EOA). See that article for details.

Brief Introduction

For the initial deployment of the pod, the pod deployer calls the APIs in the Microsoft Azure subscription that you have chosen to use for the pod. These API calls perform actions in the pod's subscription to create items such as the pod manager VM, the VM's NICs, the network security groups (NSGs) on those NICS — all of the resources that a Horizon Cloud pod requires.

Then, after pod deployment, Horizon Cloud must continue to have the ability call APIs in the pod's subscription. Post-pod-deployment, the service uses API calls to create the base image VMs for the golden images, run sysprep on the golden images, create farm hosts and VDI desktop VMs, add and edit the pod's gateway configurations, and to maintain and upgrade the pod.

Create the App Registration Before Running the Pod Deployer

Because the pod deployer needs to call the APIs during the pod deployment process for programmatically creating the pod's resources within the pod's subscription, the app registration and client secret key must exist before you start the deployment wizard. Creation of the app registration automatically creates a service principal object in the pod subscription.

The client secret key must be generated in the Azure Portal and a role assigned to the Horizon Cloud app registration to operate at the level of the pod's subscription.

If you want to use the feature where the external Unified Access Gateway configuration is deployed in its own subscription, separate from the pod's subscription, Horizon Cloud must also have the ability to call APIs in that subscription at the time you run the wizard to deploy that external gateway. In this case, an app registration and client secret key are needed in that subscription in addition to the ones for the pod's subscription.

About Assigning a Role to the App Registration

The Horizon Cloud app registration must have an assigned role in the pod's subscription. Typically the built-in Contributor role is the role used by Horizon Cloud with the pod's subscription. The reason why the Contributor role is used is because this role covers all of the API calls that Horizon Cloud would need to perform within the pod's subscription.

The role assignment must be a direct assignment. The use of a group-based assignment of a role — in which the role is assigned to a group and the app registration is a member in that group — is currently unsupported.

If your organization prefers to avoid use of the Contributor role in the pod's subscription, Horizon Cloud also supports use of a custom role instead. If used, the custom role needs to provide for the specific API calls that Horizon Cloud needs to use. For more information, see the Custom Roles section near the bottom of this page.

Register Resource Providers

In the pod's subscription, the following resource providers must all have Registered status. You might see that some of the resource providers in this list already have Registered status while others do not. That is a result of standard Microsoft Azure behavior, where they have a set of resource providers typically registered for all Azure subscriptions.

You will want to ensure these listed resource providers have Registered status before running the pod deployment wizard. At the wizard's final step, it will validate that these resource providers have Registered status and will prevent the start of the pod deployment if one is unregistered.

  • Microsoft.Compute
  • microsoft.insights
  • Microsoft.Network
  • Microsoft.Storage
  • Microsoft.KeyVault
  • Microsoft.Authorization
  • Microsoft.Resources
  • Microsoft.ResourceHealth
  • Microsoft.ResourceGraph
  • Microsoft.Security
  • Microsoft.DBforPostgreSQL
  • Microsoft.Sql
  • Microsoft.MarketplaceOrdering

The following screenshot is an illustration of seeing the Registered status and unregistered status in the Azure portal.


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

To verify the resource providers in the pod's subscription:

  1. Log in to the Azure portal and search for the subscription into which you plan to deploy the pod.
  2. Click the subscription name and scroll down until you see Resource providers menu choice in the Subscription settings menu (Resource providers).
  3. Look for the resource provides in the preceding list and verify that they each display Icon of Registered status in the Azure portal for a resource provider (Registered) status.

    For any resource provide from the preceding list that you see as NotRegistered, use the portal to register it.

Creating the Horizon Cloud App Registration

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 Commercial (standard global regions)
  • Microsoft Azure China
  • Microsoft Azure US Government

When you are going to use the Horizon Cloud feature where the external gateway uses its own subscription, separate from the pod's, you would repeat the steps in that subscription for its app registration.

To complete all of the following steps in the Azure Portal yourself, your portal login must have sufficient permissions to create an app registration and assign a role to that app registration in the subscription into which you plan to deploy the pod. If you are not the owner or administrator of that subscription, ask one of them if you have the required permissions to create an app registration and assign a role to that app registration.

  1. Log in to the Microsoft Azure portal using credentials that have the ability to register applications
  2. In the portal's search bar, search for App registrations, and click App registrations when you see it appear in the results list.
    Screenshot that demonstrates searching in the Azure Portal for the words App registrations and seeing it appear in the results

    The portal displays the App registrations page.

  3. On the App registrations page, click New registration.
    Screenshot illustrating the location of the New registration action on the Azure Portal's App registrations page
  4. Type a display name that will remind you this registration is for Horizon Cloud use.
  5. Select Accounts in this organizational directory only.
  6. Leave the optional Redirect URI section in its default, empty state.
  7. Click the Register button to complete creating the app registration.

    The newly created app registration is displayed on screen.

  8. Copy the application ID and directory ID and save them to a location where you can retrieve them later when you run the deployment wizard. The following screenshot illustrates an app registration named Hzn-Cloud-Principal and a green arrow pointing to where the application ID and directory ID are displayed.
    Screen of the service principal's details with an arrow pointing to the Application ID.

  9. Then create the app registration's client secret key:
    1. In the preceding screenshot, see where Certificates and secrets menu item in the Microsoft Azure portal appears. In the Azure portal, on your newly created app registration page, click Certificates and secrets).
    2. Click New client secret.
    3. As illustrated in the following screenshot, the portal displays the Add a client secret screen. Type a description, select an expiration duration, and click Add. The key description must be 16 characters or less, for example Hzn-Cloud-Key1.
      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.

      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. The wizard has a field into which you paste this value.
  10. Add a role assignment to the Horizon Cloud app registration. Assign the role at the subscription level:
    1. Navigate to the 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 into which you plan to have the pod deployer deploy the pod.
      Note: At this point, from the screen, note 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 Contributor role.

      If your organization has said they prefer that a custom role be used for Horizon Cloud, select the custom role that your organization set up for this purpose.

    4. In Assign access to drop-down list, select Azure AD user, group, or application.
    5. Use the Select box to search for the Horizon Cloud app registration's name. The following screenshot illustrates this step.
      Screenshot of the Azure portal's Add permissions screen with Owner role selected and searching for the service principal.

    6. Click the name that you gave to your created Horizon Cloud app registration 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.

Summary

At this point, you've created and configured the Horizon Cloud app registration, confirmed the registration status of the resource providers that Horizon Cloud requires, and you have the subscription-related values you will need to enter into 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
Note: Horizon Cloud cannot detect or know what expiration duration you set for the app registration's client secret key. To ensure that Horizon Cloud can continue using this app registration to make its necessary API calls to manage the pod and its resources, you must remember to refresh the key before the key's expiration date is reached and then enter the new key into your Horizon Cloud environment. Currently, the longest expiration duration that one can set using the Microsoft Azure portal is two (2) years. If the key expires at the end of two years and you have not refreshed it or entered new key information into your Horizon Cloud environment for use with the pod, the pod associated with the expired key will stop working. If you prefer to create a secret key with a lifetime longer than the two years that the Microsoft Azure portal's user interface allows, Microsoft Azure currently provides that ability using PowerShell, Azure CLI, or Graph API.

Custom Roles and the Horizon Cloud App Registration

When your organization prefers to avoid use of the Contributor role in the pod's subscription, your organization can create a custom role instead and have that assigned to the Horizon Cloud app registration. The custom role must be configured so that it permits the API calls required by Horizon Cloud. If your organization prefers to avoid use of the Contributor role in the pod's subscription, refer to the information in First-Gen Tenants - When Your Organization Prefers to Use a Custom Role for the First-Gen Horizon Cloud App Registration.