diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 18:44:42 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 18:44:42 +0300 |
commit | 4555e1b21c365ed8303ffb7a3325d773c9b8bf31 (patch) | |
tree | 5423a1c7516cffe36384133ade12572cf709398d /doc/administration/auth/ldap | |
parent | e570267f2f6b326480d284e0164a6464ba4081bc (diff) |
Add latest changes from gitlab-org/gitlab@13-12-stable-eev13.12.0-rc42
Diffstat (limited to 'doc/administration/auth/ldap')
-rw-r--r-- | doc/administration/auth/ldap/index.md | 34 | ||||
-rw-r--r-- | doc/administration/auth/ldap/ldap-troubleshooting.md | 23 |
2 files changed, 28 insertions, 29 deletions
diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 0e55efba8ae..364c7cebea3 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -5,7 +5,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# General LDAP Setup +# General LDAP setup **(FREE SELF)** GitLab integrates with LDAP to support user authentication. @@ -29,7 +29,7 @@ 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 **(FREE SELF)** +## Security GitLab assumes that LDAP users: @@ -44,7 +44,7 @@ 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 **(FREE SELF)** +### User deletion If a user is deleted from the LDAP server, they are also blocked in GitLab. Users are immediately blocked from logging in. However, there is an @@ -56,13 +56,13 @@ immediately block all access. GitLab Enterprise Edition Premium supports a [configurable sync time](#adjusting-ldap-user-sync-schedule). **(PREMIUM)** -## Git password authentication **(FREE SELF)** +## 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. -## Enabling LDAP sign-in for existing GitLab users **(FREE SELF)** +## 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 @@ -73,7 +73,7 @@ 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. -## Google Secure LDAP **(FREE SELF)** +## Google Secure LDAP > Introduced in GitLab 11.9. @@ -81,7 +81,7 @@ LDAP email address, and then sign into GitLab via their LDAP credentials. 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 **(FREE SELF)** +## Configuration 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 @@ -100,7 +100,7 @@ would be on port 389. `plain` also operates on port 389. Removed values: `tls` w LDAP users must have a set email address, regardless of whether or not it's used to sign in. -### Example Configurations **(FREE SELF)** +### Example Configurations **Omnibus Configuration** @@ -163,7 +163,7 @@ production: ... ``` -### Basic Configuration Settings **(FREE SELF)** +### Basic Configuration Settings | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -190,7 +190,7 @@ Some examples of the `user_filter` field syntax: - `'(employeeType=developer)'` - `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` -### SSL Configuration Settings **(FREE SELF)** +### SSL Configuration Settings | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -200,7 +200,7 @@ Some examples of the `user_filter` field syntax: | `cert` | Client certificate | no | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` | | `key` | Client private key | no | `'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'` | -### Attribute Configuration Settings **(FREE SELF)** +### Attribute Configuration Settings 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. @@ -221,7 +221,7 @@ LDAP attributes that GitLab uses to create an account for the LDAP user. The spe | `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']` | | `sync_ssh_keys` | The LDAP attribute containing a user's public SSH key. | no | `'sshPublicKey'` or false if not set | -### Set up LDAP user filter **(FREE SELF)** +### Set up LDAP user filter 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, @@ -266,7 +266,7 @@ Support for 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 **(FREE SELF)** +#### Escaping special characters The `user_filter` DN can contain special characters. For example: @@ -297,7 +297,7 @@ The `user_filter` DN can contain special characters. For example: OU=Gitlab \28Inc\29,DC=gitlab,DC=com ``` -### Enabling LDAP username lowercase **(FREE SELF)** +### 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. @@ -335,7 +335,7 @@ the configuration option `lowercase_usernames`. By default, this configuration o 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### Disable LDAP web sign in **(FREE SELF)** +### 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 @@ -367,7 +367,7 @@ This does not disable [using LDAP credentials for Git access](#git-password-auth 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### Using encrypted credentials **(FREE SELF)** +### Using encrypted credentials Instead of having the LDAP integration credentials stored in plaintext in the configuration files, you can optionally use an encrypted file for the LDAP credentials. To use this feature, you first need to enable @@ -454,7 +454,7 @@ If initially your LDAP configuration looked like: 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -## Encryption **(FREE SELF)** +## Encryption ### TLS Server Authentication diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 9d9c01b870f..1e6684751ed 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -5,7 +5,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# LDAP Troubleshooting for Administrators +# LDAP Troubleshooting for Administrators **(FREE SELF)** ## Common Problems & Workflows @@ -27,7 +27,7 @@ Could not authenticate you from Ldapmain because "Connection timed out - user sp ``` If your configured LDAP provider and/or endpoint is offline or otherwise -unreachable by GitLab, no LDAP user will be able to authenticate and sign-in. +unreachable by GitLab, no LDAP user is able to authenticate and sign-in. GitLab does not cache or store credentials for LDAP users to provide authentication during an LDAP outage. @@ -181,14 +181,13 @@ user = User.find_by_any_email('email@example.com') user.username ``` -This will show you which user has this email address. One of two steps will -have to be taken here: +This shows you which user has this email address. One of two steps must be taken here: - To create a new GitLab user/username for this user when signing in with LDAP, remove the secondary email to remove the conflict. - To use an existing GitLab user/username for this user to use with LDAP, remove this email as a secondary email and make it a primary one so GitLab - will associate this profile to the LDAP identity. + associates this profile to the LDAP identity. The user can do either of these steps [in their profile](../../../user/profile/index.md#access-your-user-profile) or an administrator can do it. @@ -227,7 +226,7 @@ output](#example-console-output-after-a-user-sync). ##### Example console output after a user sync **(PREMIUM SELF)** -The output from a [manual user sync](#sync-all-users) will be very verbose, and a +The output from a [manual user sync](#sync-all-users) is very verbose, and a single user's successful sync can look like this: ```shell @@ -255,8 +254,8 @@ uid: John There's a lot here, so let's go over what could be helpful when debugging. -First, GitLab will look for all users that have previously -signed in with LDAP and iterate on them. Each user's sync will start with +First, GitLab looks for all users that have previously +signed in with LDAP and iterate on them. Each user's sync starts with the following line that contains the user's username and email, as they exist in GitLab now: @@ -274,7 +273,7 @@ link between this user and the configured LDAP provider(s): Identity Load (0.9ms) SELECT "identities".* FROM "identities" WHERE "identities"."user_id" = 20 AND (provider LIKE 'ldap%') LIMIT 1 ``` -The identity object will have the DN that GitLab will use to look for the user +The identity object has the DN that GitLab uses to look for the user in LDAP. If the DN isn't found, the email is used instead. We can see that this user is found in LDAP: @@ -294,18 +293,18 @@ following message instead: LDAP search error: No Such Object ``` -...in which case the user will be blocked: +...in which case the user is blocked: ```shell User Update (0.4ms) UPDATE "users" SET "state" = $1, "updated_at" = $2 WHERE "users"."id" = $3 [["state", "ldap_blocked"], ["updated_at", "2019-10-18 15:46:22.902177"], ["id", 20]] ``` -Once the user is found in LDAP the rest of the output will update the GitLab +Once the user is found in LDAP, the rest of the output updates the GitLab database with any changes. #### Query a user in LDAP -This will test that GitLab can reach out to LDAP and read a particular user. +This tests that GitLab can reach out to LDAP and read a particular user. It can expose potential errors connecting to and/or querying LDAP that may seem to fail silently in the GitLab UI. |