Connect with us

Hi, what are you looking for?


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.


  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:

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.



  1. Doug Fulgoni

    April 24, 2019 at 2:14 PM

    Great article! Quick question, did you leverage Citrix FAS behind this in order to allow the AD credential to prevent a second auth pop up when launching the published resource, or was this not necessary?

  2. Jason Samuel

    April 24, 2019 at 11:18 PM

    Hi Doug, yes you still need Citrix FAS.

  3. bharat Chawla

    May 2, 2019 at 8:03 AM

    Thanks Jason. It’s a great article. So we can’t integrate NetScaler with SAML authentication without using FAS and CA server ?

  4. Jason Samuel

    May 3, 2019 at 12:43 AM

    Thanks Bharat. You will need FAS for the Windows side. Windows does not natively understand web authentication protocols so needs FAS to act as a middleman to translate web authentication to something Windows can use. This is why FAS and your CA are necessary.

  5. Jeroen

    May 8, 2019 at 2:07 AM

    Hi Jason, did you get this working for the native Workspace app in iOS devices?

  6. Floyd

    June 3, 2019 at 11:00 PM

    Awesome article! Was able to get it working both on browser and workspace. Just have a minor issue where I get “Cannot complete your request” after clicking OK. SSO is working and automatically signing into StoreFront.

  7. John smith

    June 7, 2019 at 3:39 PM

    Hi Jason how would this work from non domain joined endpoints for example users home PC’s ?

  8. Jason Samuel

    June 11, 2019 at 8:27 PM

    Hi Jeroen, have not tested this setup on iOS devices yet.

    Thanks Floyd. Have not come across a “Cannot complete your request” message with this setup.

    Hi John, they would get prompted exactly the same way as in step 22 onward for non-domain joined devices.

  9. Simon Gadsby

    June 12, 2019 at 10:45 PM

    Hi Jason, is it necessary to use AAA instead of just assigning a SAML primary auth policy to the gateway vs?

    And secondly, I realise FAS is required to prevent the auth prompt on connection to VDA, but the SAML logon shouldstill work without FAS in place shouldn’t it? I am testing and getting “Unexpected protocol was received from the server” in the AuthManSvr.txt log.

    Is it relevant how StoreFront authentication is configured?

  10. Bogdan

    September 5, 2019 at 11:58 AM

    great article. Still trying to find out a way to have this working with IOS. If you have any idea, please share it.

  11. Brian Diamond

    September 8, 2019 at 10:27 AM

    Everything is working with FAS, through the web and through the okta site, however when using workspace app, I get the pop up, i log in, but then i get an error on storefront “CitrixAGBasic single sign-on failed because the credentials failed verification with reason: FailedPasswordComplexity” and a popup on the screen saying “the expected password was missing”

    Any ideas?

  12. Syed

    November 26, 2019 at 5:48 AM

    Hi Jason, I have already done Netscaller integration with OKTA , it is useful to load Citrix desktops and access Citrix apps however I would like to publish Citrix Apps as individually in OKTA page as separate chiclet, How do I achieve this?

  13. Ram

    January 22, 2020 at 8:39 AM

    Hi Jason,

    can I use Okta RADIUS Agent as an alternative approach ?

  14. Matt

    March 22, 2020 at 3:55 PM


    Look up Citrix Resource Shortcuts. It’s not the most polished solution but it works.

  15. Leandro Basso

    May 23, 2020 at 9:25 AM

    Hi Jason, how are you?

    We have the following scenario: Citrix Gateway + FAS + Okta iDP, however we use authentication only in the browser and everything works very well, however we would like to extend this solution to the Citrix Workspace App because we understand that it is the best experience for the user. In browser authentication we are seeing the following message with some users: “You cannot login using smart card. Please close your browser to protect your account”.

    So we advise users to close the browser. Have you noticed this behavior with the Citrix Workspace App? How should I proceed if this error appears to users?


  16. Abhishek Barve

    October 7, 2020 at 3:25 PM

    Hi Jason,
    I was able to get SAML working on gateway with Okta as IDP.
    FAS is working fine for windows authentication for VDA.

    Only issue i have currently is While going via Citrix Workspace client (1907), when it sends me to Okta for Credentials and MFA, I do check “Do not challenge me for next 48 hours” but i get challenged for MFA every time is sign out of Workspace client. Expectation is MFA should avoided if i use same machine, same workspace client etc. This works as expected in browser but not on workspace app.

    For browser it is handled with cookies but not sure how citrix workspace app will handle “do not challenge me for next 24 or 48 hours”

    Any clue?

  17. Abhishek

    October 7, 2020 at 3:29 PM

    Leandro Basso, I faced the similar issue and resolve it.

    Here is how you can resolve.

    You can fix your issue by adding a line to
    CTXS.allowReloginWithoutBrowserClose = true

    Adding setting “CTXS.allowReloginWithoutBrowserClose = true ” to C:\inetpub\wwwroot\Citrix\Web\custom\script.js.

    1.In StoreFront server ,move to C:\inetpub\wwwroot\Citrix\Web\custom .
    2.Right Click script.js ,and add below content to the end of the file.
    CTXS.allowReloginWithoutBrowserClose = true
    3.Save the file.
    4.Run command “iisreset”

Leave a Reply

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

You May Also Like


Today I would like to go over proper URL redirection when using SSL but first I would like to preface this by describing what...

Citrix Workspace

You can use FIDO2 hardware security keys plugged into your physical desktop over the Citrix HDX remoting protocol for use with virtualized Windows Desktop...

Exchange 2003

A useful Exchange 2003 guide I wrote for a friend’s blog originally but I am posting it here on mine now for your viewing...


In a worst case scenario and all your web servers have failed, what do you do? You could have a standby group of servers... began in 2008 as a way for me to give back to the IT community. This website features the latest news and how-to's on enterprise mobility, security, virtualization, cloud architecture, and other technologies I work with. This website has evolved over time to become a go-to reference hub for these technologies. It receives hundreds of thousands of unique visitors from all over the world each month. More details on the About Me page.
Copyright © 2008-2023