I was recently tasked with deploying Centrify as a SAML Identity Provider (IdP) alongside a NetScaler and XenDesktop 7. If you’ve attempted this, you might have found or have been directed to this Centrify community post which details the process.

And if you’ve attempted the process documented there, you probably came to the same conclusion that I did: there’s something fundamental missing. So in the spirit of Carl Stalhood, let’s fill in some gaps in documentation.

I’d strongly recommend you follow his document on Citrix Federated Authentication Service for your implementation. Aside from the Centrify piece – he describes implementing this with ADFS instead – his document proved to be entirely accurate. I won’t be going into all of the details he covers here – just the pieces that are applicable for Centrify.

The Expectations

For those that are just now wading into the federated authentication waters, here’s how this will look when it’s working.

1. Your users can navigate to your NetScaler Gateway URL as normal. Instead of getting the NetScaler login screen, they will be immediately be redirected (via a 302 status code) to your Centrify tenant login. This login page is also where the Reset Password link is, so it keeps everything in one place.
2. The user then completes authentication to whatever requirements you’ve specified in Centrify (which can include push notifications, OATH one-time passwords, phone calls, emails, etc.), and if successful will then be redirected back to your NetScaler Gateway by way of an HTTP POST that includes a signed SAML assertion.
3. The NetScaler logs the user in and from here on out it appears the same to the user. They click an icon and get a desktop or application and they get to work.

 

The Requirements

First and foremost, you must be running XenDesktop 7.9 or newer. If you’re running an up-to-date version of LTSR (at the time of this writing, version 7.6), you cannot complete this task. Word on the street is that the next LTSR release (probably 7.15) will likely include this component but that is not yet confirmed.

You need an Enterprise CA in your domain.

For our purposes in this article, you need a NetScaler Gateway. We’ll be doing the deployment using version 12, but this will also work in version 11 and possibly in version 10.5.

Finally, you’ll want your NetScaler Gateway and XenDesktop deployment to be working otherwise. While not strictly a requirement, this type of authentication adds several more moving parts that could complicate the troubleshooting process. Make sure you can successfully log in through your NetScaler Gateway and launch a resource using a simpler authentication method first (like perhaps LDAP against AD).

 

One Catch

One issue with this configuration is that it only works on browser-based authentication. Which is to say, Receiver clients cannot leverage this. I believe that there is a workaround for this that works similar to the standard NetScaler Gateway two-factor policies, but I haven’t worked out the details. For now: this only supports browser-based clients.

 

Centrify Configuration

In the Centrify Admin Portal, click Apps, and then click Add Web Apps. In the dialog that opens, select the Custom tab and then click the Add button next to SAML.

Exit the dialog after the app has been added, and then navigate to the new application in your list (if it doesn’t take you there automatically).

 

Within the App configuration, we need to make a few changes.

There are two fields at the top of the Application Settings page that need to be adjusted.

• Assertion Consumer Service URL: This needs to be your NetScaler Gateway URL with "/cgi/samlauth" appended to the end. For example: https://centrifysaml.lockstepgroup.com/cgi/samlauth
• Issuer: Just the hostname for your NetScaler Gateway. For example: centrifysaml.lockstepgroup.com

 

If you scroll down this page, you’ll see the Identity Provider info. You’ll need these URLs later for the NetScaler configuration, as well as the Signing Certificate that you can download.

Save your settings. The next few pages should be mostly fine with defaults, but you can modify them if necessary:

• The Description page is only for appearances within the Centrify portal. Customize this as you desire; it doesn’t change the way the authentication works.
• The User Access page defines who can access the app. Ensure that the necessary users have enough rights for the app to use it.
• The Policy page defines the authentication challenges; whatever settings you need should be valid here, so long as the necessary users can complete authentication successfully somehow.
• The Account Mapping page should have “userprincipalname” as the mapping field. This appears to be the default value.

The Advanced page takes JavaScript to define the way the assertion is generated by Centrify. This is the missing bit; the default script doesn’t produce an assertion that the NetScaler will accept. Documentation on the syntax that they need can be found on Centrify’s website, but I’ve done the hard part for you and worked out the details. Here’s a valid script:

setVersion('2');
setIssuer(Issuer);
setSubjectName(LoginUser.Username);
setAudience(Application.Get('Issuer'));
setRecipient(Application.Get('Url'));
setSignatureType('Response');
setServiceUrl(Application.Get('Url'));
setHttpDestination(Application.Get('Url'));

//setAttribute('Email', LoginUser.Get('mail'));
setAttribute('Email', LoginUser.Get('userPrincipalName'));
setAttribute('userPrincipalName', LoginUser.Get('userPrincipalName'));
setAttribute('sAMAccountName', LoginUser.Get('sAMAccountName'));

Note that for the Email attribute I’ve commented out the one line and added a second. In some instances those values could be interchangeable, but depending on your domain configuration the Email value might need to be fudged in this way. If your email domain does NOT match your AD domain, but you’re able to configure Shadow Accounts with an alternate UPN suffix, you can use the email attribute. Otherwise, use userPrincipalName.

NetScaler Configuration

The instructions here are for NetScaler 12.0 41.16.nc. It’s notable that while performing this configuration the NetScaler repeatedly implored me to use Advanced Authentication, as the Basic Authentication policies have been deprecated. This configuration does still work on this NetScaler version, but it looks like I’ll need to work this out using Advanced Authentication in the future.

First we need to install the signing certificate generated by Centrify.

1. In the NetScaler management UI, navigate to Traffic Management -> SSL -> Certificates -> CA Certificates.
2. Click install, and then add the Signing certificate that you downloaded from the Centrify admin portal while adding the application. In my tests, the certificate did NOT show up in the CA Certificates list after installing, but I was able to add it to the policy with no issues.

Now we can create the authentication server and policy objects.

1. Navigate to NetScaler Gateway -> Policies -> Authentication -> SAML.
2. Click over to the Servers tab, and then add a new policy.
3. Select the certificate you just added for the IDP Certificate Name field.
4. The Redirect URL should be the value from Identity Provider Sign-in URL from your Centrify App’s Application Settings page.
5. The Single Logout URL should be the value from Identity Provider Sign-out URL from your Centrify App’s Application Settings page.
6. The User Field should be samaccountname.
7. The Issuer Name field should be your NetScaler Gateway hostname, and should match what you entered in Centrify’s Issuer field. For example, centrifysaml.lockstepgroup.com

Save your settings.

Back on the SAML authentication servers screen, you should see your new authentication server. Click the checkbox next to your new server, then click the Generate Metadata button.

 

Enter your NetScaler Gateway hostname, select the HTTPS radio button, and click continue. It will then provide you with some XML. Copy this XML and save it as a text file. You can also click the Save button at the bottom of this dialog to save it to /var/tmp in the NetScaler’s filesystem.

Switch to the Policies tab, and create a new policy that uses your SAML server with an expression of ns_true.

Back at the Centrify admin portal, edit your App again (Apps -> Your SAML Application). At the top of the Application Settings page, click button labeled Upload SP Metadata.

 

In the dialog, select the radio button beside Upload SP Metadata from file. Browse to the text file you saved from the NetScaler’s output above, then click OK.

 

The final step is to unbind any other authentication you have on your NetScaler Gateway, and bind the new SAML policy you have created. Once you’ve bound the new policy, you should be authenticating through Centrify and able to successfully launch desktops.

 

Further Steps

From here on out, you can generally configure this with Centrify’s policy. With this configuration, your NetScaler Gateway can also act as a single sign-on application in the Centrify User Portal. You can also hide the icon in the Centrify App configuration, if you prefer.