Install and configure

Install and setup sequence

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

Install the Federated Authentication Service

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

This installs the following components:

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

Enable the FAS plug-in on StoreFront stores

To enable FAS 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 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 FAS, configure the Citrix Virtual Apps or Citrix Virtual Desktops 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 FAS, 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 Virtual Delivery Agents (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. 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 FAS, locate the C:\Program Files\Citrix\Federated Authentication Service\PolicyDefinitions\CitrixFederatedAuthenticationService.admx and CitrixBase.admx files, 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.

Note:

The Federated Authentication Service policy setting is only available on domain GPO when you add the CitrixBase.admx/CitrixBase.adml template file to the PolicyDefinitions folder. The Federated Authentication Service policy setting is then listed in the Administrative Templates > Citrix Components > Authentication folder.

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 Fully Qualified Domain Names (FQDNs) of the servers hosting FAS.

Remember: If you enter multiple FQDNs, 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.

In-session certificate support and disconnect on lock

In-session certificate support

By default, VDAs do not allow access to certificates after logon. If necessary, you can use the Group Policy template to configure 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.

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 FAS administration console is installed as part of FAS. An icon (Citrix Federated Authentication Service) is placed in the Start Menu.

The first time the administration console is used, it guides you through a process that deploys certificate templates, sets up the certificate authority, and authorizes FAS 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, FAS 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 FAS 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 Federated Authentication Service

This step initiates the authorization of FAS. 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 FAS 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 FAS 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 FAS setup you must define the default rule. Click Create to create a rule or switch to the “Rules” tab and click Create rule. The wizard gathers the information needed to define a rule.

The following information is gathered by the wizard:

Template: The certificate template that is used to issue user certificates. This should be the Citrix_SmartcardLogon template, or a modified copy of it.

Certificate Authority: The certificate authority that issues user certificates. The template must be published by the certificate authority. FAS supports adding multiple certificate authorities for failover and load balancing.

In-Session Use: The Allow in-session use option controls whether a certificate can be used after logon to the VDA. Only select this option if you want users to have access to the certificate after authenticating. If this option is not selected, the certificate is only used only for logon or reconnection, and users do not have access to the certificate after authenticating.

Access control: The list of trusted StoreFront server machines that are authorized to request certificates for logon or reconnection of users.

Important:

The Access control setting is security critical, and must be managed carefully.

Restrictions: The list of VDA machines that can log users on using FAS and the list of users who can be issued certificates through FAS. 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.

Cloud rule: Currently unsupported.

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 FAS. 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 FAS server settings are preserved when you perform an in-place upgrade.
• Upgrade FAS by running the full-product Virtual Apps and Desktops installer.
• Before upgrading FAS, upgrade the Controller and VDAs (and other core components) to the required version.
• Ensure that the FAS administration console is closed before you upgrade FAS.
• Ensure that at least one FAS 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

FAS 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 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 FAS can only issue certificates for the intended users. For example, it is good practice to prevent FAS 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 FAS 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

FAS 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 FAS, are stored as non-exportable private keys by the Network Service account. FAS 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 FAS 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.

For information on FAS PowerShell cmdlets, see PowerShell cmdlets.

Performance counters

FAS 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 FAS.

Administration events [Federated Authentication Service]

[Event Source: Citrix.Authentication.FederatedAuthenticationService]

These events are logged in response to a configuration change in the FAS server.

Creating identity assertions [Federated Authentication Service]

[Event Source: Event Source: Citrix.Authentication.FederatedAuthenticationService]

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

Acting as a relying party [Federated Authentication Service]

[Event Source: Event Source: Citrix.Authentication.FederatedAuthenticationService]

These events are logged at runtime on the FAS server when a VDA logs on a user.

In-session certificate server [Federated Authentication Service]

[Event Source: Event Source: Citrix.Authentication.FederatedAuthenticationService]

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

FAS assertion plugin [Federated Authentication Service]

[Event Source: Event Source: Citrix.Authentication.FederatedAuthenticationService]

These events are logged by the FAS assertion plugin.

Log on [VDA]

[Event Source: Citrix.Authentication.IdentityAssertion]

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

In-session certificates [VDA]

[Event Source: Citrix.Authentication.IdentityAssertion]

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

Certificate request and key pair generation [Federated Authentication Service]

[Event Source: Citrix.Fas.PkiCore]

These events are logged when the FAS server performs low-level cryptographic operations.

Related information

• The common FAS deployments are summarized in Deployment architectures.
• “How-to” articles are introduced in Advanced configuration.