Kerberos proxy authentication

Configure Harness Delegate to authenticate to a Kerberos-enabled proxy using SPNEGO/Negotiate authentication.

If your outbound HTTP proxy requires Kerberos/SPNEGO (Negotiate) authentication instead of Basic authentication, the delegate can authenticate to it using a Kerberos keytab you provide. No PROXY_USER or PROXY_PASSWORD is needed.

For standard proxy configuration with Basic authentication, go to Proxy configuration guide.

What you will learn from this topic

This topic covers the following:

• Understand the scope of Kerberos proxy authentication in this release

• How to configure environment variables for Kerberos authentication

• How to author a JAAS login configuration file

• How to configure Kerberos settings in krb5.conf

• How to deploy a delegate with Kerberos proxy authentication using a complete Kubernetes manifest

• How to rotate keytabs without restarting the delegate

• How to troubleshoot common authentication failures

Before you begin

Before you configure Kerberos proxy authentication, ensure you have the following:

• Kubernetes cluster: You need kubectl access to deploy and configure the delegate. For more information, go to Delegate installation options.

• Delegate installed: A Harness Delegate must be installed in your Kubernetes cluster. For more information, go to Delegate overview and Delegate system requirements.

• Kerberos keytab: Obtain a keytab file for the delegate principal from your Kerberos administrator.

• Kerberos configuration: Your organization's krb5.conf configuration file with realm and KDC (Key Distribution Center) details.

• Network access: The delegate pod must be able to reach your KDC over the network.

• Proxy configuration: A proxy server configured to accept Kerberos/Negotiate authentication (not just Basic auth). For Basic authentication proxy setup, go to Proxy configuration guide.

Scope

Kerberos proxy authentication in this release covers delegate-to-Harness Manager traffic only:

• REST API calls (heartbeat, task polling, task acknowledgement)

• WebSocket tunnel connections

Everything else continues to use Basic authentication (PROXY_USER/PROXY_PASSWORD), for example:

• Shell script tasks that run locally on the delegate or over SSH/WinRM

• Outbound calls to third-party systems (Terraform Cloud, Jira, Jenkins, HTTP pipeline steps)

Third-party integration limitation

If your corporate proxy requires Kerberos authentication for all outbound traffic, calls to third-party systems will fail with HTTP 407 until Kerberos support is extended to those integrations in a future release.

Set up Kerberos proxy authentication

Setting up Kerberos proxy authentication requires no UI configuration, no API toggle, and no additional volumes rendered by Harness. You configure everything directly in the delegate manifest yourself.

Perform the following steps to set up Kerberos proxy authentication:

1. Set the standard proxy environment variables in your delegate manifest (these are the same as for Basic auth): PROXY_HOST, PROXY_PORT, and PROXY_SCHEME.

2. Set PROXY_AUTH_TYPE=KERBEROS on the delegate container to enable Kerberos authentication.

3. Provide your own krb5.conf file and point KRB5_CONFIG to its path.

4. Author a JAAS login config file (defining a HarnessKrb5 entry) and point KRB5_JAAS_CONFIG to its path.

5. Ensure the delegate pod can reach your KDC, and that your proxy is configured to accept Kerberos/Negotiate authentication (not just Basic).

The following sections provide detailed configuration instructions for each component.

Environment variables

Configure the following environment variables in your delegate manifest:

Variable	Required	Description
PROXY_HOST	Yes	Proxy hostname or IP address. Go to Select PROXY_HOST value for Kerberos-specific guidance.
PROXY_PORT	Yes	Proxy port number (for example, 3128).
PROXY_SCHEME	Yes	Proxy scheme (http or https).
PROXY_AUTH_TYPE	Yes	Set to KERBEROS to enable Kerberos authentication.
PROXY_MANAGER	Yes	Set to true to route Manager traffic through the proxy.
KRB5_CONFIG	Yes	Path to your krb5.conf file (for example, /etc/harness/kerberos/krb5.conf).
KRB5_JAAS_CONFIG	Yes	Path to your JAAS login config file (for example, /etc/harness/kerberos/jaas/jaas.conf).
NO_PROXY	No	Comma-separated list of hosts or domains to bypass the proxy.

Boot failure on missing configuration

The delegate fails to start if PROXY_AUTH_TYPE=KERBEROS is set but KRB5_CONFIG or KRB5_JAAS_CONFIG is unset or points to an unreadable file. For more information on delegate environment variables, go to Delegate environment variables.

JAAS login configuration

Create a JAAS login config file that defines a HarnessKrb5 entry. This file specifies the keytab location and principal to use for authentication.

The entry must be named HarnessKrb5 exactly:

HarnessKrb5 {
  com.sun.security.auth.module.Krb5LoginModule required
  useKeyTab=true
  keyTab="/etc/harness/kerberos/keytab/proxy.keytab"
  principal="[e-mail]"
  storeKey=true
  refreshKrb5Config=true
  doNotPrompt=true;
};

Replace the following values with your actual configuration:

• keyTab: Path where your keytab is mounted in the container.

• principal: Your delegate's Kerberos principal (must match an entry in the keytab).

Kerberos configuration

Your krb5.conf file defines the Kerberos realm, KDC location, and domain mappings. Here is a recommended configuration:

[libdefaults]
  default_realm = EXAMPLE.COM
  dns_lookup_realm = false
  dns_lookup_kdc = false
  dns_canonicalize_hostname = false
  rdns = false
  forwardable = true

[realms]
  EXAMPLE.COM = {
    kdc = kdc.example.com
    admin_server = kdc.example.com
  }

[domain_realm]
  .example.com = EXAMPLE.COM
  example.com = EXAMPLE.COM

The following are key settings to understand:

• dns_canonicalize_hostname = false and rdns = false prevent hostname rewriting before deriving the service principal.

• dns_lookup_realm = false and dns_lookup_kdc = false disable DNS-based KDC discovery.

• Do not set default_keytab_name. The keytab path is specified in your JAAS config.

Select PROXY_HOST value

The Service Principal Name (SPN) sent to the KDC is HTTP/<X>@<realm>, where <X> depends on your PROXY_HOST value and krb5.conf DNS settings.

The following table shows how different PROXY_HOST values and DNS settings affect the SPN hostname:

PROXY_HOST	rdns	dns_canonicalize_hostname	SPN hostname
proxy.example.com	false	false	proxy.example.com (verbatim)
proxy.example.com	false	true	Forward DNS canonical name
proxy.example.com	true	any	PTR record of resolved IP
10.2.204.25	false	any	10.2.204.25 (rarely registered at KDC)
10.2.204.25	true	any	PTR record of that IP

Recommendation: Use the proxy hostname in PROXY_HOST and set rdns = false and dns_canonicalize_hostname = false in your krb5.conf. This ensures the SPN matches what your KDC administrator registered.

Example manifest

The following is a complete Kubernetes manifest example that demonstrates how to configure a delegate with Kerberos proxy authentication.

This example uses the standard Harness Delegate image. If you need to customize the delegate image with additional tools or configurations, go to Build custom delegate images using Dockerfile.

apiVersion: v1
kind: Namespace
metadata:
  name: harness-delegate-ng

---

apiVersion: v1
kind: ConfigMap
metadata:
  name: kerberos-config
  namespace: harness-delegate-ng
data:
  krb5.conf: |
    [libdefaults]
    default_realm = EXAMPLE.COM
    dns_lookup_realm = false
    dns_lookup_kdc = false
    rdns = false
    dns_canonicalize_hostname = false
    forwardable = true

    [realms]
        EXAMPLE.COM = {
            kdc = kdc.example.com
            admin_server = kdc.example.com
        }

    [domain_realm]
        .example.com = EXAMPLE.COM
        example.com = EXAMPLE.COM

---

apiVersion: v1
kind: ConfigMap
metadata:
  name: kerberos-jaas-config
  namespace: harness-delegate-ng
data:
  jaas.conf: |
    HarnessKrb5 {
      com.sun.security.auth.module.Krb5LoginModule required
      useKeyTab=true
      keyTab="/etc/harness/kerberos/keytab/proxy.keytab"
      principal="[e-mail]"
      storeKey=true
      refreshKrb5Config=true
      doNotPrompt=true;
    };

---

apiVersion: apps/v1
kind: Deployment
metadata:
  name: harness-delegate
  namespace: harness-delegate-ng
spec:
  replicas: 1
  selector:
    matchLabels:
      harness.io/name: harness-delegate
  template:
    metadata:
      labels:
        harness.io/name: harness-delegate
    spec:
      securityContext:
        fsGroup: 100
        fsGroupChangePolicy: OnRootMismatch
      containers:
      - name: delegate
        image: harness/delegate:latest
        securityContext:
          allowPrivilegeEscalation: false
          runAsUser: 0
        env:
        - name: ACCOUNT_ID
          value: "YOUR_ACCOUNT_ID"
        - name: DELEGATE_TOKEN
          valueFrom:
            secretKeyRef:
              name: delegate-token
              key: token
        - name: MANAGER_HOST_AND_PORT
          value: https://app.harness.io
        - name: PROXY_HOST
          value: "proxy.example.com"
        - name: PROXY_PORT
          value: "3128"
        - name: PROXY_SCHEME
          value: "http"
        - name: PROXY_MANAGER
          value: "true"
        - name: PROXY_AUTH_TYPE
          value: "KERBEROS"
        - name: KRB5_CONFIG
          value: "/etc/harness/kerberos/krb5.conf"
        - name: KRB5_JAAS_CONFIG
          value: "/etc/harness/kerberos/jaas/jaas.conf"
        volumeMounts:
        - name: kerberos-config
          mountPath: /etc/harness/kerberos/krb5.conf
          subPath: krb5.conf
          readOnly: true
        - name: kerberos-jaas
          mountPath: /etc/harness/kerberos/jaas/jaas.conf
          subPath: jaas.conf
          readOnly: true
        - name: kerberos-keytab
          mountPath: /etc/harness/kerberos/keytab
          readOnly: true

      # Keytab sidecar - fetches keytab from KDC and writes to shared volume
      - name: keytab-sidecar
        image: your-keytab-sidecar-image:latest
        volumeMounts:
        - name: kerberos-keytab
          mountPath: /shared
        securityContext:
          runAsNonRoot: true
          runAsUser: 10001
          runAsGroup: 10001
        resources:
          requests:
            memory: "32Mi"
            cpu: "10m"
          limits:
            memory: "64Mi"
            cpu: "50m"

      volumes:
      - name: kerberos-config
        configMap:
          name: kerberos-config
      - name: kerberos-jaas
        configMap:
          name: kerberos-jaas-config
      - name: kerberos-keytab
        emptyDir:
          medium: Memory

Keytab sidecar container

This example includes a keytab-sidecar container that automatically fetches the keytab from the KDC and writes it to the shared emptyDir volume. The delegate container reads the keytab from this shared volume.

The sidecar runs continuously and can refresh the keytab, enabling rotation without restarting the delegate. For more information on keytab rotation, go to Use a sidecar for rotation.

Important: Mount the keytab volume as a directory (no subPath), not as a file. If you use subPath and the keytab does not exist when the pod starts, Kubernetes creates an empty directory that permanently masks the file.

Rotate keytabs

If you rotate keytabs periodically (for example, using a sidecar container), the delegate picks up the new keytab automatically on the next proxy challenge. No restart is required.

Use a sidecar for rotation

You can share the keytab between containers using an emptyDir volume. The following example shows how to configure a keytab rotation sidecar:

spec:
  containers:
  - name: delegate
    volumeMounts:
    - name: kerberos-keytab
      mountPath: /etc/harness/kerberos/keytab
      readOnly: true
  
  - name: keytab-sidecar
    image: your-keytab-rotation-image:latest
    volumeMounts:
    - name: kerberos-keytab
      mountPath: /etc/harness/kerberos/keytab
      readOnly: false
  
  volumes:
  - name: kerberos-keytab
    emptyDir:
      medium: Memory

In this configuration:

• The sidecar writes the keytab to the shared volume.

• The delegate reads the keytab from the shared volume.

• If the keytab is not yet present when the delegate starts, authentication attempts fail and log a warning, but subsequent attempts succeed once the sidecar has written the keytab.

Troubleshooting

Delegate fails to start with PROXY_AUTH_TYPE=KERBEROS requires KRB5_CONFIG

Verify that both KRB5_CONFIG and KRB5_JAAS_CONFIG environment variables are set and point to readable files. The delegate boot process fails fast if either variable is unset or points to an unreadable file.

Authentication fails with HTTP 407 responses

This can occur due to several configuration or connectivity issues:

• Keytab not readable at the path specified in your JAAS config.

• Principal in JAAS config does not match any entry in the keytab.

• Delegate pod cannot reach the KDC.

• Proxy is not configured for Negotiate/SPNEGO authentication.

• DNS or hostname mismatch breaks the HTTP/<proxy-host> service ticket.

Perform the following steps to diagnose and resolve the issue:

1. Verify keytab is mounted and readable.

2. Confirm principal matches keytab entries exactly.

3. Test KDC connectivity from the pod.

4. Confirm proxy advertises Negotiate in 407 responses.

5. Set dns_canonicalize_hostname=false and rdns=false in krb5.conf.

Authentication works briefly then fails before recovering

A proxy challenge triggered re-authentication while the KDC was briefly unreachable or the keytab was mid-rotation. Check delegate logs for Kerberos: JAAS login failed for entry HarnessKrb5. If the issue self-recovers, no action is needed.

Need to enable detailed Kerberos debugging

Enable detailed Kerberos debugging by adding the following to your delegate's JAVA_OPTS:

env:
- name: JAVA_OPTS
  value: "-Xms64M -Dsun.security.krb5.debug=true"

Look for the following log messages to confirm successful authentication:

• Kerberos: cached Subject initialized via JAAS entry HarnessKrb5

• Kerberos: refreshed cached Subject via JAAS entry HarnessKrb5

Want to test keytab and proxy connectivity independently

Run the following commands from a pod that has access to the same keytab and network configuration:

# Test keytab with kinit
kinit -kt /path/to/proxy.keytab [e-mail]

# Test proxy with curl
curl -x http://proxy.example.com:3128 \
     --proxy-negotiate -U : \
     https://app.harness.io

These commands help isolate configuration issues by testing keytab and proxy authentication separately from the delegate.

Additional considerations

In-cluster Kubernetes delegate

If the delegate runs in-cluster and needs to access Kubernetes APIs, add the cluster master IP to NO_PROXY to bypass the proxy for in-cluster connections.

The following example shows how to configure NO_PROXY:

env:
- name: NO_PROXY
  value: "kubernetes.default.svc,10.0.0.1"

mTLS support

Harness supports mTLS authentication on a case-by-case basis. Contact Harness Support to enable it.

Next steps

Continue with the following related topics:

• Go to Proxy configuration guide to learn how to configure proxy settings with Basic authentication.

• Go to Delegate overview to understand delegate architecture, lifecycle, and operational capabilities.