This article’s intent is to provide guidance on a simple SAML authentication setup leveraging Azure MFA via SAML, for Workspace App authenticating at Citrix Gateway. The TL;DR for this write up is you need a simple AAA advanced policies config for this to function. This article was tested on Citrix Workspace App for Windows 1812, as well as Workspace App for Mac 1812 and 1901. Mobile apps are not yet supported for SAML. This was tested on Citrix ADC 12.1 b50.28 and 50.31.
Similar to my earlier blog on Multi-Datacenter FAS architecture, this article is NOT a how-to guide on installing and configuring FAS or Azure MFA integration to Citrix ADC, although these are certainly pre-requisites. For those steps, hit up these useful links:
NOTE: As of June 8th, 2021, Citrix has identified two vulnerabilities covered in CTX297155. Upon remediation with appropriate firmware, SAML configurations require adjustment as per CTX316577. This article’s examples do not contain those adjustments and readers are encouraged to modify their deployments accordingly to mitigate the security risk.
While working through the design phase over summer of 2018 for our multi-national customer for their next-gen Citrix platform, our “pro-cloud” and “pro-Microsoft” client was relatively dismayed at the lack of Receiver + SAML support at Citrix Gateway for external use cases. Azure AD provides a great SSO experience for their end-users and they were adamant to extend this into the new Citrix platform, which necessitated FAS as they were in the process of winding down their Microsoft NPS platform which would have circumvented the need for SAML.
At the Citrix ADC level, keeping things browser-only for authentication simply resulted in building the Citrix Gateway vServer and binding a basic auth SAML policy for Azure MFA (in our case, two policies at each datacenter as we wanted the ability to authenticate both to the GSLB URL, and to the respected site-specific Gateway URLs behind GSLB for administrative testing). Nothing special, nothing fancy. We had no need for LDAP group extraction thus the SAML assertion returned from Azure MFA did the trick, although this config could certainly be extended to include a second factor of LDAP with the assertion being leveraged and passed into the LDAP factor for group extraction.
And then in Fall of 2018, Citrix announced the SAML at Citrix Gateway feature was finally available for Workspace App (formerly Receiver), so we had to share the good news with the client and get it working.
The first issue we ran into was well, we couldn’t even authenticate when attempting to throw the external Gateway URL into the Citrix client. We were getting the classic “Your account cannot be added using this server address…” message.
A bit of searching in the Citrix discussions yielded some indication that basic auth policies just will not do for Workspace App. It expects the browser-based authentication screen that comes only with advanced polices from an AAA vServer. I wasn’t thrilled at the notion of adding much more complexity to the solution merely for the rare instances of external users authenticating Workspace App to Citrix Gateway, but luckily it really wasn’t all that bad.
On a totally unrelated note, once we got that working however, we were authenticating just fine, but post-auth we were again receiving the same error message. After a fair bit of troubleshooting it was determined that the session policies we had bound to our Gateway vServers were the culprit. The use of || for (or) statements were impacting Workspace App’s attempts to continue forward integrating with StoreFront, which was quite baffling as the || expression element was set on policies that the Citrix client wouldn’t even be hitting on account of the binding order and expression filtering (user-agent). But alas its mere presence in any policy bound to the vServer was sufficient to derail the process. Reworking the expression to omit || fixed the issue immediately.
For our Workspace App + SAML at Gateway challenge, we were able to get this squared away fairly easily by building a non-addressable AAA vServer (yes, this will necessitate Advanced aka Enterprise licensing on your ADC), and binding the SAML policies there. No fancy login schemas or next factors needed. Just an AAA vServer with bound SAML auth policies, and an authentication profile binding the Citrix Gateway to the AAA vServer.
Pre-requisites before we get going:
- A supported firmware version of Citrix ADC – we tested with 12.1 b50.28 and v50.31 ourselves
- Citrix ADC Advanced (formerly Enterprise) license
- Current Citrix clients (we tested with Workspace App 1812 for Windows and Mac, and 1901 for Mac)
- Azure MFA configs to be in-place already (see above article reference)
- Citrix FAS is functional and properly integrated (see above article reference)
- Citrix Gateway vServer is created and configured
- Proper Receiver policies and profiles are configured and bound to your Gateway (reference https://support.citrix.com/article/CTX139963)
In our case, the following SAML profile was sufficient for us to get the proper assertion sent back to Citrix Gateway and sent back to the StoreFront servers properly. Below is the SAML policy we used.
And here are the policies. Note that in a simpler setup with no GSLB, you may only need one policy and a ‘true’ expression. In our case we wanted to ensure we could authenticate both via GSLB and via the local URL for the Gateway at a particular datacenter so we have expression policies activating based on URL. The client’s IAM team believed there may be a way to use a single policy and server combination (vs. configuring two separate sets on the ADC and two separate apps in Azure AD) but we were on a deadline and wasn’t inclined to spend too much time further engineering something we already had working.
We then built our simple AAA vServer after enabling the feature on the appliance. Providing the CLI commands for reference. Note that our hardware supported TLS 1.3 we had some other hardening parameters set, so feel free to strip out the “set” command below if you haven’t created a DH key for PFS or your appliance doesn’t support TLS 1.3.
add authentication vserver NSG_MYAPPS_VS_AAA SSL 0.0.0.0 set ssl vserver NSG_MYAPPS_VS_AAA -dh ENABLED -dhFile "/nsconfig/ssl/dhkey2048.key" -dhCount 1000 -ssl3 DISABLED -tls1 DISABLED -tls11 DISABLED -tls13 ENABLED -HSTS ENABLED -maxage 4294967294 bind ssl vserver NSG_MYAPPS_VS_AAA -certkeyName YOURGATEWAYCERTNAMEHERE
Next, our authentication profile is created and linked to our AAA vServer. The below command will create the policy, you can link it in the GUI as an authentication profile or set it on the vServer via CLI with the -authnProfile parameter.
add authentication authnProfile nFactor_AuthProfile_MyApps -authnVsName NSG_MYAPPS_VS_AAA
And then we can bind the authentication policies to the vServer, again in our case we had two, just showing the command for one below, or of course, use the GUI.
bind authentication vserver NSG_MYAPPS_VS_AAA -policy AzureMFA_MyApps_AAA_Policy -priority 100 -gotoPriorityExpression NEXT
And now for some validation…
Michael Shuster is Ferroque Systems’ Chief Architect and noted Citrix authority. A passionate virtualization and digital workspaces advocate, he has designed, engineered, or otherwise advised clients on Citrix, VMware, and Microsoft technology platforms across the globe.