Administering Keen

SSO linking and LDAP authentication

Chapter 3 of 30

SSO email addresses and account linking

An SSO identity is matched to a Keen account by its issuer and subject. This chapter explains how a second identity can be linked through a verified e-mail address, and how directory (LDAP) sign-in works alongside local accounts.

To link another identity automatically, its provider must report a verified e-mail address that exactly matches an address verified in Keen; usernames never authorise linking. Comparison ignores case and surrounding whitespace. Provider domain restrictions and the provider's auto-link setting also apply.

Configure SMTP and an HTTPS KEEN_PUBLIC_BASE_URL.
Users open Account → Security → SSO email addresses, enter a primary or additional address they own, and send a verification link. Adding or removing an address needs a sign-in within the last five minutes.
They open the link while signed into the requesting account and confirm it within thirty minutes. Each link works once; a new request replaces it.

Going deeper: limits and edge cases

Each address belongs to one account, each account may verify up to ten addresses, and verification requests are limited to five per hour. Existing contact addresses must also be verified before they can authorise a new SSO link. Password and MFA changes invalidate pending links, and Keen stores only a hash of the verification token. Verified addresses and existing identity links keep working during an SMTP outage; removing an address stops future automatic linking through it without removing existing associations.

A user who has never been linked needs an authenticated way in to verify an address: arrange local onboarding before requiring SSO exclusively, or provision a trusted issuer and subject association through your provisioning process. SSO sign-in transactions are bound to the initiating browser and provider, expire after ten minutes and are consumed once, so a user who opened another attempt, or began one before an upgrade, restarts sign-in.

KEEN_SECURITY_TRUSTED_PROXY_CIDRS governs forwarding-header interpretation for security e-mails, audit records and IP-based rate limits. Trust only your actual proxy hops; with none configured, Keen records and limits the socket peer address.

LDAP directory authentication

Directory sign-in lets people use their existing directory password. Keen still owns the account's permissions and its second factor.

In .env, set KEEN_LDAP_ENABLED=true, KEEN_LDAP_URL, KEEN_LDAP_BIND_DN, KEEN_LDAP_BIND_PASSWORD and KEEN_LDAP_BASE_DN. Use a read-only service account for searching. A base such as ou=People,dc=example,dc=org limits logins to that OU and its descendants.
Use ldap://host:389 for mandatory StartTLS or ldaps://host:636 for LDAPS; both verify the certificate and hostname. For a private CA, mount its PEM certificate into the API container and set KEEN_LDAP_CA_CERT_PATH to that container path, such as /app/config/ldap-ca.pem.
Recreate the API container and test with a directory user while a local administrator stays available.

Setting	Default	Notes
`KEEN_LDAP_USERNAME_ATTRIBUTE`	`uid`	Active Directory commonly uses `sAMAccountName`.
`KEEN_LDAP_EMAIL_ATTRIBUTE`	`mail`
`KEEN_LDAP_ID_ATTRIBUTE`	`entryUUID`	A stable identity; Active Directory commonly uses `objectGUID`.
`KEEN_LDAP_USER_FILTER`		A directory-specific restriction. Exactly one entry must match.
`KEEN_LDAP_AUTO_PROVISION`		`false` allows only previously provisioned LDAP identities.

A successful LDAP login creates an ordinary Keen account with a separate directory identity, and administrators assign its permissions. Matching e-mail addresses or usernames do not link local and LDAP accounts, and changing the LDAP server URL means planning an identity migration.

Going deeper: MFA, passwords and disablement

LDAP logins follow Keen's MFA policy; users enter their directory password to manage authenticators, security keys and recovery codes in Account → Security. Directory passwords are changed in the directory. Disabling the Keen user blocks application access immediately; directory disablement and OU restrictions take effect at the next password authentication, and existing sessions keep Keen's configured lifetime. An empty KEEN_LDAP_CA_CERT_PATH uses system trust.