More and more Citrix partners and customers are gaining the benefits of using SAML authentication in conjunction with Active Directory Federation Services (ADFS) as SAML IdP source.
There are multiple reasons for using this scenario, including, but not limited to, transparent authentication of users that are trying to access different domains and using different user identifications for different services. I’d just tested a scenario in which a user has been authenticated on NetScaler Gateway using SAML authentication and then Citrix Federated Authentication Services (FAS) initiate certificate based logon process of this user to StoreFront and VDA.
Topology Used
- Client – MacOS with Safari Browser
- Citrix NetScaler – VPX Version 11.0-66.11
- Microsoft AD FS – Windows Server 2012R2, AD FS Management Version – 6.3.0.0
- Windows Domain Controller – Windows Server 2012R2 with Active Directory, Enterprise Certificate Authority, DNS roles installed
- Citrix Delivery Controller – Windows Server 2012R2 with collocated StoreFront Version 3.6 and DC Version 7.9
- Citrix Virtual Delivery Controller – Windows Server 2012R2 Version 7.9
- Configuration steps
I split the configuration into 2 steps:
- Configuration of AAA_TM vServer with SAML authentication on NetScaler and SAML IdP based on Windows AD FS. Just to make sure, that SAML and ADFS are working fine.
- Migration of my SAML authentification to Gateway configuration and made FAS installation to integrate SAML to StoreFront part.
Configuration of SAML authentication on NetScaler and SAML IdP based on Windows AD FS
I started with following this CTX113919 article for AD FS configuration. In spite of the fact that article describes integration with AD FS version 2, there is almost no difference between the configuration of integration with AD FS on Windows Server 2012R2 (AD FS version 3). The configuration worked just fine, but there were couple of points to play with:
Accessing AD FS web service to test if links are working. I did not have a lot of experience with AD FS. After going through all steps and faced some challeges with certificate configuration, I tried to test to see if AD FS was working properly. In step 3 of NetScaler configuration in this article, there is a link to AD FS looks like that https://<adfs_fqdn >/adfs/ls/ . I tried to access this link and got following error message:
That’s fine; no reason to worry about this. This link is only used for SAML Token assertion. Even if you are trying to access this link from your AD FS server, you will get this error. If you are able to access https://<adfs_fqdn>/adfs/ls/idpinitiatedsignon or https://<adfs_fqdn>/adfs/fs/federationserverservice.asmx , then everything is working fine.
Routing and DNS. The user that will access your LoadBalancing Server or your Gateway VIP will be automatically forwarded to AD FS site (as SAML IdP). So, the user should be able to resolve DNS name of your VIP, authentication VIP (if needed in AAA_TM configuration) and AD FS server. So, just as you can read here – https://citrixblogs.wpengine.com/2015/05/29/adfs-v3-on-windows-server-2012-r2-with-netscaler/ you need to have 3 public IP addresses (2 in case with Gateway configuration) and 2 DNS entries.
Certificates, used for communications. This was the trickiest part because of using two types of certificates, with and without private keys. I spent a lot of time dealing with the following error message in my browser:
And seeing the following output of „tail -f /var/log/ns.log“ command:Jul 21 14:26:57 <local0.err> 192.168.100.11 21/07/2016:12:26:57 GMT Netscaler 0-PPE-0 : default AAATM Message 48257 0 : “Error while trying to verify the signature”Jul 21 14:30:51 <local0.info> 192.168.100.11 21/07/2016:12:30:51 GMT Netscaler 0-PPE-0 : default AAATM Message 48889 0 : “AAATM Error Handler: Found extended error code 917511, ReqType 16388 request /cgi/samlauthSo, my mistake was, that I exported signing certificate from the AD FS, that was installed there after installation (by clicking on the certificate, importing in browser and then exporting it) and then made installation according to CTX113919 . In this case I received certificate installed in NetScaler without a private key. adfs-signing – without a key.
After that, I generated a pfx key on AD FS Server (through IIS Manager -> Server Certificates -> Create Certificate Request, then signed it in my CA Server and Complete Certificate Request in IIS Manager), installed it in AD FS (AD FS Management -> Service -> Certificates -> Right Click -> Add Token-Signing Certificate) and also installed in NetScaler (Configuration -> Traffic Management -> SSL -> Import PKCS #12)
After that, I changed “IDP Certificate Name” certificate from the “adfs-signing” (without a private key) to “fs_xenapp_local_with_key” and the problem was solved. So here is my configuration of SAML action :
So, in my case I learned, that both „fs_xenapp_local_with_key“ and „adfs.xenapp.local“ certificates should have private keys installed.
Configuration of FAS and using SAML for user authentication to StoreFront
After successful testing of SAML authentication with LoadBalancing VIP, I followed the guide, written by Carl Stalhood, to make installation and configuration of FAS with already configured SAML and migrated my LoadBalancing VIP to NetScaler Gateway (by just deleting LB VIP and creating Gateway VIP with the same IP Address and SAML authentication).
The authentication flow looked like this:
After accessing Gateway VIP (adfs.xenapp.local and IP 192.168.100.95 in my case), the user is automatically forwarded to AD FS page for SAML authentication (no more green bubble Theme or black screen):
It takes some time, before the certificate will be issued by CA for the user and the user will be forwarded to the StoreFront web page:
We can check the issued certificates for the users on CA, that had been authenticated at AD FS. In this case, the installed Certificate Template „Citrix_SmartcardLogon“ will be used:
Summary
I would like to summarize and thank the authors of the following articles, that had been used for testing this scenario:
- How to Configure NetScaler SAML to Work with Microsoft AD FS 2.0 IDP – http://support.citrix.com/article/CTX133919
- ADFS v3 on Windows Server 2012 R2 with NetScaler – https://citrixblogs.wpengine.com/2015/05/29/adfs-v3-on-windows-server-2012-r2-with-netscaler/
- Citrix Federated Authentication Service (SAML) – http://www.carlstalhood.com/citrix-federated-authentication-service-saml/
