22. Kerberos Authentication for Windows Jobs

Koios Automation Platform can run playbooks against domain-joined Windows hosts using Kerberos over WinRM. The Ansible connection plugin runs inside the job’s execution environment (EE), where it needs the Kerberos client, Python dependencies, domain configuration and network access to the domain services and Windows targets.

This page describes authentication to managed Windows hosts. Configuring a Machine credential for a job does not configure Active Directory authentication for users signing in to the platform.

22.1. Prepare the execution environment

The default Koios EE recipe includes krb5-workstation (which supplies kinit), pykerberos, pywinrm[kerberos,credssp], pexpect and the ansible.windows collection. These dependencies do not supply your organization’s realm configuration, credentials or Windows WinRM configuration. Check the image selected for the job: a custom or minimal EE can have different contents.

For an EE that lacks Kerberos support, build a custom image with:

  • The Kerberos client utilities and libraries, including an MIT Kerberos-compatible kinit on the container’s executable search path. On RPM-based images, the runtime package is krb5-workstation; compiling Python Kerberos bindings can also require krb5-devel and compiler dependencies during the build.

  • pywinrm with its kerberos extra, the corresponding Python Kerberos bindings and pexpect installed for the Python interpreter used by Ansible.

  • The ansible.windows collection for Windows modules.

  • The required realm configuration and CA trust for the Windows HTTPS endpoint, either in the image or supplied to the job container at runtime.

Install dependencies while building the EE, rather than in a running controller pod or on a Kubernetes node. Make configuration files readable by the non-root user of the job container and provide a writable temporary directory for ticket acquisition. See Execution Environments for registering the image and selecting it in the job template’s Execution environment field.

22.2. Configure the domain inside the job container

Work with the directory and cluster administrators to ensure that:

  • The Windows target has a WinRM listener and permits the domain account to connect and run the required commands.

  • The job pod can resolve the target’s fully qualified domain name (FQDN), discover or resolve the domain’s Kerberos Key Distribution Center (KDC), and reach the required KDC and WinRM ports. Account for namespace network policies and cluster DNS forwarding.

  • The target name matches its Kerberos service principal name (SPN). Use an FQDN, such as win01.example.com, instead of an IP address for the WinRM connection address.

  • The cluster nodes, KDC and Windows target have synchronized clocks, and the realm name and account principal use the case expected by the domain.

  • For HTTPS, the EE trusts the certificate authority that issued the listener certificate, and the certificate matches the target name.

Provide /etc/krb5.conf inside the EE. For example, the following configuration explicitly selects a KDC instead of relying on DNS SRV discovery. Replace the realm, domain and KDC with values provided by your directory administrator:

[libdefaults]
 default_realm = EXAMPLE.COM
 dns_lookup_kdc = false

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

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

You can include this non-secret configuration in a custom EE image. For container groups, you can instead mount it from a ConfigMap into each job pod, as described below. Editing a file in a running controller pod does not configure independent job pods and does not survive operator reconciliation or pod replacement.

22.2.1. Mount configuration in a container group

Have the cluster administrator provision a ConfigMap named winrm-kerberos-config with a krb5.conf data key containing the configuration above, in the namespace where the container group creates job pods. Keep passwords, keytabs and ticket caches out of this ConfigMap.

Open Automation Execution > Infrastructure > Instance Groups and configure the container group using Customize pod spec and Pod spec override. Add the following volume and mount to the existing pod specification, preserving the other settings and keeping the worker container first:

spec:
  containers:
    - name: worker
      volumeMounts:
        - name: winrm-kerberos-config
          mountPath: /etc/krb5.conf
          subPath: krb5.conf
          readOnly: true
  volumes:
    - name: winrm-kerberos-config
      configMap:
        name: winrm-kerberos-config

This is a fragment showing the fields to add, not a replacement for an existing complete pod specification. Preserve existing container settings, volume mounts and volumes: list overrides replace the corresponding default lists. The controller sets the first container’s image and command from the job’s selected EE. Ensure that the job actually runs in this container group; see Container Groups and Customize the pod spec for scheduling, namespace and service account requirements.

A volume mounted into the controller’s web or task deployment is not automatically mounted into container-group job pods. Likewise, Paths to expose to isolated jobs is not a general ConfigMap mounting mechanism: its host-path mappings apply to Kubernetes job pods only when AWX_MOUNT_ISOLATED_PATHS_ON_K8S is enabled, and depend on files on the Kubernetes nodes. Use the job pod specification for this ConfigMap mount.

If you supply a configuration file at another path through KRB5_CONFIG, make that environment variable available in the EE and also forward it to managed kinit using the inventory variable:

ansible_winrm_kinit_env_vars:
  - KRB5_CONFIG

Setting this list alone does not create the file or set KRB5_CONFIG. It is unnecessary for the default /etc/krb5.conf path shown above.

22.3. Configure the credential and inventory

Create a credential with Credential type set to Machine. Set Username to the domain principal, for example automation-user@EXAMPLE.COM, and supply its Password through the credential. Select this credential in the job template. See Add a New Credential.

Create an inventory group named windows and add the target host, for example win01.example.com. Set these group variables for a WinRM HTTPS listener on port 5986:

ansible_connection: winrm
ansible_winrm_transport: kerberos
ansible_port: 5986
ansible_winrm_scheme: https
ansible_winrm_server_cert_validation: validate
ansible_winrm_kinit_mode: managed

Adjust the port and listener settings to match the target. If you set ansible_host, use the target FQDN that matches its SPN. The EE must trust the listener’s certificate; disabling certificate validation is not a substitute for configuring that trust.

Keep the password in the Machine credential, not in inventory variables or the playbook. Avoid setting ansible_user or ansible_password in inventory when relying on the Machine credential, because Ansible variables can override the credential’s connection values.

22.4. Ticket handling

In managed mode, Ansible uses the supplied username and password to obtain a ticket with kinit inside the EE and uses a temporary credential cache for the WinRM connection. The binary must be available in that container. If a custom image puts it elsewhere, set ansible_winrm_kinit_cmd to the absolute path of an MIT Kerberos-compatible executable inside the EE.

Do not generate a ticket as the awx user on a server and expect jobs to inherit it. A Machine credential supplies connection credentials; it does not import a host’s existing ticket cache into job containers.

Setting ansible_winrm_kinit_mode: manual disables automatic acquisition. Use it only with a separately designed process that supplies a valid ticket cache inside each job’s EE and manages its permissions, lifetime and cleanup. Merely changing the variable does not create or mount a ticket. Do not share a writable ticket cache between unrelated jobs.

22.5. Validate with a Windows job

Add a small test playbook to the project selected by the job template:

- name: Verify Windows Kerberos connectivity
  hosts: windows
  gather_facts: false
  tasks:
    - name: Verify remote module execution
      ansible.windows.win_ping:

Launch the template with the intended inventory, Machine credential, EE and container group, then inspect the job output. A successful win_ping verifies module execution using that job’s connection settings; it does not validate platform user authentication or every Windows permission needed by other playbooks.

When a job fails, distinguish the following causes:

  • Missing kinit or Python Kerberos/WinRM modules: correct the EE image and confirm that the template uses it.

  • KDC discovery or realm errors: check the file visible inside the job container, DNS and network access from its namespace.

  • Server not found in Kerberos database: check the connection FQDN and the target’s SPN with the directory administrator.

  • Authentication failures or clock-skew errors: check the Machine credential, account status, realm and time synchronization.

  • HTTPS certificate errors: check the listener name and the trust store visible inside the EE.

Keep passwords and ticket-cache contents out of diagnostic output. For connection options, including managed and manual ticket modes, see the Ansible WinRM connection documentation.