yeke.io · docs · enterprise

Active Directory / LDAP Login

Enterprise lets users sign in with Active Directory or LDAP accounts. This guide covers connection settings, group mapping and common connection issues.

Overview

One login screen; the branching happens on the server.

Local and directory users share one login screen. YEKE identifies the account and authenticates it locally or against the directory. Users do not need to choose a provider.

YEKE uses its service account to find the user in the directory, then verifies the supplied password with a separate bind. The service account and base DN settings are required for this lookup.

This capability is unlocked by the Enterprise license's sso item, and this page covers the directory half of it: binding to the directory, authenticating, and reading group membership. OIDC-based SSO with providers like Keycloak or Entra ID shipped in 0.14.0 under the same flag; both can be enabled at the same time.

Connecting the directory

One directory is configured from the admin screen, and saving it really tests the connection.

Field	What it does
Server and port	The directory server's address. Must be a hostname (FQDN) — an IP address puts you straight into the first pitfall below.
Connection type	LDAPS (the default) or StartTLS. There is no plaintext option and it cannot be turned off: two passwords cross the wire — the service account's and yours.
CA certificate	If your server certificate is signed by an internal CA, paste its PEM here. Verification cannot be disabled; a certificate-less test environment is solved by generating your own CA and adding it here.
Service account	A read-only account's bind DN and password, used to search the directory. No write access is requested; YEKE never writes to the directory.
Search base (base DN)	The directory root under which users are searched for.
User filter	An LDAP filter with a placeholder for the entered username. Also the place to narrow scope: for example, only members of a given group.

server and port         :  ldaps://ad.example.com:636
CA certificate          :  corp-ca.pem
service account (bind)  :  CN=yeke-read,OU=Service Accounts,DC=example,DC=com
search base (base DN)   :  OU=Users,DC=example,DC=com
user filter             :  (sAMAccountName={login})

Once saved, the "Test connection" button on screen binds for real with the service account. A wrong field shows up on the setup screen, not on the first real user login.

The username field: `sAMAccountName` or `userPrincipalName`

Chosen once, in the directory record; this is the value YEKE stores as the username.

The default is sAMAccountName — the short name most organizations are used to (e.g. ayilmaz). userPrincipalName is also selectable (e.g. [email protected]). Whichever a user types at login, the user filter can search for either, but the name shown in YEKE's user list and audit trail is always the value of the attribute you chose.

YEKE updates a renamed directory user at the next sign-in. The account remains linked by objectGUID, and the audit trail records both names. If the new name conflicts with a local account, the update fails with an error.

Common connection issues

If the connection fails, check the certificate name and DNS resolution first.

Don't put an IP in the server field — it has to match the certificate's name

With LDAPS, the name on the certificate has to match the address you connect to exactly. Most Active Directory deployments issue a server certificate that carries only the hostname; put an IP address in the server field and the connection never establishes. The fix is to enter the directory's full hostname (FQDN); the connection test names the mismatch directly: "the certificate says …, you connected to …".

The machine running YEKE needs DNS that can resolve the directory

The hostname you enter has to resolve to the right IP. On a corporate Active Directory network this is already true, because the directory runs its own DNS. If you run YEKE on a different network — say, a machine using public internet DNS — this is the first thing that breaks, and the symptom can be misleading: the error looks like a certificate mismatch, but the root cause is connecting to the wrong address.

Roles and Kubernetes group mapping

Directory groups can feed both the YEKE role and the cluster identity; two separate settings.

Roles can be derived from the directory

The directory record lets you optionally name an "admin group". When set, a user's role is recomputed on every login based on membership in that group: a member becomes admin, everyone else is member. Leave it unset and the role is managed the usual way, from YEKE's user screen. Once a directory group is driving the role, that user's role can no longer be changed by hand; otherwise a manual edit would be silently overwritten by the next login.

Kubernetes identity: an explicit list added to the cluster rule

The cluster rule plus personal binding model described on the Permissions and RBAC page still applies. Adding a directory adds an explicit list to the cluster identity rule, mapping which AD group flows into which Kubernetes group (the impersonation group). The mapping is per cluster — the same AD group can map to different Kubernetes groups on different clusters.

AD group (DN)                                       Kubernetes group
CN=YEKE-Operators,OU=Groups,DC=example,DC=com    →  yeke:cluster-admins
CN=Payments-Team,OU=Groups,DC=example,DC=com     →  payments-oncall

system:masters is never accepted in a mapping; it is rejected the moment you write it, the same rule enforced on the permissions page.

Nested group membership is always read

Nested group memberships are included in identity mapping and cannot be disabled. The extra lookup runs at sign-in, not on every cluster request.

First login: automatic user creation and license seats

You do not pre-invite anyone from the directory.

Just-in-time creation. A user who authenticates against the directory but has no YEKE record yet is created automatically on their first successful login. You do not keep a second "who can sign in" list in YEKE — that decision already belongs to the directory; to narrow it, add a group condition to the user filter.
It consumes a seat. An automatically created user consumes a license seat exactly like one created by hand. If the user ceiling is reached, a new directory user's first login is refused with an explicit error and no row is created.
YEKE's own brake wins. A user disabled on the YEKE side is refused at login even if their directory password still works. This is an emergency brake that operates independently of the directory's own state.

Local accounts and emergency access

Connecting a directory does not remove local login.

Both paths run at once. Turning on Active Directory / LDAP does not remove username-and-password login; the two live on the same screen at the same time.
The install owner is always local. Ownership cannot be transferred to a directory user — local administrator login stays available even when the directory is unreachable, misconfigured, or the license is frozen.
A directory user can become admin, never owner. The role can come from the group above or be set by hand; ownership belongs only to a local account.
An unreachable directory does not touch local login. When the directory cannot be reached — network, certificate, a server that is down — directory users fail to sign in, but the local path is unaffected because it uses a completely separate connection budget.

Limits

The line between what exists today and what does not.

No SAML or SCIM. OIDC-based SSO with providers like Keycloak or Entra ID shipped in 0.14.0 and is part of the same sso item; SAML and SCIM remain in the demand-driven queue.
One directory is supported. There is no binding to more than one independent directory at a time. The answer for a multi-domain Active Directory forest is connecting to the Global Catalog port (3268/3269) — one connection searches the whole forest.
YEKE never writes to the directory. Password changes/resets, enabling or disabling accounts — all of that stays on the directory's side; YEKE's service account only reads, and is meant to stay that way.
Group membership is read at login, not watched continuously. When a user's group changes in the directory, YEKE sees it on their next login or when their session is revoked, not instantly.
No passwordless or desktop single sign-on. Only username-and-password binding (a simple bind, inside TLS) is supported; Kerberos/GSSAPI is out of scope.
None of this works without a license. The directory setup screen and directory login are refused with an explicit error without the Enterprise sso item; local login is never affected.

See how access plays out on the Kubernetes side

Directory groups feed into Kubernetes groups here — but the decision is still RBAC's. The full model lives on the permissions page.

Permissions and RBAC Pricing