Citrix ADC (NetScaler) as a SAML IDP and SAML SP

last update: 2018/11/20

I needed to use a Citrix ADC (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 ADC, 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 Citrix ADCs / 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).

You may try it, using test both, as username and password. Just surf to https://sp.josel.net. There is some chance for certs to be outdated as I don’t put much effort into this. The Saml IDP only does local authentication and will then forward to the SP showing content of www.norz.at. I’d suggest doing your experiments using FireFox and SAML Tracer plugin. This will give you good insight is SAML assertions. The Policies are displayed and discussed here.

I also provide the original ns.conf files of both partitions for download. They are just copied from my Citrix ADC (NetScaler) 12.1


How SAML works:

In Saml the ressource (SP, Service Provider, so the web-site needing authentication) uses an external withness (IDP, Identity Provider) to handle user logon. They send messages called assertions.

Of course it’s a bit hard to make sure the IDP is the desired, trustworthy, one. Same for the IDP, it’s hard to find out wether the SP requestiong authentiocation is a trustworthy one. Trust is created using certificates.

So a user connects to a resource (SAML SP). If the user had not been authenticated before, he gets gets forwarded to the logon server, the so called SAML-IDP. The SAML-IDP does the authentication.

After successful authentication, the SAML-IDP forwards the user back to the SAML-SP, also sendig 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 checked 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”.


Certificates

SAML uses certificates to establish trust between SAML-SP and SAML-IDP.

The SAML-SP uses a server certificate to sign it’s assertion (message) sent to the IDP. So the IDP needs to own the SP’s certificate (not it’s private key!). These certificates usually are private, not trusted ones.

The SAML-IDP also uses a certificate to 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. In my setup I use the same let’s encrypt certs for both, SSL and SAML.


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 service svc_HTTP 192.168.0.1 HTTP 80
add lb vserver lb_vsev_sp SSL 192.168.0.100 443 -AuthenticationHost idp.josel.net -Authentication ON -authnVsName SAML_SP
bind lb vserver lb_vsev_sp svc_HTTP
bind ssl vserver lb_vsev_sp -certkeyName sp.josel.net
set ssl vserver lb_vsev_sp -ssl3 DISABLED -tls13 ENABLED

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.

Citrix NetScaler: SAML authentication service provider (SP) policy action
add authentication samlAction saml_sp_server -samlIdPCertName idp.josel.net -samlSigningCertName sp.josel.net -samlRedirectUrl "https://idp.josel.net/saml/login" -samlUserField "Name ID" -samlIssuerName "https://sp.josel.net" -signatureAlg RSA-SHA256 -digestMethod SHA256

IDP Certificate Name* SAML IDP’s certificate (we need to own it, but we don’t own it’s private key)
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. We own a private key!)
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

Citrix NetScaler: SAML authentication service provider (SP) policy
add authentication Policy SAML_SP_pol -rule true -action saml_sp_server


The SAML Service Provider (SAML-SP) Authentication vServer.

creating a Service Provider on Citrix NetScaler
Click add
Citrix NetScaler as a SAML authentication server
Provide name and IP (port s usually 443, protocol can’t be changed)
binding a certificate
bind a server certificate (this one gets exposed to users, so it has to be trusted!)
Citrix NetScaler VPX: binding a SAML SP policy
bind the authentication policy you previously created

add authentication vserver SAML_SP SSL 0.0.0.0
set ssl vserver SAML_SP -ssl3 DISABLED -tls13 ENABLED
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, Negotiate, O-Auth, SAML, WebAuth, EPA. In my example I do Citrix ADC (NetScaler) local authentication.


Creating the a SAML Identity Provider Policy

Creating the a SAML Identity Provider Action (Saml IDP Action) on a Citrix NetScaler

Navigate to:

Security → AAA-Application Traffic  → Policies → Authentication → Advanced Policies →  SAML IDP. Go to Profiles.

Click Add.

Citrix NetScaler: SAML IDP authentication Profile
add aaa user test -password 05c23bc6c5fa0108182aabb53367c84a7f67693371667cf044dc246ac3b88aa2 -encrypted -encryptmethod ENCMTHD_3
add authentication samlIdPProfile saml_IDP_profile -samlSPCertName sp.josel.net -samlIdPCertName idp.josel.net -assertionConsumerServiceURL "https://sp.josel.net/cgi/samlauth" -samlIssuerName "https://idp.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, we own the private key)
SP Certificate Name Certificate used by the service provider, so it can be trusted (IDP does not need to own the private key)
Issuer Name The FQDN of the SAML Identity Provider (this SAML IDP’s name)

The SAML-IDP policy

Citrix NetScaler: a SAML IDP Policy
add authentication samlIdPPolicy saml_IDP_Policy -rule true -action saml_idp


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.

add authentication Policy local_auth -rule true -action LOCAL
bind authentication vserver aaa_vsrv_test -policy local_auth -priority 100 -gotoPriorityExpression NEXT


The SAML Identity Provider (SAML-IDP) Authentication vServer.

Citrix NetScaler: creating a SAML IDP server
click add
Citrix NetScaler as a SAML IDP
provide name, IP address and port, usually 443 (the protocol can’t get changed)
binding a certificate
bind a server certificate. This one gets exposed to the user, the user has to trust this certificate!
Bind authentication methodes
bind an authentication method and a SAML IDP policy
NetScaler SAML IDP: Binding the IDP policy
select both, the IDP and the authentication policy

add authentication vserver aaa_vsrv_test SSL 192.168.1.1 443
set ssl vserver aaa_vsrv_test -ssl3 DISABLED -tls13 ENABLED
bind authentication vserver aaa_vsrv_test -policy samlIdPPolicy -priority 100 -gotoPriorityExpression END
bind authentication vserver aaa_vsrv_test -policy local_auth -priority 100 -gotoPriorityExpression NEXT


Trouble shooting

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

Issues:

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!

Leave a Reply

Your email address will not be published. Required fields are marked *