LDAP Configuration

⚠Not yet available

Runtime LDAP integration is Phase 4 of the RBAC rollout. As of v0.0.x, Honeyframe authenticates against honeyframe.users only. There is no LDAP login path, no group sync, and no LDAP-backed attribute mapping in the deployed product.

This page documents the planned runtime model so operators can prepare directory state. For the install-time configuration that will activate this feature, see Installation → LDAP.

What's planned

When Phase 4 ships, LDAP will provide three runtime capabilities:

1. Authentication — users sign in with their directory credentials. The platform binds against the configured LDAP server using the user's DN and the supplied password.
2. Group sync — directory groups are mirrored into honeyframe.groups on a schedule. Membership changes in the directory propagate into Honeyframe within the sync window.
3. Attribute mapping — selected directory attributes (displayName, mail, department) populate the corresponding fields on the Honeyframe user record.

Authentication flow (planned)

1. User submits username + password to POST /api/auth/login.
2. The platform looks up honeyframe.users by username:
   • If the row exists with auth_source='ldap', proceed to LDAP bind.
   • If the row exists with auth_source='local', fall back to the local password check.
   • If no row exists and LDAP-on-first-login is enabled, attempt LDAP bind and create the row if successful.
3. Bind to LDAP at LDAP_URL using the user's DN (looked up via LDAP_USER_SEARCH_FILTER) and the supplied password.
4. On successful bind, issue a JWT access token. On failure, return 401.

The local password column is preserved for users with auth_source='local' so a hybrid deployment can keep service accounts on local auth while users sign in via LDAP.

Group sync (planned)

A scheduled job will periodically sync directory groups → honeyframe.groups:

• Each LDAP group whose name matches LDAP_GROUP_FILTER becomes a honeyframe.groups row with external_id=<group_dn> and auth_source='ldap'.
• For each user authenticated against LDAP, the job lists their group memberships via LDAP_GROUP_SEARCH_FILTER and reconciles honeyframe.user_groups rows accordingly.
• Local-only groups (no external_id) are untouched. Mixing LDAP-sourced and local groups in the same organization is supported.

The sync schedule defaults to every 15 minutes. Tighten it for security-sensitive deployments where access revocation needs to propagate within minutes; loosen it for large directories where the bind cost is high.

Attribute mapping (planned)

A small fixed map covers the common cases:

Honeyframe field	Default LDAP attribute
username	uid (Linux directories) or sAMAccountName (Active Directory)
full_name	cn or displayName
email	mail
external_id	the user's DN

Override defaults via install-time config (LDAP_ATTR_USERNAME=sAMAccountName, etc.).

Configuration surface

Refer to Installation → LDAP for the full set of install.conf parameters. The runtime exposes the same parameters as environment variables on the Platform service, so they can be rotated without re-running the installer:

LDAP_URL
LDAP_BIND_DN
LDAP_BIND_PASSWORD
LDAP_USER_SEARCH_BASE
LDAP_USER_SEARCH_FILTER
LDAP_GROUP_SEARCH_BASE
LDAP_GROUP_SEARCH_FILTER
LDAP_GROUP_NAME_ATTR
LDAP_USE_STARTTLS
LDAP_CA_BUNDLE

After changing any of these, restart the Platform service (systemctl restart hub-platform) for the new values to take effect.

Until Phase 4 ships

For installs that need centralized identity now:

• Google Identity — the existing Google sign-in flow on /api/auth/google works against any Google Workspace domain. Configure your client ID and trusted email domains in the Platform .env.
• Local users with provisioning script — for small deployments, manage users via the /api/users endpoint scripted from your existing identity workflow.
• Reverse-proxy SSO — terminate SSO at nginx (e.g. via oauth2-proxy) and pass the authenticated identity to Honeyframe. The platform's session model can be initialized from a trusted upstream header with a small custom integration.

These are workarounds; full LDAP support is the long-term path.