Configuring the Active Directory integration

Configure the Active Directory integration for Private Test Cloud in Automation Suite, including required settings and verification guidance.

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 Private Test Cloud, 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, as described in the following table:

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, as described in the following table:

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 host portal as a system administrator.
3. Make sure that Host is selected at the top of the left pane and then select Security.
4. Under Active Directory, select 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. Select Save to save your changes and return to the previous page.
6. Select 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

Old Admin Experience

If you have turned off the New admin experience toggle, follow these instructions:

1. Configure Kerberos authentication following the instructions in Setting up Kerberos authentication.
2. Log in to the host portal as a system administrator.
3. Go to Security Settings.
4. In the External Providers section, select Configure under Active Directory.
   • Select the Enabled checkbox to enable the integration.
   • Select the Force automatic login using this provider checkbox if you want to only allow login with Active Directory accounts. :fa-warning: Only do this if the integration with the provider has been successfully validated to prevent lockout.
   • In the Display Name field, type the text you want to show under this login option on the Login page.
   • Leave the Use Kerberos Auth checkbox selected.
5. Select Test and Save to save your changes.
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

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, refer to 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>"))
   

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, select 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. Select SYNC to apply your changes.

B.2. Active Directory Configuration

1. Log in to the host portal as a system administrator.
2. Make sure that Host is selected at the top of the left pane and then select Security.
3. Under Active Directory, select 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 AD account.
4. Select Test and Save to save the changes and return to the previous page.
5. Select 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. Select 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. Select 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 work, take the following steps:

1. Go to Tools > Internet Options > Security.

2. Select Local Intranet.

3. Select Sites.

4. Make sure that Automatically detect intranet network is selected or that all of the options are selected.

5. Select on Advanced.

6. Add the Automation Suite FQDN to the Local Intranet.

7. Select Close and OK.

8. Select 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 the UiPath platform is integrated with Windows Authentication, users for which a user account is created in UiPath can use the Windows option on the Login page to sign in to the UiPath platform.

Figure 1. Windows sign in option

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

1. Log in 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 previous 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 UiPath 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, perform the following checks:

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, the following is displayed:

      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/[e-mail] 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, the following is displayed:

   kinit: Client '[e-mail]' 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, the following is displayed:

   Request 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 encounter 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).
   

   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 , the KDC_ERR_S_PRINCIPAL_UNKNOWN error is shown in the Kerberos event logs. For details on this issue, refer to Microsoft documentation .

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

Debugging the Active Directory integration with Kerberos

Use the following flow to debug login and integration failures that are not covered by the checks above.

Check the Kerberos job pods in ArgoCD

1. In ArgoCD, go to the uipath application and verify that the applications are synced and healthy.
2. Make sure the services-preinstall-validations-job and kerberos-jobs-trigger pods are in a successful state. These two jobs run kinit to generate the TGT once Kerberos is configured, so if both are in a successful state, Kerberos is configured correctly. If either failed, check its logs for the cause.
3. Make sure the kerberos-tgt-update cron job pod runs successfully. This cron job is triggered regularly to get a fresh TGT before the existing one expires. If it failed, check its logs.

Inspect the identity service logs

If the identity-service-api pods are unhealthy, open the pod in ArgoCD, navigate to Logs, and select the identity-server container. Match the errors in the log to the following causes:

• The domain controller cannot be reached — This is a network-level issue. The cluster is trying to reach the domain specified in the configuration, and the DNS service that the cluster connects to does not have information about the domain. A related cause is DNS returning multiple unreachable domain controllers: connection attempts can time out within the retry limit before a healthy controller is reached. Work with your IT department so that the cluster uses an official domain registered in your network's DNS service and that DNS resolution only returns reachable domain controllers.
• LDAP error A local error occurred — This is a generic error from the LDAP libraries (displayed in the identity-service-api logs as Ldap connection failed due to error 82). The following root causes are known:
  • Switching between the Kerberos and LDAPS configurations — a known issue occurs when you switch the AD integration from a Kerberos configuration to LDAPS, or the other way around. To work around it:
    1. Open the cluster's SQL database.
    2. In the [identity].[DirectoryConnections] table, find the ldapad entry and set the IsDeleted value to True.
    3. In the [identity].[ExternalIdentityProviders] table, find the ldapad entry and set the IsActive value to True.
    4. Restart the identity-service-api pods.
    5. Configure the AD integration through the host security settings again.
  • LDAP canonicalization in older builds — upgrade to the latest available cumulative update (CU). Recent CUs contain changes that turn off LDAP canonicalization, which can cause this error when the openldap libraries are used.
  • Stale DNS SRV records for de-provisioned domain controllers — if domain controllers were removed without cleaning up DNS, the _kerberos._udp. SRV records may no longer match the _kerberos._tcp. records. In your DNS server, list the SRV records for your domain under _kerberos._udp. and _kerberos._tcp., make sure they match one-to-one, and remove the stale entries that point to de-provisioned domain controllers.

Debug browser-based authentication

If the pods are healthy but you still cannot authenticate in the browser:

1. Make sure the browser runs on a Windows machine domain-joined to the domain (or forest, or trusted forest) to which the account represented by the keytab belongs. Kerberos only works in such an environment. Note that on MSI installations, Windows authentication also works with NTLM; in Automation Suite, only Kerberos is supported.
2. If the cluster name resolves through a CNAME record in DNS and you use Chrome or Edge, disable the CNAME lookup when negotiating Kerberos authentication (see the "Does the browser use the expected SPN?" check above), restart the browser, and try again. If this fixes the issue, configure the DNS entry as an A record instead of a CNAME record, or apply the browser setting across your organization by using Group Policy.
3. If the error persists — for example, An unsupported mechanism was requested or a repeated authentication prompt — enable Kerberos event logging as described in the Microsoft documentation, retry the scenario, and inspect the System log in Event Viewer:
   • KDC_ERR_PREAUTH_REQUIRED errors are expected and can be ignored.
   • KDC_ERR_S_PRINCIPAL_UNKNOWN or KRB_AP_ERR_MODIFIED — the SPN for the service account is not set correctly. Set the SPN HOST/<cluster name> on the account represented by the keytab configured in the cluster.
   • KDC_ERR_ETYPE_NOTSUPP — encryption types are disabled in your organization. By default, Windows uses RC4-HMAC unless AES128 or AES256 is explicitly configured. To force AES256, in Active Directory Users and Computers, navigate to the user account that represents the keytab file used by the cluster, open the Account tab, select This account supports Kerberos AES 256 bit encryption, and select OK. Then reset the password of this account, regenerate the keytab, and update it in the cluster configuration. This generates the new password hashes required for AES256.

Enable verbose Kerberos logging

To get additional logging for the Kerberos integration, set the following environment variable in the identity-service-api pod env section:

- name: KRB5_TRACE
  value: /dev/stderr