| `label`| A human-friendly name for your LDAP server. It is displayed on your sign-in page. | yes | `'Paris'` or `'Acme, Ltd.'` |
| `label` | A human-friendly name for your LDAP server. It is displayed on your sign-in page. | **{check-circle}** Yes | `'Paris'` or `'Acme, Ltd.'` |
| `host`| IP address or domain name of your LDAP server. | yes | `'ldap.mydomain.com'` |
| `host` | IP address or domain name of your LDAP server. | **{check-circle}** Yes | `'ldap.mydomain.com'` |
| `port`| The port to connect with on your LDAP server. Always an integer, not a string. | yes | `389` or `636` (for SSL) |
| `port` | The port to connect with on your LDAP server. Always an integer, not a string. | **{check-circle}** Yes | `389` or `636` (for SSL) |
| `uid`| LDAP attribute for username. Should be the attribute, not the value that maps to the `uid`. | yes | `'sAMAccountName'` or `'uid'` or `'userPrincipalName'` |
| `uid` | LDAP attribute for username. Should be the attribute, not the value that maps to the `uid`. | **{check-circle}** Yes | `'sAMAccountName'` or `'uid'` or `'userPrincipalName'` |
| `bind_dn`| The full DN of the user you bind with. | no | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` |
| `bind_dn` | The full DN of the user you bind with. | **{dotted-circle}** No | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` |
| `password`| The password of the bind user. | no | `'your_great_password'` |
| `password` | The password of the bind user. | **{dotted-circle}** No | `'your_great_password'` |
| `encryption`| Encryption method. The `method` key is deprecated in favor of `encryption`. | yes | `'start_tls'` or `'simple_tls'` or `'plain'` |
| `encryption` | Encryption method. The `method` key is deprecated in favor of `encryption`. | **{check-circle}** Yes | `'start_tls'` or `'simple_tls'` or `'plain'` |
| `verify_certificates` | Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. Defaults to true. | no | boolean |
| `verify_certificates` | Enables SSL certificate verification if encryption method is `start_tls` or `simple_tls`. Defaults to true. | **{dotted-circle}** No | boolean |
| `timeout`| Set a timeout, in seconds, for LDAP queries. This helps avoid blocking a request if the LDAP server becomes unresponsive. A value of `0` means there is no timeout. (default: `10`) | no | `10` or `30` |
| `timeout` | Set a timeout, in seconds, for LDAP queries. This helps avoid blocking a request if the LDAP server becomes unresponsive. A value of `0` means there is no timeout. (default: `10`) | **{dotted-circle}** No | `10` or `30` |
| `active_directory` | This setting specifies if LDAP server is Active Directory LDAP server. For non-AD servers it skips the AD specific queries. If your LDAP server is not AD, set this to false. | no | boolean |
| `active_directory` | This setting specifies if LDAP server is Active Directory LDAP server. For non-AD servers it skips the AD specific queries. If your LDAP server is not AD, set this to false. | **{dotted-circle}** No | boolean |
| `allow_username_or_email_login` | If enabled, GitLab ignores everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you need to disable this setting, because the userPrincipalName contains an `@`. | no | boolean |
| `allow_username_or_email_login` | If enabled, GitLab ignores everything after the first `@` in the LDAP username submitted by the user on sign-in. If you are using `uid: 'userPrincipalName'` on ActiveDirectory you need to disable this setting, because the userPrincipalName contains an `@`. | **{dotted-circle}** No | boolean |
| `block_auto_created_users` | To maintain tight control over the number of billable users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by an administrator (default: false). | no | boolean |
| `block_auto_created_users` | To maintain tight control over the number of billable users on your GitLab installation, enable this setting to keep new users blocked until they have been cleared by an administrator (default: false). | **{dotted-circle}** No | boolean |
| `base` | Base where we can search for users. | yes | `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` |
| `base` | Base where we can search for users. | **{check-circle}** Yes | `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` |
| `user_filter`| Filter LDAP users. Format: [RFC 4515](https://tools.ietf.org/search/rfc4515) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | no | For examples, read [Examples of user filters](#examples-of-user-filters). |
| `user_filter` | Filter LDAP users. Format: [RFC 4515](https://tools.ietf.org/search/rfc4515) Note: GitLab does not support `omniauth-ldap`'s custom filter syntax. | **{dotted-circle}** No | For examples, read [Examples of user filters](#examples-of-user-filters). |
| `lowercase_usernames` | If lowercase_usernames is enabled, GitLab converts the name to lower case. | no | boolean |
| `lowercase_usernames` | If enabled, GitLab converts the name to lower case. | **{dotted-circle}** No | boolean |
#### Examples of user filters
#### Examples of user filters
...
@@ -192,41 +184,44 @@ Some examples of the `user_filter` field syntax:
...
@@ -192,41 +184,44 @@ Some examples of the `user_filter` field syntax:
| `ca_file`| Specifies the path to a file containing a PEM-format CA certificate, for example, if you need to use an internal CA. | no | `'/etc/ca.pem'` |
| `ca_file` | Specifies the path to a file containing a PEM-format CA certificate, for example, if you need to use an internal CA. | **{dotted-circle}** No | `'/etc/ca.pem'` |
| `ssl_version` | Specifies the SSL version for OpenSSL to use, if the OpenSSL default is not appropriate. | no | `'TLSv1_1'` |
| `ssl_version` | Specifies the SSL version for OpenSSL to use, if the OpenSSL default is not appropriate. | **{dotted-circle}** No | `'TLSv1_1'` |
| `ciphers`| Specific SSL ciphers to use in communication with LDAP servers. | no | `'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'` |
| `ciphers` | Specific SSL ciphers to use in communication with LDAP servers. | **{dotted-circle}** No | `'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'` |
LDAP attributes that GitLab uses to create an account for the LDAP user. The specified attribute can either be the attribute name as a string (for example, `'mail'`), or an array of attribute names to try in order (for example, `['mail', 'email']`). Note that the user's LDAP sign-in is the attribute specified as `uid` above.
LDAP attributes that GitLab uses to create an account for the LDAP user. The specified
attribute can either be the attribute name as a string (for example, `'mail'`), or an
array of attribute names to try in order (for example, `['mail', 'email']`). Note that
the user's LDAP sign-in is the attribute specified as `uid` above.
| `username`| The username is used in paths for the user's own projects (like `gitlab.example.com/username/project`) and when mentioning them in issues, merge request and comments (like `@username`). If the attribute specified for `username` contains an email address, the GitLab username is part of the email address before the `@`. | no | `['uid', 'userid', 'sAMAccountName']` |
| `username` | The username is used in paths for the user's own projects (like `gitlab.example.com/username/project`) and when mentioning them in issues, merge request and comments (like `@username`). If the attribute specified for `username` contains an email address, the GitLab username is part of the email address before the `@`. | **{dotted-circle}** No | `['uid', 'userid', 'sAMAccountName']` |
| `email`| LDAP attribute for user email. | no | `['mail', 'email', 'userPrincipalName']` |
| `email` | LDAP attribute for user email. | **{dotted-circle}** No | `['mail', 'email', 'userPrincipalName']` |
| `name`| LDAP attribute for user display name. If `name` is blank, the full name is taken from the `first_name` and `last_name`. | no | Attributes `'cn'`, or `'displayName'` commonly carry full names. Alternatively, you can force the use of `first_name` and `last_name` by specifying an absent attribute such as `'somethingNonExistent'`. |
| `name` | LDAP attribute for user display name. If `name` is blank, the full name is taken from the `first_name` and `last_name`. | **{dotted-circle}** No | Attributes `'cn'`, or `'displayName'` commonly carry full names. Alternatively, you can force the use of `first_name` and `last_name` by specifying an absent attribute such as `'somethingNonExistent'`. |
| `first_name` | LDAP attribute for user first name. Used when the attribute configured for `name` does not exist. | no | `'givenName'` |
| `first_name` | LDAP attribute for user first name. Used when the attribute configured for `name` does not exist. | **{dotted-circle}** No | `'givenName'` |
| `last_name`| LDAP attribute for user last name. Used when the attribute configured for `name` does not exist. | no | `'sn'` |
| `last_name` | LDAP attribute for user last name. Used when the attribute configured for `name` does not exist. | **{dotted-circle}** No | `'sn'` |
| `group_base`| Base used to search for groups. | no | `'ou=groups,dc=gitlab,dc=example'` |
| `group_base` | Base used to search for groups. | **{dotted-circle}** No | `'ou=groups,dc=gitlab,dc=example'` |
| `admin_group`| The CN of a group containing GitLab administrators. Note: Not `cn=administrators` or the full DN. | no | `'administrators'` |
| `admin_group` | The CN of a group containing GitLab administrators. Note: Not `cn=administrators` or the full DN. | **{dotted-circle}** No | `'administrators'` |
| `external_groups` | An array of CNs of groups containing users that should be considered external. Note: Not `cn=interns` or the full DN. | no | `['interns', 'contractors']` |
| `external_groups` | An array of CNs of groups containing users that should be considered external. Note: Not `cn=interns` or the full DN. | **{dotted-circle}** No | `['interns', 'contractors']` |
| `sync_ssh_keys`| The LDAP attribute containing a user's public SSH key. | no | `'sshPublicKey'` or false if not set |
| `sync_ssh_keys` | The LDAP attribute containing a user's public SSH key. | **{dotted-circle}** No | `'sshPublicKey'` or false if not set |
### Set up LDAP user filter
### Set up LDAP user filter
If you want to limit all GitLab access to a subset of the LDAP users on your
If you want to limit all GitLab access to a subset of the LDAP users on your
LDAP server, the first step should be to narrow the configured `base`. However,
LDAP server, the first step should be to narrow the configured `base`. However,
it is sometimes necessary to filter users further. In this case, you can set up
it's sometimes necessary to further filter users. In this case, you can set
an LDAP user filter. The filter must comply with
up an LDAP user filter. The filter must comply with
If you configure multiple LDAP servers, use a unique naming convention for the `label` section of each entry. That label is used as the display name of the tab shown on the sign-in page.
If you configure multiple LDAP servers, use a unique naming convention for the
`label` section of each entry. That label is used as the display name of the tab
shown on the sign-in page.
## User sync **(PREMIUM SELF)**
## User sync **(PREMIUM SELF)**
...
@@ -545,13 +541,13 @@ For more information, see [Bitmask Searches in LDAP](https://ctovswild.com/2009/
...
@@ -545,13 +541,13 @@ For more information, see [Bitmask Searches in LDAP](https://ctovswild.com/2009/
<!-- vale gitlab.Spelling = YES -->
<!-- vale gitlab.Spelling = YES -->
The user is set to an `ldap_blocked` state in GitLab if the previous conditions
The user is set to an `ldap_blocked` state in GitLab if the previous conditions
fail. This means the user is not able to sign in or push/pull code.
fail. This means the user cannot sign in or push or pull code.
The process also updates the following user information:
The process also updates the following user information:
- Email address.
- Email address
-If `sync_ssh_keys` is set, SSH public keys.
-SSH public keys (if `sync_ssh_keys` is set)
-If Kerberos is enabled, Kerberos identity.
-Kerberos identity (if Kerberos is enabled)
The LDAP sync process:
The LDAP sync process:
...
@@ -643,7 +639,8 @@ or more LDAP group links](#adding-group-links).
...
@@ -643,7 +639,8 @@ or more LDAP group links](#adding-group-links).
### Adding group links **(PREMIUM SELF)**
### Adding group links **(PREMIUM SELF)**
For information on adding group links via CNs and filters, refer to [the GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap).
For information on adding group links by using CNs and filters, refer to the
[GitLab groups documentation](../../../user/group/index.md#manage-group-memberships-via-ldap).
### Administrator sync **(PREMIUM SELF)**
### Administrator sync **(PREMIUM SELF)**
...
@@ -705,8 +702,8 @@ When enabled, the following applies:
...
@@ -705,8 +702,8 @@ When enabled, the following applies:
To enable it you need to:
To enable it you need to:
1.[Enable LDAP](#configuration)
1.[Enable LDAP](#configuration)
1. Go to **Admin Area > Settings > Visibility and access controls**.
1. Go to the Admin Area (**{admin}**) and select **Settings > Visibility and access controls**.
1.Make sure the **Lock memberships to LDAP synchronization** checkbox is selected.
1.Ensure the **Lock memberships to LDAP synchronization** checkbox is selected.
### Adjusting LDAP group sync schedule **(PREMIUM SELF)**
### Adjusting LDAP group sync schedule **(PREMIUM SELF)**
...
@@ -717,13 +714,13 @@ The values shown are in cron format. If needed, you can use a
...
@@ -717,13 +714,13 @@ The values shown are in cron format. If needed, you can use a
WARNING:
WARNING:
Do not start the sync process too frequently as this
Do not start the sync process too frequently as this
could lead to multiple syncs running concurrently. This is primarily a concern
could lead to multiple syncs running concurrently. This is primarily a concern
for installations with a large number of LDAP users. Please review the
for installations with a large number of LDAP users. Review the
[LDAP group sync benchmark metrics](#benchmarks) to see how
[LDAP group sync benchmark metrics](#benchmarks) to see how
your installation compares before proceeding.
your installation compares before proceeding.
You can manually configure LDAP group sync times by setting the
You can manually configure LDAP group sync times by setting the
following configuration values. The example below shows how to set group
following configuration values. The example below shows how to set group
sync to run once every 2 hours at the top of the hour.
sync to run once every two hours at the top of the hour.
**Omnibus installations**
**Omnibus installations**
...
@@ -786,15 +783,14 @@ task.
...
@@ -786,15 +783,14 @@ task.
### Group sync technical details
### Group sync technical details
There is a lot going on with group sync 'under the hood'. This section
This section outlines what LDAP queries are executed and what behavior you
outlines what LDAP queries are executed and what behavior you can expect
can expect from group sync.
from group sync.
Group member access are downgraded from a higher level if their LDAP group
Group member access are downgraded from a higher level if their LDAP group
membership changes. For example, if a user has 'Owner' rights in a group and the
membership changes. For example, if a user the Owner role in a group and the
next group sync reveals they should only have 'Developer' privileges, their
next group sync reveals they should only have the Developer role, their
access is adjusted accordingly. The only exception is if the user is the
access is adjusted accordingly. The only exception is if the user is the
*last* owner in a group. Groups need at least one owner to fulfill
last owner in a group. Groups need at least one owner to fulfill
administrative duties.
administrative duties.
#### Supported LDAP group types/attributes
#### Supported LDAP group types/attributes
...
@@ -805,18 +801,20 @@ GitLab supports LDAP groups that use member attributes:
...
@@ -805,18 +801,20 @@ GitLab supports LDAP groups that use member attributes:
-`submember`
-`submember`
-`uniquemember`
-`uniquemember`
-`memberof`
-`memberof`
-`memberuid`.
-`memberuid`
This means group sync supports (at least) LDAP groups with the following object
classes:
This means group sync supports, at least, LDAP groups with the following object classes:
-`groupOfNames`
`groupOfNames`, `posixGroup`, and `groupOfUniqueNames`.
-`posixGroup`
-`groupOfUniqueNames`
Other object classes should work fine as long as members
Other object classes should work if members are defined as one of the
are defined as one of the mentioned attributes. This also means GitLab supports
mentioned attributes.
Microsoft Active Directory, Apple Open Directory, Open LDAP, and 389 Server.
Other LDAP servers should work, too.
Active Directory also supports nested groups. Group sync recursively
Active Directory supports nested groups. Group sync recursively resolves
resolves membership if `active_directory: true` is set in the configuration file.
membership if `active_directory: true` is set in the configuration file.
##### Nested group memberships
##### Nested group memberships
...
@@ -842,7 +840,7 @@ Group sync was written to be as performant as possible. Data is cached, database
...
@@ -842,7 +840,7 @@ Group sync was written to be as performant as possible. Data is cached, database
queries are optimized, and LDAP queries are minimized. The last benchmark run
queries are optimized, and LDAP queries are minimized. The last benchmark run
revealed the following metrics:
revealed the following metrics:
For 20000 LDAP users, 11000 LDAP groups and 1000 GitLab groups with 10
For 20,000 LDAP users, 11,000 LDAP groups, and 1,000 GitLab groups with 10
LDAP group links each:
LDAP group links each:
- Initial sync (no existing members assigned in GitLab) took 1.8 hours
- Initial sync (no existing members assigned in GitLab) took 1.8 hours
...
@@ -855,4 +853,4 @@ network and LDAP server response time affects these metrics.
...
@@ -855,4 +853,4 @@ network and LDAP server response time affects these metrics.
## Troubleshooting
## Troubleshooting
Please see our [administrator guide to troubleshooting LDAP](ldap-troubleshooting.md).
See our [administrator guide to troubleshooting LDAP](ldap-troubleshooting.md).
