Add latest changes from gitlab-org/gitlab@14-8-stable-eev14.8.0-rc42

12 files changed, 106 insertions, 15 deletions

diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md
index 08d07b13e22..7c6aee2c2da 100644
--- a/doc/administration/auth/atlassian.md
+++ b/doc/administration/auth/atlassian.md
@@ -1,7 +1,7 @@
 ---
 type: reference
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md
index 23735b75991..a4a085a494c 100644
--- a/doc/administration/auth/authentiq.md
+++ b/doc/administration/auth/authentiq.md
@@ -1,7 +1,7 @@
 ---
 type: reference
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md
index 2509bbb73d7..66f8407894c 100644
--- a/doc/administration/auth/cognito.md
+++ b/doc/administration/auth/cognito.md
@@ -1,7 +1,7 @@
 ---
 type: concepts, howto
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md
index 9a5f6b0a642..8dfa832a103 100644
--- a/doc/administration/auth/crowd.md
+++ b/doc/administration/auth/crowd.md
@@ -1,7 +1,7 @@
 ---
 type: reference
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md
index d469988e719..d09344629e2 100644
--- a/doc/administration/auth/index.md
+++ b/doc/administration/auth/index.md
@@ -2,7 +2,7 @@
 comments: false
 type: index
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
@@ -50,3 +50,31 @@ For more information, see the links shown on this page for each external provide
 | **Authentication**                              | SAML at top-level group (1 provider)    | LDAP (multiple providers)<br>Generic OAuth2<br>SAML (only 1 permitted per unique provider)<br>Kerberos<br>JWT<br>Smartcard<br>OmniAuth Providers (only 1 permitted per unique provider) |
 | **Provider-to-GitLab Role Sync**                | SAML Group Sync                         | LDAP Group Sync                    |
 | **User Removal**                                | SCIM (remove user from top-level group) | LDAP (Blocking User from Instance) |
+
+## 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 ac2f699dd5d..98f928fd7ee 100644
--- a/doc/administration/auth/jwt.md
+++ b/doc/administration/auth/jwt.md
@@ -1,7 +1,7 @@
 ---
 type: reference
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md
index 6b8e699e861..10745c5e2bf 100644
--- a/doc/administration/auth/ldap/google_secure_ldap.md
+++ b/doc/administration/auth/ldap/google_secure_ldap.md
@@ -1,7 +1,7 @@
 ---
 type: reference
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md
index b773281b216..2a396c4d53a 100644
--- a/doc/administration/auth/ldap/index.md
+++ b/doc/administration/auth/ldap/index.md
@@ -1,7 +1,7 @@
 ---
 type: reference
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
@@ -468,7 +468,7 @@ If initially your LDAP configuration looked like:
      password: '123'
    ```
 
-1. Edit `/etc/gitlab/gitlab.rb` and remove the settings for `user_bn` and `password`.
+1. Edit `/etc/gitlab/gitlab.rb` and remove the settings for `user_dn` and `password`.
 
 1. [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -502,7 +502,7 @@ If initially your LDAP configuration looked like:
     password: '123'
    ```
 
-1. Edit `config/gitlab.yaml` and remove the settings for `user_bn` and `password`.
+1. Edit `config/gitlab.yaml` and remove the settings for `user_dn` and `password`.
 
 1. [Restart GitLab](../../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md
index 97a626f4a40..06fe579e101 100644
--- a/doc/administration/auth/ldap/ldap-troubleshooting.md
+++ b/doc/administration/auth/ldap/ldap-troubleshooting.md
@@ -1,7 +1,7 @@
 ---
 type: reference
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
@@ -382,7 +382,7 @@ the following are true:
 - 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 only grants the Administrator role to the users whose
+  credentials. GitLab only grants 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,
diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md
index 3329ea8e9cc..d7ce54a47c0 100644
--- a/doc/administration/auth/ldap/ldap_synchronization.md
+++ b/doc/administration/auth/ldap/ldap_synchronization.md
@@ -1,6 +1,6 @@
 ---
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
@@ -347,3 +347,7 @@ These metrics are meant to provide a baseline and performance may vary based on
 any number of factors. This benchmark was extreme and most instances don't
 have near this many users or groups. Disk speed, database performance,
 network and LDAP server response time affects these metrics.
+
+## Troubleshooting
+
+See our [administrator guide to troubleshooting LDAP](ldap-troubleshooting.md).
diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md
index efe4b7440ee..a099b9c76f8 100644
--- a/doc/administration/auth/oidc.md
+++ b/doc/administration/auth/oidc.md
@@ -1,7 +1,7 @@
 ---
 type: reference
 stage: Manage
-group: Authentication & Authorization
+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
 ---
 
@@ -461,6 +461,65 @@ To use symmetric key encryption:
 If after reconfiguring, you see the error `JSON::JWS::VerificationFailed` error message, this means
 the incorrect secret was specified.
 
+#### Casdoor
+
+GitLab works with OpenID providers that use HTTPS. To connect to GitLab using OpenID with Casdoor, use HTTPS instead of HTTP.
+
+For your app, complete the following steps on Casdoor:
+
+1. Get a client ID and a client secret.
+1. Add your GitLab redirect URL. For example, if your GitLab domain is `gitlab.example.com`, ensure the Casdoor app has the following
+   `Redirect URI`: `https://gitlab.example.com/users/auth/openid_connect/callback`.
+
+See the [Casdoor documentation](https://casdoor.org/docs/integration/gitlab) for more details.
+
+Example Omnibus GitLab configuration (file path: `/etc/gitlab/gitlab.rb`):
+
+```ruby
+gitlab_rails['omniauth_providers'] = [
+    {
+        name: "openid_connect",
+        label: "Casdoor", # optional label for login button, defaults to "Openid Connect"
+        args: {
+            name: "openid_connect",
+            scope: ["openid", "profile", "email"],
+            response_type: "code",
+            issuer:  "https://<CASDOOR_HOSTNAME>",
+            client_auth_method: "query",
+            discovery: true,
+            uid_field: "sub",
+            client_options: {
+                identifier: "<YOUR CLIENT ID>",
+                secret: "<YOUR CLIENT SECRET>",
+                redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
+            }
+        }
+    }
+]
+```
+
+Example installations from source configuration (file path: `config/gitlab.yml`):
+
+```yaml
+  - { name: 'openid_connect',
+      label: 'Casdoor', # optional label for login button, defaults to "Openid Connect"
+      args: {
+        name: 'openid_connect',
+        scope: ['openid','profile','email'],
+        response_type: 'code',
+        issuer: 'https://<CASDOOR_HOSTNAME>',
+        discovery: true,
+        client_auth_method: 'query',
+        uid_field: 'sub',
+        client_options: {
+          identifier: '<YOUR CLIENT ID>',
+          secret: '<YOUR CLIENT SECRET>',
+          redirect_uri: 'https://gitlab.example.com/users/auth/openid_connect/callback'
+        }
+      }
+    }
+```
+
 ## General troubleshooting
 
 If you're having trouble, here are some tips:
diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md
index f77d3a36a7b..3f0d95967bf 100644
--- a/doc/administration/auth/smartcard.md
+++ b/doc/administration/auth/smartcard.md
@@ -1,6 +1,6 @@
 ---
 stage: Manage
-group: Authentication & Authorization
+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
 type: reference
 ---