Configure a custom domain (Preview)

Configuring a custom domain for your workspace allows you to use a domain of your choice to access your Citrix Workspace store. You can then use this domain in place of your assigned cloud.com domain for access from both a web browser and Citrix Workspace applications.

A custom domain can’t be shared with other Citrix Workspace customers. Each custom domain must be unique to that customer. Ensure that you choose the custom domain that you don’t want to assign to another customer, unless you’re willing to remove the custom domain later.

Disabling the Workspace URL within the Citrix Cloud doesn’t disable Citrix Workspace access through the custom domain. To disable Citrix Workspace access when using a custom domain, also disable the custom domain.

Supported scenarios

Scenarios	Supported	Not supported
Identity providers	AD (+Token), Azure AD, Citrix Gateway, Okta, and SAML	Google
Resource types	Virtual Apps and Desktops	SaaS apps
Access methods	Browser (excluding Internet Explorer), Citrix Workspace app for Windows, Mac, and Linux, iOS and Android apps	-
Usage	Workspace	Cloud Connector and Cloud Administrator Console

How is it different from the current Custom Workspace URL?

If you already have a Custom Workspace URL enabled for your customer, then you’re presented with the following view.

You can use this URL for the time being, and continue with the steps in this document to onboard a different Custom Workspace URL. It will be deprecated in the future.

If you want to use the same URL, remove the previous Custom Workspace URL and remove any DNS Records to proceed.

Prerequisites

• You can either choose a newly registered domain, or one that you already own. The domain must be in subdomain format (your.company.com). Citrix doesn’t support using just a root domain (company.com).

• Citrix recommends that you use a dedicated domain as a custom domain for Citrix Workspace access, so that you can easily change it if necessary.

• Custom domains cannot contain any Citrix trademarks. Find the full list of Citrix trademarks here.
• The domain you choose must be configured in public DNS. Any CNAME record names and values included in your domain configuration must be resolvable by Citrix.

Note:

Private DNS configurations are not supported.

Configuring your custom domain

Once a custom domain is set, you can’t change the URL or certificate type. You can only delete it. Ensure that the domain you choose isn’t already configured in DNS. Remove any existing CNAME records before attempting to configure your custom domain.

If you’re using SAML to connect to your Identity Provider, you need to perform an extra step to complete the SAML configuration. For more information, see SAML.

Adding a custom domain

1. Sign into Citrix Cloud at https://citrix.cloud.com.

2. From the Citrix Cloud menu, select Workspace Configuration and then select Access.

3. On the Access tab, under Custom Workspace URL select + Add your own domain.

   

4. Read the information displayed on the Overview page, and select Next.

5. Enter your chosen domain in the Provide a URL page. Confirm that you own the specified domain by selecting Confirm that you or your company own the URL provided, and choose your TLS certificate management preference. Citrix recommends managed, as the certificate renewals are handled for you. For more information, see Providing a renewed certificate. Click Next.

   If any warnings appear on this page, correct the highlighted issue to proceed.

   If you have chosen to provide your own certificate, there’s an extra step to complete in the instructions.

   Provisioning of your chosen domain takes some time. You can wait with the page open or close it while provisioning is in progress.

   

6. If you have the Provide a URL page open while provisioning completes, the Configure your DNS page opens automatically. If you have closed the page, select the Continue button for your custom domain from the Access tab.

   

7. Perform this step in the management portal provided by your DNS registrar. Add a CNAME record for your chosen custom domain that points to the Azure Traffic Manager assigned to you.

   Copy the address of the traffic manager from the Configure your DNS page. The address in the example is as follows:

   wsp-cd-eastus2-production-traffic-manager-profile-1-52183.trafficmanager.net

   If you have any Certificate Authority Authorization (CAA) records configured in your DNS, add one that allows Let’s Encrypt to generate certificates for your domain. Let’s Encrypt is the Certificate Authority (CA) that Citrix uses to generate a certificate for your custom domain. The value for the CAA record must be as follows: 0 issue “letsencrypt.org”

   

8. Once you configure the CNAME record with your DNS provider, select Detect CNAME record to verify that your DNS configuration is correct. If the CNAME record has been configured correctly, a green tick appears next to the CNAME configuration section.

   If any warnings appear on this page, correct the highlighted issue to continue.

   If you have any CAA records configured with your DNS provider a separate CAA configuration appears. Select Detect CAA record to verify that your DNS configuration is correct. If your CAA record configuration is correct, a green tick appears next to the CAA configuration section.

   When your DNS configuration is verified, click Next.

   

9. This is an optional step. If you chose to add your own certificate, complete the required information on the Add your own certificate page.

   If any warnings appear on this page, correct the highlighted issue to proceed. Ensure that the certificate fulfills the following conditions.

   • It should be PEM encoded.
   • It should remain valid for at least next 30 days.
   • It should be used exclusively for custom Workspace URL, wildcard certificates are not acceptable.
   • The common name of the certificate should match the custom domain.
   • SANs on the certificate should be for the custom domain, any additional SANs are not allowed.
   • The duration for which the certificate is valid should not exceed 10 years.

   

   Note:

   Citrix recommends that you use a certificate using a secure cryptographic hash function ( SHA 256 or > higher). You are responsible for renewing the certificate. If your certificate has expired or is about to expire, see the Providing a renewed certificate section.

10. This is an optional step. If you’re using SAML as your Identity Provider, supply the related configuration. Complete the required information on the Configure for SAML page.

    Use the following details when configuring the application in your Identity Provider:

    Property	Value
    Audience	https://saml.cloud.com
    Recipient	https://<your custom domain>/saml/acs
    ACS URL Validator	https://<your custom domain>/saml/acs
    ACS Consumer URL	https://<your custom domain>/saml/acs
    Single Logout URL	https://<your custom domain>/saml/logout/callback

11. Read the information displayed on the Provision your domain page and acknowledge the given instructions. When you’re ready to continue, select Agree and continue.

    This final provisioning step can take some time to complete. You can wait with the page open while the operation completes, or you can close the page.

    

Deleting a custom domain

Deleting a custom domain from your customer removes the ability to access Citrix Workspace using a custom domain. After deleting the custom domain, you can only access Citrix Workspace using the cloud.com address.

When you delete a custom domain, ensure that the CNAME record is removed from your DNS provider.

To delete a custom domain,

1. Sign into Citrix Cloud at https://citrix.cloud.com.

2. From the Citrix Cloud menu, select Workspace Configuration > Access.

3. Expand the context menu (…) for the custom domain on the Access tab, and select Delete.

   

4. Read the information displayed on the Delete custom domain page and acknowledge the given instructions. When you’re ready to continue, select Delete.

   Deleting a custom domain takes some time to complete. You can wait with the page open while the operation completes, or you can close the page.

   

Providing a renewed certificate

1. Sign into Citrix Cloud.

2. From the Citrix Cloud menu, select Workspace Configuration > Access.

3. The certificate’s expiration date will be shown alongside the custom domain that it is assigned to.

   

   When your certificate will expire in 30 days or less, your custom domain displays a warning.

   

4. Expand the context menu (…) for the custom domain on the Access tab. Select Update certificate.

   

5. Enter the required information on the Update certificate page, and Save.

If any warnings appear on this page, correct the highlighted issue to proceed.

The certificate must meet the same requirements as when the custom domain was created and can be see here Adding a custom domain.

Configuring your identity provider

Configuring Okta

Perform the following steps if you are using Okta as the identity provider for Citrix Workspace access.

1. Sign in to the administrator portal for your Okta instance. This instance contains the application that is used by Citrix Cloud.

2. Expand Applications then select Applications in the menu.

   

3. Open the application linked to Citrix Cloud.

4. Select Edit in the General Settings section.

   

5. In the LOGIN section of General Settings, add a new value for Sign-in redirect URIs. Add the new value in addition to, and not replace any existing values. The new value must be of the following format: https://your.company.com/core/login-okta

6. In the same section add a new value for Sign-out redirect URIs. Add the new value in addition to, and not replace any existing values. The new value must be of the following format: https://your.company.com

   

7. Click Save to store the new configuration.

Configuring OAuth Policies and Profiles

Important

The existing OAuth policy and profile that links Citrix Cloud and either Citrix Gateway or your Adaptive Authentication HA pair together, must only be updated if the OAuth credentials are lost. Altering this policy risks breaking the link between Citrix Cloud and Workspaces and will affect your ability to log into Workspaces.

Configuring Citrix Gateway

The Citrix Cloud admin has the access to the unencrypted client secret. These credentials are provided by Citrix Cloud during the Citrix Gateway linking process within Identity and Access Management > Authentication. The OAuth profile and policy was created by the Citrix admin manually on the Citrix Gateway during the connection process.

You need the client ID and unencrypted client secret that were provided during the Citrix Gateway connection process. These credentials are provided by Citrix Cloud and have been saved securely. The unencrypted secret is needed to use both the Citrix ADC interface or command line interface (CLI) to create a OAuth policy and profile.

Here’s an example of the UI when the client ID and secret are provided to the Citrix Admin. If the Citrix admin fails to save the credentials during the connection process they will not be able to obtain a copy of the unencrypted secret after the Citrix Gateway has been connected.

Using Citrix Cloud

Perform these steps to add an additional OAuth profile and policy using the Citrix Gateway interface:

1. From the menu select Security > AAA - Application Traffic > OAuth IDP. Select the existing OAuth policy and click Add.

   

2. When prompted, modify the name of the new OAuth policy to be different from the existing policy selected the previous step. Citrix suggests adding custom-url to its name.

   

3. On the Citrix Gateway GUI, create your existing OAuth Profile

4. On the same GUI menu next to Action click Add.

   

5. On the Citrix Gateway GUI, bind the new OAuth Policy to your existing authentication, authorization, and auditing virtual server.

6. Navigate to Security > Virtual Servers > Edit.

   

Using the command line interface (CLI)

Important

If you don’t have a copy of the OAuth credentials saved securely you need to disconnect and reconnect your Citrix Gateway and update your existing OAuth profile with new OAuth credentials provided by Citrix Cloud Identity and Access Management. Only update your existing OAuth profile with new credentials if the old credentials are unrecoverable. This is not recommended unless you have no other choice.

1. Use an SSH tool such as PuTTY to connect to your Citrix Gateway instance.

2. Create the OAuthProfile and OAuthPolicy. Add authentication OAuthIDPProfile.

   "CustomDomain-OAuthProfile" -clientID "<clientID>" -clientSecret "<unencrypted client secret>" -redirectURL "https://hostname.domain.com/core/login-cip" -audience "<clientID>" -sendPassword ON

   add authentication OAuthIDPPolicy "CustomDomain-OAuthPol" -rule true -action "CustomDomain-OAuthProfile"

3. Bind the OAuthPolicy to the correct authentication, authorization, and auditing virtual server with a lower priority than the existing policy. This instance assumes that the existing policy has a priority of 10, so 20 is used for the new policy. Bind authentication virtual server.

   "CitrixGatewayAAAvServer" -policy "CustomDomain-OAuthPol" -priority 20

Configuring Adaptive Authentication

Important

The encrypted secret and encryption parameters for the OAuth profile are different on the Adaptive Authentication primary vs secondary HA gateways. Make sure you obtain the encrypted secret from the primary HA gateway and also run these commands on the primary HA gateway.

The Citrix Cloud admin doesn’t have access to the unencrypted client secret. The OAuth policy and profile is created by the Citrix Adaptive auth service during the provisioning phase. It is necessary to use the encrypted secret and CLI commands obtained from the ns.conf file to create OAuth profiles. This cannot be performed using the Citrix ADC UI. Bind the new Custom URL OAuthPolicy to your existing authentication, authorization, and auditing virtual server using a higher priority number than the existing policy that is bound to your existing authentication, authorization, and auditing virtual server. Note that the lower priority numbers are evaluated first. Set the existing policy to be priority 10 and the new policy to be priority 20 to ensure they are evaluated in the correct order.

1. Connect to your Adaptive Authentication primary node using an SSH tool like PuTTY.

   show ha node

   

2. Locate the line within the running configuration of the primary HA gateway containing your existing OAuth Profile.

   sh runn | grep oauth

3. Copy the output from the Citrix ADC CLI including all encryption parameters.

   

4. Modify the line that you copied from the previous step, and use it to construct a new CLI command that will allow you to create an OAuth profile using the encrypted version of the client ID. This requires all encryption parameters to be included.

   • Update the name of the OAuth profile to CustomDomain-OAuthProfile
   • Update the -redirectURL to https://hostname.domain.com/core/login-cip

   Here’s an example after both updates.

   add authentication OAuthIDPProfile "CustomDomain-OAuthProfile" -clientID b1656835-20d1-4f6b-addd-1a531fd253f6 -clientSecret <long encrypted client Secret> -encrypted -encryptmethod ENCMTHD_3 -kek -suffix 2023_04_19_09_12_25 -redirectURL "https://hostname.domain.com/core/login-cip" -audience b1656835-20d1-4f6b-addd-1a531fd253f6 -sendPassword ON

   add authentication OAuthIDPPolicy "CustomDomain-OAuthPol" -rule true -action "CustomDomain-OAuthProfile"

5. Bind the OAuthPolicy to the correct authentication, authorization, and auditing virtual server with a lower priority than the existing policy. The authentication, authorization, and auditing virtual server name for all Adaptive Authentication deployments is the name auth_vs. This instance assumes that the existing policy has a priority of 10, so 20 is used for the new policy.

   bind authentication vserver "auth_vs" -policy "CustomDomain-OAuthPol" -priority 20

Known limitations

Some known limitations of the custom domain solution are as follows:

Workspace platform

• Currently supports only one custom domain per customer.
• A custom domain can only be linked to the default Workspace URL. Other Workspace URLs added through the multi-URL feature can’t have a custom domain. The multi-URL feature is currently in Private Tech Preview, and may not be available to all customers.

• For some identity providers, when a user is signed out of the Workspace either through session timeout, or manual action, the user may be presented with a login screen for the “default” workspace URL. The needs to manually navigate to the custom domain to re-authenticate.

  While using the Citrix Workspace app, the user may not be presented with the URL of the Workspace they are accessing, and may have to exit the application and re-launch to use the custom domain.

• If you have a custom domain configured on the previous solution and are using SAML to authenticate Citrix Workspace access, you’re unable to configure a custom domain on the new solution without deleting your existing custom domain first.

SAML

SAML support is limited to one of the following use cases:

• SAML can be used exclusively for cloud.com domains. In this instance the use of SAML would cover Citrix Workspace access and Citrix Cloud administrator access.
• SAML can be used exclusively for a custom domain.