diff options
Diffstat (limited to 'doc/administration/auth/ldap.md')
| -rw-r--r-- | doc/administration/auth/ldap.md | 554 |
1 files changed, 2 insertions, 552 deletions
diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 1e91b539db5..f5565628af1 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -1,555 +1,5 @@ --- -type: reference +redirect_to: 'ldap/index.md' --- -<!-- If the change is EE-specific, put it in `ldap-ee.md`, NOT here. --> - -# 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 -- 389 Server. - -GitLab Enterprise Editions (EE) include enhanced integration, -including group membership syncing as well as multiple LDAP servers support. - -For more details about EE-specific LDAP features, see the -[LDAP Enterprise Edition documentation](ldap-ee.md). - -NOTE: **Note:** -The information on this page is relevant for both GitLab CE and EE. - -## Overview - -[LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) -stands for **Lightweight Directory Access Protocol**, which is a standard -application protocol for accessing and maintaining distributed directory -information services over an Internet Protocol (IP) network. - -## Security - -GitLab assumes that LDAP users: - -- Are not able to change their LDAP `mail`, `email`, or `userPrincipalName` attribute. - An LDAP user who is allowed to change their email on the LDAP server can potentially - [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users) - on your GitLab server. -- Have unique email addresses, otherwise it is possible for LDAP users with the same - email address to share the same GitLab account. - -We recommend against using LDAP integration if your LDAP users are -allowed to change their 'mail', 'email' or 'userPrincipalName' attribute on -the LDAP server or share email addresses. - -### User deletion - -If a user is deleted from the LDAP server, they will be blocked in GitLab as -well. Users will be immediately blocked from logging in. However, there is an -LDAP check cache time of one hour (see note) which means users that -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: **Note**: -GitLab Enterprise Edition Starter supports a -[configurable sync time](ldap-ee.md#adjusting-ldap-user-sync-schedule), -with a default of one hour. - -## Git password authentication - -LDAP-enabled users can always authenticate with Git using their GitLab username -or email and LDAP password, even if password authentication for Git is disabled -in the application settings. - -## Google Secure LDAP **(CORE ONLY)** - -> Introduced in GitLab 11.9. - -[Google Cloud Identity](https://cloud.google.com/identity/) provides a Secure -LDAP service that can be configured with GitLab for authentication and group sync. -See [Google Secure LDAP](google_secure_ldap.md) for detailed configuration instructions. - -## 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, see - [How to configure LDAP with GitLab CE](how_to_configure_ldap_gitlab_ce/index.md). -- Enterprise Editions, see - [How to configure LDAP with GitLab EE](how_to_configure_ldap_gitlab_ee/index.md). **(STARTER ONLY)** - -To enable LDAP integration you need to add your LDAP server settings in -`/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. - -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 -LDAP settings in both the old syntax and the new syntax, only the __old__ -syntax will be used by GitLab. - -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. - -NOTE: **Note:** -LDAP users must have an email address set, regardless of whether it is used to log in. - -**Omnibus configuration** - -```ruby -gitlab_rails['ldap_enabled'] = true -gitlab_rails['prevent_ldap_sign_in'] = false -gitlab_rails['ldap_servers'] = YAML.load <<-EOS # remember to close this block with 'EOS' below -## -## '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' - ## - host: '_your_ldap_server' - - ## - ## 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' - ## - 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: '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 set up properly. - ## - verify_certificates: true - - # OpenSSL::SSL::SSLContext options. - tls_options: - # 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' - # - ssl_version: '' - - # Specific SSL ciphers to use in communication with LDAP servers. - # - # Example: 'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2' - ciphers: '' - - # Client certificate - # - # Example: - # cert: | - # -----BEGIN CERTIFICATE----- - # MIIDbDCCAlSgAwIBAgIGAWkJxLmKMA0GCSqGSIb3DQEBCwUAMHcxFDASBgNVBAoTC0dvb2dsZSBJ - # bmMuMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQDEwtMREFQIENsaWVudDEPMA0GA1UE - # CxMGR1N1aXRlMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTAeFw0xOTAyMjAwNzE4 - # rntnF4d+0dd7zP3jrWkbdtoqjLDT/5D7NYRmVCD5vizV98FJ5//PIHbD1gL3a9b2MPAc6k7NV8tl - # ... - # 4SbuJPAiJxC1LQ0t39dR6oMCAMab3hXQqhL56LrR6cRBp6Mtlphv7alu9xb/x51y2x+g2zWtsf80 - # Jrv/vKMsIh/sAyuogb7hqMtp55ecnKxceg== - # -----END CERTIFICATE ----- - cert: '' - - # Client private key - # key: | - # -----BEGIN PRIVATE KEY----- - # MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC3DmJtLRmJGY4xU1QtI3yjvxO6 - # bNuyE4z1NF6Xn7VSbcAaQtavWQ6GZi5uukMo+W5DHVtEkgDwh92ySZMuJdJogFbNvJvHAayheCdN - # 7mCQ2UUT9jGXIbmksUn9QMeJVXTZjgJWJzPXToeUdinx9G7+lpVa62UATEd1gaI3oyL72WmpDy/C - # rntnF4d+0dd7zP3jrWkbdtoqjLDT/5D7NYRmVCD5vizV98FJ5//PIHbD1gL3a9b2MPAc6k7NV8tl - # ... - # +9IhSYX+XIg7BZOVDeYqlPfxRvQh8vy3qjt/KUihmEPioAjLaGiihs1Fk5ctLk9A2hIUyP+sEQv9 - # l6RG+a/mW+0rCWn8JAd464Ps9hE= - # -----END PRIVATE KEY----- - key: '' - - ## - ## 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. - ## - 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 '@'. - ## - 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). - ## - 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: '' - - ## - ## 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. - ## - 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 '@'. - ## - 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`. - ## - name: 'cn' - first_name: 'givenName' - last_name: 'sn' - - ## - ## 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 - ## - group_base: '' - - ## The CN of a group containing GitLab administrators - ## - ## Ex. administrators - ## - ## Note: Not `cn=administrators` or the full DN - ## - admin_group: '' - - ## 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: -# .... -EOS -``` - -**Source configuration** - -Use the same format as `gitlab_rails['ldap_servers']` for the contents under -`servers:` in the example below: - -```yaml -production: - # snip... - ldap: - enabled: false - prevent_ldap_sign_in: false - servers: - ## - ## '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... -``` - -## Using an LDAP filter to limit access to your GitLab server - -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, -it is sometimes necessary to filter users further. In this case, you can set up -an LDAP user filter. The filter must comply with -[RFC 4515](https://tools.ietf.org/search/rfc4515). - -**Omnibus configuration** - -```ruby -gitlab_rails['ldap_servers'] = YAML.load <<-EOS -main: - # snip... - user_filter: '(employeeType=developer)' -EOS -``` - -**Source configuration** - -```yaml -production: - ldap: - servers: - main: - # snip... - user_filter: '(employeeType=developer)' -``` - -Tip: If you want to limit access to the nested members of an Active Directory -group, you can use the following syntax: - -```plaintext -(memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com) -``` - -Find more information about this "LDAP_MATCHING_RULE_IN_CHAIN" filter at -<https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax>. Support for -nested members in the user filter should not be confused with -[group sync nested groups support](ldap-ee.md#supported-ldap-group-typesattributes). **(STARTER ONLY)** - -Please note that GitLab does not support the custom filter syntax used by -OmniAuth LDAP. - -### Escaping special characters - -The `user_filter` DN can contain special characters. For example: - -- A comma: - - ```plaintext - OU=GitLab, Inc,DC=gitlab,DC=com - ``` - -- Open and close brackets: - - ```plaintext - OU=Gitlab (Inc),DC=gitlab,DC=com - ``` - - These characters must be escaped as documented in - [RFC 4515](https://tools.ietf.org/search/rfc4515). - -- Escape commas with `\2C`. For example: - - ```plaintext - OU=GitLab\2C Inc,DC=gitlab,DC=com - ``` - -- Escape open and close brackets with `\28` and `\29`, respectively. For example: - - ```plaintext - OU=Gitlab \28Inc\29,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 -email address is the primary email address of an existing GitLab user, then -the LDAP DN will be associated with the existing user. If the LDAP email -attribute is not found in GitLab's database, a new user is created. - -In other words, if an existing GitLab user wants to enable LDAP sign-in for -themselves, they should check that their GitLab email address matches their -LDAP email address, and then sign into GitLab via their LDAP credentials. - -## Enabling LDAP username lowercase - -Some LDAP servers, depending on their configurations, can return uppercase usernames. -This can lead to several confusing issues such as creating links or namespaces with uppercase names. - -GitLab can automatically lowercase usernames provided by the LDAP server by enabling -the configuration option `lowercase_usernames`. By default, this configuration option is `false`. - -**Omnibus configuration** - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_rails['ldap_servers'] = YAML.load <<-EOS - main: - # snip... - lowercase_usernames: true - EOS - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. - -**Source configuration** - -1. Edit `config/gitlab.yaml`: - - ```yaml - production: - ldap: - servers: - main: - # snip... - lowercase_usernames: true - ``` - -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. - -## Disable LDAP web sign in - -It can be useful to prevent using LDAP credentials through the web UI when -an alternative such as SAML is preferred. This allows LDAP to be used for group -sync, while also allowing your SAML identity provider to handle additional -checks like custom 2FA. - -When LDAP web sign in is disabled, users will not see a **LDAP** tab on the sign in page. -This does not disable [using LDAP credentials for Git access](#git-password-authentication). - -**Omnibus configuration** - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_rails['prevent_ldap_sign_in'] = true - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. - -**Source configuration** - -1. Edit `config/gitlab.yaml`: - - ```yaml - production: - ldap: - prevent_ldap_sign_in: true - ``` - -1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. - -## Encryption - -### TLS Server Authentication - -There are two encryption methods, `simple_tls` and `start_tls`. - -For either encryption method, if setting `verify_certificates: false`, TLS -encryption is established with the LDAP server before any LDAP-protocol data is -exchanged but no validation of the LDAP server's SSL certificate is performed. - ->**Note**: Before GitLab 9.5, `verify_certificates: false` is the default if -unspecified. - -## Limitations - -### TLS Client Authentication - -Not implemented by `Net::LDAP`. -You should disable anonymous LDAP authentication and enable simple or SASL -authentication. The TLS client authentication setting in your LDAP server cannot -be mandatory and clients cannot be authenticated with the TLS protocol. - -## Troubleshooting - -Please see our [administrator guide to troubleshooting LDAP](ldap-troubleshooting.md). +This document was moved to [another location](ldap/index.md). |