Troubleshooting Kerberos Authentication in Automation Suite

News Knowledge Base
,
1

How to troubleshoot Kerberos authentication issues in Automation Suite?

Collect Diagnostic Logs

  1. To ensure all AD errors are captured, run: 
    1. kubectl -n uipath set env deploy/identity-service-api KRB5_TRACE=/dev/stderr
    1. In newer versions, this is already set (starting with 25.10+ and any version released after October 2025).
  2. For versions 23.10+ go into argocd and got to the IntegratedAuth application.
    1. Once in the application sync the application.
    2. If any jobs fail, check the logs and capture them. See How to Debug Issues Using Argocd for more information.
      1. The jobs involved are called:
        1. services-preinstall-validations-job
        2. kerberos-jobs-trigger
      2. Either failing is a problem that needs to be investigated.
    3. When the application is synced, it will regenerate the TGT tickets used for authentication. If the job fails, it means that the TGT tickets could not be generated and most likely the issue is with the keytab file (for example, the password for the service account could have changed and would necessitate regenerating the keytab file).
    4. If this fails, capture the failed job log and go to the section Validate Keytab File.
    5. If there are no failures, then it means the keytab file is valid. Continue on to the next step.
    6. If failures occurred syncing the app, capture the logs from argocd, and capture the outputs from the Validate Keytab File section and raise a ticket. There is no need to continue through the rest of this KB article.
  3. For versions before 23.10, the same step applies but instead we sync the UiPath app.
  4. On one of the Windows machines facing the issue, enable the event viewer Kerberos logs (This requires admin access and should be executed from an elevated prompt): 
    1. reg add HKLM\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters /v LogLevel /t REG_DWORD /d 1 /f
    2. For more details see: https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/enable-kerberos-event-logging
  5. Reproduce the issue. (From the machine where the event view logs were enabled, a user should try and log in using Windows AD.)
  6. After the issue is reproduced, capture the event viewer logs and the automation suite logs:
    1. How to get event viewer logs
      1. The logs will be under System
    2. How to generate a support bundle (Make sure to use the version-specific documentation)
  7. Check the SPN.
    1. On the Windows machine, open a command prompt.
    2. Run the following command: 
      1. setspn -Q HTTP/<Automation suite FQDN>
      2. The automation suite FQDN should be the FQDN that a user enters into the browser. If the URL for Automation Suite were https://autosuite.uipath.devtest, then the command would be:
      3. setspn -Q HTTP/autosuite.uipath.devtest
      4. Make sure to capture the output.
  8. Please provide the username used for Kerberos in the cluster config.
    1. On a linux terminal, the following command can be used to extract this: 
      1. cat cluster_config.json | jq '.kerberos_auth_config.default_ad_username'
    2. Alternatively, just inspect the cluster_config.json. The user name is in the kerberos_auth_config section under default_ad_username.
  9. Check the Common Errors section.
  10. If none of this helps, please raise a ticket with UiPath. Make sure to include:
    1. Windows Event Viewer logs (specifically the logs from system).
    2. Support bundle (specifically we need the identity service api logs after the issue has occurred).
    3. Output of the setspn commands.
    4. Any other findings during investigation. For example, if the Validate keytab section was executed, include the outputs. If the IntegratedAuth jobs failed, make sure to include those logs (support bundle may not capture those as they are not persistent)

Validate Keytab File

  1. The following should be done from a Linux terminal.
  2. Extract and Verify the Username in the Keytab
    1. The keytab is base64 encoded in the cluster_config.json.
    2. From Linux the following command can be used to get the keytab file 
      1. cat cluster_config.json | jq '.kerberos_auth_config.default_user_keytab' | base64 -d > keytab
    3. Alternatively, the file can be opened and the base64 encoded string can be extracted manually. Once the string is copied, make sure to decode it and output it into a file. (Its the default_user_keytab under kerberos_auth_config) 
      1. echo <base64 string> | base64 -d > keytab
      2. (Make sure to replace <base64 string> with the keytab string)
  3. Install the kerberos tools. 
    1. sudo yum install krb5-workstation
  4. Once the tools are installed, run through the following checks:
    1. Check which username the keytab file is for: 
      1. klist -kt /path/to/keytab/file
    2. The above command will show what the username the keytab is mapped to and some other details. Make sure to note them down. Example: 
      1. Slot KVNO Principal

        

        1    2    HTTP/aduser@DOMAIN.COM

    3. The username displayed should be the same username in the cluster_config.json. The user name is in the kerberos_auth_config section under default_ad_username. If the username from klist does not match the username in the keytab file, then either the keytab file name was generated incorrectly or the cluster_config.json is using the wrong username.
      1. The username can be extracted with the following command as well: 
        1. cat cluster_config.json | jq '.kerberos_auth_config.default_ad_username'
    4. If the username seems correct, then try and generate a ticket using the keytab file.
      1. export KRB5_TRACE=/dev/stderr
kinit -k -t /path/to/keytab/file <AD User>
    5. Make sure to capture the above output.
  5. If all the above looks as expected, then the integratedAuth app jobs should work without issue (If this is not the case, then please raise a ticket to UiPath). If any of the validations failed, capture the errors and what failed, and raise a ticket to UiPath if needed. Often, the above check will indicate where the issue is.

Common Errors

  1. Principal not found in Kerberos database:
    1. Have the AD admin run: Get-ADUser <AD User> -Properties msDS-KeyVersionNumber 
      1. Get-ADUser uipath -Properties msDS-KeyVersionNumber

        DistinguishedName     : CN=UiPath test,CN=Users,DC=UiPath,DC=devtest
        
Enabled               : True
        
GivenName             : UiPath
        
msDS-KeyVersionNumber : 5
        
Name                  : UiPath Test
        
ObjectClass           : user
        
ObjectGUID            : b5fd923f-8f81-40f1-a78a-32ccec95f04d
        
SamAccountName        : UiPath.Test
        
SID                   : S-1-5-21-61077822-455226763-1539332448-15102
        
Surname               : Test
        
UserPrincipalName     : HTTP/autosuite.uipath.devtest@uipath.devtest

      2. The UserPrincipalName should match the AD_Username used in the cluster_config.json.
      3. In the example above, this would be: HTTP/autosuite.uipath.devtest@uipath.devtest. However, this is probably not the principal name that was set at account creation time. In our example, this would have been: uipath.test@uipath.devtest.
      4. If the principal name got reverted, it would need to be set back to the HTTP SPN. This can be done by regenerating the keytab file or simply manually setting the SPN with setspn:
        1. setspn -A HTTP/<Automation Suite A-Record> <accountName>
  2. Unsupported key type found
    1. Make sure that AES encryption is enabled on the account. See: https://docs.uipath.com/automation-suite/automation-suite/2024.10/installation-guide/setting-up-kerberos-authentication
    2. If this is not enabled, the keytab must be regenerated.