Connect SAML as an identity provider to Citrix Cloud

Citrix Cloud supports using SAML (Security Assertion Markup Language) as an identity provider to authenticate Citrix Cloud administrators and subscribers signing in to their workspaces. You can use the SAML 2.0 provider of your choice with your on-premises Active Directory (AD).

About this article

This article describes the required steps for configuring a connection between Citrix Cloud and your SAML provider. Some of these steps describe actions that you perform in your SAML provider’s administration console. The specific commands you use to perform these actions might vary from the commands described in the article, depending on your chosen SAML provider. These SAML provider commands are provided as examples only. Refer to your SAML provider’s documentation for more information about the corresponding commands for your SAML provider.

Supported SAML providers

SAML providers that support the official SAML 2.0 specification are supported for use with Citrix Cloud.

Citrix has tested the following SAML providers for authenticating Citrix Cloud administrators and for authenticating Citrix Workspace subscribers using Single Sign-on (SSO) and Single Logout (SLO). SAML providers that don’t appear in this list are also supported.

• Microsoft ADFS
• Microsoft Azure AD
• Duo
• Okta
• OneLogin
• PingOne SSO
• PingFederate

When testing these providers, Citrix used the following settings to configure the SAML connection in the Citrix Cloud console:

• Binding Mechanism: HTTP Post
• SAML Response: Sign Either Response or Assertion
• Authentication Context: Unspecified, Exact

The values for these settings are configured by default when you configure your SAML connection in Citrix Cloud. Citrix recommends using these settings when configuring the connection with your chosen SAML provider.

For more information about these settings, see Add SAML provider metadata to Citrix Cloud in this article.

Support for scoped Entity IDs

This article describes how to configure SAML authentication using a single SAML application and Citrix Cloud’s default generic Entity ID.

If your SAML authentication requirements include the need for multiple SAML applications within a single SAML provider, refer to Configure a SAML application with a scoped Entity ID in Citrix Cloud.

Prerequisites

Using SAML authentication with Citrix Cloud has the following requirements:

• SAML provider that supports SAML 2.0.
• On-premises AD domain.
• Two Cloud Connectors deployed to a resource location and joined to your on-premises AD domain. The Cloud Connectors are used to ensure Citrix Cloud can communicate with your resource location.
• AD integration with your SAML provider.

Cloud Connectors

You need at least two (2) servers on which to install the Citrix Cloud Connector software. Citrix recommends at least two servers for Cloud Connector high availability. These servers must meet the following requirements:

• Meets the system requirements described in Cloud Connector Technical Details.
• Does not have any other Citrix components installed, is not an AD domain controller, and is not a machine critical to your resource location infrastructure.
• Joined to the domain where your resources reside. If users access resources in multiple domains, you need to install at least two Cloud Connectors in each domain.
• Connected to a network that can contact the resources that subscribers access through Citrix Workspace.
• Connected to the Internet. For more information, see System and Connectivity Requirements.

For more information about installing the Cloud Connector, see Cloud Connector Installation.

Active Directory

Before configuring SAML authentication, perform the following tasks:

• Verify that your workspace subscribers have user accounts in your AD. Subscribers without AD accounts can’t sign in to their workspaces successfully when SAML authentication is configured.
• Connect your AD to your Citrix Cloud account by deploying Cloud Connectors in your on-premises AD.
• Synchronize your AD users to the SAML provider. Citrix Cloud requires the AD user attributes for your workspace subscribers so they can sign in successfully.

AD user attributes

The following attributes are required for all Active Directory user objects and must be populated:

• Common name
• SAM account name
• User Principal Name (UPN)
• Object GUID
• SID

Citrix Cloud uses the Object GUID and SID attributes from your AD to establish the user context when subscribers sign in to Citrix Workspace. If either of these properties isn’t populated, subscribers can’t sign in.

The following attributes aren’t required for using SAML authentication with Citrix Cloud, but Citrix recommends populating them to ensure the best user experience:

• Email address
• Display Name

Citrix Cloud uses the Display Name attribute to show subscribers’ names correctly in Citrix Workspace. If this attribute isn’t populated, subscribers can still sign in, but their names might not be displayed as expected.

SAML integration with Active Directory

Before enabling SAML authentication, you must integrate your on-premises AD with your SAML provider. This integration allows the SAML provider to pass the following required AD user attributes to Citrix Cloud in the SAML assertion:

• objectSID (SID)
• objectGUID (OID)
• userPrincipalName (UPN)
• Mail (email)
• Display Name (displayName)

You can configure a subset of these attributes, provided either the SID or UPN attributes are included in the SAML assertion. Citrix Cloud retrieves the other attributes from your AD as needed.

Note:

To ensure the best performance, Citrix recommends configuring all of the attributes mentioned in this section.

Although the precise integration steps vary among SAML providers, the integration process typically includes the following tasks:

1. Install a synchronization agent in your AD domain to establish a connection between your domain and your SAML provider. If you’re using ADFS as your SAML provider, this step isn’t required.
2. Create custom attributes and map them to the required AD user attributes mentioned earlier in this section. For reference, the general steps for this task are described in Create and map custom SAML attributes in this article.
3. Synchronize your AD users to your SAML provider.

For more information about integrating your AD with your SAML provider, consult your SAML provider’s product documentation.

Administrator authentication with SAML 2.0

Citrix Cloud supports using SAML 2.0 to authenticate members of administrator groups in AD. For more information about adding administrator groups to Citrix Cloud, see Manage administrator groups.

Using an existing SAML connection for administrator authentication

If you already have a SAML 2.0 connection in Citrix Cloud and want to use it to authenticate administrators, you must first disconnect SAML 2.0 in Identity and Access Management and then reconfigure the connection. If you’re using your SAML connection to authenticate Citrix Workspace subscribers, you must also disable the SAML authentication method in Workspace Configuration. After reconfiguring the SAML connection, you can add administrator groups to Citrix Cloud.

If you attempt to add administrator groups without first disconnecting and reconnecting SAML 2.0, the Active Directory identity option described in Add an administrator group to Citrix Cloud doesn’t appear.

Task overview for setting up a new SAML connection

To set up a new SAML 2.0 connection in Citrix Cloud, you perform the following tasks:

1. In Identity and Access Management, connect your on-premises AD to Citrix Cloud as described in Connect Active Directory to Citrix Cloud.
2. Integrate your SAML provider with your on-premises AD as described in SAML integration with Active Directory in this article.
3. Configure the sign-in URL that administrators can use to sign in to Citrix Cloud.
4. In Identity and Access Management, configure SAML authentication in Citrix Cloud. This task involves configuring your SAML provider with the SAML metadata from Citrix Cloud and then configuring Citrix Cloud with the metadata from your SAML provider to create the SAML connection.

Task overview for using an existing SAML connection for Citrix Cloud administrators

If you already have a SAML 2.0 connection in Citrix Cloud and want to use it for administrator authentication, perform the following tasks:

1. If applicable, disable SAML 2.0 workspace authentication: In Workspace Configuration > Authentication, select a different authentication method and then select Confirm when prompted.
2. Disconnect your existing SAML 2.0 connection: In Identity and Access Management > Authentication, locate the SAML connection. From the ellipsis menu at the far right, select Disconnect. Select Yes, disconnect to confirm the action.
3. Reconnect SAML 2.0 and configure the connection: From the ellipsis menu for SAML 2.0, select Connect.
4. When prompted, enter a unique identifier for the sign-in URL that administrators will use to sign in.
5. Configure the SAML connection as described in Configure the SAML provider metadata in this article.

After configuring your SAML connection, you can add your AD administrator groups to Citrix Cloud as described in Manage administrator groups. You can also reenable SAML for workspace subscribers as described in this article.

Create and map custom SAML attributes

If you already have custom attributes for the SID, UPN, OID, email, and displayName attributes configured in your SAML provider, you don’t have to perform this task. Proceed to Create a SAML connector application and use your existing custom SAML attributes in Step 5.

Note:

The steps in this section describe actions that you perform in your SAML provider’s administration console. The specific commands you use to perform these actions might vary from the commands described in this section, depending on your chosen SAML provider. The SAML provider commands in this section are provided as examples only. Refer to your SAML provider’s documentation for more information about the corresponding commands for your SAML provider.

1. Sign in to the administration console of your SAML provider and select the option for creating custom user attributes. For example, depending on your SAML provider’s console, you might select Users > Custom User Fields > New User Field.

2. Add attributes for the following AD properties. Name the attributes using the default values shown.

   AD Property	Required or optional	Default value
   userPrincipalName	Required if not adding an attribute for SID (recommended).	cip_upn
   objectSID	Required if not adding an attribute for UPN.	cip_sid
   objectGUID	Optional for authentication	cip_oid
   mail	Optional for authentication	cip_email
   displayName	Required by the Workspace UI	displayName
   givenName	Required by the Workspace UI	firstName
   sn	Required by the Workspace UI	lastName
   AD Forest	Optional for authentication	cip_forest
   AD Domain	Optional for authentication	cip_domain

3. Select the AD that you connected with Citrix Cloud. For example, depending on your SAML provider’s console, you might select Users > Directories.
4. Select the option for adding directory attributes. For example, depending on your SAML provider’s console, you might select Directory Attributes.
5. Select the option for adding attributes and map the following AD attributes to the custom user attributes you created in Step 2:
   • If you added the attribute for SID in Step 2 (for example, cip_sid), select objectSid and map to the attribute that you created.
   • If you added the attribute for UPN in Step 2 (for example, cip_upn), select userPrincipalName and map to the attribute that you created.
   • If you added the attribute for ObjectGUID in Step 2 (for example, cip_oid), select ObjectGUID and map to the attribute that you created.
   • If you added the attribute for Mail in Step 2 (for example, cip_email), select mail and map to the attribute that you created.
   • If you added the attribute for Display Name in Step 2 (for example, displayName), select displayName and map to the attribute that you created.

Configure the administrator sign-in URL

1. Sign in to Citrix Cloud at https://citrix.cloud.com.
2. From the Citrix Cloud menu, select Identity and Access Management.
3. Locate SAML 2.0 and select Connect from the ellipsis menu.
4. When prompted, enter a short, URL-friendly identifier for your company and select Save and continue. The Configure SAML page appears.
5. Proceed to the next section to configure the SAML connection to Citrix Cloud.

Configure the SAML provider metadata

In this task, you create a connector application using SAML metadata from Citrix Cloud. After you configure the SAML application, you use the SAML metadata from your connector application to configure the SAML connection to Citrix Cloud.

Note:

Some steps in this section describe actions that you perform in your SAML provider’s administration console. The specific commands you use to perform these actions might vary from the commands described in this section, depending on your chosen SAML provider. The SAML provider commands in this section are provided as examples only. Refer to your SAML provider’s documentation for more information about the corresponding commands for your SAML provider.

Create a SAML connector application

1. From your SAML provider’s administration console, add an application for an identity provider with attributes and sign response. For example, depending on your provider’s console, you might select Applications > Applications > Add App and then select SAML Test Connector (IdP w/ attr w/ sign response).
2. If applicable, enter a display name and save the app.
3. From the Configure SAML screen in Citrix Cloud, in SAML Metadata, select Download. The metadata XML file appears in another browser tab.

   Note:

   If needed, you can also download this file from https://saml.cloud.com/saml/metadata.xml. This endpoint might be more friendly to some identity providers when importing and monitoring the SAML provider metadata.

4. Enter the following details for the connector application:
   • In the Audience field, enter https://saml.cloud.com.
   • In the Recipient field, enter https://saml.cloud.com/saml/acs.
   • In the field for ACS URL validator, enter https://saml.cloud.com/saml/acs.
   • In the field for ACS URL, enter https://saml.cloud.com/saml/acs.

5. Add your custom SAML attributes as parameter values in the application:

   Create this field	Assign this custom attribute
   cip_sid	The custom attribute you created for SID. Example: cip_sid
   cip_upn	The custom attribute you created for UPN. Example: cip_upn
   cip_oid	The custom attribute you created for ObjectGUID. Example: cip_oid
   cip_email	The custom attribute you created for Mail. Example: cip_email
   displayName	The custom attribute you created for Display Name. Example: displayName

6. Add your Workspace subscribers as users to allow them to access the application.

Add SAML provider metadata to Citrix Cloud

1. Acquire the SAML metadata from your SAML provider. The following image is an example of what this file might look like:

   

2. In the Configure SAML screen in Citrix Cloud, enter the following values from your SAML provider’s metadata file:

   • In Identity Provider Entity ID, enter the entityID value from the EntityDescriptor element in the metadata.

     

   • In Sign Authentication Request, select Yes to allow Citrix Cloud to sign authentication requests, certifying they came from Citrix Cloud and not a malicious actor. Select No if you prefer to add the Citrix ACS URL to an allow list that your SAML provider uses for posting SAML responses safely.

   • In SSO Service URL, enter the URL for the binding mechanism you want to use. You can use either HTTP-POST or HTTP-Redirect binding. In the metadata file, locate the SingleSignOnService elements with Binding values of either HTTP-POST or HTTP-Redirect.

     

   • In Binding Mechanism, select the mechanism that matches the binding for the SSO Service URL you chose from the metadata file. By default, HTTP Post is selected.
   • In SAML Response, select the signing method your SAML provider uses for the SAML Response and SAML Assertion. By default, Sign Either Response or Assertion is selected. Citrix Cloud rejects any responses that aren’t signed as specified in this field.
3. In your SAML provider’s administration console, perform the following actions:
   • Select SHA-256 for the SAML signing algorithm.
   • Download the X.509 certificate as a Base64-encoded PEM, CRT, or CER file.
4. On the Configure SAML page in Citrix Cloud, in X.509 Certificate, select Upload File and select the certificate file you downloaded in the previous step.
5. Select Continue to complete the upload.
6. In Authentication Context, select the context you want to use and how strictly you want Citrix Cloud to enforce this context. Select Minimum to request authentication at the selected context without enforcing authentication at that context. Select Exact to request authentication at the selected context and enforce authentication only at that context. If your SAML provider doesn’t support authentication contexts or you choose not to use them, select Unspecified and Minimum. By default, Unspecified and Exact are selected.
7. For Logout URL (optional), decide whether or not you want users signing out of Citrix Workspace or Citrix Cloud to also sign out of all web applications that they previously signed in to through the SAML provider.
   • If you want users to stay signed in to their web applications after signing out of Citrix Workspace or Citrix Cloud, leave the Logout URL field blank.

   • If you want users to sign out of all web applications after signing out of Citrix Workspace or Citrix Cloud, enter the SingleLogout (SLO) endpoint from your SAML provider. If you’re using Microsoft ADFS or Azure Active Directory as your SAML provider, the SLO endpoint is the same as the single sign-on (SSO) endpoint.

     

8. Verify that the following default attribute values in Citrix Cloud match the corresponding attribute values configured in your SAML provider. For Citrix Cloud to find these attributes within the SAML assertion, the values entered here must match those in your SAML provider. If you didn’t configure a certain attribute in your SAML provider, you can use the default value in Citrix Cloud or leave the field blank, unless noted otherwise.

   • Attribute name for User Display Name: Default value is displayName.
   • Attribute name for User Given Name: Default value is firstName.
   • Attribute name for User Family Name: Default value is lastName.
   • Attribute name for Security Identifier (SID): You must enter this attribute name from your SAML provider if you didn’t create an attribute for UPN. The default value is cip_sid.
   • Attribute name for User Principal Name (UPN): You must enter this attribute name from your SAML provider if you didn’t create an attribute for SID. The default value is cip_upn.
   • Attribute name for Email: Default value is cip_email.
   • Attribute name for AD Object Identifier (OID): Default value is cip_oid.
   • Attribute name for AD Forest: Default value is cip_forest.
   • Attribute name for AD Domain: Default value is cip_domain.
9. Select Test and Finish to verify you configured the connection successfully.

Add administrators to Citrix Cloud from AD

For instructions for adding and managing AD groups in Citrix Cloud, see Manage administrator groups.

Enable SAML authentication for workspaces

1. From the Citrix Cloud menu, select Workspace Configuration.
2. Select the Authentication tab
3. Select SAML 2.0.

Troubleshooting

Attribute errors

Attribute errors might arise under any of the following conditions:

• The required attributes in your SAML configuration are not encoded correctly.
• The cip_sid and cip_upn attributes are missing from SAML assertion.
• The cip_sid or cip_oid attributes are missing from the SAML assertion and Citrix Cloud can’t retrieve them from Active Directory due to a connectivity issue.

When an attribute error occurs, Citrix Cloud displays an error message that includes the faulty attributes.

To resolve this type of error:

1. Ensure that your SAML provider sends the required attributes with the correct encoding, as shown in the following table. At a minimum, either the SID or UPN attribute must be included.

   Attribute	Encoding	Required
   cip_email	Must be in String format (user@domain)
   cip_oid	Must be in Base64 or String format
   cip_sid	Must be in Base64 or String format	Yes, if not using cip_upn
   cip_upn	Must be String format (user@domain)	Yes, if not using cip_sid

2. Verify the Cloud Connectors are online and healthy so Citrix Cloud can retrieve any missing attributes that it needs. For more information, see Cloud Connector advanced health checks.

Unexpected errors

Citrix Cloud might experience an unexpected error when:

• A user initiates a SAML request using an IDP-initiated flow. For example, the request is made by selecting a tile through the identity provider’s app portal instead of navigating directly to the workspace URL (customer.cloud.com).
• The SAML certificate is invalid or has expired.
• The authentication context is invalid.
• SAML assertion and response signature is mismatched.

When this error occurs, Citrix Cloud displays a generic error message.

If this error results from navigating to Citrix Cloud through an identity provider’s app portal, you can use the following workaround:

1. Create a bookmark app in the identity provider’s app portal that references your workspace URL (for example, https://customer.cloud.com).
2. Assign users to both the SAML app and the bookmark app.
3. Change the visibility settings of the SAML app and the bookmark app so that the bookmark app is visible and the SAML app is hidden in the app portal.
4. Disable the Federated Identity Provider Sessions setting in Workspace Configuration to remove additional password prompts. For instructions, see Federated identity provider sessions in the Citrix Workspace product documentation.

Debugging recommendations

Citrix recommends the use of the SAML-tracer browser extension for all SAML debugging. This extension is available for most common web browsers. The extension decodes Base64-encoded requests and responses into SAML XML, which renders them human-readable.

This tool allows you, as an administrator, to check the value of SAML attributes that are sent for the user and to look for the presence of signatures in SAML requests and responses. In the event you need assistance with a SAML-related issue, Citrix Support requests the SAML-tracer file to understand the issue and resolve your support case.

More information

• Microsoft Docs: Tutorial: Azure Active Directory single sign-on (SSO) integration with Citrix Cloud SAML SSO
• SAML with Active Directory Federated Services (ADFS): Configure SAML authentication in Citrix Cloud using ADFS
• Citrix Tech Zone: Tech Insight: Authentication - SAML