Setting up Kerberos authentication

Prerequisites

To successfully set up Kerberos authentication, you must meet the following prerequisites:

• Ensuring the Automation Suite cluster can access your AD
• Configuring the AD service account for Kerberos authentication
• Optional: SQL authentication prerequisites

Ensuring the Automation Suite cluster can access your AD

Before you can configure Kerberos authentication, work with your IT administrators to ensure the Automation Suite cluster can access your AD.

The following requirements must be met:

• Automation Suite cluster must be on the same network as the AD domain;

• DNS must be set up correctly on the network so that the Automation Suite cluster can resolve the AD domain names.

  Note: It is critical that the Automation Suite cluster can resolve the AD domain names. You can verify this by running nslookup <AD domain name> on the host machine.

Configuring the AD service account for Kerberos authentication

Generating Kerberos default keytab and username parameters

Option 1: by Running the script (recommended)

1. Log in with your AD administrator account on a Windows domain-joined machine.
2. Run the keytab-creator.ps1 script as administrator.
3. Input the following values to the script:
   1. Service Fabric FQDN. For example, uipath-34i5ui35f.westeurope.cloudapp.azure.com.
   2. AD domain FQDN. For example, TESTDOMAIN.LOCAL.
   3. An AD user account. You can use an existing account, such as sAMAccountName, or you can allow the script to create a new one.

The output file contains the <KERB_DEFAULT_USERNAME> and <KERB_DEFAULT_KEYTAB> parameters required by the Kerberos setup.

Option 2: Manually

Reach out to your AD administrator for an AD user account, and retrieve the <KERB_DEFAULT_USERNAME> and <KERB_DEFAULT_KEYTAB> for that account as follows:

1. In your AD Server, create a new user account. If you already have one, skip to step 2.
   1. In the Active Directory Users and Computers console, right-click the Users folder, select New, and then select User.
   2. Finish creating the user account.
2. Right-click the user account and select Properties.
3. Go to the Account tab, then under Account options, select This account supports Kerberos AES 256 bit encryption.
4. Important: The keytab generated in the next steps will become invalid if the AD user's password is expired or updated. Consider checking Password never expires under Account options for this AD user account. Alternatively, you can update the password when it is about to expire and generate a new keytab.
5. To generate a keytab file for the SPN, open PowerShell with admin access and execute the following command:

   ktpass -princ HTTP/<Service Fabric FQDN>@<AD FQDN in cap> -pass <AD user's password> -mapuser <AD NetBIOS name in cap>\<AD user name> -pType KRB5_NT_PRINCIPAL -out <output file path> -crypto AES256-SHA1

   Some fields must be specified in uppercase. For example:

   ktpass -princ HTTP/[e-mail] -pass pwd123 -mapuser TESTDOMAIN\aduser -pType KRB5_NT_PRINCIPAL -out c:\krb5.keytab -crypto AES256-SHA1

   After the keytab generation, the user logon name changes to HTTP/<Service Fabric FQDN>. Use this value for the <KERB_DEFAULT_USERNAME> field in the default_ad_username in input.json as follows:

   "kerberos_auth_config": {
         "enabled": true,
         "ticket_lifetime_in_hour": 8,
         "ad_domain": "AUTOSUITEAD.LOCAL",
         "default_ad_username": "HTTP/sfqakxxxx-ea.infra.uipath-dev.com",
         "default_user_keytab": "BQIAAAB9AAIxxxxxxxxxxxxxxxxxxGRCqh+yQ="
       },

6. Encode the generated keytab file in Base64, open PowerShell, and execute the following command:

   [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("<path to the generated keytab file>"))

7. Save the encoded keytab file. You will use it when configuring the UiPath® cluster for Kerberos. Let's call the value from step 6 <KERB_DEFAULT_KEYTAB>.

Optional: SQL authentication prerequisites

To configure the UiPath® cluster to connect to SQL using Windows integrated authentication/Kerberos, you need to perform a few additional steps:

• the SQL server must join the AD domain;
• the Automation Suite cluster must be on the same network as the SQL Server;
• the Automation Suite cluster can resolve the AD and SQL servers` domain names;
• the AD user must have access to SQL server and DB permissions.

To create a new login in SQL Server Management Studio, take the following steps:

a. In the Object Explorer panel, navigate to Security > Logins.

b. Right-click the Logins folder and select New Login. The Login - New window is displayed.

c. Select the Windows Authentication option. The window is updated accordingly.

d. In the Login name field, type the user domain you want to use as a service account.

e. From the Default Language list, select English.

Important: Ensure that the Default Language is set to English. If it isn't, the website cannot start, and the Event Viewer on the computer on which Orchestrator is installed displays the following error message: “The conversion of a varchar data type to a datetime data type resulted in an out of range value”.

f. Select OK. Your configurations are saved.

If the service account has already been created and added to the Security > Logins section of the SQL Server, please check whether the Default Language of that SQL account is set to English. If it isn't, please make the necessary adjustments.

You need to provide the user connecting to the SQL database with the db_owner user mapping role, as in the following screenshot.

If security restrictions do not allow you to use the db_owner user mapping role with the UiPath® login, grant the following permissions:

• db_datareader
• db_datawriter
• db_ddladmin
• EXECUTE permission on dbo schema
  
  

  

  
  

The EXECUTE permission has to be granted by using the GRANT EXECUTE SQL command, as follows:

USE UiPath
GO
GRANT EXECUTE ON SCHEMA::dbo TO [domain\)\)user]
GO

If you want UiPath® applications to use unique AD user accounts to connect to SQL using Integrated Security=True, you need to create a unique keytab for each UiPath® application, as follows. This will be referred to as <KERB_APP_KEYTAB> for that application.

Generating Kerberos application keytab and username parameters

Option 1: by Running the script (recommended)

1. Run the service-keytab-creator.ps1 script.
2. Input the following values to the script:
   1. AD domain FQDN. For example, TESTDOMAIN.LOCAL.
   2. The username and password of an AD user account. For example, the AD user account sAMAccountName and its password.

The output file contains the <KERB_APP_USERNAME> and <KERB_APP_KEYTAB> parameters required by Kerberos.

Option 2: Manually

Run the following script manually:

# Generate keytab file and output it in the desired path 
ktpass /princ <AD username>@<AD domain in cap> /pass <AD user password> /ptype KRB5_NT_PRINCIPAL /crypto AES256-SHA1 /out <path to keytab file> -setpass 

# Converts AD user's keytab file to base 64 
[Convert]::ToBase64String([System.IO.File]::ReadAllBytes("<path to the generated keytab file>"))

The value <AD username> will be the <KERB_APP_USERNAME> corresponding to the <KERB_APP_KEYTAB>.

Configuring Automation Suite as a Kerberos client

This section explains how you can configure Automation Suite as a Kerberos client for LDAP or SQL access.

With <KERB_DEFAULT_KEYTAB>, configure Automation Suite as a Kerberos client by following the instructions in Configuring Kerberos authentication via input.json.

Note: If you want to set up different services to run under their own AD account, and access SQL as that AD account, you can specify ad_username with that <KERB_APP_USERNAME>, and user_keytab as <KERB_APP_KEYTAB> under the configuration section of the service.

Configuring Kerberos authentication via input.json

1. In the input.json file, set the kerberos_auth_config.enabled parameter to true.
2. If you want to use Kerberos for SQL access, configure the sql_connection_string_template, sql_connection_string_template_jdbc, and sql_connection_string_template_odbc with the Integrated Security flag.
3. If you want to set up a different AD user per service, take the following steps:
   1. Specify the ad_username and user_keytab in the JSON object of the service group.
   2. Update the SQL connection string for the service to enable integrated security.

      The JSON object should be as follows:

      "<serviceGroupName>": {
          "kerberos_auth_config": {
            "ad_username": "PLACEHOLDER - INSERT KERB_APP_USERNAME for this service group",
            "user_keytab": "PLACEHOLDER - INSERT KERB_APP_KEYTAB for this service group"
          }
      }

      Note: For the list of service group names, see Service groups and services.
4. After updating the input.json file, run the installer script to update the configuration. For details, see Managing products.

Sample of updating Orchestrator and the platform to use Kerberos authentication

"kerberos_auth_config": {
    "enabled" : true, 
    "ticket_lifetime_in_hour" : 8, 
    "ad_domain": "PLACEHOLDER - INSERT ACTIVE DIRECTORY DOMAIN ",
    "default_ad_username": "PLACEHOLDER - INSERT KERB_DEFAULT_USERNAME",
    "default_user_keytab": "PLACEHOLDER - INSERT KERB_DEFAULT_KEYTAB"
  },
"sql_connection_string_template": "PLACEHOLDER",
"sql_connection_string_template_jdbc": "PLACEHOLDER",
"sql_connection_string_template_odbc": "PLACEHOLDER",
"orchestrator": {
    "sql_connection_str": "Server=tcp:sfdev1804627-c83f074b-sql.database.windows.net,1433;Initial Catalog=AutomationSuite_Orchestrator;Persist Security Info=False;Integrated Security=true;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Max Pool Size=100;",
    "kerberos_auth_config": {
      "ad_username": "PLACEHOLDER - INSERT KERB_APP_USERNAME for Orchestrator",
      "user_keytab": "PLACEHOLDER - INSERT KERB_APP_KEYTAB for Orchestrator"
    }
    "testautomation": {
      "enabled": true
    },
    "updateserver": {
      "enabled": true
    }
},
"platform": {
    "sql_connection_str": "Server=tcp:sfdev1804627-c83f074b-sql.database.windows.net,1433;Initial Catalog=AutomationSuite_Platform;Persist Security Info=False;Integrated Security=true;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Max Pool Size=100;",
    "kerberos_auth_config": {
      "ad_username": "PLACEHOLDER - INSERT KERB_APP_USERNAME for platform",
      "user_keytab": "PLACEHOLDER - INSERT KERB_APP_KEYTAB for platform"
    }
}

Service groups and services

The following table lists the available service groups and the services that they include, The names are slightly different in the input.json file, or in the ArgoCD UI.

Service group name for input.json	Service group name for ArgoCD	Included services
orchestrator	orchestrator	Orchestrator, Webhooks
platform	platform	Identity, License Accountant (LA), Audit, Location, License Resource Manager (LRM), Organization Management Service (OMS)
discovery_group	discoverygroup	Automation Hub, Task Mining
test_manager	testmanager	Test Manager
automation_ops	automationops	Automation Ops
aicenter	aicenter	AI Center
documentunderstanding	documentunderstanding	Document Understanding
insights	insights	Insights
dataservice	dataservice	Data Service
asrobots	asrobots	Automation Suite Robots
processmining	processmining	Process Mining

Configuring the Active Directory integration

For Kerberos authentication to be used when logging in to Automation Suite, you must further configure Automation Suite host settings.

Disabling Kerberos authentication

Removing Kerberos authentication completely

To remove Kerberos authentication completely, take the following steps:

1. If you used Kerberos to configure AD integration, reconfigure AD with the username and password option by following the instructions in Configuring the Active Directory integration.
2. If you used SQL integrated authentication, configure the SQL connection strings to use User Id and Password.
3. Disable Kerberos authentication. In the cluster_config.json file, set the kerberos_auth_config.enabled parameter to false, then run the installer script to update the configuration. For details, see Managing products.

Removing SQL integrated authentication

To remove SQL integrated authentication, take the following steps:

1. Configure the SQL connection strings to use User Id and Password.
2. If want to disable SQL integrated authentication for all the services, in the cluster_config.json file, set the kerberos_auth_config.enabled parameter to false and then run the installer script to update the configuration. For details, see Managing products.