LDAP support

[h-2]

Hi,

I am really liking this so far! I have been looking for a nice Note-keeping service and Jotty seems to check all the boxes, and do exactly what I want: simple UI, folders for notes, intuitive multi-user, TODO-lists and even plaintext-storage!!
It really stands out between the other apps. However, I currently don't have OIDC, because I have been trying to avoid that complexity on my server. I just have LDAP (in particular LLDAP).

Have you considered adding support for LDAP? Wouldn't it be simpler than the OIDC implementation?

Thank you in any case!

[fccview]

Hey!

I never built anything with it, I'll do some proper research and see how feasible it is with the current setup, if it's an easy change I'll happily implement, more ways to authenticate are always welcome, just need to make sure security is tight and I do it properly, so may be a while!

Thank you for giving Jotty a go and feel free to share any resources/videos/diagrams of how you imagine the Auth to work, that'll definitely help me see what you are envisioning ♥️

[h-2]

Thank you!

feel free to share any resources/videos/diagrams of how you imagine the Auth to work, that'll definitely help me see what you are envisioning ♥️

I think most people right now have this setup Jotty → OIDC → LDAP, or not? What I suggested was also allowing direct auth against an LDAP server. I am not expert on this either, but from what I read, it should be easier to auth against an LDAP server…

Maybe looking at another small self-host project like radicale would help: https://github.com/Kozea/Radicale/tree/master/radicale/auth

[fccview]

Thank you for the share!

Just looked a bit more into it, and shouldn't bee too tough, just hook the file login to talk to the LDAP server first if env variables are set.

Still not sure when I'll have capacity for this, currently focusing on tasks/kanban, next release will have a huge rehaul of it all :)

Feel free to join discord for a more direct communication in case, I'll keep you posted either way ♥️

[h-2]

I had Claude come up with a plan for implementing LDAP support, giving it some specific guidance that I use on several projects, in particular regarding code re-use and preferring library solutions.
Below is what it came up with.

DISCLAIMER: I have no background in TS and am not an expert in LDAP, but I also don't want to create needless work for you, especially if the AI produces bad code, so I will iterate on this a bit, and see if I can get it working. If you have architectural concerns or ideas, please let me know. If you'd rather not receive AI contributions, that's fine, as well, of course :)

---

LDAP Authentication — Implementation Plan

Overview

This plan describes how to add LDAP/AD (Lightweight Directory Access Protocol) authentication to Jotty, as an alternative to local auth and OIDC. LDAP auth is credential-based: the user enters their username and password in the existing login form, and the server verifies them against the LDAP directory. No browser redirects are needed.

This is intentionally a minimal viable implementation. Advanced features (LDAPS certificate pinning, attribute mapping, nested groups, etc.) are explicitly out of scope.

---

Key Difference vs. OIDC

OIDC delegates auth to an external provider via browser redirects. LDAP is different: the user's credentials are verified server-side by binding to the LDAP server. This means:

• No new API routes for the login flow
• The existing username/password form works as-is
• The implementation plugs into the existing login server action, not a callback handler
• Conceptually closer to local auth than OIDC

---

Recommended Library: ldapts

ldapts is a pure-TypeScript LDAP client with no native bindings.

• No native compilation needed (relevant given the aarch64 situation discussed separately)
• Supports LDAP and LDAPS (TLS) out of the box
• Actively maintained
• TypeScript-first API

Estimated savings: ~90% of the implementation. Without it, you'd need to implement the LDAP protocol framing, BER encoding, TLS negotiation, and search grammar by hand. With it, the entire auth logic reduces to a few dozen lines.

Alternative: ldapjs — older, more popular, battle-tested but ships as CommonJS with weaker TypeScript support. Either would work; ldapts is the better fit for this codebase.

---

Environment Variables

Modeled after the OIDC env vars in howto/SSO.md and howto/ENV-VARIABLES.md.

# Required
SSO_MODE=ldap
LDAP_URL=ldap://ldap.example.com:389          # Use ldaps:// for TLS (port 636)
LDAP_BIND_DN=cn=service,dc=example,dc=com     # Service account DN for searching
LDAP_BIND_PASSWORD=secret                     # Service account password
LDAP_BASE_DN=ou=users,dc=example,dc=com       # Where to search for users

# Optional — auth config
SSO_FALLBACK_LOCAL=yes                        # Allow both LDAP and local login (reuses existing var)
LDAP_USER_ATTRIBUTE=uid                       # Attribute matched against submitted username (default: uid; use sAMAccountName for AD)
LDAP_ADMIN_GROUPS=cn=admins,ou=groups,dc=example,dc=com   # Comma-separated group DNs → admin role
LDAP_USER_GROUPS=cn=jotty,ou=groups,dc=example,dc=com     # Restrict access to these group members

# Docker secrets support (mirrors OIDC pattern)
LDAP_BIND_PASSWORD_FILE=/run/secrets/ldap_password

SSO_FALLBACK_LOCAL already exists in the codebase for OIDC. It should be extended to also work for LDAP mode, allowing a local admin fallback.

---

Auth Flow (Step by Step)

1. User enters username + password in the existing login form and submits.
2. The login server action (in app/_server/actions/auth/index.ts) checks SSO_MODE.
3. If SSO_MODE === "ldap", it delegates to a new ldapLogin function instead of the local hash check.
4. ldapLogin:
   a. Opens a connection to LDAP_URL.
   b. Binds as the service account (LDAP_BIND_DN / LDAP_BIND_PASSWORD) to gain search access.
   c. Searches LDAP_BASE_DN for an entry where LDAP_USER_ATTRIBUTE=<submitted username>.
   d. If no entry found → return error (same "invalid credentials" message, don't leak whether user exists).
   e. Attempts a second bind as the found user's DN with the submitted password. If this bind fails → invalid credentials.
   f. If bind succeeds: fetch the user's group memberships (see "Group Lookup" below).
   g. Check LDAP_USER_GROUPS (if set) to determine whether the user is allowed.
   h. Check LDAP_ADMIN_GROUPS to determine whether the user gets admin.
   i. Unbind / close the LDAP connection.
5. Call ensureUser(username, isAdmin) — this function already exists verbatim in app/api/oidc/callback/route.ts and should be extracted to a shared location (see "Code Reuse" below).
6. Call createSession(sessionId, username, "ldap") — this already accepts a loginType string.
7. Set the session cookie and redirect to / — identical to the OIDC callback.

---

Group Lookup

Two viable approaches:

Option A — memberOf attribute (recommended)

Fetch the memberOf attribute from the user's LDAP entry. This is a multi-value attribute listing all group DNs the user belongs to. Widely supported by Active Directory and most OpenLDAP setups with the memberof overlay enabled.

user entry:
  uid: alice
  memberOf: cn=admins,ou=groups,dc=example,dc=com
  memberOf: cn=jotty,ou=groups,dc=example,dc=com

Check: does any value of memberOf appear in LDAP_ADMIN_GROUPS (or LDAP_USER_GROUPS)?

Pro: Single search, simple. Con: Requires memberof overlay on the LDAP server; not always available on older OpenLDAP.

Option B — Reverse group search

After authenticating the user, perform a second search in the groups OU:

base: ou=groups,dc=example,dc=com
filter: (&(objectClass=groupOfNames)(member=<user DN>))

Pro: Works on any LDAP server without special overlays. Con: Requires an additional search; admin must set a separate LDAP_GROUP_BASE_DN env var if groups are not under LDAP_BASE_DN.

Recommendation: Implement Option A by default, with a silent fallback to Option B if the memberOf attribute is absent. This handles the majority of setups with minimal configuration.

Uncertainty: Whether to surface this as a user-facing config option (e.g., LDAP_GROUP_LOOKUP=memberof|search) or keep it transparent. The fallback approach avoids the need to expose this, but adds complexity. Given the MVP goal, the fallback is acceptable.

---

Code Reuse

ensureUser()

Currently duplicated in app/api/oidc/callback/route.ts (lines 49–126). This function should be extracted to app/_server/actions/users/index.ts (or a new app/_server/actions/auth/sso.ts) and imported by both the OIDC callback and the new LDAP login. No logic change needed.

createSession()

Already lives in app/_server/actions/session/index.ts and already accepts loginType. No changes needed — just call createSession(sessionId, username, "ldap").

getEnvOrFile()

Already in app/_server/actions/file/index.ts. Use it for LDAP_BIND_PASSWORD / LDAP_BIND_PASSWORD_FILE to get Docker secrets support for free.

Session cookie creation

The cookie setup (name, flags, maxAge) is currently duplicated between the OIDC callback and local auth. For LDAP, copy the same pattern. A shared helper would be a nice cleanup but is out of scope.

---

Files to Create / Modify

Action	File	What changes
Create	app/_server/actions/auth/ldap.ts	New file: ldapLogin(username, password) — full LDAP bind + group check logic
Modify	app/_server/actions/auth/index.ts	login action: branch on SSO_MODE === "ldap" → call ldapLogin
Modify	app/(loggedOutRoutes)/auth/login/page.tsx	Extend ssoEnabled / mode detection to cover ldap; ensure the setup redirect doesn't fire in LDAP mode when no local users exist
Modify	app/(loggedOutRoutes)/auth/setup/page.tsx	Disable/hide user registration when SSO_MODE=ldap (users come from LDAP; local accounts don't make sense unless SSO_FALLBACK_LOCAL is set)
Extract	app/_server/actions/users/index.ts (or auth/sso.ts)	Move ensureUser() out of the OIDC callback into a shared location
Create	howto/LDAP.md	User-facing documentation (env vars, example docker-compose, AD-specific notes)

UI changes

The existing username/password form requires no changes for LDAP mode — it already does what we need. The only login page change is to not show "Sign in with SSO" (OIDC button) when in LDAP mode, and to handle the redirect-to-setup edge case (currently !hasExistingUsers && !ssoEnabled triggers setup; this must also account for LDAP mode where no local users will ever exist).

---

Error Handling

• LDAP connection failure (server unreachable): surface as a generic "authentication service unavailable" error, log the underlying error server-side.
• Invalid credentials: return the same error message as local auth ("Invalid username or password") — do not distinguish "user not found" from "wrong password" to avoid user enumeration.
• User not in LDAP_USER_GROUPS: redirect to /auth/login?error=unauthorized (same as OIDC).
• Reuse existing brute-force protection from login in auth/index.ts — it operates on the returned error before LDAP is ever contacted, so it applies naturally.

Uncertainty: Should LDAP connection errors lock out the account like wrong passwords do? Probably not — a misconfigured server shouldn't lock users out. The brute-force counter should only increment on actual credential failures (step 4e above), not on LDAP connectivity errors.

---

Security Notes

• The service account password should be stored via LDAP_BIND_PASSWORD_FILE in production (Docker secrets).
• For LDAPS (ldaps://), ldapts validates the server certificate by default using the system CA store. Self-signed certs would require either adding the CA to the container or disabling verification. Disabling verification (rejectUnauthorized: false) is a possible escape hatch but should be documented as insecure.
• The user's plaintext password is only held in memory for the duration of the bind — it is never stored or logged.
• Do not log LDAP search filters that contain the submitted username at INFO level — only at DEBUG/DEBUGGER (consistent with how the OIDC callback gates sensitive logging behind process.env.DEBUGGER).

---

Out of Scope (MVP)

• SASL / Kerberos / GSSAPI bind mechanisms
• Nested group membership (group-of-groups)
• LDAP attribute → Jotty profile field mapping (e.g., setting avatarUrl from jpegPhoto)
• Automatic user deactivation when removed from LDAP
• LDAP referrals
• Connection pooling (one connection per login request is fine at MVP scale)