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, seeAzure Active Directory joined.
Before you create the machine catalog, you need the following:
- 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 clickSave.
- Create a hosting connection. SeeCreate and manage connectionssection for details. When deploying machines on Azure, seeConnection to Azure Resource Manager.
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 Interfaceor perform the following steps:
- Sign in to the Azure portal and navigate toAzure Active Directory > Roles and administrators.
- Search forCloud Device Administratorbuilt-in role and clickAdd assignmentsto assign the role to the service principal of the application used by the hosting connection.
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.- Open aPowerShellwindow.
- Run
asnp citrix*
to load the Citrix-specificPowerShellmodules. Run the following command to get the existing custom properties of the hosting connection.
(Get-Item -LiteralPath XDHyp:\Connections\${HostingConnectionName}).CustomProperties
- Copy the CustomProperties from the connection to a notepad and append property setting
. - In thePowerShellwindow, assign a variable to the modified custom properties. For example, $
UpdatedCustomProperties=’
.’ Set the custom property back to the hosting connection:
Set-Item -LiteralPath XDHyp:\Connections\${HostingConnectionName} -CustomProperties ${UpdatedCustomProperties} -ZoneUid ${ZoneUid}
- 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 orPowerShell.
Use the Full Configuration interface
The following information is a supplement to the guidance inCreate 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:
- On theMaster Imagepage:
- Select 2106 or later as the functional level.
- SelectUse a machine profileand select the appropriate machine from the list.
On theMachine Identitiespage, selectAzure 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:
- TheAzure Active Directory joinedidentity 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.
- Users must be granted explicit access in Azure to log into the machines using their AAD credentials. SeeAzure Active Directory joinedsection for more details.
Use PowerShell
The following arePowerShellsteps equivalent to operations in Full Configuration. For information on how to create a catalog using the Remote PowerShell SDK, seehttps://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"
To create a provisioning scheme for Azure AD joined catalogs, theMachineProfileparameter is required in New-ProvScheme:
New-ProvScheme -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"
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, useSearchto identify those machines and then for each checkMachine Identityon theDetailstab in the lower pane. The following information can appear inMachine Identity:
- Azure AD joined
- Not yet joined to Azure AD
Note:
如果the machines fail to be in Azure AD joined state, they do not register with the Delivery Controller. Their registration status appears asInitialization.
Also, using the Full Configuration interface, you can learn why machines are unavailable. To do that, click a machine on theSearchnode, checkRegistrationon theDetailstab in the lower pane, and then read the tooltip for additional information.
Delivery Group
SeeCreate delivery groupssection for details.
Enable Rendezvous
Once the delivery group has been created, you can enable Rendezvous. SeeRendezvous V2for details.
Troubleshoot
如果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 toAzureAD
. You can verify this by runningGet-AcctIdentityPool
.
Check the provisioning status ofAADLoginForWindowsextension for the machines. MCS relies on this extension to join a virtual machine to Azure AD. If theAADLoginForWindowsextension does not exist, possible reasons are:
IdentityType
of the identity pool associated with the provisioning scheme is not set toAzureAD
. You can verify this by runningGet-AcctIdentityPool
.TheAADLoginForWindowsextension installation is blocked by Azure policy.
To troubleshootAADLoginForWindowsextension provisioning failures, you can check logs under
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.ActiveDirectory.AADLoginForWindows
on the MCS-provisioned machine.Check the Azure AD join status and debug logs by running
dsregcmd /status /debug
command on the MCS-provisioned machine.- Check Windows event logs underApplication 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 inCustomProperties
istrueCitrix_MCS_AzureAdDeviceManagement_PermissionGranted
property in metadata istrue
如果
Citrix_MCS_AzureAdDeviceManagement_PermissionGranted
isfalse, it indicates that theServicePrincipal
of the application used by the hosting connection is not granted with sufficient permissions to perform Azure AD device management. To resolve this, assign theServicePrincipal
with theCloud Device Administrator的角色。
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.
如果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:
如果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 usePowerShellcommands 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:
- To create a machine catalog with Azure AD dynamic security group, add machines to the catalog, and delete the machine catalog, you must have Azure AD access token. For information on getting the Azure AD access token, seehttps://docs.microsoft.com/en-us/graph/graph-explorer/graph-explorer-features#consent-to-permissions/.
- To request an access token in Azure AD, Citrix requests theGroup.ReadWrite.Allpermission for Microsoft Graph API. An Azure AD user who has tenant-wide admin consent permission can grantGroup.ReadWrite.Allpermission for Microsoft Graph API. For information on how to grant tenant-wide admin consent to an application in Azure Active Directory (Azure AD), see the Microsoft documenthttps://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent/.
Create a machine catalog with Azure AD dynamic security group
- In the machine catalog setup user interface of the web-based console, on theMachine Identitiespage, selectAzure Active Directory joined.
- Log in to Azure AD.
- Get the access token to MS Graph API. Use this access token as a value of
$AzureADAccessToken
parameter when you run thePowerShellcommands. Run the following command to verify if the dynamic security group name exists in the tenant.
Get-AcctAzureADSecurityGroup –AccessToken $AzureADAccessToken -AzureADTenantId 620387bb-9167-4bdd-8435-e3dccc58369e –SecurityGroupName "SecurityGroupName"
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
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:
- Manually create a new dynamic security group. You can also reuse an existing dynamic security group.
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 thePowerShellcommands.Note:
For information on the permissions required by the Azure AD user, seehttps://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent#prerequisites/.
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
如果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:
- Log in to Azure AD.
- Get the access token to MS Graph API. Use this access token as value of
$AzureADAccessToken
parameter when you run thePowerShellcommands. Run the following command:
Remove-AcctIdentityPool -IdentityPoolName "SecurityGroupCatalog" -AzureADAccessToken $AzureADAccessToken
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 thePowerShellcommands.
acc的s token:
- OpenMicrosoft graph explorerand log in to Azure AD.
- Make sure you have consent toGroup.ReadWrite.AllandGroupMember.ReadWrite.Allpermissions.
- Get access token from Microsoft graph explorer. Use this access token when you run thePowerShellcommands.
To get security group information by group id:
- Get the access token.
- Find group object id from Azure portal.
Run the followingPowerShellcommand in thePowerShellconsole:
Get-AcctAzureADSecurityGroup -AccessToken
-GroupId
To get security groups by group display name:
- Get the access token.
Run the followingPowerShellcommand in thePowerShellconsole:
Get-AcctAzureADSecurityGroup -AccessToken
-Name
To get security groups whose display name contains a substring:
- Get the access token.
Run the followingPowerShellcommand in thePowerShellconsole:
Get-AcctAzureADSecurityGroup -AccessToken
-SearchString
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:
- Get the access token.
Run the followingPowerShellcommand in thePowerShellconsole:
Get-AcctAzureADSecurityGroup -AccessToken
-Assigned true
To get all Azure AD dynamic security groups:
- Get the access token.
Run the followingPowerShellcommand in thePowerShellconsole:
Get-AcctAzureADSecurityGroup -AccessToken
-Dynamic true
To get Azure AD assigned security groups with maximum record count:
- Get the access token.
Run the followingPowerShellcommand in thePowerShellconsole:
Get-AcctAzureADSecurityGroup -AccessToken
-Assigned true -MaxRecordCount 10
To add Azure AD dynamic security group as a member of Azure AD assigned security group:
- Get the access token.
Run the followingPowerShellcommand in thePowerShellconsole:
Add-AcctAzureADSecurityGroupMember -AccessToken
-GroupId -RefGroupId
To get Azure AD assigned security group members:
- Get the access token.
Run the followingPowerShellcommand in thePowerShellconsole:
Get-AcctAzureADSecurityGroupMember -AccessToken
-GroupId 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:
- Get the access token.
Run the followingPowerShellcommand in thePowerShellconsole:
Remove-AcctIdentityPool -IdentityPoolName "SecurityGroupCatalog" -AzureADAccessToken $AzureADAccessToken
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 andPowerShellcommands.
To modify the Azure AD dynamic security group name usingPowerShell:
- Open thePowerShellwindow.
- Run
asnp citrix*
to load the Citrix-specificPowerShellmodules. - Run the command
Set-AcctIdentityPool -AzureAdSeurityGroupName [DSG-Name]
.
You get appropriate error messages if the Azure AD dynamic security group name cannot be modified.
In this article
- Use the Full Configuration interface
- Use PowerShell
- View the status of the Azure AD join process
- Delivery Group
- Enable Rendezvous
- Troubleshoot
- Azure Active Directory dynamic security group
- Create an Azure AD dynamic security group under an existing Azure AD assigned security group
- Modify Azure AD dynamic security group name