diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 13:34:06 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 13:34:06 +0300 |
commit | 859a6fb938bb9ee2a317c46dfa4fcc1af49608f0 (patch) | |
tree | d7f2700abe6b4ffcb2dcfc80631b2d87d0609239 /doc/administration/auth/ldap | |
parent | 446d496a6d000c73a304be52587cd9bbc7493136 (diff) |
Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc42
Diffstat (limited to 'doc/administration/auth/ldap')
-rw-r--r-- | doc/administration/auth/ldap/google_secure_ldap.md | 2 | ||||
-rw-r--r-- | doc/administration/auth/ldap/index.md | 71 | ||||
-rw-r--r-- | doc/administration/auth/ldap/ldap-troubleshooting.md | 34 |
3 files changed, 56 insertions, 51 deletions
diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 6fecf74d935..2b75d864352 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.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 --- -# Google Secure LDAP **(CORE ONLY)** +# Google Secure LDAP **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46391) in GitLab 11.9. diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index de0f123acf1..466ae8e108c 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -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 **(CORE ONLY)** +## Security **(FREE SELF)** 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 **(CORE ONLY)** +### User deletion **(FREE SELF)** 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 @@ -53,16 +53,16 @@ are already logged in or are using Git over SSH are be able to access GitLab for up to one hour. Manually block the user in the GitLab Admin Area to immediately block all access. -GitLab Enterprise Edition Starter supports a -[configurable sync time](#adjusting-ldap-user-sync-schedule). **(STARTER)** +GitLab Enterprise Edition Premium supports a +[configurable sync time](#adjusting-ldap-user-sync-schedule). **(PREMIUM)** -## Git password authentication **(CORE ONLY)** +## Git password authentication **(FREE SELF)** 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 **(CORE ONLY)** +## Enabling LDAP sign-in for existing GitLab users **(FREE SELF)** 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 **(CORE ONLY)** +## Google Secure LDAP **(FREE SELF)** > 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 **(CORE ONLY)** +## Configuration **(FREE SELF)** 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 **(CORE ONLY)** +### Example Configurations **(FREE SELF)** **Omnibus Configuration** @@ -163,7 +163,7 @@ production: ... ``` -### Basic Configuration Settings **(CORE ONLY)** +### Basic Configuration Settings **(FREE SELF)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -183,7 +183,7 @@ production: | `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 | `'(employeeType=developer)'` or `'(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'` | | `lowercase_usernames` | If lowercase_usernames is enabled, GitLab converts the name to lower case. | no | boolean | -### SSL Configuration Settings **(CORE ONLY)** +### SSL Configuration Settings **(FREE SELF)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -193,7 +193,7 @@ production: | `cert` | Client certificate | no | `'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'` | | `key` | Client private key | no | `'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'` | -### Attribute Configuration Settings **(CORE ONLY)** +### Attribute Configuration Settings **(FREE SELF)** 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. @@ -205,7 +205,7 @@ LDAP attributes that GitLab uses to create an account for the LDAP user. The spe | `first_name` | LDAP attribute for user first name. Used when the attribute configured for `name` does not exist. | no | `'givenName'` | | `last_name` | LDAP attribute for user last name. Used when the attribute configured for `name` does not exist. | no | `'sn'` | -### LDAP Sync Configuration Settings **(STARTER ONLY)** +### LDAP Sync Configuration Settings **(PREMIUM SELF)** | Setting | Description | Required | Examples | | ------- | ----------- | -------- | -------- | @@ -214,7 +214,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 **(CORE ONLY)** +### Set up LDAP user filter **(FREE SELF)** 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, @@ -254,12 +254,12 @@ group, you can use the following syntax: For more information about this "LDAP_MATCHING_RULE_IN_CHAIN" filter, see the following [Microsoft Search Filter Syntax](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) document. Support for nested members in the user filter should not be confused with -[group sync nested groups support](#supported-ldap-group-typesattributes). **(STARTER ONLY)** +[group sync nested groups support](#supported-ldap-group-typesattributes). **(PREMIUM SELF)** Please note that GitLab does not support the custom filter syntax used by OmniAuth LDAP. -#### Escaping special characters **(CORE ONLY)** +#### Escaping special characters **(FREE SELF)** The `user_filter` DN can contain special characters. For example: @@ -290,7 +290,7 @@ The `user_filter` DN can contain special characters. For example: OU=Gitlab \28Inc\29,DC=gitlab,DC=com ``` -### Enabling LDAP username lowercase **(CORE ONLY)** +### Enabling LDAP username lowercase **(FREE SELF)** 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. @@ -328,7 +328,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 **(CORE ONLY)** +### Disable LDAP web sign in **(FREE SELF)** 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 @@ -360,7 +360,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 **(CORE ONLY)** +### Using encrypted credentials **(FREE SELF)** 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 @@ -447,7 +447,7 @@ If initially your LDAP configuration looked like: 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -## Encryption **(CORE ONLY)** +## Encryption **(FREE SELF)** ### TLS Server Authentication @@ -467,7 +467,7 @@ 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. -## Multiple LDAP servers **(STARTER ONLY)** +## Multiple LDAP servers **(PREMIUM SELF)** With GitLab Enterprise Edition Starter, you can configure multiple LDAP servers that your GitLab instance connects to. @@ -515,7 +515,7 @@ gitlab_rails['ldap_servers'] = { 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 **(STARTER ONLY)** +## User sync **(PREMIUM SELF)** Once per day, GitLab runs a worker to check and update GitLab users against LDAP. @@ -530,7 +530,12 @@ The process executes the following access checks: In Active Directory, a user is marked as disabled/blocked if the user account control attribute (`userAccountControl:1.2.840.113556.1.4.803`) has bit 2 set. -For more information, see <https://ctovswild.com/2009/09/03/bitmask-searches-in-ldap/> + +<!-- vale gitlab.Spelling = NO --> + +For more information, see [Bitmask Searches in LDAP](https://ctovswild.com/2009/09/03/bitmask-searches-in-ldap/). + +<!-- vale gitlab.Spelling = YES --> 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. @@ -546,7 +551,7 @@ The LDAP sync process: - Updates existing users. - Creates new users on first sign in. -### Adjusting LDAP user sync schedule **(STARTER ONLY)** +### Adjusting LDAP user sync schedule **(PREMIUM SELF)** By default, GitLab runs a worker once per day at 01:30 a.m. server time to check and update GitLab users against LDAP. @@ -579,7 +584,7 @@ sync to run once every 12 hours at the top of the hour. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -## Group Sync **(STARTER ONLY)** +## Group Sync **(PREMIUM SELF)** If your LDAP supports the `memberof` property, when the user signs in for the first time GitLab triggers a sync for groups the user should be a member of. @@ -629,11 +634,11 @@ following. To take advantage of group sync, group owners or maintainers need to [create one or more LDAP group links](#adding-group-links). -### Adding group links **(STARTER ONLY)** +### 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). -### Administrator sync **(STARTER ONLY)** +### Administrator sync **(PREMIUM SELF)** As an extension of group sync, you can automatically manage your global GitLab administrators. Specify a group CN for `admin_group` and all members of the @@ -642,8 +647,8 @@ like the following. NOTE: Administrators are not synced unless `group_base` is also -specified alongside `admin_group`. Also, only specify the CN of the admin -group, as opposed to the full DN. +specified alongside `admin_group`. Also, only specify the CN of the `admin_group`, +as opposed to the full DN. **Omnibus configuration** @@ -677,7 +682,7 @@ group, as opposed to the full DN. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### Global group memberships lock **(STARTER ONLY)** +### Global group memberships lock **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1793) in GitLab 12.0. @@ -693,10 +698,10 @@ When enabled, the following applies: To enable it you need to: 1. [Enable LDAP](#configuration) -1. Navigate to **(admin)** **Admin Area > Settings -> Visibility and access controls**. +1. Navigate to **Admin Area > Settings -> Visibility and access controls**. 1. Make sure the "Lock memberships to LDAP synchronization" checkbox is enabled. -### Adjusting LDAP group sync schedule **(STARTER ONLY)** +### Adjusting LDAP group sync schedule **(PREMIUM SELF)** By default, GitLab runs a group sync process every hour, on the hour. The values shown are in cron format. If needed, you can use a @@ -735,7 +740,7 @@ sync to run once every 2 hours at the top of the hour. 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect. -### External groups **(STARTER ONLY)** +### External groups **(PREMIUM SELF)** Using the `external_groups` setting will allow you to mark all users belonging to these groups as [external users](../../../user/permissions.md#external-users). diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 1976bab03c6..438f591856b 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -52,7 +52,7 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server admin_group: 'my_admin_group' ``` -#### Query LDAP **(STARTER ONLY)** +#### Query LDAP **(PREMIUM SELF)** The following allows you to perform a search in LDAP using the rails console. Depending on what you're trying to do, it may make more sense to query [a @@ -148,11 +148,11 @@ We have a workaround, based on toggling the access level of affected users: 1. As an administrator, go to **Admin Area > Overview > Users**. 1. Select the name of the affected user. 1. In the user's administrative page, press **Edit** on the top right of the page. -1. Change the user's access level from **Regular** to **Admin** (or vice versa), +1. Change the user's access level from `Regular` to `Admin` (or vice versa), and press **Save changes** at the bottom of the page. 1. Press **Edit** on the top right of the user's profile page again. -1. Restore the user's original access level (**Regular** or **Admin**) +1. Restore the user's original access level (`Regular` or `Admin`) and press **Save changes** again. The user should now be able to sign in. @@ -191,7 +191,7 @@ have to be taken here: will associate this profile to the LDAP identity. The user can do either of these steps [in their -profile](../../../user/profile/index.md#user-profile) or an admin can do it. +profile](../../../user/profile/index.md#user-profile) or an administrator can do it. #### Debug LDAP user filter @@ -210,7 +210,7 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba port. - We are assuming the password for the `bind_dn` user is in `bind_dn_password.txt`. -#### Sync all users **(STARTER ONLY)** +#### Sync all users **(PREMIUM SELF)** The output from a manual [user sync](index.md#user-sync) can show you what happens when GitLab tries to sync its users against LDAP. Enter the [rails console](#rails-console) @@ -225,7 +225,7 @@ LdapSyncWorker.new.perform Next, [learn how to read the output](#example-console-output-after-a-user-sync). -##### Example console output after a user sync **(STARTER ONLY)** +##### 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 single user's successful sync can look like this: @@ -316,9 +316,9 @@ adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain') # If `main` is the LDAP pr Gitlab::Auth::Ldap::Person.find_by_uid('<uid>', adapter) ``` -### Group memberships **(STARTER ONLY)** +### Group memberships **(PREMIUM SELF)** -#### Membership(s) not granted **(STARTER ONLY)** +#### Membership(s) not granted **(PREMIUM SELF)** Sometimes you may think a particular user should be added to a GitLab group via LDAP group sync, but for some reason it's not happening. There are several @@ -358,17 +358,17 @@ the rails console. UIDs here should match the 'Identifier' from the LDAP identity checked earlier. If it doesn't, the user does not appear to be in the LDAP group. -#### Admin privileges not granted +#### Administrator privileges not granted When [Administrator sync](index.md#administrator-sync) has been configured -but the configured users aren't granted the correct admin privileges, confirm +but the configured users aren't granted the correct administrator privileges, confirm the following are true: - A [`group_base` is also configured](index.md#group-sync). - The configured `admin_group` in the `gitlab.rb` is a CN, rather than a DN or an array. - This CN falls under the scope of the configured `group_base`. - The members of the `admin_group` have already signed into GitLab with their LDAP - credentials. GitLab will only grant this admin access to the users whose + credentials. GitLab will only grant this administrator access to the users whose accounts are already connected to LDAP. If all the above are true and the users are still not getting access, [run a manual @@ -376,7 +376,7 @@ group sync](#sync-all-groups) in the rails console and [look through the output](#example-console-output-after-a-group-sync) to see what happens when GitLab syncs the `admin_group`. -#### Sync all groups **(STARTER ONLY)** +#### Sync all groups **(PREMIUM SELF)** NOTE: To sync all groups manually when debugging is unnecessary, [use the Rake @@ -394,7 +394,7 @@ LdapAllGroupsSyncWorker.new.perform Next, [learn how to read the output](#example-console-output-after-a-group-sync). -##### Example console output after a group sync **(STARTER ONLY)** +##### Example console output after a group sync **(PREMIUM SELF)** Like the output from the user sync, the output from the [manual group sync](#sync-all-groups) will also be very verbose. However, it contains lots @@ -477,14 +477,14 @@ this line will indicate the sync is finished: Finished syncing admin users for 'ldapmain' provider ``` -If [admin sync](index.md#administrator-sync) is not configured, you'll see a message +If [administrator sync](index.md#administrator-sync) is not configured, you'll see a message stating as such: ```shell No `admin_group` configured for 'ldapmain' provider. Skipping ``` -#### Sync one group **(STARTER ONLY)** +#### Sync one group **(PREMIUM SELF)** [Syncing all groups](#sync-all-groups) can produce a lot of noise in the output, which can be distracting when you're only interested in troubleshooting the memberships of @@ -506,7 +506,7 @@ EE::Gitlab::Auth::Ldap::Sync::Group.execute_all_providers(group) The output will be similar to [that you'd get from syncing all groups](#example-console-output-after-a-group-sync). -#### Query a group in LDAP **(STARTER ONLY)** +#### Query a group in LDAP **(PREMIUM SELF)** When you'd like to confirm that GitLab can read a LDAP group and see all its members, you can run the following: @@ -562,7 +562,7 @@ emails.each do |username, email| end ``` -You can then [run a UserSync](#sync-all-users) **(STARTER ONLY)** to sync the latest DN +You can then [run a UserSync](#sync-all-users) **(PREMIUM SELF)** to sync the latest DN for each of these users. ## Debugging Tools |