gwim

gwim

Windows-native Kerberos/NTLM authentication and TLS for Go HTTP servers.

Deploying a Go service inside a corporate Active Directory domain normally means standing up IIS or a reverse proxy just to get Windows integrated authentication, authorization, and TLS. gwim removes that requirement. It wraps any http.Handler with Windows-native Kerberos authentication, enriches the request context with LDAP group memberships, and pulls TLS certificates straight from the Windows certificate store — letting you ship a single self-contained web server .exe that runs seamlessly in a Windows domain environment. With gwim, you can run Go websites securely right where your users are and just how your Windows infrastructure is configured.

Prerequisites

Installation

go get github.com/akennis/gwim

Quick Start

The snippet below is the smallest possible secure server using gwim. It retrieves a TLS certificate from the Windows certificate store, wraps a handler with Kerberos authentication, and starts listening. Error handling is omitted for brevity.

package main

import (
    "crypto/tls"
    "log"
    "net/http"

    "github.com/akennis/gwim"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        username, _ := gwim.User(r)
        w.Write([]byte("Hello, " + username))
    })

    // Create a Kerberos authentication provider
    sspiProvider, _ := gwim.NewSSPIProvider()
    defer sspiProvider.Close()

    // Retrieve a TLS certificate from the Windows certificate store
    certSource, _ := gwim.GetWin32Cert("myserver.corp.local", gwim.CertStoreLocalMachine)
    defer certSource.Close()

    srv := &http.Server{
        Addr:    ":8443",
        Handler: sspiProvider.Middleware(mux),
        TLSConfig: &tls.Config{
            Certificates: []tls.Certificate{certSource.Certificate},
        },
    }

    // Windows authenticates the current domain user transparently —
    // no login prompt, no credentials to manage.
    log.Fatal(srv.ListenAndServeTLS("", ""))
}

How It Works

Requests flow through the middleware chain in the following order:

Client Request
  │
  ▼
SSPI Middleware (Kerberos or NTLM negotiation)
  │  ── sets the authenticated username in the request context
  ▼
LDAP Middleware (optional)
  │  ── looks up the user's group memberships and adds them to the context
  ▼
Your Application Handler
  │  ── reads username via gwim.User(r)
  │  ── reads groups  via gwim.UserGroups(r)

[!IMPORTANT] Middleware Order: SSPIProvider must always be applied before LDAPProvider (i.e. SSPIProvider should be the outermost middleware). This ensures the user's identity is established in the request context before the LDAP provider attempts to look up their group memberships.

Usage Examples

See the examples directory for complete, runnable servers:

• Minimal secure server — TLS + Kerberos/NTLM authentication with optional LDAP group lookup, in under 200 lines.
• Session-enabled secure server — adds session management and caching so that authentication and LDAP lookups happen once per session rather than on every request, with graceful shutdown and zero-downtime certificate rotation.

API

Authentication

gwim uses the Middleware Factory Pattern: create a provider once at startup, then register its .Middleware method with any router's Use() call or use it to wrap handlers manually. The .Middleware method satisfies the standard func(http.Handler) http.Handler signature, making it compatible with any router that supports standard Go middleware.

NewSSPIProvider

sspiProvider, err := gwim.NewSSPIProvider(opts ...SSPIOption) (*SSPIProvider, error)

Acquires Windows SSPI credentials and returns a provider. Any credential acquisition error is surfaced here at startup rather than on the first request.

// Kerberos (production default)
sspiProvider, err := gwim.NewSSPIProvider()

// NTLM (local / non-domain development)
sspiProvider, err := gwim.NewSSPIProvider(gwim.WithNTLM())

// With custom error handling
sspiProvider, err := gwim.NewSSPIProvider(
    gwim.WithNTLM(),
    gwim.WithSSPIErrorHandlers(gwim.AuthErrorHandlers{
        OnGeneralError: myErrorHandler,
    }),
)

Use the provider:

// Standard net/http
handler := sspiProvider.Middleware(mux)

// Any router with Use()
router.Use(sspiProvider.Middleware)

SSPIOption functions:

Lifecycle: Call sspiProvider.Close() on server shutdown to release Windows credential handles.

[!NOTE] Kerberos should be used in production as it is significantly more secure. NTLM support is included only to facilitate local development where the developer is hitting the server from a browser on the same host (a scenario where Kerberos loopback authentication does not work).

ConfigureNTLM

gwim.ConfigureNTLM(server *http.Server)

Configures the http.Server with the ConnContext callback required for NTLM connection tracking. NTLM is connection-oriented — each TCP connection carries its own authentication state. This function assigns a unique ID to every connection so the NTLM handler can correlate the two-step token exchange across requests on the same keep-alive connection. Only required when using NTLM; not needed for Kerberos.

LDAP Group Authorization

NewLDAPProvider

ldapProvider, err := gwim.NewLDAPProvider(opts ...LDAPOption) (*LDAPProvider, error)

Returns a provider that enriches an authenticated request's context with the user's Active Directory group memberships (transitively, via the tokenGroups attribute). Groups are returned as LDAP Distinguished Names (DNs), e.g. CN=AppAdmins,OU=Groups,DC=corp,DC=local.

Startup validation: NewLDAPProvider performs a synchronous connectivity check before returning. It opens a TLS (LDAPS) connection to the configured address, authenticates via GSSAPI/Kerberos bind using the server's current-user credentials, and executes a RootDSE search. If any step fails, an error is returned here at startup rather than on the first request.

At runtime, the provider maintains an internal connection pool (capacity: 10). On each request a pooled connection is health-checked with a lightweight RootDSE probe before use; connections that fail the probe or exceed their TTL are discarded and a new one is created.

ldapProvider, err := gwim.NewLDAPProvider(
    gwim.WithLDAPAddress("dc01.corp.local:636"),
    gwim.WithLDAPUsersDN("OU=Users,DC=corp,DC=local"),
    gwim.WithLDAPServiceAccountSPN("LDAP/DC1.corp.local"),
)
if err != nil {
    log.Fatalf("failed to create LDAP provider: %v", err)
}

// Wrap the LDAP-wrapped handler with SSPI (SSPI runs first)
handler = sspiProvider.Middleware(ldapProvider.Middleware(mux))

// Or with a router
router.Use(sspiProvider.Middleware)
router.Use(ldapProvider.Middleware)

LDAPOption functions:

Lifecycle: Call ldapProvider.Close() on server shutdown to drain the connection pool and release Windows credentials used for the LDAP bind.

Request Context Helpers

• User(r *http.Request) (string, bool) — Returns the authenticated username from the request context.
• SetUser(r *http.Request, username string) *http.Request — Injects a username into the request context. If a username is already present when the SSPI middleware runs, authentication is skipped — use this to restore a session without re-running SSPI.
• UserGroups(r *http.Request) ([]string, bool) — Returns the user's group memberships from the request context as LDAP Distinguished Names (DNs), e.g. CN=AppAdmins,OU=Groups,DC=corp,DC=local.
• SetUserGroups(r *http.Request, groups []string) *http.Request — Injects group memberships into the request context. If groups are already present when the LDAP middleware runs, the LDAP lookup is skipped — use this to restore cached groups from a session.

Use SetUser and SetUserGroups together to restore a previously authenticated identity from a session store, avoiding re-authentication and LDAP lookups on every request:

// In your session middleware, before the SSPI middleware runs:
if sessionUser, ok := getSession(r); ok {
    r = gwim.SetUser(r, sessionUser)
    r = gwim.SetUserGroups(r, sessionUser.Groups)
}

See sec-win-server/main.go for a full working example of this pattern.

TLS Certificate

• GetWin32Cert(certSubject string, store CertStore) (*CertificateSource, error) — Retrieves a TLS certificate from the Windows certificate store by Common Name. Use CertStoreLocalMachine or CertStoreCurrentUser for store. The certificate is validated before being returned: it must not be expired, must carry ExtKeyUsageServerAuth, and its full issuer chain must pass verification via the Windows CryptoAPI. The returned CertificateSource.Certificate is a tls.Certificate ready for use in tls.Config.Certificates. Call Close() on the source when it is no longer needed (e.g. on server shutdown) to release Windows store handles.

• GetCertificateFunc(certSubject string, store CertStore, refreshThreshold, retryInterval time.Duration) (func(*tls.ClientHelloInfo) (*tls.Certificate, error), io.Closer, error) — Like GetWin32Cert but returns a tls.Config.GetCertificate callback that transparently refreshes the certificate in the background when it is within refreshThreshold of expiry, enabling zero-downtime rotation. Pass DefaultRefreshThreshold and DefaultRetryInterval for standard values. Call Close() on the returned io.Closer after http.Server.Shutdown returns.

Error Handling (AuthErrorHandlers)

Both WithSSPIErrorHandlers and WithLDAPErrorHandlers accept an AuthErrorHandlers struct to customize error responses. Each field is an AuthErrorHandler func(w http.ResponseWriter, r *http.Request, err error):

If no options are provided, sensible defaults are used (plain-text HTTP error responses).

Requests do not progress to the next request hander in the chain once an error has occurred. The error handler is executed and control is sent back up the request hander chain (i.e. the earlier handlers).

Integration Testing

The integration_tests package contains client/server tests for both NTLM and Kerberos authentication.

Running NTLM Tests

NTLM tests can be run locally by spawning the test server and the test runner on the same machine.

1. Build the test server:

   go build -o testserver.exe ./integration_tests/cmd/testserver/main.go
   

2. Run the test server:

   .\testserver.exe --addr 127.0.0.1:8080 --use-ntlm=true
   

3. Run the tests:

   go test -tags=integration -v ./integration_tests -server-url http://127.0.0.1:8080 -auth-mode ntlm
   

Running Kerberos Tests

Kerberos tests require the test server and the test runner to be on separate machines within the same Active Directory domain. This is because Windows handles local Kerberos authentication (loopback) differently than remote authentication.

1. Deploy and run testserver.exe on Machine A (the "server").
2. Run the tests from Machine B (the "client") pointing to Machine A:

   go test -tags=integration -v ./integration_tests -server-url http://<machine-a-hostname>:8080 -auth-mode kerberos
   

Code Coverage

gwim supports code coverage collection for out-of-process integration tests using Go 1.22's -cover instrumentation.

1. Build an instrumented test server:

   go build -cover -o testserver.exe ./integration_tests/cmd/testserver/main.go
   

2. Run the server with GOCOVERDIR set to an output directory:

   mkdir coverage_data
   $env:GOCOVERDIR="coverage_data"
   .\testserver.exe --addr 127.0.0.1:8080 --use-ntlm=true
   

3. Run your integration tests as usual.
4. Stop the server (Ctrl+C). The server will gracefully shut down and flush coverage data to the coverage_data directory.
5. View the coverage percentage:

   go tool covdata percent -i=coverage_data
   

6. Generate an HTML report:

   go tool covdata textfmt -i=coverage_data -o coverage.out
   go tool cover '-html=coverage.out'
   

License

This project is licensed under the BSD 3-Clause License — see the LICENSE file for details.