# Configuring SSO: SAML 2.0

> You can enable SSO using any identity provider that supports the SAML 2.0 authentication protocol.

You can enable SSO using any identity provider that supports the SAML 2.0 authentication protocol.

## Overview

Enabling SAML SSO is a multi-step process and you must complete the following configuration:

1. Configure your identity provider to recognize the UiPath platform as a service provider.
2. Configure the UiPath platform as a service provider to recognize and trust your identity provider.
3. Provision users to your organization to allow them to log in with SSO using the SAML 2.0 protocol from your identity provider.

## Step 1. Configure your identity provider

UiPath supports multiple identity providers.

In this section, we exemplify how to find the specific configuration and obtain the certificates for each of the following identity providers:

* ADFS
* Google
* Okta
* PingOne

### A. Configuring ADFS

Configure a machine to support ADFS and make sure you have access to the ADFS Management software. Work with your system administrator if needed.

:::note
The following steps are a broad description of a **sample configuration**. For more detailed instructions, refer to the [ADFS documentation](https://docs.microsoft.com/en-us/windows-server/identity/active-directory-federation-services).
:::

1. Open ADFS Management and define a new relying party trust for Orchestrator as follows:
   1. Select **Relying Party Trusts**.
   2. In the **Actions** panel, select **Add Relying Party Trust**. The **Add Relying Party Trust Wizard** is displayed.
   3. In the **Welcome** section, select **Claims Aware**.
   4. In the **Select Data** section, choose the **Enter data about relying party manually** option.
   5. In the **Specify Display Name** section, in the **Display name** field, insert the URL of the Orchestrator instance.
   6. The **Configure Certificate** section does not need any specific settings so leave it as it is.
   7. In the **Configure URL** section, select **Enable support for the SAML 2.0 Web SSO Protocol**.
   8. In the **Relying party SAML 2.0 SSO service URL** field, fill in the Identity base URL of your Automation Suite instance, plus the suffix `/Saml2/Acs`. For example, `https://{yourDomain}/{organizationName}/identity_`.
   9. In the **Relying party trust identifier** field, under the **Configure Identifiers** section, fill in the Identity base URL, for example `https://{yourDomain}/{organizationName}/identity_`.
   10. In the **Choose Access Control Policy** section, make sure to select the **Permit everyone** access control policy.
   11. The **Ready to Add Trust** and **Finish** do not need any specific settings, so leave them as they are.

      The newly added party trust is displayed on the **Relying Party Trusts** window.
   12. Go to **Actions** > **Properties** > **Endpoints** and make sure that POST is selected for **Binding** and that the **Set the trusted URL as default** checkbox is selected.

      The Endpoint binding needs to be *Post*. Other bindings such as *redirect* are not compatible with UiPath® as ADFS doesn't sign redirect assertions.
   13. Go to **Actions** > **Properties** > **Identifiers** and make sure the Identity base URL is present, `https://{yourDomain}/{organizationName}/identity_`.
2. Select the relying party trust and select **Edit Claim Issuance Policy** from the **Actions** panel.

   The **Edit Claim Issuance Policy** wizard is displayed.
3. Select **Add rule** and create a new rule using the **Send LDAP Attributes as Claims** template with the following settings, as described in the table:

   | **LDAP Attribute** | **Outgoing Claim Type** |
   | --- | --- |
   | E-Mail-Addresses | E-Mail Address |
   | User-Principal-Name | Name ID |
4. Once ADFS is configured, open PowerShell as an administrator and run the following commands:
   1. `Set-ADFSRelyingPartyTrust -TargetName "DISPLAYNAME" -SamlResponseSignature MessageAndAssertion`

      Replace `DISPLAYNAME` with the value set at step **1.e**.
   2. `Restart-Service ADFSSRV`.

### B. Configuring Google

:::note
The following steps are a broad description of a **sample configuration**. For more detailed instructions, refer to the [Google documentation](https://support.google.com/a/answer/6087519).
:::

1. Log in to the Admin console as an administrator, go to **Apps** and then **Web and mobile apps**.
2. Select **Add App** and then **Add custom SAML app**.
3. In the **App Details** page, fill in a name for your Automation Suite instance.
4. On the **Google Identity Provider details page**, copy and save the following for later:
   * **SSO URL**
   * **Entity ID**
5. Download the **Certificate**, open it with a text editor, copy and save the value for the next part of setup in **Step 2. Configure Automation Suite**.
6. In the **Service Provider Details** page, enter the following:
   * **ACS URL**: `https://{yourDomain}/{organizationName}/identity_/Saml2/Acs`
   * **Entity ID**: `https://{yourDomain}/{organizationName}/identity_`
7. In the **Attribute Mapping** page, provide the following mappings:
   * `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`

   Note that this claim is case sensitive.
   * `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn`
8. After configuring the SAML app, go to **User access** on the Automation Suite SAML app in the Google admin console and select **On for everyone**.

### C. Configuring Okta

:::note
The following steps are a broad description of a **sample configuration**. For more detailed instructions, refer to the [Okta documentation](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm).
:::

1. Log in to the Okta Admin Console, go to **Applications > Applications**, select **Create App Integration**, and select **SAML 2.0** as the **Sign-on method**.
2. In the **General Settings** page, specify a name for your Automation Suite instance.
3. On the **Configure SAML** page, fill in the **General** section.

   For example:

   * **Single sign on URL**: The Identity base URL + `/Saml2/Acs`. For example, `https://{yourDomain}/{organizationName}/identity_/Saml2/Acs`.
   * Select the **Use this for Recipient URL and Destination URL** checkbox.
   * **Audience URI**: `https://{yourDomain}/{organizationName}/identity_`
   * **Name ID Format**: **EmailAddress**
   * **Application Username**: **Email**
4. Fill in the **Attribute Statements** section:
   * In the **Name** field, type `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. Note that this claim is case sensitive.
   * From the **Value** list, select **user.email**.
5. In the **Feedback** section, select the option that suits you.
6. Select **Finish**.
7. On the **Sign On** tab, in the **Settings** section, select **View Setup Instructions**.

   You are redirected to a new page containing the instructions required to complete the next part of setup in **Step 2. Configure Automation Suite**:

   * **Identity Provider Sign-On URL**
   * **Identity Provider Issuer**
   * **X.509 Certificate**
8. In order for users to be able to use Okta authentication, they must be assigned the newly created application:
   1. On the **Application** page, select the newly created application.
   2. On the **Assignments** tab, select **Assign > Assign to People** and then select the users to be given the necessary permissions. The newly added users are displayed on the **People** tab.

### D. Configuring PingOne

:::note
The following steps are a broad description of a sample configuration. For more detailed instructions, refer to the [PingOne documentation](https://docs.pingidentity.com/pingone/introduction_to_pingone/p1_introduction.html) .
:::

1. [Add a web application that connects using SAML in PingOne](https://docs.pingidentity.com/pingone/directory/p1_groups_vs_populations.html), with the following specifics:
   1. On the **Configure SAML Connection** page, select **Manually Enter** and fill out the following:
      * **ACS URLS**: Case-sensitive Identity base URL + `/Saml2/Acs` . For example, `https://{yourDomain}/{organizationName}/identity_`
      * **Entity ID**: `https://{yourDomain}/{organizationName}/identity_`
      * **SLO binding**: HTTP Redirect
      * **Assertion Validity Duration**: Enter the number of seconds for the validity period.
   2. On the **Map Attributes** page, map the following attribute:

**Email Address** = `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. Note that this claim is case sensitive.
2. On the **Connections > Applications** page, find the application you just created and select the icon at the right end of box to show its details.
3. From the **Profile** tab, copy and save the following values for the next part of setup, described further in Step 2:
   * **Client ID**
   * **Home Page URL**.
4. If you did not download it during application setup, download the PingOne signing certificate:
   1. Go to **Connections > Certificates & Keypairs**.
   2. Find the application you just created and select at the right end of the box to show its details.
   3. At the right of the **Details** tab, select **Download Certificate** and select the **.crt** format.
5. Open the certificate file in any text editor, copy and save the certificate value for the next part of setup, described further in Step 2.

## Step 2. Configure `Private Test Cloud`

To enable `Private Test Cloud` as a service provider that recognizes your identity provider:

1. Log in to the as a system administrator.
2. Make sure that **Host** is selected at the top of the left pane and then select **Security**.
3. Select **Configure** under **SAML SSO** and follow the instructions for the identity provider that you use:
   1. To configure SAML for **ADFS**:
      1. Select the **Enabled** checkbox.
      2. Select the **Force automatic login using this provider** checkbox if you want to only allow login with Active Directory accounts.
      3. In the **Display Name** field, type the text you want to show under this login option on the **Login** page.
      4. In the **Service Provider Entity ID** field, type `https://{yourDomain}/{organizationName}/identity_`.
      5. In the **Identity Provider Entity ID** field, paste the value obtained while configuring ADFS authentication.
      6. In the **Single Sign-On Service URL** field, paste the value obtained while configuring ADFS authentication.
      7. Select the **Allow unsolicited authentication response** checkbox.
      8. In the **Return URL** field, type `https://{yourDomain}/{organizationName}/identity_/externalidentity/saml2redirectcallback`.
      9. Set the **external user mapping strategy** parameter to **By user e-mail**.
      10. For the **SAML binding type**, select **HTTP redirect**.
      11. In the **Signing Certificate** field, paste the certificate text.
   2. To configure SAML for **Google**:
      1. Select the **Enabled** checkbox.
      2. Select the **Force automatic login using this provider** checkbox if you want to only allow login with Active Directory accounts.
      3. In the **Display Name** field, type the text you want to show under this login option on the **Login** page.
      4. In the **Service Provider Entity ID** field, type `https://{yourDomain}/{organizationName}/identity_`.
      5. In the **Identity Provider Entity ID** field, paste the **Entity ID** value obtained while configuring Google authentication.
      6. In the **Single Sign-On Service URL** field, paste the **SSO URL** value obtained while configuring Google authentication.
      7. Select the **Allow unsolicited authentication response** checkbox.
      8. In the **Return URL** field, type `https://{yourDomain}/{organizationName}/identity_/externalidentity/saml2redirectcallback`.
      9. For **External user mapping strategy**, select **By user e-mail**.
      10. For **SAML binding type**, select **HTTP redirect**.
      11. In the **Signing Certificate** field, paste the **Certificate** value obtained while configuring Google.
   3. To configure SAML for **Okta**:
      1. Select the **Enabled** checkbox.
      2. Select the **Force automatic login using this provider** checkbox if you want to only allow login with Active Directory accounts.
      3. In the **Display Name** field, type the text you want to show under this login option on the **Login** page.
      4. In the **Service Provider Entity ID** field, type `https://{yourDomain}/{organizationName}/identity_`.
      5. In the **Identity Provider Entity ID** field, paste the **Identity Provider Issuer** value obtained while configuring Okta.
      6. In the **Single Sign-On Service URL** field, paste the **Identity Provider Sign-On URL** value obtained while configuring Okta.
      7. Select the **Allow unsolicited authentication response** checkbox.
      8. In the **Return URL** field, type `https://{yourDomain}/{organizationName}/identity_/externalidentity/saml2redirectcallback`.
      9. For **SAML binding type**, select **HTTP redirect**.
      10. In the **Signing Certificate** field, paste the **X.509 Certificate** value obtained while configuring Okta.
   4. To configure SAML for **PingOne**:
      1. Select the **Enabled** checkbox.
      2. Select the **Force automatic login using this provider** checkbox if you want to only allow login with Active Directory accounts.
      3. In the **Display Name** field, type the text you want to show under this login option on the **Login** page.
      4. In the **Service Provider Entity ID** field, paste your Automation Suite URL in the format `https://{yourDomain}/{organizationName}/identity_`.
      5. In the **Identity Provider Entity ID** field, paste the **Issuer ID** value obtained while configuring PingOne.
      6. Set the **Single Sign-On Service URL** parameter to the **Single SignOn URL** value obtained while configuring PingOne.
      7. Select the **Allow unsolicited authentication response** checkbox.
      8. In the **Return URL** field, type `https://{yourDomain}/{organizationName}/identity_/externalidentity/saml2redirectcallback`.
      9. For the **External user mapping strategy**, select **By user e-mail**.
      10. For the **SAML binding type**, select **HTTP redirect**.
      11. In the **Signing Certificate** field, paste the value obtained while configuring PingOne.
4. Select **Save** to save the changes and return to the previous page.
5. Select the toggle to the left of SAML SSO to enable the integration.
6. Restart the 'identity-service-api-*' pod. This is required after making any changes to external providers.
   1. Connect to the primary server using SSH.
   2. Run the following command:

`kubectl -n uipath rollout restart deployment identity-service-api`

## Step 3. Optional settings

The following configuration is optional and is only required if you want to use one or both advanced security features.

### Step 3.1. Custom mapping

ADFS, Google, and Okta all use the email address as a SAML attribute. This section handles custom SAML mapping based on either the user name or an external provider key.

:::important
Configuring custom mapping attributes impacts the entire system, meaning they apply to all existing identity providers. As a result, no other provider (Azure, Windows) can work while a new mapping is set.
:::

The following parameters need to be set in the SAML SSO configuration in the **Security** page at the host level.

* **External user mapping strategy** - Defines the mapping strategy. The following options are available:
  + `By user email` - Your email address is set as the attribute. This is the default value.
  + `By username` - Your user name is set as the attribute.
  + `By external provider key` - An external provider key is set as the attribute.
* **External user identifier claim name** - Defines the claim to be used as an identifier for the mapping. This is only required if you set your username as the attribute.