Last Updated on October 12, 2020
Citrix cloud allows using on-premises gateway for authenticating Citrix Workspace users. One of the reason why you would prefer to do that is when you don’t want to use Citrix Workspace URL i.e. yourcompany.cloud.com. In Citrix cloud, it is not possible to use your company domain in the workspace URL. It means you cannot have a workspace URL like citrix.guptanishith.com. However, what you can have is guptanishith.cloud.com. If you want users to interact with a URL like citrix.guptanishith.com (or citrix.contoso.com), you have to use on-premises Storefront store(s) and Citrix Gateway.
As the name suggests, Citrix Gateway is a managed gateway as a service that takes a lot of scalability, high availability, SSL certificates and configuration hassles away from a customer’s architect and admin team. With that said, Citrix Gateway service cannot be compared with full-fledged Citrix ADC in terms of features. This can be one another simple reason why a customer would prefer using on-premises gateway for Citrix Workspace. In this article, we will see how to configure on-premises gateway for Citrix Workspace to be used with workspace URL (yourcompany.cloud.com). I am assuming that Citrix Cloud Connectors are already installed.
Another compelling reason, which has been sorted now, was due to lack of a bridge between modern authentication systems like OAuth or SAML and traditional authentication systems like IWA that on-premises Active Directory uses. If you are using Azure Active Directory (AAD) or Okta to authenticate Workspace users then users will have to provide login credentials one more time once the desktop/application is launched for them. The seamless login that you normally experience in an on-premises Citrix environment was not possible in Citrix Cloud because the resources (Virtual desktops and applications), which are on-premises domain joined, don’t understand modern authentication systems. This limitation led companies to continue using their on-premises gateway. Now, Citrix cloud offers FASaaS (Federated Authentication Service) that fully resolves this problem. The information in this paragraph is just contextual and requires a separate article.
For one customer whose identities were fully federated to Azure Active Directory and wanted to use on-premises Storefront store, I had to configure on-premises Citrix ADC as SP (service provider), AAD as IdP (identity provider) and Citrix FAS as CVAD offering to achieve seamless login experience. This was around 2 years back, I think, when Citrix FAS as a service was not available in Citrix Cloud.
Citrix Gateway authentication is supported for use with the following on-premises product versions:
- Citrix Gateway 12.1 54.13 Advanced edition or later
- Citrix Gateway 13.0 41.20 Advanced edition or later
How to Configure On-Premises Gateway for Citrix Workspace
Before selecting an authentication method under Workspace configuration (screenshot 1), it needs to be configured in “Identity and Access Management” (screenshot 2).
Clicking on ellipsis (3 dots) in front of Citrix Gateway will show the option to connect (screenshot 3). Click on Connect. Citrix Gateway appears at many locations in Citrix cloud. Read different use cases of Citrix Gateway in Citrix cloud.
This will open “Configure your On-premise Gateway as an Identity Provider for Workspace” window where you need to provide Public FQDN of your On-premises Gateway and then click on Detect.
After successful detection, click on Continue.
You will be presented with Client ID, Secret and Redirect URL.
You will need these values while configuring OAuth IDP advanced authentication policy on your on-premises Citrix ADC.
Login to on-premises Citrix ADC and expand Security/AAA Application Traffic/Policies/Authentication/Advanced Policies/OAuth IDP. Click on Profiles tab and then click on Add.
Fill values as described below:
- Workspace Name: something relevant.
- Client ID: value generated by Citrix Cloud.
- Client Secret: value generated by Citrix Cloud.
- Redirect URL: value generated by Citrix Cloud.
- Issuer Name: FQDN of the on-premises Citrix Gateway.
- Audience: Client ID generated by Citrix Cloud.
Scroll down and check “Send Password”. Then click on Create.
OAuth IDP profile has been created.
Click on Policies tab and then click on Add. Fill values as described below:
- Name: something relevant.
- Action: selection the profile that was created in previous step.
- Expression: true.
Click on Create.
OAuth IDP policy has been created.
Go to Security/AAA Application Traffic/Authentication Virtual Servers (Virtual Servers). Provide some relevant Name and change IP Address Type to Non Addressable. Click on OK.
Notice the IP address under Basic Settings is 0.0.0.0. This is because we selected “Non Addressable” in IP address type. Since we are going to attach this Authentication virtual server to Gateway virtual server using an Authentication profile, there is no need to assign an IP address and port to AAA Authentication virtual server.
Under Certificate, click on No Server Certificate.
Click on > in front of Click to select under Select Server Certificate if the SSL certificate is already installed. If not, click on +.
Select the certificate and click on Select. If you clicked on + in previous step, you will be presented with a different window.
Click on Bind. After that click on Continue.
Click on No OAuth IDP Policy under Advanced Authentication Policy.
Click on Add Binding.
Click on > in front of Click to Select under Select Policy.
Select the OAuth IDP Policy we previously created and click on Select.
Click on Bind.
I don’t have any other authentication policy like LDAP or LDAP+Radius bound to AAA Authentication Virtual Server in the lab, however, in production, I do have advanced authentication policies that are being used along with Authentication Policy Labels and Login Schemas as a second factor of authentication. Ensure that OAuth IDP policy has lower priority than any other authentication policy.
Click on Continue.
Scroll down and click on Done.
Authentication Virtual Server has been created.
Go to Security/AAA Application Traffic/Authentication Profile and click Add.
Provide something relevant in Name. Authentication Host is name of the authentication virtual server. Select Authentication Virtual Server, if not by default selected, under Choose Virtual Server Type. Click on > in front of Click to Select under Authentication Virtual Server.
Select the previously created Authentication Virtual Server and click on Select.
Click on Create.
Authentication Profile has been created.
Go to Citrix Gateway/Virtual Servers and click on your Gateway Virtual Server.
Click on + Authentication Profile on the right side under Advanced Settings.
Select the previously created Authentication Profile from the drop down under Authentication Profile.
Scroll down and click on Done.
Connect to Citrix ADC through SSH using a client like Putty and bind the certificate to the VPN globally.
Why bind, and what certificate: According to Citrix Docs – “When configuring the Gateway for authenticating subscribers to Citrix Workspace, the Gateway acts as an OpenID Connect provider. Messages between Citrix Cloud and Gateway conform to the OIDC protocol, which involves digitally signing tokens. Therefore, you must configure a certificate for signing these tokens. This certificate must be issued from a public Certificate Authority (CA). Using a certificate issued by a private CA is not supported, as there is no way to provide Citrix Cloud with the private root CA certificate. So, the certificate chain of trust cannot be established. If you configure multiple certificates for signature, these keys are rotated for each message. Keys must be bound to vpn global. Without these keys, subscribers cannot access their workspace successfully after signing in”.
Open Putty or an equivalent client, enter NSIP, select SSH, ensure that port is 22 and click on Connect.
Provide Login ID and Password.
Type show vpn global. The output shows that no SSL certificate is globally bound to VPN.
Now type show ssl certkey. All the keys installed on Citrix ADC will show up. Copy the value of the Name parameter.
Type bind vpn global –certkeyName citrix.guptanishith.com. Replace citrix.guptanishith.com with the name of your key.
Type show vpn global one more time. Certificate has been globally bound to the VPN.
Because digitally signed messages in OIDC carry a timestamp, the Gateway must be synchronized to NTP time. If the clock isn’t synchronized, Citrix Cloud assumes tokens are stale when checking their validity.
Go to System/NTP Servers. Select the checkbox before the NTP Server and click on NTP Synchronization from Select Action drop down menu. If you haven’t configured a NTP server, click on Add to create one.
Select Enabled in Synchronization State and then click on OK.
Go back to Citrix cloud portal and click on Test and Finish. It will test and verify the connection. Now you can go to Authentication under Workspace configuration and select Citrix Gateway as the authentication method for Citrix Workspace.
Select I understand the impact on subscriber experience and click on Save.
Open up Workspace URL through either the HTML5 version or an installed version of Workspace App, you will be redirected to the on-premises Citrix Gateway for authentication.