Citrix DaaS

Create Azure Active Directory joined catalogs

This article describes how to create Azure Active Directory (AD) joined catalogs using Citrix DaaS.

For information on requirements, limitations, and considerations, see Azure Active Directory joined.

Before you create the machine catalog, you need the following:

  1. New resource location
    • Navigate to the Citrix Cloud admin UI > upper left hamburger menu > Resource Locations.
    • Click + Resource Location.
    • Enter a name for the new resource location and click Save.
  2. Create a hosting connection. See Create and manage connections section for details. When deploying machines on Azure, see Connection to Azure Resource Manager.
  3. To consistently delete stale Azure AD devices and allow new devices to join Azure AD, you can assign the Cloud Device Administrator role to the provisioning service principal. If you do not delete the Azure stale AD devices, then the corresponding non-persistent VM stays in the initializing state until you manually remove it from the Azure AD portal. To do this, enable Azure AD joined device management of host connections using Full Configuration Interface or perform the following steps:

    1. Sign in to the Azure portal and navigate to Azure Active Directory > Roles and administrators.
    2. Search for Cloud Device Administrator built-in role and click Add assignments to assign the role to the service principal of the application used by the hosting connection.
    3. Use the Citrix Remote PowerShell SDK to run the following commands to get the existing CustomProperties of the hosting connection. The ${HostingConnectionName} refers to the name of the hosting connection.

      1. Open a PowerShell window.
      2. Run asnp citrix* to load the Citrix-specific PowerShell modules.
      3. Run the following command to get the existing custom properties of the hosting connection.

        (Get-Item -LiteralPath XDHyp:\Connections\${HostingConnectionName}).CustomProperties
        <!--NeedCopy-->
        
      4. Copy the CustomProperties from the connection to a notepad and append property setting <Property xsi:type="StringProperty" Name="AzureAdDeviceManagement" Value="true" />.
      5. In the PowerShell window, assign a variable to the modified custom properties. For example, $UpdatedCustomProperties=’<CustomProperties …</CustomProperties>’.
      6. Set the custom property back to the hosting connection:

        Set-Item -LiteralPath XDHyp:\Connections\${HostingConnectionName} -CustomProperties ${UpdatedCustomProperties} -ZoneUid ${ZoneUid}
        <!--NeedCopy-->
        
      7. Run the command (Get-Item -LiteralPath XDHyp:\Connections\${HostingConnectionName}).CustomProperties to verify the updated custom property settings.

You can create Azure AD joined catalogs by using the Full Configuration interface or PowerShell.

Use the Full Configuration interface

The following information is a supplement to the guidance in Create machine catalogs. To create Azure AD joined catalogs, follow the general guidance in that article, minding the details specific to Azure AD joined catalogs.

In the catalog creation wizard:

  1. On the Image page:
    • Select 2106 or later as the functional level.
    • Select Use a machine profile and select the appropriate machine from the list.
  2. On the Machine Identities page, select Azure Active Directory joined. The created machines are owned by an organization and are signed into with an Azure AD account that belongs to that organization. They exist only in the cloud.

    Note:

    • The Azure Active Directory joined identity type requires version 2106 or later as the minimum functional level for the catalog.
    • The machines are joined to the Azure AD domain associated with the tenant to which the hosting connection is bound.
  3. Users must be granted explicit access in Azure to log into the machines using their AAD credentials. See Azure Active Directory joined section for more details.

Use PowerShell

The following are PowerShell steps equivalent to operations in Full Configuration. For information on how to create a catalog using the Remote PowerShell SDK, see https://developer-docs.citrix.com/projects/citrix-virtual-apps-desktops-sdk/en/latest/creating-a-catalog/.

The difference between on-premises AD joined catalogs and Azure AD joined ones lies in the creation of the identity pool and the provisioning scheme.

To create an identity pool for Azure AD joined catalogs:

New-AcctIdentityPool -AllowUnicode -IdentityType="AzureAD" -WorkgroupMachine -IdentityPoolName "AzureADJoinedCatalog" -NamingScheme "AzureAD-VM-##" -NamingSchemeType "Numeric" -Scope @() -ZoneUid "81291221-d2f2-49d2-ab12-bae5bbd0df05"
<!--NeedCopy-->

To create a provisioning scheme for Azure AD joined catalogs, the MachineProfile parameter is required in New-ProvScheme:

New-ProvScheme -CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"UseManagedDisks`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"StorageType`" Value=`"StandardSSD_LRS`" /><Property xsi:type=`"StringProperty`" Name=`"LicenseType`" Value=`"Windows_Server`" /></CustomProperties>" -HostingUnitName "AzureResource" -IdentityPoolName "AzureADJoinedCatalog" -InitialBatchSizeHint 1 -MachineProfile "XDHyp:\HostingUnits\AzureResource\image.folder\azuread-rg.resourcegroup\MasterVDA.vm" -MasterImageVM "XDHyp:\HostingUnits\AzureResource\image.folder\azuread-rg.resourcegroup\azuread-small_OsDisk_1_5fb42fadf7ff460bb301ee0d56ea30da.manageddisk" -NetworkMapping @{"0"="XDHyp:\HostingUnits\AzureResource\virtualprivatecloud.folder\East US.region\virtualprivatecloud.folder\azuread-rg.resourcegroup\azuread-vnet.virtualprivatecloud\Test_VNET.network"} -ProvisioningSchemeName "AzureADJoinedCatalog" -RunAsynchronously -Scope @() -SecurityGroup @() -ServiceOffering "XDHyp:\HostingUnits\AzureResource\serviceoffering.folder\Standard_DS1_v2.serviceoffering"
<!--NeedCopy-->

All other commands used to create Azure AD joined catalogs are the same as for traditional on-premises AD joined catalogs.

View the status of the Azure AD join process

In the Full Configuration interface, the status of the Azure AD join process is visible when Azure AD joined machines in a delivery group are in a powered-on state. To view the status, use Search to identify those machines and then for each check Machine Identity on the Details tab in the lower pane. The following information can appear in Machine Identity:

  • Azure AD joined
  • Not yet joined to Azure AD

Note:

If the machines fail to be in Azure AD joined state, they do not register with the Delivery Controller. Their registration status appears as Initialization.

Also, using the Full Configuration interface, you can learn why machines are unavailable. To do that, click a machine on the Search node, check Registration on the Details tab in the lower pane, and then read the tooltip for additional information.

Delivery Group

See Create delivery groups section for details.

Enable Rendezvous

Once the delivery group has been created, you can enable Rendezvous. See Rendezvous V2 for details.

Troubleshoot

If machines fail to be Azure AD joined, do the following:

  • Check if the system assigned managed identity is enabled for the machines. MCS-provisioned machines must have this enabled automatically. The Azure AD join process fails without system assigned managed identity. If the system assigned managed identity is not enabled for MCS-provisioned machines, possible reason is:

    • IdentityType of the identity pool associated with the provisioning scheme is not set to AzureAD. You can verify this by running Get-AcctIdentityPool.
  • For catalogs that use master images with VDA version 2206 or earlier, check the provisioning status of AADLoginForWindows extension for the machines. If the AADLoginForWindows extension does not exist, possible reasons are:

    • IdentityType of the identity pool associated with the provisioning scheme is not set to AzureAD. You can verify this by running Get-AcctIdentityPool.

    • The AADLoginForWindows extension installation is blocked by Azure policy.

  • To troubleshoot AADLoginForWindows extension provisioning failures, you can check logs under C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.ActiveDirectory.AADLoginForWindows on the MCS-provisioned machine.

    Note:

    MCS does not rely on the AADLoginForWindows extension to join a VM to Azure AD when using a master image with VDA version 2209 or later. In this case, the AADLoginForWindows extension will not be installed on the MCS-provisioned machine. Therefore, AADLoginForWindows extension provisioning logs can’t be collected.

  • Check the Azure AD join status and debug logs by running dsregcmd /status command on the MCS-provisioned machine.

  • Check Windows event logs under Application and Services Logs > Microsoft > Windows > User Device Registration.
  • Check if Azure AD device management is correctly configured by running Get-Item -LiteralPath XDHyp:\Connections\${HostingConnectionName}.

    Ensure that the value of:

    • AzureAdDeviceManagement property in CustomProperties is true
    • Citrix_MCS_AzureAdDeviceManagement_PermissionGranted property in metadata is true

    If Citrix_MCS_AzureAdDeviceManagement_PermissionGranted is false, it indicates that the ServicePrincipal of the application used by the hosting connection is not granted with sufficient permissions to perform Azure AD device management. To resolve this, assign the ServicePrincipal with the Cloud Device Administrator role.

Azure Active Directory dynamic security group

Dynamic group rules place the VMs in the catalog to a dynamic security group based on the naming scheme of the machine catalog.

If the naming scheme of the machine catalog is Test### (where, # means number), Citrix creates the dynamic membership rule ^Test[0-9]{3}$ in the dynamic security group. Now, if the name of the VM created by Citrix is anything from Test001 to Test999, then the VM is included in the dynamic security group.

Note:

If the name of the VM created by you manually is anything from Test001 to Test999, then also the VM is included in the dynamic security group. This is one of the limitations of the dynamic security group.

The dynamic security group feature is useful when you want to manage the VMs by Azure Active Directory (Azure AD). This is also useful when you want to apply Conditional Access policies or distribute apps from Intune by filtering the VMs with Azure AD dynamic security group.

You can use PowerShell commands to:

  • Create a machine catalog with Azure AD dynamic security group
  • Enable security group feature for an Azure AD catalog
  • Delete a machine catalog with Azure AD joined device security group

Important:

Create a machine catalog with Azure AD dynamic security group

  1. In the machine catalog setup user interface of the web-based console, on the Machine Identities page, select Azure Active Directory joined.
  2. Log in to Azure AD.
  3. Get the access token to MS Graph API. Use this access token as a value of $AzureADAccessToken parameter when you run the PowerShell commands.
  4. Run the following command to verify if the dynamic security group name exists in the tenant.

    Get-AcctAzureADSecurityGroup
    –AccessToken  $AzureADAccessToken
    –Name "SecurityGroupName"
    <!--NeedCopy-->
    
  5. Create a machine catalog using the Tenant ID, access token, and dynamic security group. Run the following command to create an IdentityPool with IdentityType=AzureAD and create a dynamic security group in Azure.

    New-AcctIdentityPool
    -AllowUnicode
    -IdentityPoolName "SecurityGroupCatalog"
    -NamingScheme "SG-VM-###"
    -NamingSchemeType "Numeric" -Scope @()
    -ZoneUid "81291221-d2f2-49d2-ab12-bae5bbd0df05"
    -WorkgroupMachine
    -IdentityType "AzureAD"
    -DeviceManagementType "None"
    -AzureADTenantId  620387bb-9167-4bdd-8435-e3dccc58369e
    -AzureADSecurityGroupName "SecurityGroupName"
    -AzureADAccessToken $AzureADAccessToken
    <!--NeedCopy-->
    

Enable security group feature for an Azure AD catalog

You can enable the dynamic security feature for an Azure AD catalog that was created without the dynamic security group feature enabled. To do this:

  1. Manually create a new dynamic security group. You can also reuse an existing dynamic security group.
  2. Log in to Azure AD, and get the access token to MS Graph API. Use this access token as a value of $AzureADAccessToken parameter when you run the PowerShell commands.

    Note:

    For information on the permissions required by the Azure AD user, see https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent#prerequisites/.

  3. Run the following command to connect the identity pool to the created Azure AD dynamic security group.

    Set-AcctIdentityPool
    -IdentityPoolName "SecurityGroupCatalog"
    -AzureADTenantId 620387bb-9167-4bdd-8435-e3dccc58369e
    -AzureADSecurityGroupNam "ExistingSecurityGroupName"
    -AzureADAccessToken $AzureADAccessToken
    <!--NeedCopy-->
    

If you update the naming scheme, Citrix updates the naming scheme to a new membership rule. If you delete the catalog, membership rule gets deleted, and not the security group.

Delete a machine catalog with Azure AD joined device security group

When you delete a machine catalog, the Azure AD joined device security group is also deleted.

To delete the Azure AD dynamic security group, do the following:

  1. Log in to Azure AD.
  2. Get the access token to MS Graph API. Use this access token as value of $AzureADAccessToken parameter when you run the PowerShell commands.
  3. Run the following command:

    Remove-AcctIdentityPool
    -IdentityPoolName "SecurityGroupCatalog"
    -AzureADAccessToken $AzureADAccessToken
    <!--NeedCopy-->
    

Create an Azure AD dynamic security group under an existing Azure AD assigned security group

You can create an Azure AD dynamic security group under an existing Azure AD assigned security group. You can do the following:

  • Get security group information.
  • Get all Azure AD assigned security groups that are synced from on-premises AD server or the assigned security groups to which Azure AD roles can be assigned.
  • Get all Azure AD dynamic security groups.
  • Add Azure AD dynamic security group as a member of Azure AD assigned group.
  • Remove the membership between Azure AD dynamic security group and Azure AD assigned security group when Azure AD dynamic security group is deleted along with the machine catalog.

You can also see explicit error messages when any of the operations fail.

Requirement:

You must have the access token to the MS Graph API when you run the PowerShell commands.

To get the access token:

  1. Open Microsoft graph explorer and log in to Azure AD.
  2. Make sure you have consent to Group.ReadWrite.All and GroupMember.ReadWrite.All permissions.
  3. Get access token from Microsoft graph explorer. Use this access token when you run the PowerShell commands.

To get security group information by group id:

  1. Get the access token.
  2. Find group object id from Azure portal.
  3. Run the following PowerShell command in the PowerShell console:

    Get-AcctAzureADSecurityGroup
    -AccessToken <token> -GroupId <GroupUid>
    <!--NeedCopy-->
    

To get security groups by group display name:

  1. Get the access token.
  2. Run the following PowerShell command in the PowerShell console:

    Get-AcctAzureADSecurityGroup
    -AccessToken <token>
    -Name <TargetGroupDisplayName>
    <!--NeedCopy-->
    

To get security groups whose display name contains a substring:

  1. Get the access token.
  2. Run the following PowerShell command in the PowerShell console:

    Get-AcctAzureADSecurityGroup
    -AccessToken <token>
    -SearchString <displayNameSubString>
    <!--NeedCopy-->
    

To get all Azure AD assigned security groups that are synced from on-premises AD server or the assigned security groups to which Azure AD roles can be assigned:

  1. Get the access token.
  2. Run the following PowerShell command in the PowerShell console:

    Get-AcctAzureADSecurityGroup
    -AccessToken <token>
    -Assigned true
    <!--NeedCopy-->
    

To get all Azure AD dynamic security groups:

  1. Get the access token.
  2. Run the following PowerShell command in the PowerShell console:

    Get-AcctAzureADSecurityGroup
    -AccessToken <token>
    -Dynamic true
    <!--NeedCopy-->
    

To get Azure AD assigned security groups with maximum record count:

  1. Get the access token.
  2. Run the following PowerShell command in the PowerShell console:

    Get-AcctAzureADSecurityGroup
    -AccessToken <token>
    -Assigned true
    -MaxRecordCount 10
    <!--NeedCopy-->
    

To add Azure AD dynamic security group as a member of Azure AD assigned security group:

  1. Get the access token.
  2. Run the following PowerShell command in the PowerShell console:

    Add-AcctAzureADSecurityGroupMember
    -AccessToken <token>
    -GroupId <ASG-Id>
    -RefGroupId <DSG-Id>
    <!--NeedCopy-->
    

To get Azure AD assigned security group members:

  1. Get the access token.
  2. Run the following PowerShell command in the PowerShell console:

    Get-AcctAzureADSecurityGroupMember
    -AccessToken <token>
    -GroupId <ASG-Id>
    <!--NeedCopy-->
    

    Note:

    Get-AcctAzureADSecurityGroupMember provides you only the direct members of the security group type under Azure AD assigned security group.

To remove the membership between Azure AD dynamic security group and Azure AD assigned security group when Azure AD dynamic security group is deleted along with machine catalog:

  1. Get the access token.
  2. Run the following PowerShell command in the PowerShell console:

    Remove-AcctIdentityPool
    -IdentityPoolName "SecurityGroupCatalog"
    -AzureADAccessToken $AzureADAccessToken
    <!--NeedCopy-->
    

Modify Azure AD dynamic security group name

You can modify the Azure AD dynamic security group name associated with a machine catalog. This modification makes the security group information stored in Azure AD identity pool object to be consistent with the information stored in Azure portal.

Note:

The Azure AD dynamic security groups do not include security groups synced from on-premises AD and other group types like Office 365 group.

You can modify the Azure AD dynamic security group name using Full Configuration interface and PowerShell commands.

To modify the Azure AD dynamic security group name using PowerShell:

  1. Open the PowerShell window.
  2. Run asnp citrix* to load the Citrix-specific PowerShell modules.
  3. Run the command Set-AcctIdentityPool -AzureAdSeurityGroupName [DSG-Name].

You get appropriate error messages if the Azure AD dynamic security group name cannot be modified.