Enable LDAP Authentication in Forgejo: A Step‑by‑Step Guide

Desired Outcome

Configure Forgejo to authenticate users against an LDAP/Active Directory server so that existing Forgejo accounts are bypassed and new users are created automatically with attributes pulled from LDAP.

Prerequisites

• A reachable LDAP/AD server with a service account that can perform searches and bind.
• Network connectivity from the Forgejo host to the LDAP server on the required port (usually 389 for plain LDAP or 636 for LDAPS).
• Administrative access to Forgejo (either via the web UI or the app.ini file).
• Knowledge of the LDAP attributes used for username, email, and display name (e.g., uid, mail, displayName).
• Optional: TLS certificates if using LDAPS.

Focused Procedure

1. Verify LDAP Connectivity

   From the Forgejo host, test connectivity:

   # Plain LDAP (port 389)
   telnet ldap.example.com 389
   # LDAPS (port 636)
   openssl s_client -connect ldap.example.com:636 -servername ldap.example.com
   

   Both commands should establish a connection (or a TLS handshake). If they fail, resolve network or firewall issues before proceeding.

2. Gather LDAP Settings

   Collect the following values from your directory administrator:

   • Server URL – e.g., ldap://ldap.example.com:389 or ldaps://ldap.example.com:636
   • Base DN – the search root, e.g., dc=example,dc=com
   • Bind DN – the service account DN, e.g., cn=forgejo,ou=Service Accounts,dc=example,dc=com
   • Bind Password – the password for the Bind DN.
   • User Filter – LDAP filter to locate users, e.g., (objectClass=person) or more specific like (memberOf=cn=forgejo-users,ou=Groups,dc=example,dc=com).
   • Username Attribute – attribute that maps to Forgejo username, e.g., uid.
   • Email Attribute – attribute for email, e.g., mail.
   • Display Name Attribute – attribute for full name, e.g., displayName.

3. Configure LDAP via the Admin UI (recommended for quick setup)

   1. Log in as a system administrator. 2. Navigate to Site Settings > Authentication > LDAP. 3. Enable LDAP by checking Enable LDAP authentication. 4. Fill in the fields using the values gathered above. 5. Optionally, enable Use TLS and upload the CA certificate if using LDAPS. 6. Click Save.

   Forgejo will immediately attempt to connect to the LDAP server and validate the Bind DN. A success message will appear; otherwise, review the error and correct the settings.

4. Configure LDAP via app.ini (for scripted or production deployments)

   Locate the [Auth.LDAP] section in app.ini (create it if missing) and add:

   [Auth.LDAP]
   Enabled = true
   ServerURL = ldap://ldap.example.com:389
   BaseDN = dc=example,dc=com
   BindDN = cn=forgejo,ou=Service Accounts,dc=example,dc=com
   BindPassword = <password>
   UserFilter = (objectClass=person)
   UsernameAttribute = uid
   EmailAttribute = mail
   DisplayNameAttribute = displayName
   UseTLS = false
   # UseTLS = true   # Uncomment if using LDAPS
   # TLSCACert = /path/to/ca.pem  # Path to CA cert if needed
   

   After editing, restart the Forgejo service to apply changes.

5. Validate the Configuration

   1. Attempt to log in with a known LDAP account that does not yet exist in Forgejo. The login page should accept the credentials, and upon success, Forgejo will create a new user record. 2. Verify that the user’s name and email match LDAP attributes by viewing the profile. 3. Check the Forgejo logs for an entry similar to:

   [2026-10-15 06:45:12] INFO  LDAP authentication succeeded for user jdoe
   

   4. Ensure that a local account with the same username cannot log in without LDAP. This confirms LDAP is the primary source.

6. Rollback (if needed)

   To disable LDAP, either uncheck the Enable LDAP authentication toggle in the UI or set Enabled = false in app.ini and restart. Existing local accounts remain functional.

Expected Checks and Recovery Options

• Connectivity Check – Use telnet or openssl s_client as shown. If the connection fails, verify firewall rules and DNS resolution.
• Bind DN Validation – If Forgejo logs “Unable to bind LDAP server”, double‑check the Bind DN and password. A common mistake is using an account without read permissions on the Base DN.
• User Filter Accuracy – An overly broad filter may create duplicate accounts. Test the filter in an LDAP browser (e.g., Apache Directory Studio) to ensure it returns only expected users.
• Attribute Mapping – If the user’s email or name appears blank, confirm that the LDAP attributes exist and match the names used in the config.
• TLS Issues – When UseTLS = true, missing or mismatched CA certificates will cause a “certificate verify failed” error. Provide the correct CA file path or disable TLS only for testing (not recommended in production).

Limitations

• Forgejo does not enforce LDAP password policies; ensure your directory’s policy meets your security requirements.
• Group membership sync is not automatic; you must configure group settings if you need role‑based access.
• Disabling LDAP does not delete users created via LDAP; manual cleanup may be required.

Practical Verification Checklist

Check	Method
LDAP server reachable	telnet/openssl test
Bind DN valid	Forgejo log entry “LDAP authentication succeeded”
User created on first login	Login with LDAP user, view profile
Local account blocked for LDAP user	Attempt login with same username but wrong password
TLS certificate accepted	Check log for no TLS errors

Conclusion

Enabling LDAP in Forgejo is straightforward once you have the necessary server details. By following the steps above, you can centralize authentication, reduce password fatigue, and keep user data in sync with your directory. Always test with a non‑critical account first and review logs for any authentication failures.