Manage users

Defining users, groups, roles and permissions allows you to control who has access to your Citrix Hypervisor servers and pools and what actions they can perform.

When you first install Citrix Hypervisor, a user account is added to Citrix Hypervisor automatically. This account is the local super user (LSU), or root, which Citrix Hypervisor authenticates locally.

The LSU, or root, is a special user account intended for system administration and has all permissions. In Citrix Hypervisor, the LSU is the default account at installation. Citrix Hypervisor authenticates the LSU account. LSU does not require any external authentication service. If an external authentication service fails, the LSU can still log in and manage the system. The LSU can always access the Citrix Hypervisor physical server through SSH.

You can create more users by adding the Active Directory accounts through either XenCenter’s Users tab or the xe CLI. If your environment does not use Active Directory, you are limited to the LSU account.

Note:

When you create users, Citrix Hypervisor does not assign newly created user accounts RBAC roles automatically. Therefore, these accounts do not have any access to the Citrix Hypervisor pool until you assign them a role.

A limitation in recent SSH clients means that SSH does not work for usernames that contain any of the following characters: {}[]|&. Ensure that your usernames and Active Directory server names do not contain any of these characters.

These permissions are granted through roles, as discussed in the Authenticating users with Active Directory (AD) section.

Authenticate users with Active Directory (AD)

If you want to have multiple user accounts on a server or a pool, you must use Active Directory user accounts for authentication. AD accounts let Citrix Hypervisor users log on to a pool using their Windows domain credentials.

Note:

You can enable LDAP channel binding and LDAP signing on your AD domain controllers. For more information, see Microsoft Security Advisory.

You can configure varying levels of access for specific users by enabling Active Directory authentication, adding user accounts, and assign roles to those accounts.

Active Directory users can use the xe CLI (passing appropriate -u and -pw arguments) and also connect to the host using XenCenter. Authentication is done on a per-resource pool basis.

Subjects control access to user accounts. A subject in Citrix Hypervisor maps to an entity on your directory server (either a user or a group). When you enable external authentication, Citrix Hypervisor checks the credentials used to create a session against the local root credentials and then against the subject list. To permit access, create a subject entry for the person or group you want to grant access to. You can use XenCenter or the xe CLI to create a subject entry.

If you are familiar with XenCenter, note that the Citrix Hypervisor CLI uses slightly different terminology to refer to Active Directory and user account features: XenCenter Term Citrix Hypervisor CLI Term Users Subjects Add users Add subjects

Even though Citrix Hypervisor is Linux-based, Citrix Hypervisor lets you use Active Directory accounts for Citrix Hypervisor user accounts. To do so, it passes Active Directory credentials to the Active Directory domain controller.

When you add Active Directory to Citrix Hypervisor, Active Directory users and groups become Citrix Hypervisor subjects. The subjects are referred to as users in XenCenter. Users/groups are authenticated by using Active Directory on logon when you register a subject with Citrix Hypervisor. Users and groups do not need to qualify their user name by using a domain name.

To log on to a Citrix Hypervisor server, Active Directory users must have permission at the domain level to log on to the computer that hosts Citrix Hypervisor’s machine account. By default, in a Windows Server 2019 domain, all users are permitted to log on to any computer in the domain. However, if you have changed this setting, ensure that the users that you want to have access to a Citrix Hypervisor server are permitted to log on at the domain level.

To qualify a user name, you must type the user name in Down-Level log on Name format, for example, mydomain\myuser.

Note:

By default, if you did not qualify the user name, XenCenter attempts to log in users to AD authentication servers using the domain to which it is joined. The exception to this is the LSU account, which XenCenter always authenticates locally (that is, on the Citrix Hypervisor) first.

The external authentication process works as follows:

1. The credentials supplied when connecting to a server are passed to the Active Directory domain controller for authentication.

2. The domain controller checks the credentials. If they are invalid, the authentication fails immediately.

3. If the credentials are valid, the Active Directory controller is queried to get the subject identifier and group membership associated with the credentials.

4. If the subject identifier matches the one stored in the Citrix Hypervisor, authentication succeeds.

When you join a domain, you enable Active Directory authentication for the pool. However, when a pool joins a domain, only users in that domain (or a domain with which it has trust relationships) can connect to the pool.

Note:

Manually updating the DNS configuration of a DHCP-configured network PIF is unsupported and can cause AD integration, and therefore user authentication, to fail or stop working.

Configure Active Directory authentication

Citrix Hypervisor supports use of Active Directory servers using Windows 2008 or later.

To authenticate Active Directory for Citrix Hypervisor servers, you must use the same DNS server for both the Active Directory server (configured to allow interoperability) and the Citrix Hypervisor server. In some configurations, the active directory server can provide the DNS itself. This can be achieved either using DHCP to provide the IP address and a list of DNS servers to the Citrix Hypervisor server. Alternatively, you can set the values in the PIF objects or use the installer when a manual static configuration is used.

We recommend enabling DHCP to assign host names. Do not assign the hostnames localhost or linux to hosts.

Warning:

Citrix Hypervisor server names must be unique throughout the Citrix Hypervisor deployment.

Note the following:

• Citrix Hypervisor labels its AD entry on the AD database using its hostname. If two Citrix Hypervisor servers with the same hostname are joined to the same AD domain, the second Citrix Hypervisor overwrites the AD entry of the first Citrix Hypervisor. The overwriting occurs regardless of whether the hosts belong to the same or different pools. This can cause the AD authentication on the first Citrix Hypervisor to stop working.

  You can use the same host name in two Citrix Hypervisor servers, as long as they join different AD domains.

• The Citrix Hypervisor servers can be in different time-zones, because it is the UTC time that is compared. To ensure that synchronization is correct, you can use the same NTP servers for your Citrix Hypervisor pool and the Active Directory server.

• Mixed-authentication pools are not supported. You cannot have a pool where some servers in the pool are configured to use Active Directory and some are not).

• The Citrix Hypervisor Active Directory integration uses the Kerberos protocol to communicate with the Active Directory servers. Therefore, Citrix Hypervisor does not support communicating with Active Directory servers that do not use Kerberos.

• For external authentication using Active Directory to be successful, clocks on your Citrix Hypervisor servers must be synchronized with the clocks on your Active Directory server. When Citrix Hypervisor joins the Active Directory domain, the synchronization is checked and authentication fails if there is too much skew between the servers.

Warning:

Host names must consist solely of no more than 63 alphanumeric characters, and must not be purely numeric.

When you add a server to a pool after enabling Active Directory authentication, you are prompted to configure Active Directory on the server joining the pool. When prompted for credentials on the joining server, type Active Directory credentials with sufficient privileges to add servers to that domain.

Active Directory integration

Ensure that the following firewall ports are open for outbound traffic in order for Citrix Hypervisor to access the domain controllers.

For more information, see Communication Ports Used by Citrix Hypervisor.

Notes:

• To view the firewall rules on a Linux computer using iptables, run the following command: iptables -nL.
• Citrix Hypervisor uses PowerBroker Identity Services (PBIS) to authenticate the AD user in the AD server, and to encrypt communications with the AD server.

How does Citrix Hypervisor manage the machine account password for AD integration?

Similarly to Windows client machines, PBIS automatically updates the machine account password. PBIS renews the password every 30 days, or as specified in the machine account password renewal policy in the AD server.

Enable external authentication on a pool

External authentication using Active Directory can be configured using either XenCenter or the CLI using the following command.

xe pool-enable-external-auth auth-type=AD \
  service-name=full-qualified-domain \
  config:user=username \
  config:pass=password
<!--NeedCopy-->

The user specified must have Add/remove computer objects or workstations privilege, which is the default for domain administrators.

If you are not using DHCP on the network used by Active Directory and your Citrix Hypervisor servers, use the following approaches to set up your DNS:

1. Set up your domain DNS suffix search order for resolving non-FQDN entries:

   xe pif-param-set uuid=pif_uuid_in_the_dns_subnetwork \
      "other-config:domain=suffix1.com suffix2.com suffix3.com"
   <!--NeedCopy-->
   

2. Configure the DNS server to use on your Citrix Hypervisor servers:

   xe pif-reconfigure-ip mode=static dns=dnshost ip=ip \
     gateway=gateway netmask=netmask uuid=uuid
   <!--NeedCopy-->
   

3. Manually set the management interface to use a PIF that is on the same network as your DNS server:

   xe host-management-reconfigure pif-uuid=pif_in_the_dns_subnetwork
   <!--NeedCopy-->
   

Note:

External authentication is a per-host property. However, we recommend that you enable and disable external authentication on a per-pool basis. A per-pool setting allows Citrix Hypervisor to deal with failures that occur when enabling authentication on a particular host. Citrix Hypervisor also rolls back any changes that may be required, ensuring a consistent configuration across the pool. Use the host-param-list command to inspect properties of a host and to determine the status of external authentication by checking the values of the relevant fields.

Use XenCenter to disable Active Directory authentication, or the following xe command:

xe pool-disable-external-auth
<!--NeedCopy-->

User authentication

To allow a user access to your Citrix Hypervisor server, you must add a subject for that user or a group that they are in. (Transitive group memberships are also checked in the normal way. For example, adding a subject for group A, where group A contains group B and user 1 is a member of group B would permit access to user 1.) If you want to manage user permissions in Active Directory, you can create a single group that you then add and delete users to/from. Alternatively, you can add and delete individual users from Citrix Hypervisor, or a combination of users and groups as appropriate for your authentication requirements. You can manage the subject list from XenCenter or using the CLI as described in the following section.

When authenticating a user, the credentials are first checked against the local root account, allowing you to recover a system whose AD server has failed. If the credentials (user name and password) do not match, then an authentication request is made to the AD server. If the authentication is successful, the user’s information is retrieved and validated against the local subject list. Access is denied if the authentication fails. Validation against the subject list succeeds if the user or a group in the transitive group membership of the user is in the subject list.

Note:

When using Active Directory groups to grant access for Pool Administrator users who require host ssh access, the size of the AD group must not exceed 500 users.

To add an AD subject to Citrix Hypervisor:

xe subject-add subject-name=entity_name
<!--NeedCopy-->

The entity_name is the name of the user or group to which you want to grant access. You can include the domain of the entity (for example, ‘xendt\user1’ as opposed to ‘user1’) although the behavior is the same unless disambiguation is required.

Find the user’s subject identifier. The identifier is the user or the group containing the user. Removing a group removes access to all users in that group, provided they are not also specified in the subject list. Use the subject list command to find the user’s subject identifier. :

xe subject-list
<!--NeedCopy-->

This command returns a list of all users.

To apply a filter to the list, for example to find the subject identifier for a user user1 in the testad domain, use the following command:

xe subject-list other-config:subject-name='testad\user1'
<!--NeedCopy-->

Remove the user using the subject-remove command, passing in the subject identifier you learned in the previous step:

xe subject-remove subject-uuid=subject_uuid
<!--NeedCopy-->

You can end any current session this user has already authenticated. For more information, see Terminating all authenticated sessions using xe and Terminating individual user sessions using xe in the following section. If you do not end sessions, users with revoked permissions may continue to access the system until they log out.

Run the following command to identify the list of users and groups with permission to access your Citrix Hypervisor server or pool:

xe subject-list
<!--NeedCopy-->

Remove access for a user

When a user is authenticated, they can access the server until they end their session, or another user ends their session. Removing a user from the subject list, or removing them from a group in the subject list, doesn’t automatically revoke any already-authenticated sessions that the user has. Users can continue to access the pool using XenCenter or other API sessions that they have already created. XenCenter and the CLI provide facilities to end individual sessions, or all active sessions forcefully. See the XenCenter documentation for information on procedures using XenCenter, or the following section for procedures using the CLI.

Terminate all authenticated sessions using xe

Run the following CLI command to end all authenticated sessions using xe:

xe session-subject-identifier-logout-all
<!--NeedCopy-->

Terminate individual user sessions using xe

1. Determine the subject identifier whose session you want to log out. Use either the session-subject-identifier-list or subject-list xe commands to find the subject identifier. The first command shows users who have sessions. The second command shows all users but can be filtered. For example, by using a command like xe subject-list other-config:subject-name=xendt\\user1. You may need a double backslash as shown depending on your shell).

2. Use the session-subject-logout command, passing the subject identifier you have determined in the previous step as a parameter, for example:

   xe session-subject-identifier-logout subject-identifier=subject_id
   <!--NeedCopy-->
   

Leave an AD domain

Warning:

When you leave the domain, any users who authenticated to the pool or server with Active Directory credentials are disconnected.

Use XenCenter to leave an AD domain. For more information, see the XenCenter documentation. Alternately run the pool-disable-external-auth command, specifying the pool UUID if necessary.

Note:

Leaving the domain does not delete the host objects from the AD database. Refer to the Active Directory documentation for information about how to detect and remove your disabled host entries.