Connect SAML as an identity provider to Citrix Cloud Japan

Citrix Cloud Japan supports using SAML (Security Assertion Markup Language) as an identity provider to authenticate administrators (in preview) 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).

For most SAML providers, use the information in this article to set up SAML authentication. To use SAML authentication with Azure AD, you can opt for the Citrix Cloud Japan SAML SSO app in the Azure AD app gallery. For more information about using the Citrix Cloud Japan SAML SSO app to set up SAML authentication in Citrix Cloud Japan, see Tutorial: Azure Active Directory single sign-on (SSO) integration with Citrix Cloud SAML SSO on the Azure AD app documentation website.

Prerequisites

Using SAML authentication with Citrix Cloud Japan 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 that Citrix Cloud Japan 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 Citrix Cloud Connector requirements.
• 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 must 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 Connectivity requirements.

For more information about installing the Cloud Connector, see Task 3: Install Cloud Connectors.

Active Directory

Before configuring SAML authentication, perform the following tasks:

• Verify that your workspace subscribers have user accounts in Active Directory (AD). Subscribers without AD accounts are not allowed to sign in to their workspaces successfully when SAML authentication is configured.
• Ensure that the user properties in your subscribers’ AD accounts are populated. Citrix Cloud Japan requires these properties to establish the user context when subscribers sign in to Citrix Workspace. If these properties aren’t populated, subscribers can’t sign in. These properties include:
  • Email address
  • Display name (optional)
  • Common name
  • SAM account name
  • User Principal Name
  • Object GUID
  • SID
• Establish a connection between your on-premises Active Directory (AD) and your Citrix Cloud Japan account by deploying Cloud Connectors.
• Synchronize your AD users to the SAML provider. Citrix Cloud Japan requires the AD user attributes for your workspace subscribers so they can sign in successfully.

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 Japan in the SAML assertion:

• SecurityIDentifier (SID)
• objectGUID (OID)
• userPrincipalName (UPN)
• Mail (email)

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.
2. If the custom attributes corresponding to the AD user attributes mentioned earlier are not available, generate the custom attributes and link them to Active Directory (AD). 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.

Note:

If you’ve already created custom attributes mapping to the listed AD user attributes, no further creation or mapping is required. Instead, use your existing custom attributes when you configure the metadata from your SAML provider in Citrix Cloud Japan.

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

Administrator authentication with SAML 2.0

Note:

SAML authentication for Citrix Cloud Japan administrators is in technical preview. Citrix recommends using preview features only in non-production environments.

AD groups

You can add administrators to Citrix Cloud Japan using only AD groups. You can’t add administrators individually if you’re using SAML authentication.

Sign-in URL

When configuring SAML authentication, you configure a sign-in URL that administrators can use to sign in to Citrix Cloud Japan. This URL uses the format https://citrix.citrixcloud.jp/go/myorganization, where “myorganization” is the unique identifier you choose for your organization.

After you add AD groups, the administrators in the group can sign in to Citrix Cloud Japan immediately using the sign-in URL you specified. Citrix doesn’t send any notifications to let administrators know that they have access to Citrix Cloud Japan.

Supported permissions

Only custom access permissions are supported. When you add an AD group, you must select the permissions that you want to grant to the administrators in the group. Full access permissions are not supported.

Task overview

To set up SAML authentication, you perform the following tasks:

1. In Identity and Access Management, connect your on-premises AD to Citrix Cloud Japan as described in Connect Active Directory to Citrix Cloud Japan.
2. Integrate your SAML provider with your on-premises AD as described in SAML integration with Active Directory in this article.

3. In Identity and Access Management, configure SAML authentication in Citrix Cloud Japan configure your SAML provider with Citrix Cloud Japan’s metadata, and reciprocally configure Citrix Cloud Japan with your SAML provider’s metadata to establish the SAML connection.

4. If you’re using SAML to authenticate administrators:
   1. Configure the sign-in URL that administrators can use to sign in to Citrix Cloud Japan.
   2. Add administrators to Citrix Cloud Japan by specifying the AD groups that they belong to.
5. If you’re using SAML to authenticate workspace subscribers, enable the SAML authentication method in Workspace Configuration. If you’re using SAML only for authenticating Citrix Cloud administrators, you don’t need to perform this task.

Create and map custom SAML attributes

If you’ve already configured custom attributes for SID, UPN, OID, and email attributes in your SAML provider, there’s no need to complete this task. Proceed to Create a SAML connector application and use your existing custom SAML attributes in Step 8.

Note:

The steps in this section describe actions that you perform in your SAML provider’s administration console. The specific commands that 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 details on the relevant commands specific to 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 the following attributes:
   • cip_sid
   • cip_upn
   • cip_oid
   • cip_email
3. Select the AD that you connected with Citrix Cloud Japan. 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:
   • Select objectSid and map to the cip_sid attribute.
   • Select userPrincipalName and map to the cip_upn attribute.
   • Select ObjectGUID and map to the cip_oid attribute.
   • Select mail and map to the cip_email attribute.

Configure the administrator sign-in URL

1. Sign in to Citrix Cloud at https://citrix.citrixcloud.jp.
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

This task involves creating a connector application using the SAML metadata sourced from Citrix Cloud Japan. After you configure the SAML application, you use the SAML metadata from your connector application to configure the SAML connection to Citrix Cloud Japan.

Note:

Some steps in this section describe actions that you perform in your SAML provider’s administration console. The specific commands that 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 details on the relevant commands specific to 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. In Citrix Cloud Japan’s Configure SAML screen, select Download under SAML Metadata. The metadata XML file appears in another browser tab.

   Note:

   If needed, you can also download this file from https://saml.citrixcloud.jp/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.citrixcloud.jp.
   • In the Recipient field, enter https://saml.citrixcloud.jp/saml/acs.
   • In the field for ACS URL validator, enter https://saml.citrixcloud.jp/saml/acs.
   • In the field for ACS URL, enter https://saml.citrixcloud.jp/saml/acs.

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

   Create this field	Assign this custom attribute
   cip_sid	cip_sid or your existing SID attribute
   cip_upn	cip_upn or your existing UPN attribute
   cip_oid	cip_oid or your existing OID attribute
   cip_email	cip_email or your existing email attribute

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

Add SAML provider metadata to Citrix Cloud Japan

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 Japan, enter the following values from your SAML provider’s metadata file:

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

   • In Sign Authentication Request, select Yes to allow Citrix Cloud Japan to sign authentication requests, certifying they came from Citrix Cloud Japan 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.
   • In SAML Response, select the signing method your SAML provider uses for the SAML Response and SAML Assertion. By default, Citrix Cloud Japan 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 PEM file.
4. In the Configure SAML screen in Citrix Cloud Japan, select Upload File and select the PEM 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 Japan 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.
7. In Logout URL, locate the SingleSignOnService element with the HTTP-Redirect binding in your SAML provider’s metadata file and enter the URL. If you choose to omit the Logout URL, Citrix Cloud Japan does not send a logoff request to the identity provider. Instead, Citrix Cloud Japan redirects to the Workspace URL. Citrix Cloud Japan doesn’t support Single Log Out (SLO) or sending signed logout requests.
8. Verify the following default name attribute values in Citrix Cloud Japan match the corresponding attribute values in your SAML provider’s administration console. If your SAML provider has different values, you can change these values in Citrix Cloud Japan to ensure they match your SAML provider.
   • Attribute name for User Display Name: displayName
   • Attribute name for User Given Name: givenName
   • Attribute name for User Family Name: familyName
9. In Citrix Cloud Japan, enter the custom SAML attributes from your SAML provider:
   • In Attribute name for Security Identifier (SID), enter your custom SID attribute name. The default value is cip_sid.
   • In Attribute name for User Principal Name (UPN), enter your custom UPN attribute name. The default value is cip_upn.
   • In Attribute name for Email, enter your custom Email attribute name. The default value is cip_email.
   • In Attribute name for AD Object Identifier (OID), enter your custom OID attribute name. The default value is cip_oid.
10. Select Test and Finish to verify you configured the connection successfully.

Add administrators to Citrix Cloud Japan from AD

1. In Citrix Cloud Japan, from the Identity and Access Management page, select the Administrators tab.
2. In Administrator details, select Active Directory and then select the domain you want to use.
3. In Search for a group to add, start typing the name of the group you want to add in the search box. When it appears, click the plus sign (+) to select the group.
4. Select Next.
5. Select the custom access permissions or roles that you want to assign to the group. Select Next.
6. Review the administrator details. Select Back to make any changes.
7. When you’re finished, select Save.

Enable SAML authentication for workspaces

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

Troubleshooting

Attribute errors

Attribute errors might arise if the required attributes in your SAML configuration are not encoded correctly. When an attribute error occurs, Citrix Cloud Japan displays an error message that includes the faulty attribute.

To resolve this type of error, ensure that these attributes are encoded as described in the following table.

Unexpected errors

Citrix Cloud Japan might experience an unexpected error when:

• A user initiates a SAML request using an IDP-initiated flow. For example, rather than accessing the workspace URL directly, the request is initiated by selecting a tile within the identity provider’s app portal. (customer.citrixcloud.jp).
• The SAML certificate is invalid or has expired.
• The authentication context is invalid.
• SAML assertion and response signature are mismatched.

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

If this error results from navigating to Citrix Cloud Japan 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.citrixcloud.jp).
2. Assign users to both the SAML app and the bookmark app.
3. Change the visibility settings in the app portal to display the bookmark app while hiding the SAML app.
4. Disable the Prompt=Login parameter to remove additional password prompts.