Microsoft Azure Resource Manager cloud environments

Follow the guidance in this article when using the Microsoft Azure Resource Manager to provision virtual machines in your Citrix Virtual Apps or Citrix Virtual Desktops service deployment.

We assume you are familiar with the following:

• Azure Active Directory: https://docs.microsoft.com/en-in/azure/active-directory/fundamentals/active-directory-whatis/
• Consent framework: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/plan-an-application-integration
• Service principal: https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals/

Azure on-demand provisioning

With Azure on-demand provisioning, VMs are created only when Citrix Virtual Apps and Desktops initiates a power-on action, after the provisioning completes.

When you use MCS to create machine catalogs in the Azure Resource Manager, the Azure on-demand provisioning feature:

• Reduces your storage costs
• Provides faster catalog creation

When you create an MCS catalog, the Azure portal displays the network security group, network interfaces, base images, and identity disks in the resource groups.

The Azure portal does not show a VM until Citrix Virtual Apps and Desktops initiates a power-on action for it. Then, the VM’s status in the Full Configuration interface changes to On. There are two types of machines with the following differences:

• For a pooled machine, the operating system disk and write-back cache exist only when the VM exists. When you shut down a pooled machine in the console, the VM is not visible in the Azure portal. There is a significant storage cost saving if you routinely shut down machines (for example, outside of working hours).
• For a dedicated machine, the operating system disk is created the first time the VM is powered on. The VM in the Azure portal remains in storage until the machine identity is deleted. When you shut down a dedicated machine in the console, the VM is still visible in the Azure portal.

Connection to Azure Resource Manager

Create and manage connections describes the wizards that create a connection. The following information covers details specific to Azure Resource Manager connections.

Considerations:

• Citrix recommends using Service Principal with contributor role. However, see Minimum permissions section to get the list of minimum permissions.
• When creating the first connection, Azure prompts you to grant it the necessary permissions. For future connections you must still authenticate, but Azure remembers your previous consent and does not display the prompt again.
• Accounts used for authentication must be a co-administrator of the subscription.
• The account used for authentication must be a member of the subscription’s directory. There are two types of accounts to be aware of: ‘Work or School’ and ‘personal Microsoft account.’ See CTX219211 for details.

• While you can use an existing Microsoft account by adding it as a member of the subscription’s directory, there can be complications if the user was previously granted guest access to one of the directory’s resources. In this case, they might have a placeholder entry in the directory that does not grant them the necessary permissions, and an error is returned.

  Rectify this by removing the resources from the directory and add them back explicitly. However, exercise this option carefully, because it has unintended effects for other resources that account can access.

• There is a known issue where certain accounts are detected as directory guests when they are actually members. Configurations like this typically occurs with older established directory accounts. Workaround: add an account to the directory, which takes the proper membership value.
• Resource groups are simply containers for resources, and they can contain resources from regions other than their own region. This can potentially be confusing if you expect resources displayed in a resource group’s region to be available.
• Ensure that your network and subnet are large enough to host the number of machines you require. This requires some foresight, but Microsoft helps you specify the right values, with guidance about the address space capacity.

You can establish a host connection to Azure in two ways:

• Authenticate to Azure to create a service principal.
• Use the details from a previously created service principal to connect to Azure.

Create a service principal

Important:

This feature is not yet available for Azure China and Azure Germany subscriptions.

Before you start, authenticate to Azure. Ensure:

• You have a user account in your subscription’s Azure Active Directory tenant.
• The Azure AD user account is also a co-administrator for the Azure subscription that you want to use for provisioning resources.
• You have global administrator, application administrator, or application developer permissions for authentication. The permissions can be revoked after you create host connection. For more information about roles, see Azure AD built-in roles.

When you authenticate to Azure to create a service principal, an application is registered in Azure. A secret key (client secret) is created for the registered application. The registered application uses the client secret to authenticate to Azure AD. Be sure to change the client secret before it expires. You receive an alert on the console before the secret key expires. See Application secret and secret expiration date.

To authenticate to Azure to create a service principal, complete the following steps in the Add Connection and Resources wizard:

1. On the Connection page, select Create a new connection, the Microsoft Azure connection type, and your Azure environment.

2. Select which tools to use to create the virtual machines and then select Next.

3. On the Connection Details page, enter your Azure subscription ID and a name for the connection. After you enter the subscription ID, the Create new button is enabled.

   Note:

   The connection name can contain 1–64 characters, and cannot contain only blank spaces nor the characters \/;:#.*?=<>|[]{}"'()'.

4. Select Create new and then enter the Azure Active Directory account user name and password.

5. Select Sign in.

6. Select Accept to give Citrix Virtual Apps and Desktops the listed permissions. Citrix Virtual Apps and Desktops creates a service principal that allows it to manage Azure resources on behalf of the specified user.

7. After you select Accept, you return to the Connection page in the wizard.

   Note:

   After you successfully authenticate to Azure, the Create new and Use existing buttons disappear. The Connection successful text appears, with a green check mark, indicating the successful connection to your Azure subscription.

8. On the Connection Details page, select Next.

   Note:

   You cannot proceed to the next page until you successfully authenticate to Azure and consent to giving the required permissions.

9. Configure resources for the connection. Resources comprise the region and the network.

   • On the Region page, select a region.
   • On the Network page, do the following:
     • Type a 1–64 character resource name to help identify the region and network combination. A resource name cannot contain only blank spaces nor the characters \/;:#.*?=<>|[]{}"'()'.
     • Select a virtual network/resource group pair. (If you have more than one virtual network with the same name, pairing the network name with the resource group provides unique combinations.) If the region you selected on the previous page does not have any virtual networks, return to that page and select a region that has virtual networks.

10. On the Summary page, view a summary of settings and select Finish to complete your setup.

Use the details from a previously created service principal to connect to Azure

To create a service principal manually, connect to your Azure Resource Manager subscription and use the PowerShell cmdlets provided in the following sections.

Prerequisites:

• SubscriptionId: Azure Resource Manager SubscriptionID for the subscription where you want to provision VDAs.
• ActiveDirectoryID: Tenant ID of the application that you registered with Azure AD.
• ApplicationName: Name for the application to be created in Azure AD.

To create a service principal:

1. Connect to your Azure Resource Manager subscription.

   Connect-AzAccount

2. Select the Azure Resource Manager subscription where you want to create the service principal.

   Get-AzSubscription -SubscriptionId $subscriptionId | Select-AzSubscription

3. Create the application in your AD tenant.

   $AzureADApplication = New-AzADApplication -DisplayName $ApplicationName

4. Create a service principal.

   New-AzADServicePrincipal -ApplicationId $AzureADApplication.AppId

5. Assign a role to the service principal.

   New-AzRoleAssignment -RoleDefinitionName Contributor -ServicePrincipalName $AzureADApplication.AppId –scope /subscriptions/$SubscriptionId

6. From the output window of the PowerShell console, note the ApplicationId. You provide that ID when creating the host connection.

In the Add Connection and Resources wizard:

1. On the Connection page, select Create a new connection, the Microsoft Azure connection type, and your Azure environment.

2. Select which tools to use to create the virtual machines and then select Next.

3. On the Connection Details page, enter your Azure subscription ID and a name for the connection.

   Note:

   The connection name can contain 1–64 characters, and cannot contain only blank spaces nor the characters \/;:#.*?=<>|[]{}"'()'.

4. Select Use existing. In the Existing Service Principal Details window, enter the following settings for the existing service principal. After you enter the details, the Save button is enabled. Select Save. You cannot progress beyond this page until you provide valid details.

   • Subscription ID. Enter your Azure subscription ID. To obtain your subscription ID, sign in to the Azure portal and navigate to Subscriptions > Overview.
   • Active Directory ID (tenant ID). Enter the Directory (tenant) ID of the application that you registered with Azure AD.
   • Application ID. Enter the Application (client) ID of the application that you registered with Azure AD.
   • Application secret. Create a secret key (client secret). The registered application uses the key to authenticate to Azure AD. We recommend that you change keys regularly for security purposes. Be sure to save the key because you cannot retrieve the key later. See Application secret and secret expiration date.

   • Secret expiration date. Enter the date after which the application secret expires. You receive an alert on the console before the secret key expires. However, if the secret key expires, you receive errors.

     Note:

     For security purposes, the expiration period cannot be more than two years from now.

   • Authentication URL. This field is automatically populated and is not editable.
   • Management URL. This field is automatically populated and is not editable.
   • Storage suffix. This field is automatically populated and is not editable.

5. After selecting Save, you return to the Connection Details page. Select Next to proceed to the next page.

6. Configure resources for the connection. Resources comprise the region and the network.

   • On the Region page, select a region.
   • On the Network page, do the following:
     • Type a 1–64 character resource name to help identify the region and network combination. A resource name cannot contain only blank spaces nor the characters \/;:#.*?=<>|[]{}"'()'.
     • Select a virtual network/resource group pair. (If you have more than one virtual network with the same name, pairing the network name with the resource group provides unique combinations.) If the region you selected on the previous page does not have any virtual networks, return to that page and select a region that has virtual networks.

7. On the Summary page, view a summary of settings and select Finish to complete your setup.

Application secret and secret expiration date

View the application ID

You can view the application ID in the Full Configuration interface.

In the Add Connection and Resources wizard, select the connection to view the details. The Details tab shows the Application ID.

View the application secret

You can view the application secret in the Azure portal.

1. Get the Application ID from the Full Configuration interface.
2. Sign in to the Azure portal.
3. In Azure, select Azure Active Directory.
4. From App registrations in Azure AD, select your application.
5. Go to Certificates & secrets.
6. Click Client secrets.

Change the secret expiration date

Use the Full Configuration interface to add or modify the expiration date for the application secret in use.

1. In the Add Connection and Resources wizard, right-click a connection, and click Edit Connection.
2. On the Connection Properties page, click Secret expiration date to add or modify the expiration date for the application secret in use.

Create a new application secret

You can create a new application secret of a connection through the Azure portal.

1. Select Azure Active Directory.
2. From App registrations in Azure AD, select your application.
3. Go to Certificates & secrets.

4. Click Client secrets > New client secret.

   

5. Provide a description of the secret and specify a duration. When you are done, select Add.

   Note:

   Be sure to save the client secret because you cannot retrieve it later.

6. Copy the client secret value and the expiration date.
7. In the Full Configuration interface, edit the corresponding connection and replace the content in the Application secret and Secret expiration date field with the values you copied.

Create a machine catalog using an Azure Resource Manager image

This information is a supplement to the guidance in Create machine catalogs.

An image is the template that is used to create the VMs in a machine catalog. Before creating the machine catalog, create an image in Azure Resource Manager. For general information about images, see Create machine catalogs.

Tip:

Use of unmanaged disk to provision VM is deprecated.

In the machine catalog creation wizard:

• The Machine Type and Machine Management pages do not contain Azure-specific information. Follow the guidance in the Create machine catalogs article.

• On the Master Image page, select an image that you want to use as the master image for all machines in the catalog. The Select an image wizard appears. Select a subscription where the image resides, select a resource group, and then navigate to the Azure VHD, or the Azure Compute Gallery (formerly Shared Image Gallery), or the Azure image version.

  When selecting an image, consider the following:

  • Verify that a Citrix VDA is installed on the image.
  • If you select a VHD attached to a VM, you must shut down the VM before proceeding to the next step.

  Note:

  • The subscription corresponding to the connection (host) that created the machines in the catalog is denoted with a green dot. The other subscriptions are those that have the Azure Compute Gallery shared with that subscription. In those subscriptions, only shared galleries are shown.
  • Using a machine profile with trusted launch as Security Type is mandatory when you select an image or snapshot that has trusted launch enabled. You can then enable or disable SecureBoot and vTPM by specifying their values in the Machine Profile. Trusted Launch is not supported for Shared Image Gallery. For information about Azure trusted launch, see https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch.
  • You can create a provisioning scheme using ephemeral OS disk on Windows with trusted launch. When you select an image with trusted launch, then you must select a machine profile with trusted launch that is enabled with vTPM. To create machine catalogs using ephemeral OS disk, see How to create machines using ephemeral OS disks.
  • When image replication is in progress, you can proceed and select the image as the master image and complete the setup. However, catalog creation might take longer to complete while the image is being replicated. MCS requires the replication to complete within an hour starting from catalog creation. If the replication times out, catalog creation fails. You can verify the replication status in Azure. Try again if the replication is still pending or after the replication completes.
  • When you select a master image for machine catalogs in Azure, MCS identifies the OS type based on the master image and machine profile you select. If MCS can’t identify it, select the OS type that matches the master image.

  To enable VMs in the catalog to inherit configurations from a machine profile, select the Use a machine profile check box. From the resource group list, locate a resource group as needed. Next, in the resource group, select a VM or ARM template spec to use as the machine profile.

  Validate the ARM template spec to make sure whether it can be used as a machine profile to create a machine catalog. There are two ways to validate the ARM template spec:

  • After you select the ARM template spec from the resource group list, click Next. Error messages appear if the ARM template spec has errors.
  • Run one of the following PowerShell commands:
    • Test-ProvInventoryItem -HostingUnitName <string> -InventoryPath <string>
    • Test-ProvInventoryItem -HostingUnitUid <Guid> -InventoryPath <string>

  Examples of configurations that VMs can inherit from a machine profile include:

  • Accelerated networking
  • Boot diagnostics
  • Host disk caching (relating to OS and MCSIO disks)
  • Machine size (unless otherwise specified)
  • Tags placed on the VM

  After you create the catalog, you can view the configurations that the image inherits from the machine profile. On the Machine Catalogs node, select the catalog to view its details in the lower pane. Then, click the Template Properties tab to view machine profile properties. The Tags section displays up to three tags. To view all tags placed on the VM, click View all.

  If you want MCS to provision VMs on an Azure dedicated host, enable the Use a host group check box and then select a host group from the list. A host group is a resource that represents a collection of dedicated hosts. A dedicated host is a service that provides physical servers that host one or more virtual machines. Your server is dedicated to your Azure subscription, not shared with other subscribers. When you use a dedicated host, Azure ensures that your VMs are the only machines running on that host. This feature is suitable for scenarios where you must meet regulatory or internal security requirements. To learn more about host groups and considerations for using them, see Azure dedicated hosts.

  Important:

  -  Only host groups that have Azure auto-placement enabled are shown.
  -  When using a machine profile, you cannot use a host group.
  -  Using a host group changes the **Virtual Machines** page offered later in the wizard. Only machine sizes that the selected host group contains are shown on that page. Also, Availability Zones are selected automatically and not available for selection.