in NetScaler, Security

How To: NetScaler 10.5 as SAML Identity Provider

In this how-to we will explain how to setup the NetScaler as a SAML Identity Provider (IdP) for SAML 2.0 so we can generate tokens / assertions to be consumed by a SAML Service Providers (SP).

The SAML IdP feature is added in the 10.5 release of NetScaler released mid 2014.

Since you ended up here, most likely via Google, you know what SAML is. If not, in short, SAML can be used for authentication of users over public networks. So you can split Services (like Office 365 or SalesForce – SAML SP) from the user directory (like your internal AD – SAML IdP). NetScaler can act as both, but in this blog we will focus on being the SAML Identity Provider.

Please do note that NetScaler is not a drop in replacement for any existing IdP as they usually do more that just generating SAML tokens. Know what the requirements of your organization and SP are and see if NetScaler is IdP can fulfill them.

Requirements

  • You require some knowledge on SAML and NetScaler in general to be able to configure this and understand what you are doing.
  • NetScaler 10.5 (or higher) Enterprise Edition (we need AAA feature)
  • A directory to talk to (LDAP based, AD preferred)
  • The ability to create certificates (PKI / On the NetScaler / etc.)

Target Topology

This setup on it’s own will not lead to something particularly useful. If you have IdP in you network you can create assertions / tokens but in the end something will need to consume those tokens. This can be the same or another NetScaler, Office 365 or one of the many other services that support SAML 2.0 SP. This, however, is beyond the scope of this how to. A separate article on how to setup the NetScaler as SAML SP will follow.

We will focus on creating the topology below where the NetScaler generates SAML assertions to be consumed the a SAML Service Provider. User authentication is done via LDAP (other options are possible). Below is a simplified view of the traffic flow.

2014-08-27 SAML IdP NetScaler overview

  1. User connects to a service he / she would like to access
  2. Service redirects the users to the SAML IdP to get a assertion
  3. After user enter his / her credentials in the NetScaler the NetScaler will validate this against the LDAP server
  4. After succesfull authentication the NetScaler returns the user a SAML token and..
  5. redirects the users to the requested service from step 1

Certificates

One of the things that go wrong most commonly are the certificates. SAML relies on certificates quite heavily, so we need to make sure that we get this right. If you are experienced with certificates and SAML and you know what you need, please skip this (the rest of this how-to assumes we have 3 certs in place, a cert for the AAA vServer and a signing cert for the IdP and the cert you got from the SP), if you are not are or in doubt, please read this.

When creating a certificate on NetScaler you typically create 3 files in the process:

  1. Private key (RSA key)
    This must remain private and not leave the NetScaler at all times (ok, maybe for back-up reasons). I recommend that you create a private key for both the AAA cert and for the IdP Signing Cert
  2. Certificate Signing Request.
    This is send to you certificate authority to get singed. This certificate authority can be both public or private as this certificate will not be access by the end-users but you might need to send your root / intermediate certs to the SP in case of a private CA.
  3. Certificate
    The actual certificate to encrypt traffic or sign the assertions.

I will assume that we will need 3 certificates for our setup of which 2 are created on the NetScaler:

  1. Server certificate for the AAA vServer
    Created on the Netscaler. This certificate will be bound to the AAA vServer and must match the URL that is tied to this AAA vServer. Also, for production environments, you want this certificate to be singed by a trusted and public Certificate Authority to avoid SSL errors / warnings in the users browser. This is the same principle as any SSL vServer on the Netscaler. For example, when users access you AAA IdP vServer via the URL https://saml.domain.com you need a certificate to mach this.
  2. IdP Signing certificate
    Created on the Netscaler. This certificate will be used to sign (not the same as encrypt!) the SAML assertion. This certificate will be send to the SAML Service Provider so a secure match can be made.
  3. SP Signing Certificate
    Created on the Service Provider. This is basically the same certificate type as the IdP certificate, but the Private key is on the SP, and the NetScaler only holds the public key.

There are many articles out there how to create / import  certificates. Please use these to create certs if you are not familiar how to do this. Please create the Server, IdP and optionally the SP certificates.

Configuration of the SAML IdP part

Remember this How To is only about the IdP part. It assumes that you have a SAML SP somewhere that will point to the NetScaler. This can be any SP including the same or another NetScaler. If it is the same NetScaler it will require a second AAA vServer (that does not need to be publicly addressable a the LB vServer will send the redirect). In the setup for this article I used a second NetScaler (10.1) acting as SP. For your convenience I have included a dump of my NetScaler as SAML SP at the bottom of this article, but no explanation here!

You need the Service Provider Certificate and Issuer name (optional) to be able to complete the instruction below!

1 – General Settings

  1. Enable AAA
    We start with ensuring we have the needed features enabled. For this we need “SSL Offloading” and “Authentication, Authorization and Auditing”. Hit System -> Settings and enable those features if not done so already.
    SAML - Configure Features
  2. NTP Server settings
    SAML token have a time stamp. If there is a too big difference (think seconds, not larger) between the time on the SP and the IdP all will fail. So make sure that both the IdP and the SP have a NTP server configured. If you have not done so so far on the NetScaler please first do a time sync to a NTP server manually (so we know it is correct straight away) and configure NTP servers via the GUI afterwards. There are several URL describing how to configure NTP on NetScaler the Citrix Blogs.

    • drop into the BSD SHELL
    • type ps axfu | grep ntp
    • type  kill <Process Number>  on any NTP processes currently running
    • type ntpdate <IP of NTP server>
    • start the service again: /usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/ntpd.log &
  3. Certificates
    Triple check you have all the certificates required. You need to create a server cert for AAA, a Signing Cert for the IdP and you need to import the Public cert received from the SP. You cert GUI may look like (I used internal certs only as this is just test):
    SAML - Cert overview

2 – Create the Authentication Polices and Profiles

  1. Create the SAML IdP Profile
    • Go to NetScaler -> Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> SAML IdP and hit the tab Profiles
    • Click the Add button
      • Name: Enter a descriptive name for the profile
      • SP Certificate Name: Select the certificate the the SP uses to sign the SAML assertions. This is the certificate that you received from the SP.
      • IDP Certificate Name: Select the certificate you created for singing the assertions. The certificates public key will be shared with the SP.
      • Assertion Consumer URL: This is the URL on the Service Provider the NetScaler will post the assertion here after a successful login (SP specific setting)
      • Send Password: Leave unchecked
      • Issuer Name: Some SP expect a name here that matched on both the SP and the IdP.
        SAML - IdP settings
    • Click Create to create the profile.
  2. Create the SAML IdP Policy
    The SAML IdP policy will be used to select what profile to use under certain conditions.

    • Go to NetScaler -> Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> SAML IdP and hit the tab Policies
    • Click the Add button
      • Name: Enter a descriptive name for the profile
      • Action: Choose the action created in the previous step
      • Expression: Enter the  http.req.url.contains("saml")  value here to make sure the policy is hit for all traffic aimed at the SAML part of the AAA vServer.
        SAML - NS IdP Policy

      Click Create to create the profile.
      Also see the BONUS section at the bottom of the page.

  3. Create the back-end user validation (LDAP) Server
    When a user hits the NetScaler IdP we need a source to validate users against. We have several options here, like a local user DB, RADIUS and LDAP. Since LDAP is used most by far (to authenticate against AD) this is what we will use in this example. First we create the server that we will authenticate against. We will not describe this in detail as there are many blogs / articles on this and the GUI is also quite self explanatory.

    • Goto NetScaler -> Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> LDAP and hit the tab Servers.
    • Click the Add Button to add a server
    • Make sure to use all the info to add a server, a example below. Please note that in the screenshot the BaseDN Password is missing, please do enter that!
      SAML - LDAP Server
    • There is no real decent way to test this from the GUI in 10.5 yet, but you can sort of test this with the following command from the BSD shell:
  4. Create the back-end user validation (LDAP) Server
    The LDAP policy will be used to select what profile to use under certain conditions.

    • Goto NetScaler -> Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> LDAP and hit the tab Policies.
    • Click the Add button
      • Name: Enter a descriptive name for the profile
      • Server: Choose the server created in the previous step
      • Expression: Enter the ns_true expression to hit for all traffic
        SAML - LDAP policy
    • Click Create to create the profile.

3 – Add the SAML IdP AAA vServer

This is just a ordinary AAA-TM vServer with an extra policy bound. It is really as simple as that. But since we are describing the complete creation of the AAA-TM vserver, still a lot of text:

  1. Creating the AAA vServer
    Goto NetScaler -> Security -> AAA Application Traffic -> Virtual Servers and click Add.
  2. Basic Settings
    • Name: Enter a descriptive name for the profile
    • IP Address: Enter the IP address that users will connect to (via DNS resolving)
      SAML - AAA IdP Server
    • Click Continue
  3. Server Certificate
    • Bind the Server certificate as upload in a previous step. This is the certificate matching the external IdP hostname that users will connect to for login. For Example “myidp.domain.local”. Needless to say this DNS record must point to the IP address as entered in the previous step. Click Continue
  4. Advanced Authentication Policies
    • We do NOT bind any Advanced Authentication Policies. Click Continue
  5. Basic Authentication Policies for SAML IdP
    This will add the authentication policy for SAML IdP to accept and consume the incoming tokens.

    • Hit the “+” icon to add a Basic Authentication Policy and click Continue
      SAML - Basic Auth Pol
    • Configure
      • Policy: SAMLIDP
      • Type: Primary
        SAML - SAML IdP Pol
      • Click Continue
    • Click Bind to bind a policy
    • Select the SAML IdP policy we created in a previous step and click Insert.
      SAML - Bind IdP pol
    • Click OK to close the SAMLIDP binding
  6. Basic Authentication Policies for LDAP
    This will create the LDAP policy to authenticate the entered user credentials to a LDAP server.

    • Hit the “+” icon again to add a second Basic Authentication Policy and click Continue
      SAML - Basic Auth Pol
    • Configure
      • Policy: LDAP
      • Type: Primary
        SAML - LDAP pol
      • Click Continue
    • Click Bind to bind a policy
    • Select the LDAP policy we created in a previous step and click Insert.
      SAML - Bind LDAP Pol
    • Click OK to close the bindings.
    • Now please check that both the SAMLIDP policy has an equal or lower Priority that the LDAP policy as we would like to evaluate the SAML policy first. You can check this by opening both policies. The priority is listed in the first column. When added by default the priority for both is 100.
  7. Check the AAA vServer
    • The AAA-TM vServer should look like this:
      SAML - AAA vServer complete
    • Click done and we’re done. The status of the vServer should say Up (green icon) and you can now send SAM traffic towards the vServer.

4 – Point your SAML Service Provider towards the NetScaler AAA vServer

Next step is to redirect the SAML SP towards to created AAA IdP so we can authenticate users. As stated this is out of scope for this document, but below are some pointers that you need for setting up your SP

  • Point the SP towards to correct URL (https://aaatmidp.domain.local/saml/login)
  • Make sure to sign the SAML request with the correct certificate (SP Signing Certificate)
  • Make sure your SP has the public key of the IdP you just created
  • If needed (optional, not needed if both SP and IdP are NetScaler) provide Issuer Name

As promised, here is a snipped from my Service Provider config (running on a NetScaler 10.1 version). This is a AAA vServer with a SAML config that redirects / relays authentication to the SAML IdP we just created. This AAA on the SP will NOT be accessed by users directly. Though we need to bind a certificate for the AAA server to up it will not be used. Also the IP does not have to be accessible by users.

The flow will be:

Users => LB vServer => AAA SP (internal in NS) => AAA IdP in second NetScaler => log in => LB vServer with SAML token => Access to web resource.

The AAA vServer config (not checked, please use with caution):

And a sample config of a vServer that will redirect towards the AAA SP vServer

Troubleshooting

When you run into issues you might want to check what is going wrong. Here are some pointers to get you started troubleshooting you config.

  • Most likely the first step would be the error that shows in the users browser. This will be an error code, most of the times accompanied with a descriptive error. Start looking here. I had one that clearly stated that there was a time mismatch between the SP and the IdP.
  • On the NetScaler the first step would be checking the /tmp/aaad.debug during a logon. This is a real time view of what happens on the NetScaler AAA vServer. On the SAML IdP you should see a SAML action happening when the vServer is hit after the redirect from the SP, followed by s LDAP action when the user enters his or her credentials.
  • You can adjust the log level on the NetScaler to a more detailed level to see more information about what is going wrong. Please type the following in the NetScaler shell: set syslogparams -loglevel debug
  • To check if the LDAP connection is working and the credentials are correct you can try a LDAP search from the CLI with the command: ldapsearch -b "DC=domain,DC=local" -D "serviceaccount@domain.local" -h 192.168.1.1 -p 389 -w "password"

Resources

Many thanks to Naresh Jampani from Citrix for helping me out with the config and support in getting the SAML IdP to work.

Bonus

Update 24-12-2014. You can create multiple SAML Profiles (Each profile matches a SAML Service Provider with it’s own certificates, URI, etc.). But you would like to keep a single entry point. You can select the correct profile based on the referer in the HTTP header by creating multiple SAML IdP Policies. Example (to replace step two of “2 – Create the Authentication Polices and Profiles”):

Thanks Morten for bringing this question up and testing!

What do you think?

Comment

20 Comments

  1. Do you have a guide, or can point me to a guide, for configuring the Service Provider on Netscaler? I have a requirement to provide SSO functionality to a customers web page we host on our network. Thank you

    • Hi Zac, planning on writing one but not there yet. There is this blog post on Citrix blogs that describes NS as SP with SimpleSAMLphp. You should be able to use the NS config part to create a SAML SP that would work with most SAML IdP, including NetScaler.

      • Thanks Matthijs. I took a look at the blog post, and it does make sense. However, I am unsure how the internal resource web site determines the ‘user’ that has authenticated via the Netscaler as SP… Is that information passed from the Netscaler to the internal resource in some way after the SAML assertion from the idP? I can’t seem to find any info about this piece of the puzzle, or am I just not be looking in the right place? Any help you could provide would be appreciates, thanks again for your help

        • Hi Zac. The internal website (I presume you mean something like an intranet page) does not get any information about the authentication process bij default. NetScaler allows the authenticated requests when a SAML assertion is shown to NetScaler and from there on load balances / reverse proxies the session. If you would like to do authentication on the internal webserver too you can setup SAML between the IdP and the internal webserver (can re-use existing SAML session to avoid 2 x login prompt), use Kerberos Constrained Delegation, etc. This can create a user session on the internal web server. Hope this helps.

    • Hi Thomas,

      The location of the Service Provider is relevant to your users, as they need to be able to access the Service Provider. For example, if your service provider is internet.domain.local users need to be able to access this (IP, DNS, etc.). Also the need to access the Service Provider URL (authentication.domain.com / local) to be able to generate a SAML token that the SP will accept.

      Hope this helps.

    • And in extend to this, if you want to protect / authenticate intranet resources it is best to make NetScaler SP and use NetScalers reverse proxy feature to convert public to private space.

      • Hi Matthijs,

        We have required to implement SSO but SAML authentication is not supported on Citrix web interface.. Could you please suggest if it is supported by Storefront and how to implement the same in the enviroment Netscaler+storefront with the saml authentication

        • NetScaler (Gateway) supports SAML just fine, but the tricky part is in XA/XD. There is a short and a long answer on this. But either way; it is complicated.

          The short answer; are you on XA/XD 7.x: NO GO. Users need to logon somewhere (Storefront / Windows logon) with their username and password. But you can front StoreFront with a SAML based logon to secure Storefront with NS AAA / NSGW.

          The long answer; are you on XA 6.5? You can let the WI or Storefront > 2.6 perform a Kerberos Constrained Delegation (KCD) to allow users to logon to Windows Server OS without entering their password. There are several guides out there that explain this in more or less detail (like here: ). Note that this is a more complex setup and it requires way more configuration and can go wrong in several ways. Also note that XA 6.5 is coming to an support end.

          There might be more options for XD7.x towards to future, but please contact your local Citrix representative on this as I am not allowed to share futures here.

          • Hi Matthijs!

            If I understand it correctly with latest build of NS 10.5 we should be able to extract B64Encoded password from SAML-ticket. Does this mean that we can use this to SSO to Storefront if we enable HTTP Basic Authentication on the storefront and send the correct headers?

            Regards
            Joans

  2. Hi, nice article. Thanks so much for this effort. I wonder how can i apply this to a web Service provider by my Oracle OSB Weblogic Application Server as SP?

  3. Hello Matthijs,

    I am setting a netscaler 10.5 as and IDP. Following your post I was able to configure it and I think everything is on the right place. We are testing using fiddler web debugger and can confirm that the user connects to the service he / she would like to access, and that the service provide redirects the user to the SAML IdP virtual server to get an assertion.

    The problem begins here, we do not see the netscaler prompting for user credentials. The aaad.debug does not show authentication happening for the testing user, the show command for the authentication samlidp policy does not show a hit either, but the user gets a http 200 and an “undefined SAML error” response which is not at all descriptive. Can you think about what could be happening here?

  4. keep getting an odd error message when trying to logon to the SamlIDP that I created. Undefined SAML error. I’m using LDAP to log in but onl;y created a SAMLIDP profile did not link this to a Access gateway. I’m trying to let a third party authenticate my users to gain access to their site.

  5. How will you implement SAML IDP on NetScaler on Azure with the single private ip limitation ?Can this be used with Unified Gateway for web applications specifically on NetScaler on Azure ?

  6. Matthijs thanks for this great article. Do you have any idea how we would configure SAML SSO for XenMobile SecureWeb but in the scenario when SecureWeb’s traffic is tunneled to the internal network (via Netscaler gateway)? Citrix documentation says almost nothing regarding this.

  7. Great write up. This supports Web requests to o365. What about support for Outlook/ACtiveSync clients? Also can we initiate the login from the IdP in Netscaler rather than the user having to go to o365? This should help skip a step and give a similar experience to the current on-prem OWA client.

    For some of the other folks running into random errors I would suggest you guys upgrade to the latest NS code. Also you can the Microsoft online connectivity tool to help debug some of the login issues.

Webmentions

  • Use SAML Attributes in Policy Expressions - NetScaler Rocks! August 4, 2017

    Great write up. This supports Web requests to o365. What about support for Outlook/ACtiveSync clients? Also can we initiate the login from the IdP in Netscaler rather than the user having to go to o365? This should help skip a step and give a similar experience to the current on-prem OWA client.

    For some of the other folks running into random errors I would suggest you guys upgrade to the latest NS code. Also you can the Microsoft online connectivity tool to help debug some of the login issues.