Citrix Federated Authentication Service Logon Evidence Overview
The Federated Authentication Service (FAS) is a Citrix component that integrates with your Active Directory certificate authority (CA), allowing users to be authenticated seamlessly within a Citrix environment. For information about FAS architecture and deployment, see the Federated Authentication Service documentation.
You can deploy FAS to allow users to single-sign on to a VDA (or to a published app) without the need for a password or smart card. The FAS logon evidence feature provides logon evidence passed to FAS by Citrix Gateway and StoreFront. FAS can validate the evidence to ensure that it was issued by a trusted Identity Provider (IdP).
This article describes how you configure FAS logon evidence feature.
FAS infrastructure involves a “chain-of-trust” between Citrix Gateway (NSG), StoreFront (SF) and FAS; each arrow points from the trusting component to the trusted component:
The key piece of data being trusted between each of these components is the User Principal Name (UPN) of the user accessing the system. The UPN flows through the links (in the opposite direction to the arrows). The UPN may also be transformed into a different UPN as it flows through the system, but this is not directly relevant to this topic.
The identity provider (IdP) is where users authenticate. The IdP is often a third party website such as Okta or Azure. Users authenticate at the IdP by providing a set of credentials (such as a password or something more complex). Components further along the chain accept that the UPN is authentic because of the chain-of-trust between the components.
Trust is established in the following ways, labeled 1, 2, 3 in the diagram above:
(1) Citrix Gateway or StoreFront trusts the IdP using a protocol involving signed claims (for example, a claim stating the user’s UPN). The trusting party can verify the claims made by the IdP because it is configured with the certificate which it uses to check the signature is valid. There are two main protocols used for verification: SAML (Security Assertion Markup Language) and OpenID Connect. The logon evidence feature currently only supports SAML.
(2) This trust is established by configuring StoreFront with the details of the trusted Citrix Gateway. The protocol between these components, “CitrixAgBasic,” allows StoreFront to confirm that it is being called by a trusted Citrix Gateway.
(3) This trust is established using Kerberos. FAS is configured with a list of trusted StoreFront servers. Kerberos is used to check that the identity of the calling StoreFront server is on this list.
Secure authentication relies on a correctly established chain of trust. The chain of trust is strengthened by validating the evidence provided by the IdP, which is the root of trust for secure authentication. This is important, because the user credentials supplied to FAS via the chain of trust include the user name (the UPN), but do not include a secret (such as a password) which FAS can itself validate. The exposure of the password is therefore confined to the IdP. Most federated authentication systems operate this way, including FAS.
The FAS logon evidence feature provides extra security assurance in a FAS deployment. It allows you to define rules that allow or deny access to FAS.
Logon evidence (or just “evidence”) is a piece of data created by the IdP when the user authenticates. This data flows, together with the UPN, throughout the system. At VDA launch time, FAS can check the evidence is valid before allowing the launch to proceed.
Currently, only IdPs which support SAML are supported. The evidence is the SAML response, which is an XML document containing a set of claims signed by the IdP. (The IdP is the root of trust for authentication).
FAS does not have any built-in capability to check that logon evidence is valid. Instead, you need to write your own FAS plug-in using the FAS Assertion SDK. Your plug-in is responsible for checking the supplied UPN and evidence (SAML response).
Configure logon evidence collection
Step 1 - Create your deployment
Create a deployment using Citrix Gateway, StoreFront, and FAS as usual. Configure Citrix Gateway or StoreFront to use SAML authentication to your IdP.
If you are using Citrix Gateway, when you configure StoreFront with the details of your Citrix Gateway, you must configure a Callback URL, because logon evidence is transmitted via the callback:
Citrix recommends that you configure the Logon type as “Smart card”, which helps native clients perform SAML authentication.
Check that your deployment is working correctly. In other words, check that you can log in and launch VDA sessions without being prompted for credentials at the VDA.
Step 2 - Install the sample FAS assertion plug-in
The FAS Assertion SDK includes a sample plug-in which you can use as the basis for your own plug-in.
Citrix strongly recommends that you begin by installing the sample plug-in without making any changes.
For instructions for installing the plug-in, see the Readme.txt file supplied with the FAS Assertion SDK.
Step 3 - Check the FAS assertion plug-in is working
After the plug-in is installed, extra events are written into the Windows Logs/Application section of your FAS server’s event log. For a description of logging and tracing, see the FAS Assertion SDK.
Step 4 - Enable evidence collection on Citrix Gateway
If you are using Citrix Gateway for authentication, you must enable the evidence collection feature so that evidence is transmitted from Citrix Gateway to StoreFront. To do this, use the Citrix ADC admin console to enable the option “Store SAML Response” for your gateway server.
Step 5 - Enable evidence collection on StoreFront
If you enable logon evidence, then you must deploy a FAS Assertion plug-in module on the FAS Server.
By default, StoreFront does not send evidence to FAS (even if SAML authentication is configured). To enable use of logon evidence in StoreFront, use the following PowerShell to enable it for the Authentication Service associated with a store named: Store.
Get-Module "Citrix.StoreFront.\* –ListAvailable \| Import-Module \$StoreName = "Store" \$StoreVirtualPath = "/Citrix/" + \$StoreName \$store = Get-STFStoreService –VirtualPath \$StoreVirtualPath \$auth = Get-STFAuthenticationService –StoreService \$store \$auth.AuthenticationOptions.CollectFasEvidence = \$true \$auth.Save()
Step 6 - Modify the sample FAS assertion plug-in
The skeleton code in the sample plug-in accepts any evidence. Update the code in the sample to check that the supplied logon evidence (a SAML response) is valid.
It is your responsibility to ensure that the evidence supplied is checked. Consider:
checking that the SAML claims have a cryptographically valid signature
checking that the SAML claims are signed with the IdP’s certificate
checking that the UPN in the SAML claims corresponds to the UPN being presented
checking that the claims were issued within an acceptable timespan (what is “acceptable” is up to you)
StoreFront Authentication SDK
You can use the StoreFront Authentication SDK to perform advanced customization of evidence data. For more information, see the document “Custom Federated Logon Service Sample 1811.pdf” supplied in the SDK, or available on https://developer-docs.citrix.com/.
- Citrix Federated Authentication Service documentation
- StoreFront PowerShell SDK documentation
- Citrix Federated Authentication Service Assertion SDK from https://www.citrix.com/downloads/storefront/sdks