How to use Okta, Citrix Gateway, and Workspace app for a uniform SAML based single sign-on user experience
By: Jason Samuel
Several months ago I posted on Twitter how you can use on-premises or cloud IaaS hosted Citrix Gateway/NetScaler Gateway, Workspace app/Receiver, and Okta as your identity provider (IdP) with SAML 2.0 authentication for full single sign-on. In the past the Receiver client did not have the capability to pop up a web view and embrace modern web-based authentication protocols but that all changed in October when the final piece necessary for this to work was released.
#CitrixADC #CitrixGateway 12.1 49.23 using SAML with #CitrixWorkspace app. In this example I’m using a #Okta SAML Authentication Profile on the Gateway vserver. So nice to have a uniform authentication experience no matter the client! pic.twitter.com/dI0qLhzgVO
— Jason Samuel (@_JasonSamuel) October 6, 2018
Users had a bit of a disparate experience in the past with modern auth prior to this. Your company would be on the modern auth journey but Workspace app was holding you back. You could allow full SSO using SAML in the browser with StoreFront but when using the native Windows Receiver/Workspace app you had to use a RADIUS policy since it could not open a web view. You would have to identify the client being used and direct this traffic to a RADIUS policy on your Citrix Gateway. This was not a uniform experience for users so this new capability is a welcome change that allows you to finally have a uniform authentication experience no matter which client the user is using.
Since my Twitter post, I have had a lot of people reach out on how to do this so I thought I’d oblige and write a quick how-to guide.
- You need Citrix ADC firmware version 12.1 49.23 or newer. This was the key piece that we were waiting for.
- You can use any of the newer versions of Workspace App. In my original Twitter post, it was 1809 and I have tested this through the latest 1903 released just days ago.
- You need an Okta tenant.
How to setup Okta with SAML on your Citrix ADC (NetScaler):
1. In newer versions of Citrix ADC, you can do a SAML metadata import to make your configuration much easier. You can use an existing Okta SAML app for NetScaler if you have been using it for web browsers already or you can create a new one like I’m about to show you. Login to your Okta tenant > click Applications > search for “NetScaler” and click Add next to the SAML one. Please make sure it is the SAML one and not the RADIUS one:
3. In the Sign-On Options screen, select the SAML 2.0 option. Right click on the Identity Provider metadata URL and copy and paste that URL into Notepad for later. We’ll need it for Citrix Gateway config later.
4. At the bottom of the Sign-On Options page under Credential Details, I want to show you how extremely flexible Okta is. You can set the user login name format to whatever you like. Usually, Okta username matches the UPN (email address of the user in AD) but if it doesn’t you can explicitly set UPN or SAM Account Name here if you like. The full list of options here are:
- AD Employee ID
- AD SAM account name
- AD SAM account name + domain
- AD user principal name
- AD user principal name prefix
- Email prefix
- Okta username
- Okta username prefix
5. Now under Assignments click Assign and choose a security group all your users that need to use Citrix Gateway are in. Typically it is all your Domain Users. The most common Okta deployment I do is having all the SaaS apps deployed in Okta via OIN (Okta Integration Network) and use Citrix Gateway for access to all the Windows apps and virtual desktops in the datacenter delivered via HDX. What you publish in Citrix Studio determines what the users will see in Citrix Gateway and StoreFront so that is why the most common config I do is to allow all users to be able to use Citrix Gateway here:
12. Give the Authentication SAML Server a name and ensure the “Import Metadata” URL is checked. Now copy and paste in the metadata URL you had copied out from Okta earlier. Ensure the URL format looks like:
If you see a “
?isNewAppInstanceSetup=true” at the end of the URL you got from Okta make sure you take that part out just so the ADC doesn’t get confused by it. Then go ahead and hit Create. Your ADC will go out to the metadata URL and grab all that is necessary. 🙂 And you can always expand More to tighten up some of the security settings if you wish as usual:
The User Sign-In Experience with OKTA SAML and Workspace app
22. In a web browser, when you go to your Citrix Gateway login page you will be redirected to Okta immediately as normal. At that point complete your login and you will be redirected back to the Gateway and complete SSO with FAS/StoreFront and then see your apps as normal. Nothing changes here from your regular tried and true Citrix + Okta SAML experience.
24. You will immediately see a web view pop up with your Okta login page. Notice you are still in the Citrix Workspace app here but you are seeing a web page (it’s powered by your local system’s browser in reality). Go ahead and enter your user name to begin the login:
26. You will now be prompted by whatever MFA methods you have enrolled in and adaptive MFA policies in place around the context of your session. In my case I am using the Okta Verify app here and am electing to have a push notification sent to my phone:
28. Now the Okta Verify app will show full screen with the details of the login request. In my opinion this is the best MFA push notification in the industry right now. It will show:
- Your company logo
- Your email address
- The time and date of the authentication request
- Your Okta tenant URL
- The IP address the login request originated from
- The city, state, and country your login request originated from
- The ability to approve or deny the login request
For your own company, I would recommend making your Okta login page and your StoreFront branding match in color scheme and logos as close as possible. This will give the best look and feel for your users.
I hope this has helped show you how you can now make your Okta based web logins and Workspace app match for the best user sign-in experience. If you have any questions or comments on this configuration please leave them below.