https://github.com/gocd/gocd-ldap-authentication-plugin
LDAP authentication plugin for GoCD
https://github.com/gocd/gocd-ldap-authentication-plugin
authentication gocd ldap plugin
Last synced: 6 months ago
JSON representation
LDAP authentication plugin for GoCD
- Host: GitHub
- URL: https://github.com/gocd/gocd-ldap-authentication-plugin
- Owner: gocd
- License: apache-2.0
- Created: 2016-12-07T08:53:02.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2025-07-17T00:45:39.000Z (7 months ago)
- Last Synced: 2025-07-17T07:29:41.471Z (7 months ago)
- Topics: authentication, gocd, ldap, plugin
- Language: Java
- Homepage: https://www.gocd.org
- Size: 1.1 MB
- Stars: 7
- Watchers: 12
- Forks: 14
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# GoCD LDAP/AD Authentication Plugin
LDAP plugin which implements the GoCD [Authorization Plugin](https://plugin-api.gocd.io/current/authorization/) endpoint.
## Building the code base
To build the jar, run `./gradlew clean test assemble`
## Requirements
These plugins require GoCD version v17.5 or above.
## Installation
- From GoCD `17.5.0` onwards the plugin comes bundled along with server, hence a separate installation is not required.
## Ldap Client
The plugin uses JNDI and ApacheDs ldap client for the authentication. Defaults to `ApacheDs client`. In order to use JNDI
client use system property `use.jndi.ldap.client=true` while starting the GoCD server.
## Configuration
The plugin requires necessary configurations to connect to LDAP/AD. The configuration can be added by adding a Authorization Configuration by visting the Authorization Configuration page under *Admin > Security*.
Alternatively, the configuration can be added directly to the `config.xml` using the `` configuration.
* Example Configuration
```xml
Url
ldap://ldap-server-url
ManagerDN
cn=go,ou=Teams,dc=corporate,dc=example,dc=com
Password
secret
SearchBases
ou=Teams,dc=corporate,dc=example,dc=com
UserLoginFilter
(sAMAccountName={0})
UserSearchFilter
(|(sAMAccountName=*{0}*)(uid=*{0}*)(cn=*{0}*)(mail=*{0}*)(otherMailbox=*{0}*))
DisplayNameAttribute
displayName
EmailAttribute
mail
```
* **Url (Mandatory) :** Specify your ldap server URL. The plugin does not [support](https://github.com/gocd/gocd-ldap-authentication-plugin/issues/24) configuring certificates for connecting to LDAP server over SSL, a workaround for this issue involves importing the certificates directly into java's cacerts.
```xml
Url
ldap://ldap-server-url:1234
```
if you are trying to configure ldaps then use the url as:
```xml
Url
ldaps://ldap-server-url:1234
```
* **ManagerDN (Optional):** The LDAP/AD manager user's DN, used to connect to the LDAP/AD server.
```xml
ManagerDN
uid=admin,ou=system,dc=example,dc=com
```
* **Password (Mandatory if `ManagerDN` provided):** The LDAP/AD manager password, used to connect to the LDAP/AD server. Required only if a ManagerDN is specified.
* **SearchBases (Mandatory):** This field defines the location in the directory from which the LDAP search begins.
You can provide multiple search bases. If multiple search bases are configured the plugin would look for the user in each search base sequentially until the user is found.
> Single search base:
```xml
SearchBases
ou=users,ou=system
```
> Multiple search base
```xml
SearchBases
ou=users,ou=system
ou=employee,ou=system
```
* **UserLoginFilter (Mandatory):** It is an LDAP search filter used during authentication to lookup for a user entry matching the given expression.
In the following example the filter would search for a username matching the ```sAMAccountName``` attribute.
```xml
UserLoginFilter
(sAMAccountName={0})
```
* **UserSearchFilter (Optional):** It is an LDAP search filter used to lookup for users matching a given search term.
This is an optional configuration, the default filter used is ```(|(sAMAccountName=*{0}*)(uid=*{0}*)(cn=*{0}*)(mail=*{0}*)(otherMailbox=*{0}*))```.
```xml
UserSearchFilter
(|(sAMAccountName=*{0}*)(uid=*{0}*))
```
* **DisplayNameAttribute (Optional):** Value of this attribute is mapped to GoCD User displayname, default attribute used is ```cn```.
```xml
DisplayNameAttribute
displayName
```
* **EmailAttribute (Optional):** Value of this attribute is mapped to GoCD User mail, default value used is ```mail```.
```xml
EmailAttribute
mail
```
*Note: The plugin allows having multiple configurations to connect to different LDAP/AD servers*
```xml
...
```
## Troubleshooting
### Verify Connection
For a given Authorization Configuration verify if the plugin can connect to the LDAP/AD server. The Authorization Configuration page under *Admin > Security* gives an option to verify connection.
### Enable Debug Logs
#### If you are on GoCD version 19.6 and above:
Edit the file `wrapper-properties.conf` on your GoCD server and add the following options. The location of the `wrapper-properties.conf` can be found in the [installation documentation](https://docs.gocd.org/current/installation/installing_go_server.html) of the GoCD server.
```properties
# We recommend that you begin with the index `100` and increment the index for each system property
wrapper.java.additional.105=-Dplugin.cd.go.authentication.ldap.log.level=debug
```
For this to work it's extremely important that there are no other entries with the same index number for `wrapper.java.additional`. E.g. with the docker version in the docker-entrypoint.sh is a line that adds an item for `wrapper.java.additional.100` but _only_ after boot time.
If you're running with GoCD server 19.6 and above on docker using one of the supported GoCD server images, set the environment variable `GOCD_SERVER_JVM_OPTIONS`:
```shell
docker run -e "GOCD_SERVER_JVM_OPTIONS=-Dplugin.cd.go.authentication.ldap.log.level=debug" ...
```
#### If you are on GoCD version 19.5 and lower:
* On Linux:
Enabling debug level logging can help you troubleshoot an issue with this plugin. To enable debug level logs, edit the file `/etc/default/go-server` (for Linux) to add:
```shell
export GO_SERVER_SYSTEM_PROPERTIES="$GO_SERVER_SYSTEM_PROPERTIES -Dplugin.cd.go.authentication.ldap.log.level=debug"
```
If you're running the server via `./server.sh` script:
```shell
$ GO_SERVER_SYSTEM_PROPERTIES="-Dplugin.cd.go.authentication.ldap.log.level=debug" ./server.sh
```
* On windows:
Edit the file `config/wrapper-properties.conf` inside the GoCD Server installation directory (typically `C:\Program Files\Go Server`):
```
# config/wrapper-properties.conf
# since the last "wrapper.java.additional" index is 15, we use the next available index.
wrapper.java.additional.16=-Dplugin.cd.go.authentication.ldap.log.level=debug
```
### Known issues while upgrading to Plugin version 2.0.1-90
* A must change would be to now specify a fully qualified ManagerDN instead of just username.
* The user search base specified should return unique result for the given username.
## License
```plain
Copyright 2022 Thoughtworks, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```