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:

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"

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 ""

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.

localized image

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

localized image

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

localized image

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.

localized image

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

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.

localized image

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.

localized image

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.

localized image

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)

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

localized image

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.

localized image

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.

localized image

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.

localized image

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.

localized image

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.

localized image

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.

localized image

localized image

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.

localized image

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.

Parameter Description
ProviderLegacyCsp When set to true, FAS uses the Microsoft CryptoAPI (CAPI). Otherwise, FAS uses the Microsoft Cryptography Next Generation API (CNG).
ProviderName Name of the CAPI or CNG provider to use.
ProviderType Refers to Microsoft KeyContainerPermissionAccessEntry.ProviderType Property PROV_RSA_AES 24. Should always be 24 unless you are using an HSM with CAPI and the HSM vendor specifies otherwise.
KeyProtection Controls the “Exportable” flag of private keys. Also allows the use of Trusted Platform Module (TPM) key storage, if supported by the hardware.
KeyLength Key length for RSA private keys. Supported values are 1024, 2048 and 4096 (default: 2048).

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

Commands Overview
*-FasServer Lists and reconfigures the FAS servers in the current environment.
*-FasAuthorizationCertificate Manages the Registration Authority certificate.
*-FasCertificateDefinition Controls the parameters that FAS uses to generate certificates.
*-FasRule Manages User Rules configured on FAS.
*-FasUserCertificate Lists and manages certificates cached by FAS.

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.

localized image

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

Name Description
Active Sessions Number of connections tracked by FAS.
Concurrent CSRs Number of certificate requests processed at the same time.
Private Key ops Number of private key operations performed per minute.
Request time Length of time to generate and sign a certificate.
Certificate Count Number of certificates cached in FAS.
CSR per minute Number of certificate signing requests processed per minute.
Low/Medium/High Estimates of the load that FAS can accept in terms of “CSRs per minute”. Exceeding the “High Load” threshold may result in session launches failing.

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.

Log Codes
[S001] ACCESS DENIED: User [{0}] is not a member of Administrators group
[S002] ACCESS DENIED: User [{0}] is not an Administrator of Role [{1}]
[S003] Administrator [{0}] setting Maintenance Mode to [{1}]
[S004] Administrator [{0}] enrolling with CA [{1}] templates [{2} and {3}]
[S005] Administrator [{0}] de-authorizing CA [{1}]
[S006] Administrator [{0}] creating new Certificate Definition [{1}]
[S007] Administrator [{0}] updating Certificate Definition [{1}]
[S008] Administrator [{0}] deleting Certificate Definition [{1}]
[S009] Administrator [{0}] creating new Role [{1}]
[S010] Administrator [{0}] updating Role [{1}]
[S011] Administrator [{0}] deleting Role [{1}]
[S012] Administrator [{0}] creating certificate [upn: {1} sid: {2} role: {3}][Certificate Definition: {4}][Security Context: {5}]
[S013] Administrator [{0}] deleting certificates [upn: {1} role: {2} Certificate Definition: {3} Security Context: {4}]
[S015] Administrator [{0}] creating certificate request [TPM: {1}]
[S016] Administrator [{0}] importing Authorization certificate [Reference: {1}]
Log Codes
[S401] Performing configuration upgrade – [From version {0}][to version {1}]
[S402] ERROR: The Citrix Federated Authentication Service must be run as Network Service [currently running as: {0}]
[S404] Forcefully erasing the Citrix Federated Authentication Service database
[S405] An error occured while migrating data from the registry to the database: [{0}]
[S406] Migration of data from registry to database is complete (note: user certificates are not migrated)
[S407] Registry-based data was not migrated to a database since a database already existed
[S408] Cannot downgrade the configuration – [From version {0}][to version {1}]
[S409] ThreadPool MinThreads adjusted from [workers: {0} completion: {1}] to: [workers: {2} completion: {3}]
[S410] Failed to adjust ThreadPool MinThreads from [workers: {0} completion: {1}] to: [workers: {2} completion: {3}]

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.

Log Codes
[S101] Server [{0}] is not authorized to assert identities in role [{1}]
[S102] Server [{0}] failed to assert UPN [{1}] (Exception: {2}{3})
[S103] Server [{0}] requested UPN [{1}] SID {2}, but lookup returned SID {3}
[S104] Server [{0}] failed to assert UPN [{1}] (UPN not allowed by role [{2}])
[S105] Server [{0}] issued identity assertion [upn: {1}, role {2}, Security Context: [{3}]]
[S120] Issuing certificate to [upn: {0} role: {1} Security Context: [{2}]]
[S121] Certificate issued to [upn: {0} role: {1}] by [certifcate authority: {2}]
[S122] Warning: Server is overloaded [upn: {0} role: {1}][Requests per minute {2}].
[S123] Failed to issue a certificate for [upn: {0} role: {1}] [exception: {2}]
[S124] Failed to issue a certificate for [upn: {0} role: {1}] at [certifcate authority: {2}] [exception: {3}]

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.

Log Codes
[S201] Relying party [{0}] does not have access to a password.
[S202] Relying party [{0}] does not have access to a certificate.
[S203] Relying party [{0}] does not have access to the Logon CSP
[S204] Relying party [{0}] accessing the Logon CSP for [upn: {1}] in role: [{2}] [Operation: {3}] as authorized by [{4}]
[S205] Calling account [{0}] is not a relying party in role [{1}]
[S206] Calling account [{0}] is not a relying party
[S208] Private Key operation failed [Operation: {0}][upn: {1} role: {2} certificateDefinition {3}][Error {4} {5}].

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.

Log Codes
[S301] Access Denied: User [{0}] does not have access to a Virtual Smart Card
[S302] User [{0}] requested unknown Virtual Smart Card [thumbprint: {1}]
[S303] Access Denied: User [{0}] does not match Virtual Smart Card [upn: {1}]
[S304] User [{0}] running program [{1}] on computer [{2}] using Virtual Smart Card [upn: {3} role: {4} thumbprint: {5}] for private key operation [{6}]
[S305] Private Key operation failed [Operation: {0}][upn: {1} role: {2} containerName {3}][Error {4} {5}].

FAS assertion plugin [Federated Authentication Service]

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

These events are logged by the FAS assertion plugin.

Log Codes
[S500] No FAS assertion plugin is configured
[S501] The configured FAS assertion plugin could not be loaded [exception:{0}]
[S502] FAS assertion plugin loaded [pluginId={0}] [assembly={1}] [location={2}]
[S503] Server [{0}] failed to assert UPN [{1}] (logon evidence was supplied but the plugin [{2}] does not support it)
[S504] Server [{0}] failed to assert UPN [{1}] (logon evidence was supplied but there is no configured FAS plugin)
[S505] Server [{0}] failed to assert UPN [{1}] (the plugin [{2}] rejected the logon evidence with status [{3}] and message [{4}])
[S506] The plugin [{0}] accepted logon evidence from server [{1}] for UPN [{2}] with message [{3}]
[S507] Server [{0}] failed to assert UPN [{1}] (the plugin [{2}] threw exception [{3}])
[S507] Server [{0}] failed to assert UPN [{1}] (the plugin [{2}] threw exception [{3}])
[S508] Server [{0}] failed to assert UPN [{1}] (access disposition was supplied but the plugin [{2}] does not support it)
[S509] Server [{0}] failed to assert UPN [{1}] (access disposition was supplied but there is no configured FAS plugin)
[S510] Server [{0}] failed to assert UPN [{1}] (the access disposition was deemed invalid by plugin [{2}]

Log on [VDA]

[Event Source: Citrix.Authentication.IdentityAssertion]

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

Log Codes
[S101] Identity Assertion Logon failed. Unrecognised Federated Authentication Service [id: {0}]
[S102] Identity Assertion Logon failed. Could not lookup SID for {0} [Exception: {1}{2}]
[S103] Identity Assertion Logon failed. User {0} has SID {1}, expected SID {2}
[S104] Identity Assertion Logon failed. Failed to connect to Federated Authentication Service: {0} [Error: {1} {2}]
[S105] Identity Assertion Logon. Logging in [Username: {0}][Domain: {1}]
[S106] Identity Assertion Logon. Logging in [Certificate: {0}]
[S107] Identity Assertion Logon failed. [Exception: {0}{1}]
[S108] Identity Assertion Subsystem. ACCESS_DENIED [Caller: {0}]

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.

Log Codes
[S201] Virtual smart card access authorized by [{0}] for [PID: {1} Program Name: {2}][Certificate thumbprint: {3}]
[S203] Virtual Smart Card Subsystem. Access Denied [caller: {0}, session {1}]
[S204] Virtual Smart Card Subsystem. Smart card support disabled

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.

Log Codes
[S001] TrustArea::TrustArea: Installed certificate [TrustArea: {0}] [Certificate {1}][TrustAreaJoinParameters{2}
[S014] Pkcs10Request::Create: Created PKCS10 request [Distinguished Name {0}]
[S016] PrivateKey::Create [Identifier {0}][MachineWide: {1}][Provider: {2}][ProviderType: {3}][EllipticCurve: {4}][KeyLength: {5}][isExportable: {6}]
[S017] PrivateKey::Delete [CspName: {0}, Identifier {1}]
Log Codes
[S104] MicrosoftCertificateAuthority::GetCredentials: Authorized to use {0}
[S105] MicrosoftCertificateAuthority::SubmitCertificateRequest Error submit response [{0}]
[S106] MicrosoftCertificateAuthority::SubmitCertificateRequest Issued certificate [{0}]
[S112] MicrosoftCertificateAuthority::SubmitCertificateRequest - Waiting for approval [CR_DISP_UNDER_SUBMISSION] [Reference: {0}]