diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-20 02:18:09 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-09-20 02:18:09 +0300 |
commit | 6ed4ec3e0b1340f96b7c043ef51d1b33bbe85fde (patch) | |
tree | dc4d20fe6064752c0bd323187252c77e0a89144b /doc/administration/auth | |
parent | 9868dae7fc0655bd7ce4a6887d4e6d487690eeed (diff) |
Add latest changes from gitlab-org/gitlab@15-4-stable-eev15.4.0-rc42
Diffstat (limited to 'doc/administration/auth')
-rw-r--r-- | doc/administration/auth/atlassian.md | 5 | ||||
-rw-r--r-- | doc/administration/auth/index.md | 28 | ||||
-rw-r--r-- | doc/administration/auth/jwt.md | 5 | ||||
-rw-r--r-- | doc/administration/auth/ldap/index.md | 2 | ||||
-rw-r--r-- | doc/administration/auth/ldap/ldap-troubleshooting.md | 131 | ||||
-rw-r--r-- | doc/administration/auth/ldap/ldap_synchronization.md | 10 | ||||
-rw-r--r-- | doc/administration/auth/oidc.md | 2 |
7 files changed, 140 insertions, 43 deletions
diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 6be53922a5a..1d20d87bdf4 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -71,7 +71,10 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu 1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in [application registration](#atlassian-application-registration) steps. 1. Save the configuration file. -1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. + +1. For the changes to take effect: + - If you installed via Omnibus, [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + - If you installed from source, [restart GitLab](../restart_gitlab.md#installations-from-source). On the sign-in page there should now be an Atlassian icon below the regular sign in form. Select the icon to begin the authentication process. diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index a412875501e..2644e3a1f50 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -34,31 +34,3 @@ For more information, see the links shown on this page for each external provide | **User Removal** | SCIM (remove user from top-level group) | LDAP (remove user from groups and block from the instance) | 1. Using Just-In-Time (JIT) provisioning, user accounts are created when the user first signs in. - -## Change apps or configuration - -When GitLab doesn't support having multiple providers (such as OAuth), GitLab configuration and user identification must be -updated at the same time if the provider or app is changed. - -These instructions apply to all methods of authentication where GitLab stores an `extern_uid` and it is the only data used -for user authentication. - -When changing apps within a provider, if the user `extern_uid` does not change, only the GitLab configuration must be -updated. - -To swap configurations: - -1. Change provider configuration in your `gitlab.rb` file. -1. Update `extern_uid` for all users that have an identity in GitLab for the previous provider. - -To find the `extern_uid`, look at an existing user's current `extern_uid` for an ID that matches the appropriate field in -your current provider for the same user. - -There are two methods to update the `extern_uid`: - -- Using the [Users API](../../api/users.md#user-modification). Pass the provider name and the new `extern_uid`. -- Using the [Rails console](../operations/rails_console.md): - - ```ruby - Identity.where(extern_uid: 'old-id').update!(extern_uid: 'new-id')` - ``` diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 99cba3f220d..71ab084065a 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -70,8 +70,9 @@ JWT provides you with a secret key for you to use. 1. Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL. 1. Save the configuration file. -1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you - installed GitLab via Omnibus or from source respectively. +1. For the changes to take effect: + - If you installed via Omnibus, [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + - If you installed from source, [restart GitLab](../restart_gitlab.md#installations-from-source). On the sign in page there should now be a JWT icon below the regular sign in form. Select the icon to begin the authentication process. JWT asks the user to diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 2f0a0db9d6f..19f656d2f14 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -344,7 +344,7 @@ The `user_filter` DN can contain special characters. For example: OU=GitLab\2C Inc,DC=gitlab,DC=com ``` -- Escape open and close brackets with `\28` and `\29`, respectively. For example: +- Escape open brackets with `\28` and close brackets with `\29`. For example: ```plaintext OU=Gitlab \28Inc\29,DC=gitlab,DC=com diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 64ef27cbf51..a68e6ae2649 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -5,7 +5,9 @@ group: Authentication and Authorization 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 **(FREE SELF)** +# Troubleshooting LDAP **(FREE SELF)** + +If you are an administrator, use the following information to troubleshoot LDAP. ## Common Problems & Workflows @@ -165,7 +167,7 @@ may see the following message: `Access denied for your LDAP account`. We have a workaround, based on toggling the access level of affected users: -1. As an administrator, on the top bar, select **Menu > Admin**. +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 user's administrative page, press **Edit** on the top right of the page. @@ -210,7 +212,7 @@ This shows you which user has this email address. One of two steps must be taken remove this email as a secondary email and make it a primary one so GitLab associates this profile to the LDAP identity. -The user can do either of these steps +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. #### Projects limit errors @@ -223,7 +225,7 @@ field contains no data: To resolve this: -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, go to **Settings > General**. 1. Expand both of the following: - **Account and limit**. @@ -366,7 +368,7 @@ things to debug the situation. - Ensure the correct [LDAP group link is added to the GitLab group](ldap_synchronization.md#add-group-links). - Check that the user has an LDAP identity: 1. Sign in to GitLab as an administrator user. - 1. On the top bar, select **Menu > Admin**. + 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Search for the user. 1. Open the user by selecting their name. Do not select **Edit**. @@ -411,6 +413,63 @@ If all the above are true and the users are still not getting access, [look through the output](#example-console-output-after-a-group-sync) to see what happens when GitLab syncs the `admin_group`. +#### Sync now button stuck in the UI + +The **Sync now** button on the **Group > Members** page of a group can become stuck. The button becomes stuck after it is pressed and the page is reloaded. The button then +cannot be selected again. + +The **Sync now** button can become stuck for many reasons and requires debugging for specific cases. The following are two possible causes and possible solutions to the problem. + +##### Invalid memberships + +The **Sync now** button becomes stuck if some of the group's members or requesting members are invalid. You can track progress on improving the visibility of this problem in +a [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/348226). You can use a [Rails console](#rails-console) to confirm if this problem is causing the **Sync now** +button to be stuck: + +```ruby +# Find the group in question +group = Group.find_by(name: 'my_gitlab_group') + +# Look for errors on the Group itself +group.valid? +group.errors.map(&:full_messages) + +# Look for errors among the group's members and requesters +group.requesters.map(&:valid?) +group.requesters.map(&:errors).map(&:full_messages) +group.members.map(&:valid?) +group.members.map(&:errors).map(&:full_messages) +``` + +A displayed error can identify the problem and point to a solution. For example, the Support Team has seen the following error: + +```ruby +irb(main):018:0> group.members.map(&:errors).map(&:full_messages) +=> [["The member's email address is not allowed for this group. Go to the group’s 'Settings > General' page, and check 'Restrict membership by email domain'."]] +``` + +This error showed that an Administrator chose to [restrict group membership by email domain](../../../user/group/access_and_permissions.md#restrict-group-access-by-domain), +but there was a typo in the domain. After the domain setting was fixed, the **Sync now** button functioned again. + +##### Missing LDAP configuration on Sidekiq nodes + +The **Sync now** button becomes stuck when GitLab is scaled over multiple nodes and the LDAP configuration is missing from +[the `/etc/gitlab/gitlab.rb` on the nodes running Sidekiq](../../sidekiq/index.md#configure-ldap-and-user-or-group-synchronization). +In this case, the Sidekiq jobs seem to disappear. + +LDAP is required on the Sidekiq nodes because LDAP has multiple jobs that are +run asynchronously that require a local LDAP configuration: + +- [User sync](ldap_synchronization.md#user-sync). +- [Group sync](ldap_synchronization.md#group-sync). + +You can test whether missing LDAP configuration is the problem by running [the Rake task to check LDAP](#ldap-check) +on each node that is running Sidekiq. If LDAP is set up correctly on this node, it connects to the LDAP server and returns users. + +To solve this issue, [configure LDAP](../../sidekiq/index.md#configure-ldap-and-user-or-group-synchronization) on the Sidekiq nodes. +When configured, run [the Rake task to check LDAP](#ldap-check) to confirm +that the GitLab node can connect to LDAP. + #### Sync all groups NOTE: @@ -430,7 +489,7 @@ Next, [learn how to read the output](#example-console-output-after-a-group-sync) ##### Example console output after a group sync -Like the output from the user sync, the output from the +Like the output from the user sync, the output from the [manual group sync](#sync-all-groups) is also very verbose. However, it contains lots of helpful information. @@ -600,6 +659,66 @@ end You can then [run a UserSync](#sync-all-users) **(PREMIUM SELF)** to sync the latest DN for each of these users. +## Could not authenticate you from ldapmain because "Unknown provider" + +You can receive the following error when authenticating with an LDAP server: + +```plaintext +Could not authenticate you from Ldapmain because "Unknown provider (ldapsecondary). available providers: ["ldapmain"]". +``` + +This error is caused when using an account that previously authenticated with an LDAP server that is renamed or removed from your GitLab configuration. For example: + +- Initially, `main` and `secondary` are set in `ldap_servers` in GitLab configuration. +- The `secondary` setting is removed or renamed to `main`. +- A user attempting to sign in has an `identify` record for `secondary`, but that is no longer configured. + +Use the [Rails console](../../operations/rails_console.md) to list affected users and check what LDAP servers they have identities for: + +```ruby +ldap_identities = Identity.where(provider: "ldapsecondary") +ldap_identities.each do |identity| + u=User.find_by_id(identity.user_id) + ui=Identity.where(user_id: identity.user_id) + puts "user: #{u.username}\n #{u.email}\n last activity: #{u.last_activity_on}\n #{identity.provider} ID: #{identity.id} external: #{identity.extern_uid}" + puts " all identities:" + ui.each do |alli| + puts " - #{alli.provider} ID: #{alli.id} external: #{alli.extern_uid}" + end +end;nil +``` + +You can solve this error in two ways. + +### Rename references to the LDAP server + +This solution is suitable when the LDAP servers are replicas of each other, and the affected users should be able to sign in using a configured LDAP server. For example, if a +load balancer is now used to manage LDAP high availability and a separate secondary sign-in option is no longer needed. + +NOTE: +If the LDAP servers aren't replicas of each other, this solution stops affected users from being able to sign in. + +To [rename references to the LDAP server](../../raketasks/ldap.md#other-options) that is no longer configured, run: + +```shell +sudo gitlab-rake gitlab:ldap:rename_provider[ldapsecondary,ldapmain] +``` + +### Remove the `identity` records that relate to the removed LDAP server + +With this solution, affected users can sign in with the configured LDAP servers and a new `identity` record is created by GitLab. In a +[Rails console](../../operations/rails_console.md), delete the `ldapsecondary` identities: + +```ruby +ldap_identities = Identity.where(provider: "ldapsecondary") +ldap_identities.each do |identity| + puts "Destroying identity: #{identity.id} #{identity.provider}: #{identity.extern_uid}" + identity.destroy! +rescue => e + puts 'Error generated when destroying identity:\n ' + e.to_s +end; nil +``` + ## Expired license causes errors with multiple LDAP servers Using [multiple LDAP servers](index.md#use-multiple-ldap-servers) requires a valid license. An expired license can diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index 62706a9e3b9..37a27fc058e 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -38,9 +38,11 @@ fail. This means the user cannot sign in or push or pull code. The process also updates the following user information: -- Email address -- SSH public keys (if `sync_ssh_keys` is set) -- Kerberos identity (if Kerberos is enabled) +- 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. +- Email address. +- SSH public keys if `sync_ssh_keys` is set. +- Kerberos identity if Kerberos is enabled. ### Adjust LDAP user sync schedule @@ -192,7 +194,7 @@ When enabled, the following applies: To enable it, you must: 1. [Configure LDAP](index.md#configure-ldap). -1. On the top bar, select **Menu > Admin**. +1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Ensure the **Lock memberships to LDAP synchronization** checkbox is selected. diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index 8c5bf96e99e..9f3c96902f8 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -250,7 +250,7 @@ but `LocalAccounts` works for authenticating against local, Active Directory acc <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" /> ``` -1. For OIDC discovery to work with B2C, the policy must be configured with an issuer compatible with the +1. For OIDC discovery to work with B2C, the policy must be configured with an issuer compatible with the [OIDC specification](https://openid.net/specs/openid-connect-discovery-1_0.html#rfc.section.4.3). See the [token compatibility settings](https://docs.microsoft.com/en-us/azure/active-directory-b2c/configure-tokens?pivots=b2c-custom-policy#token-compatibility-settings). In `TrustFrameworkBase.xml` under `JwtIssuer`, set `IssuanceClaimPattern` to `AuthorityWithTfp`: |