Citrix Federated Authentication Service Integration with APM

Introduction

This guide will cover how to use APM as the access gateway in front of Storefront when using Citrix FAS. This will enable you to leverage authentication methods like SAML, Kerberos, or NTLM on the client side. Note that almost any auth method can be supported via Receiver for web, but Receiver self-service does not support some auth methods such as SAML.

Deploy Citrix Federated Authentication Service

Now you’ll need to deploy Citrix Federated Authentication Service (FAS). Deployment of FAS is out of scope for this article, but as there are many parts I found the following guide from Carl Stalhood very helpful: http://www.carlstalhood.com/citrix-federated-authentication-service-saml.

Ignore the section “SAML on Netscaler Gateway” since you’re going to deploy APM instead, but don’t miss that last section “Configuring Storefront for SAML Gateway”. When configuring Storefront anywhere it requests the Netscaler Access Gateway address you’ll use the FQDN you intend to use for your virtual server on Big-IP (how users will access Storefront). Examples include the callback URL field when configuring the authentication and when configuring the Netscaler gateway.

Before proceeding, you should be able to go direct to the Storefront server, log in, and be able to launch an application successfully. There can still be misconfigurations that prevent access through an access gateway, but you will have fewer areas left as problems.

You must use an Enterprise CA, otherwise on the CA you will see pending certificates not getting approved automatically and you will be unable to launch apps.

Also note that if you have previously made configuration modifications usually needed for earlier versions like Citrix 6.5, such as host file entries, those should be removed prior to proceeding. For correct operation of FAS, DNS needs to be setup properly which may include setting up PTR records.

Create the SAML SP

In the Big-IP GUI go to Access Policy -> SAML -> Big-IP as SP and click create. You’ll create an SP config and for the entity ID in the format https://my-vs-fqdn.domain.com. All the rest can be left default.

Now you’ll need to setup your IdP Connector. This could be another Big-IP APM, ADFS, Okta, or any other IdP service. You can import the metadata if available or you can manually configure it. Configuring the IdP connector is out of scope for this article, but after configuring it, you’ll select your SP and click the “Bind/Unbind IdP Connectors” button, “Add New Row”, select it from the drop down as the SAML IdP Connector, then click Update, OK.

Note that you can bind multiple IdP connectors here if there are multiple IdPs. You need to set a matching source (variable) and the matching value that should cause use of that IdP. A common solution might be %{session.server.landinguri} for the source and /customer1 for the matching value to go to customer 1’s IdP.

Now you’ll see this on the SP configuration page.

Your IdP should be setup to send either the user’s userPrincipalName or sAMAccountName as the NameID. This should match either the userPrincipalName or sAMAccountName of the user account in the AD domain used by Citrix that you want the user logged in as. Carl Stalhood’s guide linked above provides an example configuring the ADFS IdP and he is using userPrincipalName.

Note that if you decide to use alternate UPNs (not matching your AD domain name) for your users you will also need to enable those domains in “Trusted Domains” on your Storefront server.

Deploy the iApp

Now we can move on to deploying APM as your access gateway. First, deploy the latest iApp. At the time of writing this article, that’s version 2.4.0. When deploying the iApp you’ll need to answer the following questions as shown:

You’ll need to specify your STA servers:

Finally, pay special attention to the DNS name you’re going to have clients use. This should be the same as you used in the Citrix Storefront configuration earlier and the SAML configuration later. This is how users are going to access the deployment.

Now you have the iApp for Citrix deployed, but it’s using the default forms based authentication. You need to customize the authentication method. This guide will help you deploy SAML authentication, but as mentioned you could use NTLM, Kerberos, or another authentication method.

Before proceeding you need to verify that the certificate you’ve selected is valid. If it is not, SSO will fail when Storefront tries to callback to the virtual server and the user will get the error “Cannot Complete Your Request”. You can browse to the FQDN you entered from the Storefront server to make sure you don’t get certificate errors. Normally you would use a publicly signed certificate and that will work fine (but don’t forget the chain). If it’s an internally signed certificate, your Storefront server needs to trust it as well.

Modify the iApp’s APM Policy

By default the policy looks like this:

We need to modify it to look like this:

To modify the policy you will need to turn off “strict updates” on the iApp:

Note that in this case we aren’t modifying the Receiver branch because Receiver doesn’t support SAML authentication. You could just change it to deny receiver clients if desired.

First remove the Logon Page, AD Authentication, and SSO Credential Mapping objects from the Browser branch.

Next add a SAML Auth object right before the Session Variable Assign object (plus sign, Authentication tab, SAML Auth). Select the SP you configured earlier.

Next, open the Session Variable Assign. You need to add a new entry, and set session.logon.last.username to equal the session variable session.saml.last.nameIDValue. Notice that the domain and sta_servers variables were set here already, those were done by the iApp.

Here is what creating that looks like:

Now your policy should look like the one above.

Be sure to click Apply Policy in the top left.

Test

And finally you should be able to browse to the FQDN of your new virtual server, be redirected to your SAML IdP for authentication, then get redirected back and SSO’ed in to your Citrix environment. You should be able to see the Storefront catalog and launch an application

Updates

12/21/2016 - Removed an iRule that is not needed for SSO to function properly in a complete deployment