automation-suite
2024.10
true
UiPath logo, featuring letters U and I in white
Automation Suite Admin Guide
Last updated Nov 11, 2024

Configuring SSO: SAML 2.0

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 below steps are a broad description of a sample configuration. For more detailed instructions, see the ADFS documentation.
  1. Open ADFS Management and define a new relying party trust for Orchestrator as follows:
    1. Click Relying Party Trusts.
    2. In the Actions panel, click 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 URL of your Automation Suite instance, plus the suffix identity_/Saml2/Acs. For example, https://baseURL/identity_/Saml2/Acs.
    9. In the Relying party trust identifier field, under the Configure Identifiers section, fill in the URL of your Orchestrator instance, plus the suffix 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 URL of your Orchestrator instance plus the suffix identity_ is present.
  2. Select the relying party trust and click Edit Claim Issuance Policy from the Actions panel.

    The Edit Claim Issuance Policy wizard is displayed.

  3. Click Add rule and create a new rule using the Send LDAP Attributes as Claims template with the following settings:

    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 below steps are a broad description of a sample configuration. For more detailed instructions, see the Google documentation.
  1. Log in to the Admin console as an administrator, go to Apps and then Web and mobile apps.
  2. Click 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://baseURL/identity_/Saml2/Acs
    • Entity ID: https://baseURL/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 click On for everyone.

C. Configuring Okta

Note: The below steps are a broad description of a sample configuration. For more detailed instructions, see the Okta documentation.
  1. Log in to the Okta Admin Console, go to Applications > Applications, click 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: Your Automation Suite URL + /identity_/Saml2/Acs. For example, https://baseURL/identity_/Saml2/Acs.
    • Select the Use this for Recipient URL and Destination URL checkbox.
    • Audience URI: https://baseURL/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. Click Finish.
  7. On the Sign On tab, in the Settings section, click 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, see the PingOne documentation.
  1. Add a web application that connects using SAML in PingOne, with the following specifics:
    1. On the Configure SAML Connection page, select Manually Enter and fill out the following:
      • ACS URLS: Case-sensitive URL for your Automation Suite instance + /identity_/Saml2/Acs (https://baseURL/identity_/Saml2/Acs).
      • Entity ID: https://baseURL/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.
    Tip: Alternatively, you can configure the PingOne SAML connection using the Import Metadata option. The SAML2 metadata of the UiPath Identity Server is available for download in XML format at https://baseURL/identity/Saml2.
  2. On the Connections > Applications page, find the application you just created and click 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 below in Step 2. Configure Automation Suite:

    • 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 click at the right end of the box to show its details.
    3. At the right of the Details tab, click 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 below in Step 2. Configure Automation Suite.

Step 2. Configure Automation Suite

To enable Automation Suite as a service provider that recognizes your identity provider:

  1. Log in to the Automation Suite host portal as a system administrator.
  2. Make sure that Host is selected at the top of the left pane and then click Security.
  3. Click 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://baseURL/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:/baseURL/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://baseURL/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://baseURL/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://baseURL/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://baseURL/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://baseURL/identiy_.

      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://baseURL/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. Click Save to save the changes and return to the previous page.
  5. Click 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.

Step 3.3. Service certificate

In the SAML protocol, the service certificate is used for signing and/or encrypting requests sent from the service provider, i.e. Automation Suite.

To set the service certificate:

  1. Go to ArgoCD and log in as an administrator.
  2. Select and go to the uipath application.
  3. Click APP DETAILS in the top left corner.
  4. In the PARAMETERS section, search for 'ServiceCert'.
  5. Update the global.userInputs.certificate.identity.saml.currentServiceCert parameter with your base64 serialization of the service certificate. The service certificate requires a private key.
  6. If your service certificate has a password, also update the global.userInputs.certificate.identity.saml.currentServiceCertPassword parameter.

    In ArgoCD, both the certificate and password are encoded in base64.

  7. If you need to rotate the service certificate, update the global.userInputs.certificate.identity.saml.futureServiceCert and global.userInputs.certificate.identity.saml.futureServiceCertPassword parameters.
  8. Click SYNC to apply the change.

    Wait a few minutes for the Identity Server to restart automatically.

Was this page helpful?

Support and Services
Get The Help You Need
UiPath Academy
Learning RPA - Automation Courses
UiPath Forum
UiPath Community Forum
Uipath Logo White
Trust and Security
Terms of Use
Privacy Policy
Cookies Policy
© 2005-2024 UiPath. All rights reserved.