Refactor LDAP docs
This commit is contained in:
parent
38912b528a
commit
8346092233
|
@ -1,10 +1,20 @@
|
|||
[//]: # (Do *NOT* modify this file in EE documentation. All changes in this)
|
||||
[//]: # (file should happen in CE, too. If the change is EE-specific, put)
|
||||
[//]: # (it in `ldap-ee.md`.)
|
||||
|
||||
# LDAP
|
||||
|
||||
GitLab integrates with LDAP to support user authentication.
|
||||
This integration works with most LDAP-compliant directory
|
||||
servers, including Microsoft Active Directory, Apple Open Directory, Open LDAP,
|
||||
and 389 Server. GitLab EE includes enhanced integration, including group
|
||||
membership syncing.
|
||||
and 389 Server. GitLab Enterprise Editions include enhanced integration,
|
||||
including group membership syncing as well as multiple LDAP servers support.
|
||||
|
||||
## GitLab EE
|
||||
|
||||
The information on this page is relevant for both GitLab CE and EE. For more
|
||||
details about EE-specific LDAP features, see the
|
||||
[LDAP Enterprise Edition documentation](https://docs.gitlab.com/ee/administration/auth/ldap-ee.html).
|
||||
|
||||
## Security
|
||||
|
||||
|
@ -27,8 +37,10 @@ are already logged in or are using Git over SSH will still be able to access
|
|||
GitLab for up to one hour. Manually block the user in the GitLab Admin area to
|
||||
immediately block all access.
|
||||
|
||||
>**Note**: GitLab EE supports a configurable sync time, with a default
|
||||
of one hour.
|
||||
NOTE: **Note**:
|
||||
GitLab Enterprise Edition Starter supports a
|
||||
[configurable sync time](https://docs.gitlab.com/ee/administration/auth/ldap-ee.html#adjusting-ldap-user-and-group-sync-schedules),
|
||||
with a default of one hour.
|
||||
|
||||
## Git password authentication
|
||||
|
||||
|
@ -38,19 +50,21 @@ in the application settings.
|
|||
|
||||
## Configuration
|
||||
|
||||
NOTE: **Note**:
|
||||
In GitLab Enterprise Edition Starter, you can configure multiple LDAP servers
|
||||
to connect to one GitLab server.
|
||||
|
||||
For a complete guide on configuring LDAP with GitLab Community Edition, please check
|
||||
the admin guide [How to configure LDAP with GitLab CE](how_to_configure_ldap_gitlab_ce/index.md).
|
||||
|
||||
To enable LDAP integration you need to add your LDAP server settings in
|
||||
`/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml`.
|
||||
`/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml` for Omnibus
|
||||
GitLab and installations from source respectively.
|
||||
|
||||
There is a Rake task to check LDAP configuration. After configuring LDAP
|
||||
using the documentation below, see [LDAP check Rake task](../raketasks/check.md#ldap-check)
|
||||
for information on the LDAP check Rake task.
|
||||
|
||||
>**Note**: In GitLab EE, you can configure multiple LDAP servers to connect to
|
||||
one GitLab server.
|
||||
|
||||
Prior to version 7.4, GitLab used a different syntax for configuring
|
||||
LDAP integration. The old LDAP integration syntax still works but may be
|
||||
removed in a future version. If your `gitlab.rb` or `gitlab.yml` file contains
|
||||
|
@ -61,159 +75,202 @@ The configuration inside `gitlab_rails['ldap_servers']` below is sensitive to
|
|||
incorrect indentation. Be sure to retain the indentation given in the example.
|
||||
Copy/paste can sometimes cause problems.
|
||||
|
||||
NOTE: **Note:**
|
||||
The `encryption` value `ssl` corresponds to 'Simple TLS' in the LDAP
|
||||
library. `tls` corresponds to StartTLS, not to be confused with regular TLS.
|
||||
Normally, if you specify `ssl` it will be on port 636, while `tls` (StartTLS)
|
||||
would be on port 389. `plain` also operates on port 389.
|
||||
|
||||
**Omnibus configuration**
|
||||
|
||||
```ruby
|
||||
gitlab_rails['ldap_enabled'] = true
|
||||
gitlab_rails['ldap_servers'] = YAML.load <<-EOS # remember to close this block with 'EOS' below
|
||||
main: # 'main' is the GitLab 'provider ID' of this LDAP server
|
||||
## label
|
||||
#
|
||||
# A human-friendly name for your LDAP server. It is OK to change the label later,
|
||||
# for instance if you find out it is too large to fit on the web page.
|
||||
#
|
||||
# Example: 'Paris' or 'Acme, Ltd.'
|
||||
##
|
||||
## 'main' is the GitLab 'provider ID' of this LDAP server
|
||||
##
|
||||
main:
|
||||
##
|
||||
## A human-friendly name for your LDAP server. It is OK to change the label later,
|
||||
## for instance if you find out it is too large to fit on the web page.
|
||||
##
|
||||
## Example: 'Paris' or 'Acme, Ltd.'
|
||||
##
|
||||
label: 'LDAP'
|
||||
|
||||
# Example: 'ldap.mydomain.com'
|
||||
##
|
||||
## Example: 'ldap.mydomain.com'
|
||||
##
|
||||
host: '_your_ldap_server'
|
||||
# This port is an example, it is sometimes different but it is always an integer and not a string
|
||||
|
||||
##
|
||||
## This port is an example, it is sometimes different but it is always an
|
||||
## integer and not a string.
|
||||
##
|
||||
port: 389 # usually 636 for SSL
|
||||
uid: 'sAMAccountName' # This should be the attribute, not the value that maps to uid.
|
||||
|
||||
# Examples: 'america\\momo' or 'CN=Gitlab Git,CN=Users,DC=mydomain,DC=com'
|
||||
##
|
||||
## Examples: 'america\\momo' or 'CN=Gitlab Git,CN=Users,DC=mydomain,DC=com'
|
||||
##
|
||||
bind_dn: '_the_full_dn_of_the_user_you_will_bind_with'
|
||||
password: '_the_password_of_the_bind_user'
|
||||
|
||||
# Encryption method. The "method" key is deprecated in favor of
|
||||
# "encryption".
|
||||
#
|
||||
# Examples: "start_tls" or "simple_tls" or "plain"
|
||||
#
|
||||
# Deprecated values: "tls" was replaced with "start_tls" and "ssl" was
|
||||
# replaced with "simple_tls".
|
||||
#
|
||||
##
|
||||
## Encryption method. The "method" key is deprecated in favor of
|
||||
## "encryption".
|
||||
##
|
||||
## Examples: "start_tls" or "simple_tls" or "plain"
|
||||
##
|
||||
## Deprecated values: "tls" was replaced with "start_tls" and "ssl" was
|
||||
## replaced with "simple_tls".
|
||||
##
|
||||
##
|
||||
encryption: 'plain'
|
||||
|
||||
# Enables SSL certificate verification if encryption method is
|
||||
# "start_tls" or "simple_tls". Defaults to true since GitLab 10.0 for
|
||||
# security. This may break installations upon upgrade to 10.0, that did
|
||||
# not know their LDAP SSL certificates were not setup properly. For
|
||||
# example, when using self-signed certificates, the ca_file path may
|
||||
# need to be specified.
|
||||
##
|
||||
## Enables SSL certificate verification if encryption method is
|
||||
## "start_tls" or "simple_tls". Defaults to true since GitLab 10.0 for
|
||||
## security. This may break installations upon upgrade to 10.0, that did
|
||||
## not know their LDAP SSL certificates were not setup properly.
|
||||
##
|
||||
verify_certificates: true
|
||||
|
||||
# Specifies the path to a file containing a PEM-format CA certificate,
|
||||
# e.g. if you need to use an internal CA.
|
||||
#
|
||||
# Example: '/etc/ca.pem'
|
||||
#
|
||||
ca_file: ''
|
||||
|
||||
# Specifies the SSL version for OpenSSL to use, if the OpenSSL default
|
||||
# is not appropriate.
|
||||
#
|
||||
# Example: 'TLSv1_1'
|
||||
#
|
||||
##
|
||||
## Specifies the SSL version for OpenSSL to use, if the OpenSSL default
|
||||
## is not appropriate.
|
||||
##
|
||||
## Example: 'TLSv1_1'
|
||||
##
|
||||
##
|
||||
ssl_version: ''
|
||||
|
||||
# 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.
|
||||
##
|
||||
## 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.
|
||||
##
|
||||
timeout: 10
|
||||
|
||||
# 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.
|
||||
##
|
||||
## 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.
|
||||
##
|
||||
active_directory: true
|
||||
|
||||
# If allow_username_or_email_login is enabled, GitLab will ignore everything
|
||||
# after the first '@' in the LDAP username submitted by the user on login.
|
||||
#
|
||||
# Example:
|
||||
# - the user enters 'jane.doe@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 ActiveDirectory you need to
|
||||
# disable this setting, because the userPrincipalName contains an '@'.
|
||||
##
|
||||
## If allow_username_or_email_login is enabled, GitLab will ignore everything
|
||||
## after the first '@' in the LDAP username submitted by the user on login.
|
||||
##
|
||||
## Example:
|
||||
## - the user enters 'jane.doe@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 ActiveDirectory you need to
|
||||
## disable this setting, because the userPrincipalName contains an '@'.
|
||||
##
|
||||
allow_username_or_email_login: false
|
||||
|
||||
# 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
|
||||
# (default: false).
|
||||
##
|
||||
## 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
|
||||
## (default: false).
|
||||
##
|
||||
block_auto_created_users: false
|
||||
|
||||
# Base where we can search for users
|
||||
#
|
||||
# Ex. 'ou=People,dc=gitlab,dc=example' or 'DC=mydomain,DC=com'
|
||||
#
|
||||
##
|
||||
## Base where we can search for users
|
||||
##
|
||||
## Ex. 'ou=People,dc=gitlab,dc=example' or 'DC=mydomain,DC=com'
|
||||
##
|
||||
##
|
||||
base: ''
|
||||
|
||||
# Filter LDAP users
|
||||
#
|
||||
# Format: RFC 4515 https://tools.ietf.org/search/rfc4515
|
||||
# Ex. (employeeType=developer)
|
||||
#
|
||||
# Note: GitLab does not support omniauth-ldap's custom filter syntax.
|
||||
#
|
||||
# Example for getting only specific users:
|
||||
# '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
|
||||
#
|
||||
##
|
||||
## Filter LDAP users
|
||||
##
|
||||
## Format: RFC 4515 https://tools.ietf.org/search/rfc4515
|
||||
## Ex. (employeeType=developer)
|
||||
##
|
||||
## Note: GitLab does not support omniauth-ldap's custom filter syntax.
|
||||
##
|
||||
## Example for getting only specific users:
|
||||
## '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
|
||||
##
|
||||
user_filter: ''
|
||||
|
||||
# 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'),
|
||||
# or an array of attribute names to try in order (e.g. ['mail', 'email']).
|
||||
# Note that the user's LDAP login will always be the attribute specified as `uid` above.
|
||||
##
|
||||
## 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'),
|
||||
## or an array of attribute names to try in order (e.g. ['mail', 'email']).
|
||||
## Note that the user's LDAP login will always be the attribute specified as `uid` above.
|
||||
##
|
||||
attributes:
|
||||
# The username will be 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 will be the part of the email address before the '@'.
|
||||
##
|
||||
## The username will be 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 will be the part of the email address before the '@'.
|
||||
##
|
||||
username: ['uid', 'userid', 'sAMAccountName']
|
||||
email: ['mail', 'email', 'userPrincipalName']
|
||||
|
||||
# If no full name could be found at the attribute specified for `name`,
|
||||
# the full name is determined using the attributes specified for
|
||||
# `first_name` and `last_name`.
|
||||
##
|
||||
## If no full name could be found at the attribute specified for `name`,
|
||||
## the full name is determined using the attributes specified for
|
||||
## `first_name` and `last_name`.
|
||||
##
|
||||
name: 'cn'
|
||||
first_name: 'givenName'
|
||||
last_name: 'sn'
|
||||
|
||||
# If lowercase_usernames is enabled, GitLab will lower case the username.
|
||||
##
|
||||
## If lowercase_usernames is enabled, GitLab will lower case the username.
|
||||
##
|
||||
lowercase_usernames: false
|
||||
|
||||
|
||||
##
|
||||
## EE only
|
||||
##
|
||||
|
||||
# Base where we can search for groups
|
||||
#
|
||||
# Ex. ou=groups,dc=gitlab,dc=example
|
||||
#
|
||||
## Base where we can search for groups
|
||||
##
|
||||
## Ex. ou=groups,dc=gitlab,dc=example
|
||||
##
|
||||
group_base: ''
|
||||
|
||||
# The CN of a group containing GitLab administrators
|
||||
#
|
||||
# Ex. administrators
|
||||
#
|
||||
# Note: Not `cn=administrators` or the full DN
|
||||
#
|
||||
## The CN of a group containing GitLab administrators
|
||||
##
|
||||
## Ex. administrators
|
||||
##
|
||||
## Note: Not `cn=administrators` or the full DN
|
||||
##
|
||||
admin_group: ''
|
||||
|
||||
# The LDAP attribute containing a user's public SSH key
|
||||
#
|
||||
# Ex. ssh_public_key
|
||||
#
|
||||
## An array of CNs of groups containing users that should be considered external
|
||||
##
|
||||
## Ex. ['interns', 'contractors']
|
||||
##
|
||||
## Note: Not `cn=interns` or the full DN
|
||||
##
|
||||
external_groups: []
|
||||
|
||||
##
|
||||
## The LDAP attribute containing a user's public SSH key
|
||||
##
|
||||
## Example: sshPublicKey
|
||||
##
|
||||
sync_ssh_keys: false
|
||||
|
||||
# GitLab EE only: add more LDAP servers
|
||||
# Choose an ID made of a-z and 0-9 . This ID will be stored in the database
|
||||
# so that GitLab can remember which LDAP server a user belongs to.
|
||||
# uswest2:
|
||||
# label:
|
||||
# host:
|
||||
# ....
|
||||
## GitLab EE only: add more LDAP servers
|
||||
## Choose an ID made of a-z and 0-9 . This ID will be stored in the database
|
||||
## so that GitLab can remember which LDAP server a user belongs to.
|
||||
#uswest2:
|
||||
# label:
|
||||
# host:
|
||||
# ....
|
||||
EOS
|
||||
```
|
||||
|
||||
|
@ -222,21 +279,23 @@ EOS
|
|||
Use the same format as `gitlab_rails['ldap_servers']` for the contents under
|
||||
`servers:` in the example below:
|
||||
|
||||
```
|
||||
```yaml
|
||||
production:
|
||||
# snip...
|
||||
ldap:
|
||||
enabled: false
|
||||
servers:
|
||||
main: # 'main' is the GitLab 'provider ID' of this LDAP server
|
||||
## label
|
||||
#
|
||||
# A human-friendly name for your LDAP server. It is OK to change the label later,
|
||||
# for instance if you find out it is too large to fit on the web page.
|
||||
#
|
||||
# Example: 'Paris' or 'Acme, Ltd.'
|
||||
##
|
||||
## 'main' is the GitLab 'provider ID' of this LDAP server
|
||||
##
|
||||
main:
|
||||
##
|
||||
## A human-friendly name for your LDAP server. It is OK to change the label later,
|
||||
## for instance if you find out it is too large to fit on the web page.
|
||||
##
|
||||
## Example: 'Paris' or 'Acme, Ltd.'
|
||||
label: 'LDAP'
|
||||
# snip...
|
||||
## snip...
|
||||
```
|
||||
|
||||
## Using an LDAP filter to limit access to your GitLab server
|
||||
|
@ -283,6 +342,24 @@ nested members in the user filter should not be confused with
|
|||
Please note that GitLab does not support the custom filter syntax used by
|
||||
omniauth-ldap.
|
||||
|
||||
### Escaping special characters
|
||||
|
||||
If the `user_filter` DN contains special characters. For example, a comma:
|
||||
|
||||
```
|
||||
OU=GitLab, Inc,DC=gitlab,DC=com
|
||||
```
|
||||
|
||||
This character needs to be escaped as documented in [RFC 4515](https://tools.ietf.org/search/rfc4515).
|
||||
|
||||
Due to the way the string is parsed, the special character needs to be converted
|
||||
to hex and `\\5C\\` (`5C` = `\` in hex) added before it.
|
||||
As an example the above DN would look like
|
||||
|
||||
```
|
||||
OU=GitLab\\5C\\2C Inc,DC=gitlab,DC=com
|
||||
```
|
||||
|
||||
## Enabling LDAP sign-in for existing GitLab users
|
||||
|
||||
When a user signs in to GitLab with LDAP for the first time, and their LDAP
|
||||
|
|
Loading…
Reference in New Issue