Automation Suite on Linux installation guide

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​

• 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.

Option 2: Manually​

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:

   assignment

   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
   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:

   assignment

   ktpass -princ HTTP/uipath-34i5ui35f.westeurope.cloudapp.azure.com@TESTDOMAIN.LOCAL -pass pwd123 -mapuser TESTDOMAIN\aduser -pType KRB5_NT_PRINCIPAL -out c:\krb5.keytab -crypto AES256-SHA1 -setpass
   ktpass -princ HTTP/uipath-34i5ui35f.westeurope.cloudapp.azure.com@TESTDOMAIN.LOCAL -pass pwd123 -mapuser TESTDOMAIN\aduser -pType KRB5_NT_PRINCIPAL -out c:\krb5.keytab -crypto AES256-SHA1 -setpass
   

   Note:

   To update the keytab for Automation Suite, run the command with the -setpass option. The first time you generate the keytab, you must run the command as a domain administrator. This is required because the command updates the service account's SPN. For later updates, you can run the command as the domain user if the SPN mapping hasn't changed.

   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 cluster_config.json as follows:

   assignment

   "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="
         "enable_integrated_sql_auth": true
   },
   "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="
         "enable_integrated_sql_auth": true
   },
   

   Note:

   The enable_integrated_sql_auth parameter is set to true by default. If you want to disable Kerberos authentication for SQL for all products, you must set the parameter to false.

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

   assignment

   [Convert]::ToBase64String([System.IO.File]::ReadAllBytes("<path to the generated keytab file>"))
   [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​

• 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.

• db_datareader

• db_datawriter

• db_ddladmin

• EXECUTE permission on dbo schema

  

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

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.

Option 2: 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>"))
# 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>"))

Configuring Automation Suite as a Kerberos client​

• Configuring Kerberos authentication via the interactive installer
• Configuring Kerberos authentication via cluster_config.json
  Note:

  Currently, we allow independent configuration of only user authentication by setting kerberos_auth_config.enabled to true and kerberos_auth_config.enable_integrated_sql_auth to false. Independent SQL authentication is still not supported.

Configuring Kerberos authentication via cluster_config.json​

1. In the cluster_config.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.

   Note:

   Kerberos authentication is not exclusively supported for SQL. For activating Kerberos with SQL authentication, you must enable kerberos_auth_config. This also adds user authentication.

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.

   3. The enabled parameter is set to true by default when Kerberos authentication is enabled at global level. If you want to disable Kerberos authentication for SQL for a specific product, you must set enabled to false.

      The JSON object should be as follows:

      assignment

      "<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",
            "enabled": true
          }
      }
      "<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",
            "enabled": true
          }
      }
      

      Note:

      For the list of service group names, see Service groups and services.

4. After updating the cluster_config.json, run the installer script to update the configuration. For details, see Managing products.

   Note:

   You can use this procedure to update or rotate the Kerberos keytab.

  "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",
    "enable_integrated_sql_auth": true
  },
  "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",
      "enabled": true
    },
    "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",
      "enabled": true
    }
  }
  "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",
    "enable_integrated_sql_auth": true
  },
  "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",
      "enabled": true
    },
    "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",
      "enabled": true
    }
  }

Configuring the Active Directory integration​

Disabling Kerberos authentication​

Removing Kerberos authentication completely​

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​

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.

Kerberos troubleshooting​