Authentication

Ordered fallback

Several schemes form an ordered fallback list: each is tried in the given order until one succeeds. authentication(KERBEROS, NTLM) attempts Kerberos first and falls back to NTLM — for example when the KDC is unreachable or the clock skew is too large.

User name and domain

The user name may be given as DOMAIN\user or as a bare user. When a backslash is present, the part before it is treated as the Windows domain and the part after it as the account name. In Java, remember to escape the backslash in a string literal:

"DOMAIN\\Administrator"   // domain = DOMAIN, user = Administrator
"Administrator"           // no domain

The password is a char[], and the builder deliberately does not copy it: after closing the client you can wipe the single authoritative copy of the secret (Arrays.fill(password, '\0')).

NTLM

NTLM is the default. It works over both transports:

• HTTP — the WinRM payload is protected with NTLM message encryption, so credentials and data are not sent in the clear even without TLS.
• HTTPS — NTLM runs inside the TLS tunnel. See TLS / HTTPS^[3].

NTLM needs no extra configuration beyond the user name and password.

Kerberos (SPNEGO)

Kerberos authentication uses SPNEGO through the JDK's GSS-API and requires HTTPS. Connect by the FQDN the KDC knows (the service principal is HTTP/<hostname>), not by IP address:

try (WinRMClient client = WinRMClient.builder("server.internal.example.com")
        .https()
        .credentials("DOMAIN\\Administrator", password)
        .authentication(AuthScheme.KERBEROS)
        // .ticketCache(Path.of("/tmp/krb5cc_1000"))   // optional
        .build()) {
    ...
}

Requesting Kerberos on a plain-HTTP client fails at build() with a clear message: there is no Kerberos message encryption over HTTP.

java -Djava.security.krb5.realm=EXAMPLE.COM \
     -Djava.security.krb5.kdc=dc01.example.com \
     -cp ... MyApp

Authentication failures

A rejected credential (after every scheme of the fallback list was tried) surfaces as a WinRMAuthenticationException^[4] whose message has the stable form Authentication error on <endpoint> with user name "<user>".

Choosing the scheme on the command line

The standalone jar selects the scheme with --ntlm (the default) or --kerberos. The two are mutually exclusive, and --kerberos requires --https:

java -jar winrm-java-2.0.00-standalone.jar \
  -h server.example.com -u 'DOMAIN\user' -pf password.txt \
  --https --kerberos \
  command whoami

Instead of relying on the ambient configuration, the CLI can set the JDK Kerberos configuration for the current invocation:

java -jar winrm-java-2.0.00-standalone.jar \
  -h server.internal.example.com -u 'DOMAIN\user' -pf password.txt \
  --https --kerberos --kerberos-kdc dc01.internal.example.com \
  command whoami

Here the realm is inferred as INTERNAL.EXAMPLE.COM by dropping the KDC's first DNS label and upper-casing the rest. This follows a common Active Directory naming convention but is not guaranteed by Kerberos — pass --kerberos-realm when the realm does not match the KDC's DNS suffix, or when the KDC is not a fully qualified DNS name.

See also

• Preparing the Windows Host^[5] — the privileges the account needs, and why local administrator accounts are often denied
• TLS / HTTPS^[3] — required for Kerberos and recommended for NTLM
• Timeouts and Errors^[6] — how authentication failures surface