This topic describes how to configure single sign-on (SSO) to log on to Elastic Desktop Service (EDS) clients by using Active Directory Federation Services (AD FS). After SSO is configured, the identity of a regular user must be verified only in AD FS when the user logs on to an EDS client. This improves logon security of the EDS client and helps manage client logons from regular users.

Background information

SSO (also known as identity federation) is a secure communications technology that helps you access multiple application systems in a quick manner. It allows you to use a single logon to log on to multiple mutually trusted systems. The following section describes the terms related to SSO:
  • IdP: provides identity management services, collects and stores user identity information such as usernames and passwords, and authenticates user identities on user logons. AD FS and Shibboleth are two of the well-known IdPs.
  • service provider (SP): establishes mutual trust relationships with IdPs and uses the identity management services provided by IdPs to provide services to users.
  • Security Assertion Markup Language (SAML): a standard protocol that implements enterprise-level user identity authentication and that is used to exchange identity authentication and authorization data between IdPs and SPs.

EDS supports the Security Assertion Markup Language (SAML)-based SSO. If you have used Active Directory Domain Services (AD DS) to manage users, you can use AD FS to implement SSO. In this case, EDS acts as a service provider (SP) and AD FS acts as an identity provider (IdP). The providers exchange metadata files with each other to implement SAML-based SSO. After you configure SSO, you can use your logon credentials in AD FS to log on to an EDS client in a secure manner.

This topic describes how to configure SSO for AD users by using AD FS. If you have created a workspace of the enterprise AD account type and connected the AD system of your enterprise to EDS, you can directly configure SSO for AD users. For more information, see Configure SSO for AD users.

Note Only software clients that run Windows or macOS and hardware clients support the SSO feature. Web clients and mobile clients that run iOS or Android do not support the SSO feature.

Procedure

The following figure shows how to configure SSO.Procedure

Preparations

Create a workspace of the convenience account type in the EDS console and enable the SSO feature for the workspace.
  • If no workspace is available, log on to the EDS console and create a workspace. For information about how to create a workspace, see Create a workspace of the convenience account type.
  • If a workspace of the convenience account type is available, click the workspace ID on the Overview page to go to the workspace details page and enable the SSO feature.
Workspace details

Step 1: Create a convenience user that has the same username as an AD user in the EDS console

If you do not want to create a workspace of the enterprise AD type in the EDS console to connect to the AD system of your enterprise, you can create a convenience user in the EDS console to allow an AD user to implement SSO. This way, the identity of the AD user is verified only in AD FS when the user logs on to an EDS client. If you create a workspace of the enterprise AD type in the EDS console to connect to the AD system of your enterprise, EDS obtains the information about the AD system of your enterprise. If an AD user needs to use EDS, you must create a convenience user that has the same username as the AD user. When you create the convenience user in the EDS console, you can use manual entry or batch entry to import user information. To import user information in batches, perform the following steps:
Note If you want to import information about a few users, you can use manual entry to enter the information about the users in the EDS console. When you enter the information about a convenience user, make sure that the username of the user is the same as that of an AD user. The username is not case-sensitive. For more information, see Create a convenience user.
  1. Create a CSV file that contains the AD user information on the AD domain server.
    1. Check whether the existing AD user information meets the requirements of creating convenience users.
      Make sure that the username of the convenience user that you create is the same as the username of an AD user. The username is not case-insensitive. The username of the AD user must follow the format of EDS usernames. If the username of the AD user is in an invalid format, you cannot create the convenience user that corresponds to the AD user. In this case, you must specify the username in the valid format.
      The username of the convenience user must meet the following format requirements:
      • The username must be 3 to 24 characters in length.
      • The username can contain lowercase letters, digits, and special characters such as hyphens (-), underscores (_), and periods (.).
      • The username must start with a lowercase letter and cannot start with a digit or special character.
    2. Run the Get-ADUser command in PowerShell to export the CSV file that contains the AD user information.
      Configure the command parameters based on your business requirements. For example, if you want to export a CSV file that contains all AD user information and save the file to a specified path, run the following command:
      Get-ADUser -filter * |export-csv The path in which you want to save the CSV file -Encoding utf8
      If the name of the file is test.csv, and you want to save the file to C:\Users, run the following command:
      Get-ADUser -filter * |export-csv C:\Users\test.csv -Encoding utf8
  2. Open the CSV file, modify the user information based on the import requirements for EDS convenience users, and then save the file.
    When you modify the user information, take note of the following items:
    • You must specify usernames in the first column, email addresses in the second column, and mobile numbers in the third column. The third column is optional.
    • In the CSV file, the value that is specified in the SamAccountName column can be used as the username column of a convenience user in EDS, and the value that is specified in the UserPrincipalName column can be used as the email address column of the convenience user. If the actual email address differs from the email address that is specified in the UserPrincipalName column, specify the actual email address.
  3. Create the convenience user in the EDS console.
    1. Log on to the EDS console.
    2. In the left-side navigation pane, click Users.
    3. On the Users page, click Create User.
    4. In the Create User panel, click the Batch entry tab.
    5. Click Select File and select the CSV file that you saved in Step 2.
      When you upload the CSV file, the user information fields in the file are automatically populated in the Create User panel. After you upload the CSV file, check whether all user information is imported. If the import fails, check whether the user information in the CSV file complies with the EDS username format.
    6. In the message that appears, click Close.
      After you create the convenience users, you can view the user information on the Users page.

Step 2: Configure AD FS as a trusted SAML-based IdP in the EDS console

To configure AD FS as a trusted SAML-based IdP in the EDS console, you must upload the metadata file that is provided by AD FS to EDS.

  1. In AD FS, download the IdP metadata file and save the file to your local computer.
    You can download the IdP metadata file from the following URL: https://<ADFS server>/FederationMetadata/2007-06/FederationMetadata.xml. <ADFS server> specifies the domain name or IP address of the AD FS server.
  2. Upload the IdP metadata file that is provided by AD FS to EDS.
    1. On the Overview page in the EDS console, find the workspace of the convenience account type that you want to manage and click the workspace ID.
    2. In the Metadata File section of the workspace details page, click Upload File.
    3. Double-click the downloaded IdP metadata file and click OK.

Step 3: Configure EDS as a trusted SAML-based SP in AD FS

To configure EDS as a trusted SAML-based SP in AD FS, you must upload the metadata file that is provided by EDS to AD FS.

  1. Obtain the SP metadata file from the EDS console.
    1. On the Overview page, find the required workspace of the convenience account type and click the workspace ID.
    2. In the Metadata File section of the workspace details page, click Download File.
      The downloaded metadata file is saved in the download folder on your local computer.
  2. Upload the metadata file that is provided by EDS to AD FS.
    1. Log on to the server of AD FS and open Server Manager.
    2. In the upper-right corner, choose Tools > AD FS Management.
    3. In the left-side navigation pane of the AD FS window, choose Trust Relationships > Relying Party Trusts.
    4. In the Actions section on the right, click Add Relying Party Trust.
    5. Add the relying party trust by following the wizard.
      In the Select Data Source step, select Import data about the relying party from a file and import the SP metadata file that you obtained in Step 1. Use the default settings for other parameters. ADFS1
  3. Edit the claim issuance policy of the relying party trust and configure SAML assertion attributes for the SP.
    1. In the list of relying party trusts, right-click the relying party trust that you added in the previous step and select Edit Claim Issuance Policy.
    2. In the dialog box that appears, click Add Rule.
    3. Configure the claim rules.
      • In the Choose Rule Type step, select Transform an Incoming Claim from the Claim rule template drop-down list.
      • In the Configure Claim Rule step, set Incoming claim type to UPN and Outgoing claim type to Name ID.

Step 4: Verify whether the AD user can log on to the EDS client by using SSO

Launch the EDS client. If the SSO feature is enabled for the workspace that you specified on the Configuration page, you are redirected to the enterprise IdP page for logon verification. Only software clients that run Windows or macOS and hardware clients support the SSO feature. To check whether you can log on to the EDS client by using SSO, perform the following steps. In this example, an EDS client that runs Windows is used.

  1. Launch the EDS client that runs Windows.
  2. On the Configuration page, enter the ID of the workspace that you created and click Next.
    The ID of the workspace of the convenience account type that you created in Preparations is used. If you do not select Use VPC tunnel, the client connects to your cloud desktop over the Internet.
  3. On the AD FS logon page, enter the AD user information for identity verification.
    • If the logon is successful, the SSO configurations take effect.
      Note After SSO is configured, you can use an AD user to log on to the EDS client even if no workspace of the enterprise AD account type is created to connect to the AD system of your enterprise. By default, no cloud desktop is assigned to the AD user. If you want to connect to a cloud desktop as an AD user, log on to the EDS console to create a cloud desktop and assign the cloud desktop to a convenience user that has the same username as the AD user. For more information, see Create a cloud desktop and Assign cloud desktops to regular users and view the regular users.
    • If an internal error occurs, check whether the AD FS configurations are correct.

What to do next

If a new AD user needs to use a cloud desktop, perform the following operations:
  1. Create a new AD user on the AD domain server.
  2. In the EDS console, create a convenience user that has the same username as the AD user that you created.
  3. Create a cloud desktop and assign the cloud desktop to the convenience user.