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. The scheme that succeeded is retried first when the connection is re-established; once every scheme has failed, the next request starts over from the first one.

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

With Kerberos the DOMAIN\ part is ignored: the principal is the account name in the default realm of the Kerberos configuration. Write user@REALM (e.g. admin@EXAMPLE.COM) to name the realm explicitly.

The password is a char[], and the builder deliberately does not copy it: the client keeps that same array by reference end-to-end and never converts it to a String internally, so 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(), even in a fallback list such as (KERBEROS, NTLM), rather than being silently dropped: there is no Kerberos message encryption over HTTP.

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

try (WinRMClient client = WinRMClient.builder("server.internal.example.com")
        .https()
        .authentication(AuthScheme.KERBEROS)
        .allowDelegation()                       // Kerberos only
        .credentials("DOMAIN\\user", password)
        .build()) {
    client.command("dir \\\\fileserver\\share").execute();
}

[libdefaults]
  forwardable = true

Basic

HTTP Basic sends the credential in the Authorization header of every request — there is no handshake and no message protection, so the payload travels as plaintext SOAP. It works over both transports, but over plain HTTP the credential and the data are sent in the clear: use Basic over HTTPS only, where TLS protects both.

On Windows, WinRM accepts Basic for local accounts only, addressed by their bare user name: a domain account, or a local account written MACHINE\user or DOMAIN\user, gets a 401 even with the correct password. Use credentials("user", password), not credentials("MACHINE\\user", password). (The client itself does not reject a qualified name, for the non-Microsoft WSMan services that accept one; like every user name, it is sent with all whitespace removed: DOMAIN\John Smith becomes DOMAIN\JohnSmith.)

try (WinRMClient client = WinRMClient.builder("server.example.com")
        .https()
        .credentials("Administrator", password)   // Windows: a bare LOCAL account name
        .authentication(AuthScheme.BASIC)
        .build()) {
    ...
}

The WinRM service must have Basic enabled (it is off by default): winrm set winrm/config/service/auth @{Basic=true}; see Preparing the Windows Host^[5]. Over plain HTTP it must also set AllowUnencrypted=true, or it refuses the request with a 401 or a WSMan fault, depending on the Windows version.

A Basic 401 can therefore mean a wrong password, but also a domain or qualified account name, Basic disabled on the service, or plain HTTP with AllowUnencrypted=false: check the configuration before suspecting the credential.

Authentication failures

A credential the server rejects (HTTP 401, after every scheme of the fallback list was tried) surfaces as a WinRMAuthenticationException^[6] whose message has the stable form Authentication error on <endpoint> with user name "<user>". When Kerberos is the last scheme tried and fails on the client side (a password the KDC rejects, an unreachable KDC, an unknown service principal, a ticket that cannot be delegated), the error is a plain WinRMClientException carrying the JDK's Kerberos message.

Choosing the scheme on the command line

The standalone jar selects the scheme with --ntlm (the default), --kerberos, or --basic:

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

Its Kerberos options (--kerberos-kdc, --kerberos-realm, --allow-delegate) are described in the Command-Line Client^[7] manual.

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 the only safe transport for Basic
• Timeouts and Errors^[8] — how authentication failures surface