Configuring the GitLab tile with LDAP is handled through the LDAP tab in the GitLab tile’s settings. These settings are separate from the rest of the GitLab settings due to the complexity and size of the configuration.
There are three primary points:
- It is possible to enable and disable LDAP, while retaining your settings.
- If you provide no LDAP servers, the system automatically disables LDAP integration.
- You may configure any number of LDAP servers, handled through the
You may use any GitLab-compatible LDAP provider, including Microsoft Active Directory, Apple Open Directory, Open LDAP, and 389 Server. For the purposes of this document, we write “LDAP server”.
When LDAP is enabled and configured successfully, you have additional forms on the Sign-In page.
Below is an example where the
label field of the LDAP server setting is
All settings presented here should abide to the documentation present in the GitLab EE LDAP configuration documentation in terms of format, with the exception of lists which should be entered in comma-separated lists.
This is the primary flag for enable and disable of the LDAP configuration for LDAP within GitLab. If this checkbox is unchecked, LDAP is disabled regardless of servers being configured in the collection below it. If this checkbox is checked and no servers are provided in the collection below it, this setting is ignored.
You may disable LDAP without removing the servers provided in the collection.
LDAP Server(s) is a collection of servers configurations. To add an item, click the small
Add button to the right. To remove an item, click the small trash icon beside the item.
Each Server item has 24 fields, of which 12 are required. Of the 12 required fields, 9 are pre-filled with defaults. At minimum, the
Bind DN, and
Base DN fields need to be populated.
This is the label that is used for display and logging purposes. This is the label presented on the Sign-in page, as well as used for referencing multiple items from this configuration page in the future. This value defaults to
main, and in the sample Sign-in form pictured above, we have labelled it
LDAP. You can not have two items with the same value in
This should be the IP address for Fully-Qualified Domain Name of your LDAP server. This much be reachable for communication from your deployed Tile, please ensure that firewall rules allow this.
Port (required, default)
The port to which GitLab should connect to your LDAP server. This is most commonly
636. The default provided is
Provide the LDAP attribute that will map to a user’s login. In Active Directory, this is commonly
sAMAccountName, which is provided by default.
Encryption (required, default)
This dropdown provides selection of the encryption method used for connecting to the LDAP server. GitLab allows for
Start TLS and
Simple TLS. Please see the Limitations section of the GitLab EE LDAP documentation in regards to
Checkbox to enable SSL certificate verification if encryption method is “Start TLS” or “Simple TLS”. (Defaults to off for backward-compatibility)
Provide the SSL version for OpenSSL to use. The OpenSSL default will be used if a value is not specified.
Bind DN (required)
The full user or Distinguished Name used to authenticate (bind) to the LDAP server. Examples are
The password used for binding to the LDAP server, should one be required by the LDAP server.
LDAP Request Timeout (required, default)
This integer value, in seconds, provides the timeout to LDAP queries. This helps to avoid blocking a request if the LDAP server were to become unresponsive. A value of
0 disables this timeout, and
10 is provided by default.
Checkbox to determine if the LDAP server is expected to be an Active Directory server. This defaults to off, but should be checked if you are configuring an Active Directory server.
Allow username or email login
Allow username or email login is enabled, GitLab ignores everything after the first ’@’ in the LDAP username submitted by the user on login.
- The user enters ’email@example.com’ and 'p@ssw0rd’ as LDAP credentials;
- GitLab queries the LDAP server with 'jane.doe’ and 'p@ssw0rd’.
If you are using “uid: 'userPrincipalName’” on Active Directory you need to disable this setting, because the userPrincipalName contains an ’@’.
Block Auto-created Users
To maintain tight control over the number of active users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by the admin. This defaults to off.
Base DN (required)
The Distinguished Name that will act as the base for user searches. Example:
Filter LDAP users based on attributes. See RFC 4515 for the format.
- Allow only users who have the attribute
- Allow only specific
Attributes (required, default)
LDAP attributes that GitLab will use to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (e.g.
mail, email). Note that the user’s LDAP login will always be the attribute specified as
username: Attribute’s value to be used as the users canonical name in paths (
https://gitlab.example.com/username/) and mentions (
email: Attribute’s value that contains the user’s email address for notifications from GitLab
name,first_name,last_name: Attribute’s value that contains the user’s full name. If no full name could be found in the
name attribute, the full name is determined from the
Groups Base DN
The Distinguished Name for the base on which searches will be performed for groups. See
The name of the group that will contain users with Admin role. This is only the CN value, not a full Distinguished Name. Example:
External User Group(s)
List of groups containing users that should be considered external users. Example:
Enable SSH Public Key Sync
This checkbox controls the behavior of syncing a user’s public SSH key from an LDAP attribute. Defaults to off.
Attribute for SSH Keys
The attribute name that will contain the public SSH key of a user.