Diagnosing LDAP Authentication Failures in Forgejo

Recognizable Condition

When users attempt to log in to Forgejo with LDAP credentials, the interface shows errors such as “Invalid credentials” or “LDAP bind failed”. The Forgejo log file (typically log/forgejo.log) contains entries like LDAP bind error: Invalid credentials or LDAP search failed: Can't contact LDAP server.

Common Causes and Diagnostic Indicators

Possible Cause	Typical Log Message	What to Verify
Incorrect LDAP URI or port	“Can't contact LDAP server”	URI scheme, host, port in app.ini
Wrong bind DN or password	“Invalid credentials”	Bind DN matches an LDAP entry; password correct
Mis‑configured user search base or filter	“No such object” or empty search result	Base DN and filter return the expected user entry
TLS/SSL certificate problems (ldaps://)	“TLS handshake failed” or “certificate verify failed”	Server certificate trusted by Forgejo’s trust store
Syntax error in app.ini	Forgejo fails to start or logs “unknown key”	INI parsing, no stray spaces or missing sections

Ordered Checks

1. Verify network reachability – From the Forgejo host, run ping or nc -zv to the LDAP host and port. Run as the forgejo user (or with sudo) to ensure the same outbound path Forgejo uses.
2. Test LDAP bind with ldapsearch – Execute a search that mirrors the Forgejo configuration. Example:

   ldapsearch -x -H ldaps://ldap.example.com:636 -D 'cn=forgejo-bind,ou=ServiceAccounts,dc=example,dc=com' -w 'bindPassword' -b 'ou=Users,dc=example,dc=com' '(uid=testuser)' cn

   Replace placeholders with the values from app.ini. The command should return the user entry; if it fails, note the error code.
3. Inspect Forgejo configuration – Check custom/conf/app.ini (or /etc/forgejo/app.ini) for the [auth.ldap] section. Ensure there are no typos, that the HOST, PORT, BIND_DN, BIND_PASSWORD, USER_BASE, USER_FILTER, and SSL (or START_TLS) settings match the ldaptest.
4. Validate TLS trust (if using ldaps://) – Export the LDAP server’s certificate and add it to the system trust store or to Forgejo’s custom certs/ directory, then run openssl s_client -connect ldap.example.com:636 -showcerts to verify the chain is trusted.
5. Review Forgejo logs – After each change, tail log/forgejo.log (or journal if using systemd) and look for lines containing LDAP or authentication. A successful login will produce LDAP authentication succeeded for uid=….

Fixes Tied to Findings

• If the URI/port is wrong – correct HOST and PORT in app.ini, restart Forgejo (systemctl restart forgejo or ./forgejo web).
• If bind DN/password is incorrect – update BIND_DN and BIND_PASSWORD; ensure the file permissions are 640 owned by the forgejo user to avoid exposing the password.
• If user search base or filter is off – adjust USER_BASE and USER_FILTER to match the LDAP DNs; test with ldapsearch using the same base and filter.
• If TLS certificate is not trusted – obtain the LDAP server’s CA certificate, copy it to custom/certs/ (or add to /etc/ssl/certs), run update-ca-certificates if needed, and set SSL_VERIFY = true (or SKIP_TLS_VERIFY = false) in app.ini.
• If app.ini has syntax errors – correct any stray characters, ensure sections are properly headed with [auth.ldap], then validate with inih or simply restart Forgejo and watch for startup errors.

Escalation Criteria

Proceed to escalation when:

• Network connectivity and ldapsearch succeed with the exact Forgejo settings, yet Forgejo still logs authentication failures.
• The bind DN has correct permissions but the LDAP server returns 530 (not authorized) or 532 (password expired) – these require LDAP admin inspection.
• You suspect schema changes, account lockouts, or time‑based restrictions (e.g., logon hours) that are not visible from the client side.
• After enabling Forgejo debug logging ([log] LEVEL = Debug) the logs still do not reveal the root cause.

At this point, collect the following information for the LDAP administrator:

• Exact bind DN used by Forgejo.
• Timestamp (UTC) of a failed login attempt.
• The full error message from Forgejo logs.
• Output of the successful ldapsearch query (to show the server is reachable and returns the user entry).
• Relevant LDAP server logs (if available) showing the bind attempt and any access‑control decisions.