I needed to use a Citrix NetScaler both, as a SAML identity provider (IDP) and service provider (SP). So I set up my test environment accordingly.
What my test environment looked like:
You see, I created two admin partitions on my Citrix NetScaler, one for the service provider (SP partition), cotaining both, the SAML SP and a web server, and one for my identity provider (IDP partition), containing the IDP.
I used this partitions to emulate “2 different NetScalers” as it does not make sense to have both, SAML-SP and SAML-IDP in the same data center (you could do conventional LDAP/RADIUS/TACACS authentication instead).
How SAML works:
SAML authentication uses an external server for authentication, the so called SAML Identity Provider (SAML-IDP).
The SAML Service Provider (SAML-SP) is local, close to the resource, and calls for Authentication to the SAML-IDP.
So a user connects to a resource. If the user had not been authenticated before, he gets gets forwarded to the logon server, the so called SAML-SP.
The SAML-SP forwards the user to the SAML-IDP for actual authentication. The SAML-IDP does the authentication.
After successful authentication, the SAML-IDP forwards the user to the SAML-SP. It also passes the so called assertion, the prove this user was authenticated successfully. You could think of an assertion like a man’s ID card. As soon as the SAML-SP has validated the assertion, it forwards the user to the resource.
SAML-SP and resource are always located on the same Citrix NetScaler, the SAML-IDP is usually located “somewhere else on the internet”.
SAML uses certificates to establish trust between SAML-SP and SAML-IDP.
The SAML-SP uses a server certificate to authenticate to the SAML-IDP. This certificate (not the private key, of course) has to be on the SAML-IPD as well, so it can get checked.
The SAML-IDP uses a certificate to digitally sign (and encrypt) the assertion. This certificate (again: not the private key) has to be present on the SAML-SP, so the SAML-SP is able to decrypt and validate the assertion.
It’s possible to use the same certificates for both, SSL between client and SAML-IDP / SAML-SP, and to prove identity, however I would rather use private (and therefore more trustworthy) certificates to prove identity.
NetScaler as a SAML Service Provider (SAML-SP)
A Citrix NetScaler may be a SAML identity provider for any SAML service provider. An other NetScaler may be the service provider, but also services like Microsoft Azure, Microsoft Office 365, Citrix Sharefile and many more may use a NetScaler as an authentication source.
In my example I just created a simple load-balancing vServer and added authentication to it. There is nothing special about it, in fact I used my test server (a description might be found there).
add server www 10.127.255.250
add service lb_svc_www www HTTP 80
add lb lb_vserver lb_vsrv_www HTTP 192.168.0.4 80
bind lb lb_vserver lb_vsrv_www lb_svc_www
The NetScaler SAML Authentication policy
The NetScaler SAML Service provider action
GUI: Navigate to:
Security → AAA-Application Traffic → Policies → Authentication → Basic Policies → SAML
With SAML Actions click Add.
add authentication samlAction saml_sp_server -samlIdPCertName lets_encrypt -samlSigningCertName lets_encrypt -samlRedirectUrl "https://idp.norz.at/saml/login" -samlUserField "Name ID" -samlIssuerName "https://sp.norz.at"
|IDP Certificate Name*||SAML IDP’s certificate|
|Redirect URL*||The URL of the SAML IDP in use, if IDP is a NetScaler: /saml/login|
|User Field||User Name in assertion, if IDP is a NetScaler this is Name ID|
|Signing Certificate Name||a certificate used to sign the SAML assertion (a normal server certificate)|
|Issuer Name||The FQDN of the SAML Service Provider (this AAA server)|
The NetScaler SAML Service provider policy
GUI: Navigate to:
Security → AAA-Application Traffic → Policies → Authentication → Advanced Policies → SAML
The SAML Service Provider (SAML-SP) Authentication vServer.
Provide name and IP (port s usually 443, protocol can’t be changed)
bind a server certificate (this one gets exposed to users, so it has to be trusted!)
bind the authentication policy you previously created
add authentication vserver SAML_SP SSL 192.168.0.4 443
set ssl vserver SAML_SP -ssl3 DISABLED
bind authentication vserver SAML_SP -policy SAML_SP_pol -priority 100 -gotoPriorityExpression NEXT
NetScaler as a SAML Identity Provider (SAML IDP)
A Citrix NetScaler may also get used as a SAML Identity Provider (SAML-IDP). This allows to authenticate to any authentication source like LDAP, RADIUS, Certificates, TACACS, local (to IDP), Negotiate, O-Auth, SAML, WebAuth, EPA or Citrix StoreFront. In my example I authenticate to TACACS (TACACS policy is not included)
Creating the a SAML Identity Provider Policy
Creating the a SAML Identity Provider Action (Saml IDP Action) on a Citrix NetScaler
Security → AAA-Application Traffic → Policies → Authentication → Advanced Policies → SAML IDP. Go to Profiles.
add authentication samlIdPProfile SAML_IDP_profile2 -samlSPCertName SP-assertions-signing-cert -samlIdPCertName IDP-Signing-Cert -assertionConsumerServiceURL "https://sp.josel.net/cgi/samlauth" -samlIssuerName "https://sp.josel.net" -signatureAlg RSA-SHA256 -digestMethod SHA256
|Assertion Consumer Service URL||The URL of the Service provider (if NetScaler: https://FQFN/cgi/samlauth)|
|IDP Certificate Name||Certificate used to digitally sign the assertion (a normal server certificate)|
|SP Certificate Name||Certificate used by the service provider, so it can be trusted (see above)|
|Encrypt assertion||keep SAML traffic a secret (best practice)|
|Issuer Name||The FQDN of the SAML Identity Provider (this SAML IDP’s name)|
The SAML-IDP policy
The authentication policy
I don’t go into authentication policies here. Just follow Citrix bast practices, there are many guides out there. I created a policy similar to CTX113820.
The SAML Identity Provider (SAML-IDP) Authentication vServer.
provide name, IP address and port, usually 443 (the protocol can’t get changed)
bind a server certificate. This one gets exposed to the user, the user has to trust this certificate!
bind an authentication method and a SAML IDP policy
select both, the IDP and the authentication policy
I used following tools:
Citrix NetScaler’s log (Yes, there is a log on a NetSaler and SAML issues get logged there! You look at /var/log/ns.log)
FireFox add-on SAML-Message Decoder (also available for Chrome)
Citrix NetScaler Network traces
I have seen several issues recently:
SAML-SP fails to forward to SAML-IDP
detected: error in browser
check settings on in SAML-SP’s SAML Authentication action: Redirect URL
SAML-IDP fails to forward to SAML-SP
detected: error in browser
check settings on in SAML-IDP’s SAML-IDP Authentication action: Assertion Consumer Service URL
Certificate not trusted on SAML-IDP
detected: confusing message in browser, log in IDP’s /var/log/ns.log
add SAML-SP’s signing certificate to SAML-IDP’s SAML-IDP profile: SP-Certificate Name
I hope. that helps. Just drop me a message if you need more information. You’re very much welcome to link to my blog / my website. Thanks!