Skip to main content

Directory and Kerberos Sign-In

A key server can authenticate users who already exist in your LDAP directory. Such a user is an LDAP principal — enrolled in the key server by its directory distinguished name (DN) — and can sign in two ways:

LoginModuleThe user proves
LDAP passwordLDAPAuthentication (AM06)their directory password, verified by a bind to the directory
KerberosGSSAPIAuthentication (AM10)a Kerberos ticket for the key server, in a GSS-API exchange bound to the TLS connection

Both resolve to the same LDAP principal. There is no separate Kerberos principal type: a Kerberos login ends in the LDAP principal whose directory entry names the Kerberos user (ADR-0106).

What every key server provides​

Both modules are compiled into every shipped key server, on Linux and on Windows (ADR-0106, ADR-0120). What differs is whether they are configured:

  • The LDAP password login (AM06) ships enabled, reached through the key server's directory connection (LDAPContext), whose default target is localhost:389 with a simple bind. Point it at your directory at installation.
  • The Kerberos login (AM10) ships disabled. It needs a keytab and a service principal, which only you can supply, and is enabled at configuration time.

The Kerberos login (AM10)​

How it works​

The client acquires a Kerberos ticket for the key server's service principal — for example te/ks.example.test@EXAMPLE.TEST — and runs a GSS-API exchange over the key server connection with mutual authentication. The exchange carries the connection's RFC 9266 channel binding (tls-exporter), and the key server accepts it only if the GSS-API library reports the context channel-bound to the connection the tokens arrived on. A relay that terminates TLS and re-originates it therefore cannot forward a Kerberos login.

The key server then maps the Kerberos principal name (user@REALM) to a directory entry: it searches for exactly one entry whose mapping attribute equals that name, byte for byte, and requires that entry's DN to be an enrolled, enabled LDAP principal. The session is established as that principal.

Kerberos delegation, PKINIT and Windows SSPI are not supported.

What the key server needs​

The AM10 configuration node carries:

AttributeMeaning
keytabThe keytab holding the service principal's key. Required: the module refuses to start without a readable one.
serviceThe service principal name, e.g. te/<host>@REALM.
attributeThe directory attribute that holds a user's Kerberos principal name. Defaults to krbPrincipalName; on Active Directory this is typically userPrincipalName.

AM10 is offered on the TLS listener only.

Just-in-time provisioning​

By default a Kerberos user whose DN is not already an enrolled LDAP principal is refused. The policy parameter Policy.GSSAPI.CreatePrincipal can instead create that LDAP principal at first sign-in (ADR-0110). It ships off, and when enabled it is constrained by Policy.GSSAPI.Realms, Policy.GSSAPI.BaseDNs and Policy.GSSAPI.Roles — roles that carry any management operation are refused. Changes take effect at the next key server start.

The client​

The C++ SDK's TEGssapiAuthenticationContext drives the exchange (context type TEAuthenticationContext::GSSAPI):

  • setServicePrincipal(principal) — the key server's acceptor principal;
  • setCredentialCache(ccache) — optional; the library's default cache otherwise;
  • getInitiatorName() — after authentication, the Kerberos name the credentials authenticated as.

It is available in the Linux and the Windows client libraries (ADR-0121). On Windows the client library depends on the MIT Kerberos runtime, so gssapi64.dll must be on the application's DLL search path. The Java and C clients do not offer a Kerberos login.

Through a Remote Engine​

A Remote Engine (rE) runs its own Kerberos acceptor and directory client (ADR-0117). An online engine terminates the channel-bound Kerberos login on its own connection with the client, resolves the user to a DN, and then asserts that identity to the key server under its own certificate (ADR-0118, ADR-0112). The key server accepts the assertion only from an engine principal an administrator has explicitly authorized for it, and only for an enrolled, enabled LDAP principal that holds no management operation. An offline engine refuses the login.