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
Published Dec 19, 2016
Version 1.0
Graham_Alderso1
Employee
EmployeeGraham_Alderso1Employee
Employee
Henrik_SNimbostratus
Hello,
Very helpful article, when I found this I saw that I clearly overthought on how to leverage APM in front of StoreFront with FAS. This however made me look more into how you can get SSO to work "without" password prompt also in replacement mode.
It is possible!
1: Configure StoreFront to allow Domain Pass-through on the store
2: Add group or users to each VDA's local! security group: "Direct Access Users"
3: On a domain joined PC, install Citrix Receiver with the /includeSSOn argument to install the SSO service. -This actually caches the credentials a users types in at login.
On the domain joined PC, add the of your VS to the trusted sites list of Internet Explorer -Receiver uses this zone to validate if it should try a pass-through authentication or not.
4: On BIG-IP, check that your VPE ends with your sAMAccountName in session.logon.last.username variable and that you get a full WebTop with a Citrix Remote Desktop resource.
Check that your Citrix Remote Desktop resource has SSO enabled and set to SmartCard!
-This is quite interesting, since you've configured your broker to trust XML requests, it doesn't validate the credentials at this point and enumerates the Citrix resources.
-Also here you will instruct the Receiver client to perform pass-through authentication by adding the following lines to custom parameters:
SSOnUserSetting=On
EnableSSOnThruICAFile=On
UseLocalUserAndPassword=On
ConnectionBar=1
ShowDesktopViewer=On
Conclusion: If you have a domain joined PC, you can leverage any authentication protocol on the client-side, as long as you can figure out the sAMAccountName and still be able to SSO into Citrix resources in WebTop replacement mode.
PS: This has nothing to do with FAS :)
- Graham_Alderso1
Henrik,
Thanks for the comment! Essentially you are choosing not to have the APM perform SSO and instead the client will perform its own SSO using Windows credentials. This is certainly an option instead of something like FAS when all your clients are domain joined Windows PCs.
Manuel_Cristob2Hi Graham,
I have a need to authenticate users already federated (with a saml token) form O365 as SP and WAP/ADFS as the IDP before they reach the Citrix Storefront environment.
When the user clicks on the citrix/storefrom link in Sharepoint desktop, the user is sent to the F5 APM as the SAML SP for Citrix which relays on the same WAP/ADFS( originally sent saml response for o365 for the same user) as the F5's SAML idp. question : When the http request arrives to the F5 as saml SP for the SharePoint/Citrix, can we extract the original SAMl token assigned by ADFS as the idp for o365 and use it to generate the SAMl request to the the same ADFS/WAP idp that authenticated this user (from the 0365 SP)?
Hope I am clear
thanks Manuel
- Graham_Alderso1
Manuel,
I think I understand what you're trying to do. Unfortunately what you've described won't work. O365 and F5 SAML SP will each need its own assertion and relying party relationship in ADFS. Also, your O365 Sharepoint will actually be WS-Fed with ADFS, not SAML. Fortunately this is all easy to do and is the way ADFS or any other IdP is designed to work.
Here's an example of the user experience when deployed properly with two relying parties in ADFS. User goes to Sharepoint Online. Sharepoint Online redirects them to ADFS for login. User logs in to ADFS and is sent back to Sharepoint Online with an assertion. User now goes to Citrix which is protected by F5 as SAML SP. F5 as SAML SP redirects them to ADFS for authentication. User is already logged in at ADFS so ADFS generates an assertion and sends them back to F5 as SAML SP. F5 as SAML SP validates the assertion and grants access to Citrix.
Be sure to check out the new ADFS Proxy functionality in 13.1 with MS-ADFSPIP support. It can replace the WAP servers in front of your ADFS environment. You can use the same BIG-IP that you use for SAML SP in front of Citrix.
- Manuel_Cristob2
Thanks very much this is exactly want I need to do..
Here's an example of the user experience when deployed properly with two relying parties in ADFS. User goes to Sharepoint Online. Sharepoint Online redirects them to ADFS for login. User logs in to ADFS and is sent back to Sharepoint Online with an assertion. User now goes to Citrix which is protected by F5 as SAML SP. F5 as SAML SP redirects them to ADFS for authentication. User is already logged in at ADFS so ADFS generates an assertion and sends them back to F5 as SAML SP. F5 as SAML SP validates the assertion and grants access to Citrix
is this supported?
- Graham_Alderso1
Yes. You don't need to do anything special, the flow I described will "just work" when ADFS is federated with both O365 and F5 as SAML SP and you have set things up as noted above.
ncartaya99_3514Hi Graham, I'm working with Manuel on the SHarePoint/Citrix SAML use case described above. When I look at the Session logs in the F5 and look at my session, I see the following error "SAML Agent /Common/Eaglestorefront-final_act_ag_SAML assertion is invalid error AuthenticationStatement must have AuthnInstant attribute". The claims rule in ADFS is set to map User-Principal-Name to Name ID. Do I need an additional claims rule for the AuthnInstant attribute in ADFS or is this attribute set in the F5 SP?
- Graham_Alderso1
I have never needed to add that manually with ADFS. I suspect that there was an error and the ADFS response is indicating the error instead of including an assertion and AuthenticationStatement. BIG-IP might then complain about the missing AuthnInstant, but that's just a symptom of the entire AuthenticationStatement missing. You can look for a StatusCode at the end of the SAML (Use SAML Chrome Panel or Firefox SAML Tracer to see the SAML), it should say success and there should be an assertion, if it's anything else then there is a configuration problem. You can review StatusCode messages here: https://msdn.microsoft.com/en-us/library/hh269642.aspx
Another thing to double check while you're at it is whether the time is in sync between BIG-IP and ADFS.
If you want to try adding the AuthnInstant manually (again, I've never needed this), it might be something like this: Transform: Authentication Time Stamp -> Authentication Time Stamp Transform: Authentication Method -> Authentication Method
- Manuel_Cristob2
Hi Graham
Whats the F5 version that we must run for this deployment? We seem to get stuck when the Storefront tries to validate the F5 as a trusted gateway via this URI...
/AuthService/Auth,,,asmx
Any ideas?
much appreciated
- Graham_Alderso1
It sounds like your problem might be with ADFS federation to APM, not the Citrix use case this article covers. I've successfully federated APM with ADFS in BIG-IP v11, v12, and v13. For this particular Citrix use case, I believe it was v12.1 I validated it against, but can't think of a reason it wouldn't work on an earlier version.
It's probably worth double checking that you're running the latest release of whatever version you're on so that you have all the current patches (currently v11.5.5, v11.6.3, v12.1.3, v13.1.0). See here: https://support.f5.com/csp/article/K2200.