Kerberos Authentication with Mercurial

The server refused the clone. Kerberos had blocked the handshake before Mercurial could pull a single changeset.

Kerberos authentication with Mercurial can be exacting. It demands precision in configuration, alignment between client and server, and trust across every network hop. When the protocol fails, you see terse errors. Behind them is a chain of steps that must match exactly: realm, principal, service tickets, configuration files.

Mercurial supports HTTP and SSH transport. Kerberos integrates mostly with HTTP, securing endpoints with ticket-based authentication instead of static passwords. On the server, Apache or Nginx must be built with SPNEGO modules. On the client, krb5.conf defines realms and KDC addresses. The hg command will pass the ticket through curl or the Python requests library, which must themselves be built with GSSAPI support.

Security policies often raise the bar. In large environments, service tickets are valid for short periods. This can break long clones or pushes. To avoid failure, renew tickets with kinit before running Mercurial operations. Use klist to verify that your principal matches the service configuration. Keep encryption types consistent—mismatches between AES256 and AES128 are common sources of failure.

Repository access control is tied to the Kerberos principal. The server maps it to Mercurial's ACLs, often using mod_auth_kerb or similar modules. This enables fine-grained permissions without storing passwords in the VCS. Logging is critical: capture both Apache SPNEGO logs and Mercurial server logs to trace failed authentication or ticket expiration.

When Kerberos and Mercurial are tuned correctly, the handshake is silent and fast. Tickets flow, pushes land, clones stream, and every byte is verified. The system becomes both secure and efficient, guarded at every layer.

See Kerberos with Mercurial configured and running. Visit hoop.dev and get it live in minutes.