Skip to main content

Create WinRM Connection Using Kerberos

Harness supports WinRM authentication using Kerberos, enabling you to connect to a target host via the Kerberos protocol. For a quick Kerberos summary, see Explain like I’m 5: Kerberos by Lynn Root.

In this topic:

Before You Begin

Limitations

There are some corner use cases which Harness does not support because of how Java and Python interact, and as a result of limitations in Windows:

  • The equals character (=) is not supported in the name of a Harness Service Config Variable or Environment Service Variable Override. See Add Service Config Variables and Override a Service Configuration in an Environment.
  • The underscore character (_) is not supported in the working directory for Service Commands and their shell scripts. See Create Default Application Directories and Variables and Use Script Based Services.
  • Harness has the same limitations as Windows environment variables. Harness treats all Service Config Variables and Environment Service Variable Overrides as Windows environment variables.
  • Non-UTF8 characters are not supported in Service Config Variables and Environment Service Variable Overrides. For example, äöü!ÖÜÄéÊêÈèç.
  • Harness has limited support for quotes in Service Config Variables and Environment Service Variable Overrides. A simple use such as foo'bar will work, but a complex combination of single quotes and other characters such as backslash () might not work.
  • Harness does support variable values ending in three or more slashes.
  • Secrets cannot contain special characters without escaping. For example, if the secret contains a $ like ab$c it will fail.
    Escape any special characters in your secrets: ab\$c.

Step 1: Add SPN to the Active Directory Server

Make sure you add the Service Principal Name to the Active Directory as follows using the setspn command:

WSMAN/<Fully Qualified Domain Name>@<REALM>  
HTTP/<Fully Qualified Domain Name>@<REALM>
HTTP/<Fully Qualified Domain Name>
WSMAN/<Fully Qualified Domain Name> 

For more information about setting the SPN using the setspn command, see Microsoft’s Setspn documentation.

For example, if the fully qualified domain name is 221.213.188.35.bc.googleusercontent.com and the Realm name is KERBEROS.LOCAL then add the following:

WSMAN/251.200.188.35.bc.googleusercontent.com@KERBEROS.LOCAL  
HTTP/251.200.188.35.bc.googleusercontent.com@KERBEROS.LOCAL    HTTP/251.200.188.35.bc.googleusercontent.com
WSMAN/251.200.188.35.bc.googleusercontent.com

Step 2: Access WinRM Configuration

In Secrets Management, under Execution Credentials, click WinRM Connection.

Click Add WinRM Connection.

The WinRM Connection Attributes dialog appears.

Step 3: Display Name

Name to identify the connection. You will use this name to identify this connection when setting up the Connection Attributes in the environment Service Infrastructure.

Step 4: Auth Scheme

Select Kerberos.

Step 5: Username

Username is a string that names a specific entity to which a set of credentials may be assigned. Enter the account name associated with the Kerberos account, such as johndoe.

Step 6: Domain

Domain is the logical network served by a single Kerberos database and a set of Key Distribution Centers (KDCs). This is where the service (that the user is trying to authenticate with) is located.

For example: US-EAST-2.COMPUTE.INTERNAL.

The target hosts that your WinRM connection is intending to authenticate with via Kerberos are located in a domain name with the same name you enter in Domain.

For example, ip-172-31-44-168.us-east-2.compute.internal. The domain naming convention is all uppercase letters to differentiate the domain from the internet domain, but the Domain field does not enforce the convention.

Step 7: TGT Generation

You can choose this option to generate a new TGT from the KDC every time you authenticate with the service. This ensures that the TGT is always valid and not expired when you try to authenticate.

Select one of the following options:

  • Key Tab File Path (on Delegate) - Enter the path to the KeyTab present in the Delegate for TGT generation.
  • Password - Enter a password for TGT generation.

Step 8: Keytab File Path

This field is displayed if you select Key Tab File Path for TGT Generation. Enter the file path to the keytab file on the server running the Harness Delegate. For example, /home/johndoe/a.keytab. The file is not uploaded to Harness.

To use the Kerberos WinRM connection to connect to a target host, you select it in WinRM Connection Attributes while specifying the target host in the Service Infrastructure/ Infrastructure Definition settings of an environment.

In this example, the target host that you want to use Kerberos authentication with is entered in Host Name(s).

Note that the domain name used to identify the hosts in the Host Name(s) field is likely to be the same as the domain name you entered in Domain when configuring the WinRM connection.

The Host Name cannot be an IP address and it should be a domain name. The connection will not succeed if it is an IP address.

Step 9: Advanced Options

See the Advanced Options settings in Add WinRM Connection Credentials.

Step 10: Test the Connection

Click Test to ensure that the connection is successful. Once the connection is successful, click Submit.

Step 11: Delegate dependencies

In order to perform Windows deployments using Kerberos authentication, Harness requires harness-pywinrm binary to be present in client tools (client-tools/harness-pywinrm/v0.4-dev/harness-pywinrm). Otherwise, the deployments will fail to perform the capability check using the Kerberos authentication mechanism.