Federated Authentication Service

The Citrix Federated Authentication Service is a privileged component designed to integrate with Active Directory Certificate Services. It dynamically issues certificates for users, allowing them to log on to an Active Directory environment as if they had a smart card. This allows StoreFront to use a broader range of authentication options, such as SAML (Security Assertion Markup Language) assertions. SAML is commonly used as an alternative to traditional Windows user accounts on the Internet.

The following diagram shows the Federated Authentication Service integrating with a Microsoft Certification Authority and providing support services to StoreFront and XenApp and XenDesktop Virtual Delivery Agents (VDAs).

Trusted StoreFront servers contact the Federated Authentication Service (FAS) as users request access to the Citrix environment. The FAS grants a ticket that allows a single XenApp or XenDesktop session to authenticate with a certificate for that session. When a VDA needs to authenticate a user, it connects to the FAS and redeems the ticket. Only the FAS has access to the user certificate’s private key; the VDA must send each signing and decryption operation that it needs to perform with the certificate to the FAS.

Requirements

The Federated Authentication Service is supported on Windows servers (Windows Server 2008 R2 or later).

• Citrix recommends installing the FAS on a server that does not contain other Citrix components.
• The Windows Server should be secured. It will have access to a registration authority certificate and private key that allows it to automatically issue certificates for domain users, and it will have access to those user certificates and private keys.
• The FAS PowerShell SDK requires Windows PowerShell 64-bit installed on the FAS server.
• A Microsoft Enterprise Certification Authority is required to issue user certificates.

In the XenApp or XenDesktop Site:

• The Delivery Controllers must be minimum version 7.15.
• The VDAs must be minimum version 7.15. Check that the Federated Authentication Service Group Policy configuration has been applied correctly to the VDAs before creating the Machine Catalog in the usual way; see the Configure Group Policy section for details.
• The StoreFront server must be minimum version 3.12 (this is the version provided with the XenApp and XenDesktop 7.15 ISO).

When planning your deployment of this service, review the Security considerations section.

References:

• Active Directory Certificate Services

https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/hh831740(v=ws.11)?redirectedfrom=MSDN

• Configuring Windows for Certificate Logon

https://support.citrix.com/article/CTX206156

Install and setup sequence

1. Install the Federated Authentication Service
2. Enable the Federated Authentication Service plug-in on StoreFront servers
3. Configure Group Policy
4. Use the Federated Authentication Service administration console to: (a) Deploy the provided templates, (b) Set up certificate authorities, and (c) Authorize the Federated Authentication Service to use your certificate authority
5. Configure user rules

Install the Federated Authentication Service

For security, Citrix recommends that the FAS be installed on a dedicated server that is secured in a similar way to a domain controller or certificate authority. The FAS can be installed from the Federated Authentication Service button on the autorun splash screen when the ISO is inserted.

This will install the following components:

• Federated Authentication Service
• PowerShell snap-in cmdlets to remotely configure the Federated Authentication Service
• Federated Authentication Service administration console
• Federated Authentication Service Group Policy templates (CitrixFederatedAuthenticationService.admx/adml)
• Certificate template files for simple certificate authority configuration
• Performance counters and event logs

Enable the Federated Authentication Service plug-in on a StoreFront store

To enable Federated Authentication Service integration on a StoreFront Store, run the following PowerShell cmdlets as an Administrator account. If you have more than one store, or if the store has a different name, the path text below may differ.

```
Get-Module "Citrix.StoreFront.*" -ListAvailable | Import-Module

$StoreVirtualPath = "/Citrix/Store"

$store = Get-STFStoreService -VirtualPath $StoreVirtualPath

$auth = Get-STFAuthenticationService -StoreService $store

Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "FASClaimsFactory"

Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider "FASLogonDataProvider"
<!--NeedCopy--> ```

To stop using the FAS, use the following PowerShell script:

```
Get-Module "Citrix.StoreFront.*" -ListAvailable | Import-Module

$StoreVirtualPath = "/Citrix/Store"

$store = Get-STFStoreService -VirtualPath $StoreVirtualPath

$auth = Get-STFAuthenticationService -StoreService $store

Set-STFClaimsFactoryNames -AuthenticationService $auth -ClaimsFactoryName "standardClaimsFactory"

Set-STFStoreLaunchOptions -StoreService $store -VdaLogonDataProvider ""
<!--NeedCopy--> ```

Configure the Delivery Controller

To use the Federated Authentication Service, configure the XenApp or XenDesktop Delivery Controller to trust the StoreFront servers that can connect to it: run the Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $true PowerShell cmdlet.

Configure Group Policy

After you install the Federated Authentication Service, you must specify the full DNS addresses of the FAS servers in Group Policy using the Group Policy templates provided in the installation.

Important: Ensure that the StoreFront servers requesting tickets and the VDAs redeeming tickets have identical configuration of DNS addresses, including the automatic server numbering applied by the Group Policy object.

For simplicity, the following examples configure a single policy at the domain level that applies to all machines; however, that is not required. The FAS will function as long as the StoreFront servers, VDAs, and the machine running the FAS administration console see the same list of DNS addresses. Note that the Group Policy object adds an index number to each entry, which must also match if multiple objects are used.

Step 1. On the server where you installed the FAS, locate the C:\Program Files\Citrix\Federated Authentication Service\PolicyDefinitions\CitrixFederatedAuthenticationService.admx file and the en-US folder.

Step 2. Copy these to your domain controller and place them in the C:\Windows\PolicyDefinitions and en-US subfolder.

Step 3. Run the Microsoft Management Console (mmc.exe from the command line). From the menu bar, select File > Add/Remove Snap-in. Add the Group Policy Management Editor.

When prompted for a Group Policy Object, select Browse and then select Default Domain Policy. Alternatively, you can create and select an appropriate policy object for your environment, using the tools of your choice. The policy must be applied to all machines running affected Citrix software (VDAs, StoreFront servers, administration tools).

Step 4. Navigate to the Federated Authentication Service policy located in Computer Configuration/Policies/Administrative Templates/Citrix Components/Authentication.

Step 5. Open the Federated Authentication Service policy and select Enabled. This allows you to select the Show button, where you configure the DNS addresses of your FAS servers.

Step 6. Enter the DNS addresses of the servers hosting your Federated Authentication Service.

Remember: If you enter multiple addresses, the order of the list must be consistent between StoreFront servers and VDAs. This includes blank or unused list entries.

Step 7. Click OK to exit the Group Policy wizard and apply the group policy changes. You may need to restart your machines (or run gpupdate /force from the command line) for the change to take effect.

Enable in-session certificate support and disconnect on lock

In-session certificate support

The Group Policy template includes support for configuring the system for in-session certificates. This places certificates in the user’s personal certificate store after logon for application use. For example, if you require TLS authentication to web servers within the VDA session, the certificate can be used by Internet Explorer. By default, VDAs will not allow access to certificates after logon.

Disconnect on lock

If this policy is enabled the user’s session is automatically disconnected when they lock the screen. This functionality provides similar behaviour to the “disconnect on smart card removal” policy, and is useful for situations where users do not have Active Directory logon credentials.

Note:

The disconnect on lock policy applies to all sessions on the VDA.

Using the Federated Authentication Service administration console

The Federated Authentication Service administration console is installed as part of the Federated Authentication Service. An icon (Citrix Federated Authentication Service) is placed in the Start Menu.

The console attempts to automatically locate the FAS servers in your environment using the Group Policy configuration. If this fails, see the Configure Group Policy section.

If your user account is not a member of the Administrators group on the machine running the Federated Authentication Service, you will be prompted for credentials.

The first time the administration console is used, it guides you through a three-step process that deploys certificate templates, sets up the certificate authority, and authorizes the Federated Authentication Service to use the certificate authority. Some of the steps can alternatively be completed manually using OS configuration tools.

Deploy certificate templates

To avoid interoperability issues with other software, the Federated Authentication Service provides three Citrix certificate templates for its own use.

• Citrix_RegistrationAuthority_ManualAuthorization
• Citrix_RegistrationAuthority
• Citrix_SmartcardLogon

These templates must be registered with Active Directory. If the console cannot locate them, the Deploy certificate templates tool can install them. This tool must be run as an account that has permissions to administer your Enterprise forest.

The configuration of the templates can be found in the XML files with extension .certificatetemplate that are installed with the Federated Authentication Service in:

C:\Program Files\Citrix\Federated Authentication Service\CertificateTemplates

If you do not have permission to install these template files, give them to your Active Directory Administrator.

To manually install the templates, you can use the following PowerShell commands:

```
$template = [System.IO.File]::ReadAllBytes("$Pwd\Citrix_SmartcardLogon.certificatetemplate")

 $CertEnrol = New-Object -ComObject X509Enrollment.CX509EnrollmentPolicyWebService

 $CertEnrol.InitializeImport($template)

 $comtemplate = $CertEnrol.GetTemplates().ItemByIndex(0)
$writabletemplate = New-Object -ComObject X509Enrollment.CX509CertificateTemplateADWritable

 $writabletemplate.Initialize($comtemplate)

 $writabletemplate.Commit(1, $NULL)
 <!--NeedCopy--> ```

Set up Active Directory Certificate Services

After installing the Citrix certificate templates, they must be published on one or more Microsoft Certification Authority servers. Refer to the Microsoft documentation on how to deploy Active Directory Certificate Services.

If the templates are not published on at least one server, the Setup certificate authority tool offers to publish them. You must run this tool as a user that has permissions to administer the certificate authority.

(Certificate templates can also be published using the Microsoft Certification Authority console.)

Authorize the Federated Authentication Service

The final setup step in the console initiates the authorization of the Federated Authentication Service. The administration console uses the Citrix_RegistrationAuthority_ManualAuthorization template to generate a certificate request, and then sends it to one of the certificate authorities that publish that template.

After the request is sent, it appears in the Pending Requests list of the Microsoft Certification Authority console. The certificate authority administrator must choose to Issue or Deny the request before configuration of the Federated Authentication Service can continue. Note that the authorization request appears as a Pending Request from the FAS machine account.

Right-click All Tasks and then select Issue or Deny for the certificate request. The Federated Authentication Service administration console automatically detects when this process completes. This can take a couple of minutes.

Configure user rules

A user rule authorizes the issuance of certificates for VDA logon and in-session use, as directed by StoreFront. Each rule specifies the StoreFront servers that are trusted to request certificates, the set of users for which they can be requested, and the set of VDA machines permitted to use them.

To complete the setup of the Federated Authentication Service, the administrator must define the default rule by switching to the User Rules tab of the FAS administration console, selecting a certificate authority to which the Citrix_SmartcardLogon template is published, and editing the list of StoreFront servers. The list of VDAs defaults to Domain Computers and the list of users defaults to Domain Users; these can be changed if the defaults are inappropriate.

Fields:

Certificate Authority and Certificate Template: The certificate template and certificate authority that will be used to issue user certificates. This should be the Citrix_SmartcardLogon template, or a modified copy of it, on one of the certificate authorities that the template is published to.

The FAS supports adding multiple certificate authorities for failover and load balancing, using PowerShell commands. Similarly, more advanced certificate generation options can be configured using the command line and configuration files. See the PowerShell and Hardware security modules sections.

In-Session Certificates: The Available after logon check box controls whether a certificate can also be used as an in-session certificate. If this check box is not selected, the certificate will be used only for logon or reconnection, and the user will not have access to the certificate after authenticating.

List of StoreFront servers that can use this rule: The list of trusted StoreFront server machines that are authorized to request certificates for logon or reconnection of users. Note that this setting is security critical, and must be managed carefully.

List of VDA desktops and servers that can be logged into by this rule: The list of VDA machines that can log users on using the Federated Authentication Service system.

List of users that StoreFront can log in using this rule: The list of users who can be issued certificates through the Federated Authentication Service.

Advanced use

You can create additional rules to reference different certificate templates and authorities, which may be configured to have different properties and permissions. These rules can be configured for use by different StoreFront servers, which will need to be configured to request the new rule by name. By default, StoreFront requests default when contacting the Federated Authentication Service. This can be changed using the Group Policy Configuration options.

To create a new certificate template, duplicate the Citrix_SmartcardLogon template in the Microsoft Certification Authority console, rename it (for example, Citrix_SmartcardLogon2), and modify it as required. Create a new user rule by clicking Add to reference the new certificate template.

Upgrade considerations

• All Federated Authentication Service server settings are preserved when you perform an in-place upgrade.
• Upgrade the Federated Authentication Service by running the full-product XenApp and XenDesktop installer.
• Before upgrading the Federated Authentication Service from 7.15 LTSR to 7.15 LTSR CU2 (or a later supported CU), upgrade the Controller and VDAs (and other core components) to the required version.
• Ensure that the Federated Authentication Service console is closed before you upgrade the Federated Authentication Service.
• Ensure that at least one Federated Authentication Service server is available at all times. If no server is reachable by a Federation Authentication Service-enabled StoreFront server, users cannot log on or start applications.

Security considerations

The Federated Authentication Service has a registration authority certificate that allows it to issue certificates autonomously on behalf of your domain users. As such, it is important to develop and implement a security policy to protect the the FAS servers, and to constrain their permissions.

Delegated Enrollment Agents

FAS issues user certificates by acting as an enrollment agent. The Microsoft Certification Authority allows control of which templates the FAS server can use, as well as limiting which users the FAS server can issue certificates for.

Citrix strongly recommends configuring these options so that the Federated Authentication Service can only issue certificates for the intended users. For example, it is good practice to prevent the Federated Authentication Service from issuing certificates to users in an Administration or Protected Users group.

Access Control List configuration

As described in the Configure user rules section, you must configure a list of StoreFront servers that are trusted to assert user identities to the Federated Authentication Service when certificates are issued. Similarly, you can restrict which users will be issued certificates, and which VDA machines they can authenticate to. This is in addition to any standard Active Directory or certificate authority security features you configure.

Firewall settings

All communication to FAS servers uses mutually authenticated Windows Communication Foundation (WCF) Kerberos network connections over port 80.

Event log monitoring

The Federated Authentication Service and the VDA write information to the Windows Event Log. This can be used for monitoring and auditing information. The Event logs section lists event log entries that may be generated.

Hardware security modules

All private keys, including those of user certificates issued by the Federated Authentication Service, are stored as non-exportable private keys by the Network Service account. The Federated Authentication Service supports the use of a cryptographic hardware security module, if your security policy requires it.

Low-level cryptographic configuration is available in the FederatedAuthenticationService.exe.config file. These settings apply when private keys are first created. Therefore, different settings can be used for registration authority private keys (for example, 4096 bit, TPM protected) and runtime user certificates.

PowerShell SDK

Although the Federated Authentication Service administration console is suitable for simple deployments, the PowerShell interface offers more advanced options. When you are using options that are not available in the console, Citrix recommends using only PowerShell for configuration.

The following command adds the PowerShell cmdlets:

Add-PSSnapin Citrix.Authentication.FederatedAuthenticationService.V1

Use Get-Help <cmdlet name> to display cmdlet help. The following table lists several commands where * represents a standard PowerShell verb (such as New, Get, Set, Remove).

PowerShell cmdlets can be used remotely by specifying the address of a FAS server.

You can also download a zip file containing all the FAS PowerShell cmdlet help files; see the PowerShell SDK article.

Performance counters

The Federated Authentication Service includes a set of performance counters for load tracking purposes.

The following table lists the available counters. Most counters are rolling averages over five minutes.

Event logs

The following tables list the event log entries generated by the Federated Authentication Service.

Administration events

[Event Source: Citrix.Authentication.FederatedAuthenticationService]

These events are logged in response to a configuration change in the Federated Authentication Service server.

Creating identity assertions [Federated Authentication Service]

These events are logged at runtime on the Federated Authentication Service server when a trusted server asserts a user logon.

Acting as a relying party [Federated Authentication Service]

These events are logged at runtime on the Federated Authentication Service server when a VDA logs on a user.

In-session certificate server [Federated Authentication Service]

These events are logged on the Federated Authentication Service server when a user uses an in-session certificate.

Log on [VDA]

[Event Source: Citrix.Authentication.IdentityAssertion]

These events are logged on the VDA during the logon stage.

In-session certificates [VDA]

These events are logged on the VDA when a user attempts to use an in-session certificate.

Certificate request and generation codes [Federated Authentication Service]

[Event Source: Citrix.TrustFabric]

These low-level events are logged when the Federated Authentication Service server performs log-level cryptographic operations.

Related information

• The common FAS deployments are summarized in the Federated Authentication Service architectures overview article.
• “How-to” articles are introduced in the Federated Authentication Service configuration and management article.