Discussion and Questions on Local/AD/LDAP Authentication

[1saac-k]

Is your feature request related to a problem? Please describe.

Currently, git-proxy supports three authentication mechanisms: local, Active Directory (AD), and OpenID Connect (OIDC). However, there are gaps that make it difficult for small-scale deployments and trial users:

1. Local authentication has limited functionality—users can be added via API/CLI (as of late last year; feat: Create admin protected endpoint for creating users #981), but there's no way to delete users and no WebUI is provided.
2. AD authentication is complex and unfamiliar to most developers, requiring significant effort to set up for initial users.

These limitations create friction for first-time users trying to evaluate or deploy git-proxy in small environments.

Describe the solution you'd like

Add LDAP authentication support to git-proxy, with a focus on lightweight LDAP solutions suitable for small-scale environments. Specifically:

1. Provide a docker-compose example configuration using a lightweight LDAP server (e.g., lldap) with an integrated GUI.
2. This would allow users to quickly test LDAP authentication without the complexity of full Active Directory.
3. Similar to how MongoDB is included in the existing docker-compose setup, a functional LDAP server in docker-compose would lower the barrier to entry for new users.

Describe alternatives you've considered

1. Enhance local authentication: Add user deletion capability and implement a WebUI.
2. Improve AD documentation/examples: Provide a working AD server in docker-compose—I've successfully integrated OpenLDAP and phpLDAPadmin (WebUI) with git-proxy, and if you think it would be helpful, I'll submit a PR with a complete example including docker-compose and LDIF configuration.

Additional context

Is my understanding correct? I'd appreciate your feedback and thoughts on this.

[kriswest]

My understanding is that LDAP is supported through passport, but labelled as Active Directory support. We use the following config to connect to an LDAP server:

"authentication": [
    {
      "type": "ActiveDirectory",
      "enabled": true,
      "adminGroup": "AdminGroupName",
      "userGroup": "UserGroupName",
      "domain": "DomainName",
      "adConfig": {
        "url": "ldaps://ldap.server.net:port",
        "baseDN": "DC=something,DC=net",
        "username": "ServiceUserName",
        "password": "**********",
        "searchBase": "DC=something,DC=net"
      }
    }
  ],

For a full ist of the config options for the adConfig element, see: https://www.npmjs.com/package/activedirectory2#activedirectoryoptions (as directed by the config reference ).

I agree that the docs are obtuse and could do with a better explanation and examples.

I also agree that the built in database auth option could be more complete and offer the ability to create, delete and lock users as needed, through the admin UI.

[1saac-k]

@kriswest Thanks for the response.

I've successfully integrated OpenLDAP and phpLDAPadmin (WebUI) with git-proxy ..snip..

When integrating with OpenLDAP, I did use activedirectory2 (ad2) as well.

I attempted to integrate lldap using ad2, but it did not work. ad2 is a wrapper around ldapjs that provides convenience methods tailored to Active Directory. These methods internally rely on AD-specific schema attributes such as sAMAccountName, which are not present in lldap's schema. Using ldapjs directly, with configurable search filters and attribute mappings, would likely achieve compatibility with lldap and other LDAP servers.

ad2 also has a separate issue: it is a deprecated package, and its last update was 3 years ago.
I proposed adding LDAP support, and I believe that replacing the AD library with a generic LDAP library (such as ldapjs or another alternative) would allow us to support all kinds of LDAP servers as well as AD. What I'm proposing is not specifically to support lldap, but to broaden the range of supported LDAP servers.

[kriswest]

I have no objection to that being done as long we can support the same use cases and can use the same config format (to avoid a breaking change necessitating a major release). If the config format is problematic it may just be a case of adding an additional ldap auth type.

[1saac-k]

@kriswest I also agree with your opinion that backward compatibility should be considered. As you mentioned, I think a good approach would be to add a new LDAP auth type verify that existing AD integration works properly with the newly added LDAP auth type, and then gradually consolidate into the LDAP auth type. If there are any issues, we can simply keep the existing AD auth type in place.

[1saac-k]

I looked into libraries that could be used for LDAP support. I'm sharing what I found for anyone interested in this topic. Please note that I am not a authentication expert, so there may be things I've misunderstood.

• ldapjs, which ad2 depends on, is also deprecated
  • https://www.npmjs.com/package/ldapjs
• ldapts looks like a viable alternative to ldapjs
  • https://www.npmjs.com/package/ldapts
  • https://github.com/ldapts/ldapts
• There is an ldap-authentication library that acts as a wrapper around ldapts (I understand it as a similar layer to ad2)
  • https://www.npmjs.com/package/ldap-authentication
  • https://github.com/shaozi/ldap-authentication
• There is no direct replacement for passport-activedirectory that follows the Passport strategy pattern. However, there is a library called passport-custom
  • https://www.npmjs.com/package/passport-custom
  • https://github.com/mbell8903/passport-custom
• Using passport-custom, it seems straightforward to implement Passport logic for either ldapts or ldap-authentication
  • Passport for ldap-authentication: https://github.com/shaozi/passport-ldap-example
• To summarize: either ldapts + passport-custom, or ldap-authentication + passport-custom
  • As I understand it, ldap-authentication does not provide group membership checks, so we would need to use ldapts directly for that anyway
• For reference: Cisco BPA (Business Process Automation) also has a history of replacing the old passport-ldapauth library with ldapts + passport-custom
  • https://www.cisco.com/c/en/us/support/docs/bpa/v412-patch/release-notes-v412-patch.html

  • Previously, during BPA Installation, the auth-service Lightweight Directory Access Protocol (LDAP) implementation imported an outdated library posing a security risk. This issue has been resolved by replacing “passport-ldapauth” with “passport-custom and ldapts package”.