automation-suite
2023.10
false
UiPath logo, featuring letters U and I in white
Automation Suite Admin Guide
Last updated Aug 14, 2024

Configuring the Active Directory Integration

Warning:

Active Directory integration is not supported with Automation Suite on AKS/EKS.

You can enable SSO using Windows authentication and enable the directory search functionality with the Active Directory integration.Directory search lets you search for directory accounts and groups and work with them as you would with local accounts.

Known Limitations

  • Directory search does not find users from an external trust domain. This feature is not supported because there isn't a mutually-trusted authority with external trusts.
  • Windows authentication uses the Kerberos protocol in Automation Suite, therefore Windows login can only be used with domain-joined machines.

Step 1. Configure the Active Directory Integration

Work with your IT administrators to ensure the Automation Suite cluster can access your Active Directory (AD).

The Active Directory integration can be configured using one of two options:

  1. Kerberos authentication
  2. username and password

Kerberos authentication is recommended because it supports more scenarios:

Scenario

Username and password

Kerberos Authentication

Directory search for domains in the same forest

Supported

Supported

Directory search for domains in a trusted forest

Not supported

Supported

Directory search for external trust domains

Not supported

Not supported

In an Active Directory environment, LDAPS is a commonly used secure connection for directory services. It is important to note that LDAPS support scenarios differ based on the authentication mechanism used.

Authentication mechanism

LDAPS support

Username and password

Supported

Kerberos authentication

Not supported

A. Kerberos Configuration (recommended)

  1. Configure Kerberos authentication following the instructions in Setting up Kerberos authentication.
  2. Log in to the Automation Suite host portal as a system administrator.
  3. Make sure that Host is selected at the top of the left pane and then click Security.
  4. Under Active Directory, click Configure.
    • Optionally select the Force automatic login using this provider checkbox if you want to only allow login with Active Directory accounts. Only do this if the integration with the provider has been successfully validated to prevent lockout.
    • Leave the Use Kerberos Auth checkbox selected.
    • In the Display Name field, type the text you want to show under this login option on the Login page.
  5. Click Save to save your changes and return to the previous page.
  6. Click the toggle to the left of Active Directory to enable the integration.
  7. Restart the identity-service-api-* pod.
    1. Connect to the primary server using SSH.
    2. Run the following command: kubectl -n uipath rollout restart deployment identity-service-api

B. Username and Password Configuration

Important: When you use this option, UiPath® service uses credentials provided in clear text to communicate with Active Directory. To prevent this, we recommend using LDAP over SSL (LDAPS) with this configuration.
Important: Only users from the same forest as the one configured in this page can interact with the UiPath cluster. Users from trusted forests will not be able to login to this UiPath cluster.

B.1. Prerequisite for Using LDAPS

If you intend to use LDAP over SSL (LDAPS), then you must first configure LDAP over SSL in your AD environment and obtain the root certificate to be used in UiPath cluster configuration.

Note:

Known issue: The configured LDAPS certificate is not persisted upon upgrading. As a result, after an upgrade, it is necessary to add the LDAPS certificate again in order for LDAP secure connections to work.

  1. Obtain and install the SSL certificate for LDAPS on each domain controller.

    For more information and instructions, see the article LDAP over SSL (LDAPS) Certificate.

  2. Encode the root certificate in Base64 by running the following command:
    [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("<Path to the .crt or .cer file>"))[Convert]::ToBase64String([System.IO.File]::ReadAllBytes("<Path to the .crt or .cer file>"))
  3. Add the encoded root certificate in ArgoCD:
    1. Log in to ArgoCD.
    2. Select and go to the uipath application.
    3. In the top left corner, click APP DETAILS.
    4. In the Parameters section, search for the parameter global.userInputs.certificate.identity.ldaps.customRootCA.
    5. Update the value of the parameter to the encoded content you obtained earlier.
    6. Save.
    7. Click SYNC to apply your changes.

B.2. Active Directory Configuration

  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. Under Active Directory, click Configure.
    • If you want to only allow login with Active Directory accounts, select the Force automatic login using this provider checkbox.
    • Clear the Use Kerberos Auth checkbox.
    • (Optional, but strongly recommended) Select the Use LDAP over SSL (LDAPS) checkbox.
    • In the Display Name field, type the name you want to show on the Login page for this sign in option.
    • In the Default Domain field, type your fully-qualified domain name (FQDN) for Active Directory (AD).
    • In the Username field, type the user name of an AD user. It needs to be in the format DOMAIN\username. For example, TESTDOMAIN\user1.
    • In the User Password field, type the password for the above AD account.
  4. Click Test and Save to save the changes and return to the previous page.
  5. Click the toggle to the left of Active Directory to enable the integration.
  6. Restart the identity-service-api-* pod.
    1. Connect to the primary server using SSH.
    2. Run the following command: kubectl -n uipath rollout restart deployment identity-service-api

Step 2. Configure Windows Authentication

Prerequisite

Obtain the <KERB_DEFAULT_KEYTAB>, which is the base64-encoded string of the keytab file generated as part of Kerberos setup.

Configure the Automation Suite Cluster

Important notes:

Skip this step if you already configured Automation Suite as a Kerberos client following the procedure described in the Configuring Automation Suite as a Kerberos client guide.

If you configured the Active Directory integration through the username and password method, which is not recommended, perform the following steps:

  1. Go to Argo CD 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 the global.kerberosAuthConfig.userKeytab parameter.

    The parameter has a placeholder value by default.

  5. Update the parameter's placeholder value with <KERB_DEFAULT_KEYTAB>, and then save.
  6. Click SYNC to apply the change.
  7. After a successful sync, restart Identity Server by running the following command:

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

Step 3. Browser Configuration

Microsoft Internet Explorer

Not supported.

Microsoft Edge

No additional configuration required.

Google Chrome

Normally, Google Chrome works without additional configuration.

If it does not, follow the below instructions.

  1. Go to Tools > Internet Options > Security.
  2. Select Local Intranet.
  3. Click Sites.
  4. Make sure that Automatically detect intranet network is selected or that all of the options are selected.
  5. Click on Advanced.
  6. Add the Automation Suite FQDN to the Local Intranet.
  7. Click Close and OK.
  8. Click on Custom Level.
  9. Optionally select Automatic logon only in Intranet zone under User Authentication

    If selected, when the browser receives the redirect authentication request, it checks the source of the requirement. If the domain or IP belong to the Intranet, the browser sends the user name and password automatically. If not, the browser opens a user name and password input dialog, and expects manual input.

  10. Optionally select Automatic logon with current user name and password under User Authentication.

    If selected, when the browser receives the redirect authentication request, it sends the user name and password silently. If the authentication result is successful, the browser continues to the original action. If the authentication fails, the browser opens a user name and password input dialog, and retries until successful.

  11. Make sure that Enable Integrated Windows Authentication is selected under Internet Options > Advanced tab and in the Security section.

Mozilla Firefox

  1. Open the browser configuration window.
  2. Type about:config in the address bar.
  3. Specify the Automation Suite FQDNs for which you use Kerberos authentication:
    1. Search for the term network.negotiate.
    2. Enable and set the following for Kerberos: network.negotiate-auth.delegation-uris (example value: uipath-34i5ui35f.westeurope.cloudapp.azure.com), network.negotiate-auth.trusted-uris (example value: uipath-34i5ui35f.westeurope.cloudapp.azure.com), and network.negotiate-auth.allow-non-fqdn (value: true).

Step 4. Allow Windows Authentication for the Organization

Now that Automation Suite is integrated with Windows Authentication, users for which a user account is created in Automation Suite can use the Windows option on the Login page to sign in to Automation Suite.



Each organization administrator must do this for their organization if they want to allow login with Windows credentials.

  1. Log in to Automation Suite as an organization administrator.
  2. Assign an organization-level role to an Active Directory user or group, which you can select from search.
  3. Repeat the above step for each user you want to allow to log in with Windows Authentication.

The users to which you assigned roles can then log in to the Automation Suite organization with their Active Directory account. They must log in from a domain-joined machine.

Troubleshooting

If you receive a HTTP 500 error when trying to log in using Windows credentials, here are some things to check:

  1. Is the Windows machine domain-joined?

    On the machine, go to Control Panel > System and Security > System and check if a domain is shown. If no domain is shown, add the machine to the domain. Machines must be domain-joined to use Windows Authentication with the Kerberos protocol.

  2. Can you log in to the Windows machine with the same credentials?

    If not, ask your system administrator for help.

  3. Are you using a browser other than Microsoft Edge?

    Additional configuration is required for supported browsers other than Microsoft Edge.

  4. Check the keytab configuration:
    1. After generating the keytab, on the Active Directory server, the AD user's property (servicePrincpalName) should be of the form HTTP/<Service Fabric FQDN> - for example, HTTP/uipath-34i5ui35f.westeurope.cloudapp.azure.com.

    2. The option This account supports Kerberos AES 256 bit encryption must be selected for the user account in AD.

      If this is improperly configured, in the identity-service-api log, you can see:

      Microsoft.AspNetCore.Authentication.Negotiate.NegotiateHandler An exception occurred while processing the authentication request.
GssApiException*GSSAPI operation failed with error - Unspecified GSS failure. Minor code may provide more information (Request ticket server HTTP/sfdev.eastus.cloudapp.azure.com@EXAMPLE.COM kvno 4 enctype aes256-cts found in keytab but cannot decrypt ticket).* at Microsoft.AspNetCore.Authentication.Negotiate.NegotiateHandler.HandleRequestAsync()Microsoft.AspNetCore.Authentication.Negotiate.NegotiateHandler An exception occurred while processing the authentication request.
GssApiException*GSSAPI operation failed with error - Unspecified GSS failure. Minor code may provide more information (Request ticket server HTTP/[email protected] kvno 4 enctype aes256-cts found in keytab but cannot decrypt ticket).* at Microsoft.AspNetCore.Authentication.Negotiate.NegotiateHandler.HandleRequestAsync()

  5. If you have multiple Active Directories configured in the domain you are using, authentication fails, and in the identity-service-api log, you can see: 

    kinit: Client '[email protected]' not found in Kerberos database while getting initial credentialskinit: Client '[email protected]' not found in Kerberos database while getting initial credentials

    In this case, make sure the machine account created for authentication is replicated to all Active Directories.

  6. If you run ktpass and assign a new password to the user account, the key version (kvno) increases and invalidates the old keytab. In the identity-service-api log, you can see: 
    Request ticket server HTTP/rpasf.EXAMPLE.COM kvno 4 not found in keytab; ticket is likely out of dateRequest ticket server HTTP/rpasf.EXAMPLE.COM kvno 4 not found in keytab; ticket is likely out of date
    In this case, you need to update krb5KeytabSecret in ArgoCD.
  7. If you see the following error in the identity-service-api pod: 
    GssApiException*GSSAPI operation failed with error - Unspecified GSS failure. Minor code may provide more information (Keytab FILE:/uipath/krb5/krb5.keytab is nonexistent or empty).GssApiException*GSSAPI operation failed with error - Unspecified GSS failure. Minor code may provide more information (Keytab FILE:/uipath/krb5/krb5.keytab is nonexistent or empty).
    1. First check if you provided the global.userInputs.identity.krb5KeytabSecret parameter in ArgoCD. If the parameter exists, verify if you can log into the Windows machine with the credentials of the AD user used to generate the keytab. Note that you must regenerate the keytab if the password was changed or expired.
    2. Another possible cause of this issue is that ArgoCD was previously synced incorrectly. To fix the problem, remove the existing global.userInputs.identity.krb5KeytabSecret, sync ArgoCD, and once the operation is successful, update global.userInputs.identity.krb5KeytabSecret, and sync again.

  8. Does the browser use the expected SPN?

    If Kerberos event logging is enabled by following these instructions , you will see the KDC_ERR_S_PRINCIPAL_UNKNOWN error in the Kerberos event logs. For details on this issue, see Microsoft documentation .

    To solve this issue, disable the CNAME lookup when negotiating Kerberos authentication by modifying the group policy. For details, see instructions for Google Chrome and for Microsoft Edge .

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.