diff options
Diffstat (limited to 'doc/administration/auth/ldap')
| -rw-r--r-- | doc/administration/auth/ldap/google_secure_ldap.md | 6 | ||||
| -rw-r--r-- | doc/administration/auth/ldap/index.md | 21 | ||||
| -rw-r--r-- | doc/administration/auth/ldap/ldap-troubleshooting.md | 6 | ||||
| -rw-r--r-- | doc/administration/auth/ldap/ldap_synchronization.md | 150 |
4 files changed, 170 insertions, 13 deletions
diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index e0612099221..042a65be500 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -18,6 +18,8 @@ The steps below cover: - Configuring the Secure LDAP Client in the Google administrator console. - Required GitLab configuration. +Secure LDAP is only available on specific Google Workspace editions. For more information, see the [Google Secure LDAP service documentation](https://support.google.com/a/answer/9048516). + ## Configuring Google LDAP client 1. Go to <https://admin.google.com/Dashboard> and sign in as a Google Workspace domain administrator. @@ -88,7 +90,7 @@ values obtained during the LDAP client configuration earlier: encryption: 'simple_tls' verify_certificates: true retry_empty_result_with_codes: [80] - + base: "DC=example,DC=com" tls_options: cert: | -----BEGIN CERTIFICATE----- @@ -152,7 +154,7 @@ values obtained during the LDAP client configuration earlier: servers: main: # 'main' is the GitLab 'provider ID' of this LDAP server label: 'Google Secure LDAP' - + base: "DC=example,DC=com" host: 'ldap.google.com' port: 636 uid: 'uid' diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 0c7bd33c2c1..7687f7c9340 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -270,7 +270,7 @@ These LDAP sync configuration settings are available: | Setting | Description | Required | Examples | |-------------------|-------------|----------|----------| -| `group_base` | Base used to search for groups. | **{dotted-circle}** No | `'ou=groups,dc=gitlab,dc=example'` | +| `group_base` | Base used to search for groups. | **{dotted-circle}** No (required when `external_groups` is configured) | `'ou=groups,dc=gitlab,dc=example'` | | `admin_group` | The CN of a group containing GitLab administrators. 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. 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. | **{dotted-circle}** No | `'sshPublicKey'` or false if not set | @@ -1031,6 +1031,25 @@ See [Google Secure LDAP](google_secure_ldap.md) for detailed configuration instr For more information on synchronizing users and groups between LDAP and GitLab, see [LDAP synchronization](ldap_synchronization.md). +## Move from LDAP to SAML + +1. [Configure SAML](../../../integration/saml.md). Add `auto_link_ldap_user` to: + - [`gitlab.rb` for Omnibus](../../../integration/saml.html?tab=Linux+package+%28Omnibus%29). + - [`values.yml` for Kubernetes](../../../integration/saml.html?tab=Helm+chart+%28Kubernetes%29). + For more information, see the [initial settings for all providers](../../../integration/omniauth.md#configure-initial-settings). + +1. Optional. [Disable the LDAP auth from the sign-in page](#disable-ldap-web-sign-in). + +1. Optional. To fix issues with linking users, you can first [remove those users' LDAP identities](ldap-troubleshooting.md#remove-the-identity-records-that-relate-to-the-removed-ldap-server). + +1. Confirm that users are able to sign in to their accounts. If a user cannot sign in, check if that user's LDAP is still there and remove it if necessary. If this issue persists, check the logs to identify the problem. + +1. In the configuration file, change: + - `omniauth_auto_link_user` to `saml` only. + - `omniauth_auto_link_ldap_user` to false. + - `ldap_enabled` to `false`. + You can also comment out the LDAP provider settings. + ## Troubleshooting See our [administrator guide to troubleshooting LDAP](ldap-troubleshooting.md). diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 7e21d3c6655..909ab5245ca 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -170,10 +170,10 @@ We have a workaround, based on toggling the access level of affected users: 1. As an administrator, on the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Select the name of the affected user. -1. In the upper right, select **Edit**. +1. In the upper-right corner, select **Edit**. 1. Change the user's access level from `Regular` to `Administrator` (or vice versa). 1. At the bottom of the page, select **Save changes**. -1. In the upper right, select **Edit** again. +1. In the upper-right corner, select **Edit** again. 1. Restore the user's original access level (`Regular` or `Administrator`) and select **Save changes** again. @@ -761,7 +761,7 @@ users, [see what to do when no users are found](#no-users-are-found). ### GitLab logs If a user account is blocked or unblocked due to the LDAP configuration, a -message is [logged to `application.log`](../../logs/index.md#applicationlog). +message is [logged to `application_json.log`](../../logs/index.md#application_jsonlog). If there is an unexpected error during an LDAP lookup (configuration error, timeout), the sign-in is rejected and a message is [logged to `production.log`](../../logs/index.md#productionlog). diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index cc300941470..f32a4af9e27 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -7,12 +7,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # LDAP synchronization **(PREMIUM SELF)** If you have [configured LDAP to work with GitLab](index.md), GitLab can automatically synchronize -users and groups. This process updates user and group information. +users and groups. + +LDAP synchronization updates user and group information for existing GitLab users that have an LDAP identity assigned. It does not create new GitLab users through LDAP. You can change when synchronization occurs. ## User sync +> Preventing LDAP username synchronization [introduced](<https://gitlab.com/gitlab-org/gitlab/-/issues/11336>) in GitLab 15.11. + Once per day, GitLab runs a worker to check and update GitLab users against LDAP. @@ -33,17 +37,132 @@ For more information, see [Bitmask Searches in LDAP](https://ctovswild.com/2009/ <!-- vale gitlab.Spelling = YES --> -The user is set to an `ldap_blocked` state in GitLab if the previous conditions -fail. This means the user cannot sign in or push or pull code. - The process also updates the following user information: - Name. Because of a [sync issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342598), `name` is not synchronized if - [**Prevent users from changing their profile name**](../../../user/admin_area/settings/account_and_limit_settings.md#disable-user-profile-name-changes) is enabled. + [**Prevent users from changing their profile name**](../../../user/admin_area/settings/account_and_limit_settings.md#disable-user-profile-name-changes) is enabled or `sync_name` is set to `false`. - Email address. - SSH public keys if `sync_ssh_keys` is set. - Kerberos identity if Kerberos is enabled. +### Synchronize LDAP username + +By default, GitLab synchronizes the LDAP username field. + +To prevent this synchronization, you can set `sync_name` to `false`. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['ldap_servers'] = { + 'main' => { + 'sync_name' => false, + } + } + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + ldap: + servers: + main: + sync_name: false + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['ldap_servers'] = { + 'main' => { + 'sync_name' => false, + } + } + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + ldap: + servers: + main: + sync_name: false + ``` + +1. Save the file and restart GitLab: + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + +### Blocked users + +A user is blocked if either the: + +- [Access check fails](#user-sync) and that user is set to an `ldap_blocked` state in GitLab. +- LDAP server is not available when that user signs in. + +If a user is blocked, that user cannot sign in or push or pull code. + +A blocked user is unblocked when they sign in with LDAP if all of the following are true: + +- All the access check conditions are true. +- The LDAP server is available when the user signs in. + +**All users** are blocked if the LDAP server is unavailable when an LDAP user synchronization is run. + +NOTE: +If all users are blocked due to the LDAP server not being available when an LDAP user synchronization is run, +a subsequent LDAP user synchronization does not automatically unblock those users. + ### Adjust LDAP user sync schedule By default, GitLab runs a worker once per day at 01:30 a.m. server time to @@ -387,6 +506,23 @@ To enable global group memberships lock: 1. Expand the **Visibility and access controls** section. 1. Ensure the **Lock memberships to LDAP synchronization** checkbox is selected. +### Change LDAP group synchronization settings management + +By default, group members with the Owner role can manage [LDAP group synchronization settings](../../../user/group/access_and_permissions.md#manage-group-memberships-via-ldap). + +GitLab administrators can remove this permission from group Owners: + +1. [Configure LDAP](index.md#configure-ldap). +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. Ensure the **Allow group owners to manage LDAP-related settings** checkbox is not checked. + +When **Allow group owners to manage LDAP-related settings** is disabled: + +- Group Owners cannot change LDAP synchronization settings for either top-level groups and subgroups. +- Instance administrators can manage LDAP group synchronization settings on all groups on an instance. + ### Adjust LDAP group sync schedule By default, GitLab runs a group sync process every hour, on the hour. @@ -411,7 +547,7 @@ sync to run once every two hours at the top of the hour. 1. Edit `/etc/gitlab/gitlab.rb`: ```ruby - gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *" + gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * *" ``` 1. Save the file and reconfigure GitLab: @@ -454,7 +590,7 @@ sync to run once every two hours at the top of the hour. gitlab: environment: GITLAB_OMNIBUS_CONFIG: | - gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *" + gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * *" ``` 1. Save the file and restart GitLab: |