Technical Articles
F5 SMEs share good practice.
Showing results for 
Search instead for 
Did you mean: 
Custom Alert Banner
F5 Employee
F5 Employee


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:

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


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


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




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:












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 🙂


F5 Employee
F5 Employee



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.



Hi 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


F5 Employee
F5 Employee



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.



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?


F5 Employee
F5 Employee

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.



Hi 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?


F5 Employee
F5 Employee

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:


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



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




Any ideas?


much appreciated


F5 Employee
F5 Employee

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:



Thanks Graham,,


We see the successful SAMl assertion from ADFS for NameID=emailaddress however the Storefront does not trust the F5 as a federated gateway as the callback URL renders a 404 page not found from the F5.


The CallBACK URl that we are using points to the F5 VIP... (matches F5 VIP ip)/CitrixAuthService/AuthService.asmx.


We had to create and deploy and irule at the VIP that disables the policy when the F5 sees such HTTP request otherwise, we were getting redirected to the SAML IDP for such HTTP/URI request,,,


Obviously, the F5 will reach the Storefront farm via the Floating ip and not the VIP -so we tried using a FQDN that points to the Floating ip instead of the VIP IP for the CALLBACK URL but no luck.


I am assuming that the URI in the CALLBACK URL or /CitrixAuthService/AuthService.asmx should only render a simple HTTPs handshake so the Certificate from the F5 is trusted by the Storefront as part of the gateway verification/validation process.


My next step will be to configure a separate VIP listening to SSL and rendering Client SSL profile with the Cert needed for Storefront verification that is not the VIP or the floating ip and after that -point the CALLBACK URL to this new vip. If this does not work we will upgrade to version BIGIP 12.1.3 We are running Storefront version 3.13.


Thanks again




F5 Employee
F5 Employee

Double check that you completed every step in the section "StoreFront Config for SAML NetScaler Gateway" on Carl Stalhood's FAS setup guide that I linked above. Usually this is caused by missing a step. An alternative that I have seen is where the VIP is not accessible (or internal DNS doesn't point to the VIP) so the callback fails. Storefront logs will tell you this.


If you disable APM for the calls from Storefront as it sounds like you've done, then your callback will definitely fail because the BIG-IP doesn't know how to process the callback. This has been deployed widely and no disabling of APM is necessary for the callbacks (and would actually break it as noted).


If for some reason you can't allow Storefront to talk to the VS on an external interface, you can stand up another VS on the internal interface on a new IP and either use internal DNS or HOSTS file on the Storefront server to point the DNS name at that internal side VS. The VS should be setup exactly the same as the regular one, all the same profiles.


I have also seen this occur due to cipher selections, where custom high security cipher selections were used on the BIG-IP and the Storefront server could not negotiate them.



Thanks again


We will try the cipher selection as we have the VIP's SSL profile for the front end pretty secured.


Then if still we have a no go,,,We will create a new VIP just for CALLBACKURL ( a mirrored config from the front end VIP/SAML SP)









just wondering if anyone has gotten SAML working with the new workspace app. It looks like its finally supported with a netscaler and FAS, but havent been successful trying to get the same with APM.


Any update on whether or not the Citrix Workspace APP will work with SAML and APM?






I'm not able to pass SSO to Storefront. I don't see any traffic from APM to Storefront. Only health check traffic. I see the log "Following rule 'fallback' from item 'Session Variable Assign' to ending 'Allow'" but I don't see any packet from APM to Storefront.


However, I can see the right SAML Assertion and the right username got from IdP in the APM.


On the other hand, I see an iRule in the Virtual Server, which has been added automatically with the iApp and I don't know if I have to delete it.


Thanks, best regards.

Version history
Last update:
‎19-Dec-2016 12:43
Updated by: