How to use Okta, Citrix Gateway, and Workspace app for a uniform SAML based single sign-on user experience

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.

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.

Prerequisites:

1. You need Citrix ADC firmware version 12.1 49.23 or newer. This was the key piece that we were waiting for.
2. 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.
3. 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:

2. Give it an Application label. You can leave it the default or edit as you like. Type in your Citrix Gateway URL for the Login URL. Then hit Next:

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.

You can also click on the metadata URL and see what it contains. Notice how the X.509 certificate is there already which will save you a lot of time a bit 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:

• (None)
• AD Employee ID
• AD SAM account name
• AD SAM account name + domain
• AD user principal name
• AD user principal name prefix
• Custom
• Email
• Email prefix
• Okta username
• Okta username prefix

Once you choose the username format hit Done.

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:

6. Now go to your Citrix ADC and go to Security > AAA – Application Traffic > Virtual Servers > and click Add

7. Give the Authetnication Virtual Server a name and press OK:

8. Bind an SSL certificate to it and hit Continue:

9. Now we need to add an Authentication Policy:

10. Hit Add to add a new policy:

11. Enter an authentication policy name, choose the action type of “SAML”, and set the expression to HTTP.REQ.IS_VALID. Then click Add next to Action as the final step 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:

https://yourcompany.okta.com/app/sadfjasdlfjlaskfjlkasjd/sso/saml/metadata

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:

13. Hit Create on the authentication policy

14. In the policy binding you can set the Goto Expression to END and hit Bind:

15. Hit Continue on the Authentication Virtual Server config:

16. Scroll all the way to the bottom of the screen and hit Done to finish:

17. You’ll notice your AAA vserver will be UP and have a green dot next to it:

18. Now you can go to your Gateway vserver and add an Authentication Profile:

19. Give the Authentication Profile a name and bind the Okta SAML AAA vserver you created earlier:

20. Press OK to add this new Authentication Profile to the Gateway vserver:

21. Scroll all the way down to the bottom of the page and hit Done:

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.

23. Where it will change is with Workspace app. Let’s walk through setting up a new account in Workspace app from scratch to show this experience. Enter your Citrix Gateway URL and hit Add:

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:

25. Enter your password and hit Verify:

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:

27. You will see a notification like this on your phone from the Okta Verify app. Press it and unlock your phone using a biometric or passcode:

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

Go ahead and hit Approve:

29. You will now be presented with StoreFront within the Workspace app and see all your apps and desktops like normal:

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.

Jason Samuel

Jason Samuel is a visionary product leader and trusted advisor with a proven track record of shaping strategy and driving technology innovation. With extensive expertise in enterprise end-user computing, security, cloud, automation, and virtualization technologies, Jason has become a globally recognized authority in the IT industry. His career spans consulting for hundreds of Fortune 500 enterprises across diverse business sectors worldwide, delivering cutting-edge digital solutions from Citrix, Microsoft, VMware, Amazon, Google, and NVIDIA that seamlessly balance security with exceptional user experiences.

Jason’s leadership is amplified by his dedication to knowledge-sharing as an author, speaker, podcaster, and mentor within the global IT and technology community. Recognized with numerous prestigious awards, Jason’s contributions underscore his commitment to advancing technology and empowering organizations to achieve transformative results.  Follow him on LinkedIn.