Add latest changes from gitlab-org/gitlab@14-1-stable-eev14.1.0-rc42

8 files changed, 261 insertions, 139 deletions

diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md
index a072cc73c43..5ab8653dc35 100644
--- a/doc/administration/auth/README.md
+++ b/doc/administration/auth/README.md
@@ -1,52 +1,8 @@
 ---
-comments: false
-type: index
-stage: Manage
-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
+redirect_to: 'index.md'
 ---
 
-# GitLab authentication and authorization **(FREE SELF)**
+This document was moved to [another location](index.md).
 
-GitLab integrates with the following external authentication and authorization
-providers:
-
-- [Atlassian](atlassian.md)
-- [Auth0](../../integration/auth0.md)
-- [Authentiq](authentiq.md)
-- [AWS Cognito](cognito.md)
-- [Azure](../../integration/azure.md)
-- [Bitbucket Cloud](../../integration/bitbucket.md)
-- [CAS](../../integration/cas.md)
-- [Crowd](crowd.md)
-- [Facebook](../../integration/facebook.md)
-- [GitHub](../../integration/github.md)
-- [GitLab.com](../../integration/gitlab.md)
-- [Google OAuth](../../integration/google.md)
-- [JWT](jwt.md)
-- [Kerberos](../../integration/kerberos.md)
-- [LDAP](ldap/index.md): Includes Active Directory, Apple Open Directory, Open LDAP,
-  and 389 Server.
-  - [Google Secure LDAP](ldap/google_secure_ldap.md)
-- [Salesforce](../../integration/salesforce.md)
-- [SAML](../../integration/saml.md)
-- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)**
-- [Shibboleth](../../integration/shibboleth.md)
-- [Smartcard](smartcard.md) **(PREMIUM SELF)**
-- [Twitter](../../integration/twitter.md)
-
-NOTE:
-UltraAuth has removed their software which supports OmniAuth integration. We have therefore removed all references to UltraAuth integration.
-
-## SaaS vs Self-Managed Comparison
-
-The external authentication and authorization providers may support the following capabilities.
-For more information, see the links shown on this page for each external provider.
-
-| Capability                                      | SaaS                                    | Self-Managed                       |
-|-------------------------------------------------|-----------------------------------------|------------------------------------|
-| **User Provisioning**                           | SCIM<br>JIT Provisioning                | LDAP Sync                          |
-| **User Detail Updating** (not group management) | Not Available                           | LDAP Sync                          |
-| **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) |
+<!-- This redirect file can be deleted after 2021-09-28. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md
index 365236748b9..b3892f8f5d9 100644
--- a/doc/administration/auth/atlassian.md
+++ b/doc/administration/auth/atlassian.md
@@ -11,7 +11,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu
 
 ## Atlassian application registration
 
-1. Go to <https://developer.atlassian.com/apps/> and sign-in with the Atlassian
+1. Go to <https://developer.atlassian.com/console/myapps/> and sign-in with the Atlassian
    account that will administer the application.
 
 1. Click **Create a new app**.
diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md
index 2eab4555c85..835293ff500 100644
--- a/doc/administration/auth/authentiq.md
+++ b/doc/administration/auth/authentiq.md
@@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 To enable the Authentiq OmniAuth provider for passwordless authentication you must register an application with Authentiq.
 
-Authentiq will generate a Client ID and the accompanying Client Secret for you to use.
+Authentiq generates a Client ID and the accompanying Client Secret for you to use.
 
 1. Get your Client credentials (Client ID and Client Secret) at [Authentiq](https://www.authentiq.com/developers).
 
@@ -67,15 +67,17 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t
 
 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.
 
-On the sign in page there should now be an Authentiq icon below the regular sign in form. Click the icon to begin the authentication process.
+On the sign in page there should now be an Authentiq icon below the regular sign in form. Click the
+icon to begin the authentication process. If the user:
 
-- If the user has the Authentiq ID app installed in their iOS or Android device, they can:
+- Has the Authentiq ID app installed in their iOS or Android device, they can:
   1. Scan the QR code.
   1. Decide what personal details to share.
   1. Sign in to your GitLab installation.
-- If not they will be prompted to download the app and then follow the procedure above.
+- Does not have the app installed, they are prompted to download the app and then follow the
+  procedure above.
 
-If everything goes right, the user will be returned to GitLab and will be signed in.
+If everything works, the user is returned to GitLab and is signed in.
 
 <!-- ## Troubleshooting
 
diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md
new file mode 100644
index 00000000000..a072cc73c43
--- /dev/null
+++ b/doc/administration/auth/index.md
@@ -0,0 +1,52 @@
+---
+comments: false
+type: index
+stage: Manage
+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
+---
+
+# GitLab authentication and authorization **(FREE SELF)**
+
+GitLab integrates with the following external authentication and authorization
+providers:
+
+- [Atlassian](atlassian.md)
+- [Auth0](../../integration/auth0.md)
+- [Authentiq](authentiq.md)
+- [AWS Cognito](cognito.md)
+- [Azure](../../integration/azure.md)
+- [Bitbucket Cloud](../../integration/bitbucket.md)
+- [CAS](../../integration/cas.md)
+- [Crowd](crowd.md)
+- [Facebook](../../integration/facebook.md)
+- [GitHub](../../integration/github.md)
+- [GitLab.com](../../integration/gitlab.md)
+- [Google OAuth](../../integration/google.md)
+- [JWT](jwt.md)
+- [Kerberos](../../integration/kerberos.md)
+- [LDAP](ldap/index.md): Includes Active Directory, Apple Open Directory, Open LDAP,
+  and 389 Server.
+  - [Google Secure LDAP](ldap/google_secure_ldap.md)
+- [Salesforce](../../integration/salesforce.md)
+- [SAML](../../integration/saml.md)
+- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)**
+- [Shibboleth](../../integration/shibboleth.md)
+- [Smartcard](smartcard.md) **(PREMIUM SELF)**
+- [Twitter](../../integration/twitter.md)
+
+NOTE:
+UltraAuth has removed their software which supports OmniAuth integration. We have therefore removed all references to UltraAuth integration.
+
+## SaaS vs Self-Managed Comparison
+
+The external authentication and authorization providers may support the following capabilities.
+For more information, see the links shown on this page for each external provider.
+
+| Capability                                      | SaaS                                    | Self-Managed                       |
+|-------------------------------------------------|-----------------------------------------|------------------------------------|
+| **User Provisioning**                           | SCIM<br>JIT Provisioning                | LDAP Sync                          |
+| **User Detail Updating** (not group management) | Not Available                           | LDAP Sync                          |
+| **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) |
diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md
index bc6a854c518..a9d59ca0983 100644
--- a/doc/administration/auth/ldap/index.md
+++ b/doc/administration/auth/ldap/index.md
@@ -174,6 +174,7 @@ production:
 | `base` | Base where we can search for users. | **{check-circle}** Yes | `'ou=people,dc=gitlab,dc=example'` or `'DC=mydomain,DC=com'` |
 | `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. | **{dotted-circle}** No | For examples, read [Examples of user filters](#examples-of-user-filters). |
 | `lowercase_usernames` | If enabled, GitLab converts the name to lower case. | **{dotted-circle}** No | boolean |
+| `retry_empty_result_with_codes` | An array of LDAP query response code that will attempt to retrying the operation if the result/content is empty. | **{dotted-circle}** No | `[80]` |
 
 #### Examples of user filters
 
diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md
index 1215d90134f..5e6c3443e44 100644
--- a/doc/administration/auth/ldap/ldap-troubleshooting.md
+++ b/doc/administration/auth/ldap/ldap-troubleshooting.md
@@ -552,7 +552,7 @@ LDAP.
 If the email has changed and the DN has not, GitLab finds the user with
 the DN and update its own record of the user's email to match the one in LDAP.
 
-However, if the primary email _and_ the DN change in LDAP, then GitLab 
+However, if the primary email _and_ the DN change in LDAP, then GitLab
 has no way of identifying the correct LDAP record of the user and, as a
 result, the user is blocked. To rectify this, the user's existing
 profile must be updated with at least one of the new values (primary
diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md
index 30ca7d94a1e..951c7df26ef 100644
--- a/doc/administration/auth/oidc.md
+++ b/doc/administration/auth/oidc.md
@@ -159,14 +159,14 @@ gitlab_rails['omniauth_providers'] = [
 ### Microsoft Azure
 
 The OpenID Connect (OIDC) protocol for Microsoft Azure uses the [Microsoft identity platform (v2) endpoints](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/azure-ad-endpoint-comparison).
-To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, you'll need the
+To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, you need the
 following information:
 
 - A tenant ID. You may already have one. For more information, review the
   [Microsoft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation.
 - A client ID and a client secret. Follow the instructions in the
-  [Microsoft Quickstart Register an Application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) documentation.
-to obtain the tenant ID, client ID, and client secret for your app.
+  [Microsoft Quickstart Register an Application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) documentation
+  to obtain the tenant ID, client ID, and client secret for your app.
 
 Example Omnibus configuration block:
 
@@ -199,7 +199,7 @@ Microsoft has documented how its platform works with [the OIDC protocol](https:/
 
 While GitLab works with [Azure Active Directory B2C](https://docs.microsoft.com/en-us/azure/active-directory-b2c/overview), it requires special
 configuration to work. To get started, sign in to the [Azure Portal](https://portal.azure.com).
-For your app, you'll need the following information from Azure:
+For your app, you need the following information from Azure:
 
 - A tenant ID. You may already have one. For more information, review the
   [Microsoft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation.
@@ -216,8 +216,8 @@ In addition, ensure that [ID tokens are enabled](https://docs.microsoft.com/en-u
 
 Add the following API permissions to the app:
 
-1. `openid`
-1. `offline_access`
+- `openid`
+- `offline_access`
 
 #### Configure custom policies
 
@@ -231,7 +231,7 @@ standard Azure B2C user flows [do not send the OpenID `email` claim](https://git
 other words, they do not work with the [`allow_single_sign_on` or `auto_link_user`
 parameters](../../integration/omniauth.md#initial-omniauth-configuration).
 With a standard Azure B2C policy, GitLab cannot create a new account or
-link to an existing one with an e-mail address.
+link to an existing one with an email address.
 
 Carefully follow the instructions for [creating a custom policy](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy).
 
@@ -240,42 +240,42 @@ but `LocalAccounts` works for authenticating against local, Active Directory acc
 
 1. To export the `email` claim, modify the `SignUpOrSignin.xml`. Replace the following line:
 
-    ```xml
-    <OutputClaim ClaimTypeReferenceId="email" />
-    ```
+   ```xml
+   <OutputClaim ClaimTypeReferenceId="email" />
+   ```
 
-    with:
+   with:
 
-    ```xml
-    <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />
-    ```
+   ```xml
+   <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 [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`:
-
-    ```xml
-    <ClaimsProvider>
-      <DisplayName>Token Issuer</DisplayName>
-      <TechnicalProfiles>
-        <TechnicalProfile Id="JwtIssuer">
-          <DisplayName>JWT Issuer</DisplayName>
-          <Protocol Name="None" />
-          <OutputTokenFormat>JWT</OutputTokenFormat>
-          <Metadata>
-            <Item Key="IssuanceClaimPattern">AuthorityWithTfp</Item>
-            ...
-      ```
+   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`:
+
+   ```xml
+   <ClaimsProvider>
+     <DisplayName>Token Issuer</DisplayName>
+     <TechnicalProfiles>
+       <TechnicalProfile Id="JwtIssuer">
+         <DisplayName>JWT Issuer</DisplayName>
+         <Protocol Name="None" />
+         <OutputTokenFormat>JWT</OutputTokenFormat>
+         <Metadata>
+           <Item Key="IssuanceClaimPattern">AuthorityWithTfp</Item>
+           ...
+   ```
 
 1. Now [upload the policy](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies). Overwrite
-the existing files if you are updating an existing policy.
+   the existing files if you are updating an existing policy.
 
-1. Determine the issuer URL using the sign-in policy. The issuer URL will be in the form:
+1. Determine the issuer URL using the sign-in policy. The issuer URL is in the form:
 
-    ```markdown
-    https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/
-    ```
+   ```markdown
+   https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/
+   ```
 
    The policy name is lowercased in the URL. For example, `B2C_1A_signup_signin`
    policy appears as `b2c_1a_signup_sigin`.
@@ -283,63 +283,183 @@ the existing files if you are updating an existing policy.
    Note that the trailing forward slash is required.
 
 1. Verify the operation of the OIDC discovery URL and issuer URL, append `.well-known/openid-configuration`
-to the issuer URL:
+   to the issuer URL:
+
+   ```markdown
+   https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/.well-known/openid-configuration
+   ```
+
+   For example, if `domain` is `example.b2clogin.com` and tenant ID is
+   `fc40c736-476c-4da1-b489-ee48cee84386`, you can use `curl` and `jq` to extract the issuer:
+
+   ```shell
+   $ curl --silent "https://example.b2clogin.com/tfp/fc40c736-476c-4da1-b489-ee48cee84386/b2c_1a_signup_signin/v2.0/.well-known/openid-configuration" | jq .issuer
+   "https://example.b2clogin.com/tfp/fc40c736-476c-4da1-b489-ee48cee84386/b2c_1a_signup_signin/v2.0/"
+   ```
+
+1. Configure the issuer URL with the custom policy used for `signup_signin`. For example, this is
+   the Omnibus configuration with a custom policy for `b2c_1a_signup_signin`:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+   {
+     'name' => 'openid_connect',
+     'label' => 'Azure B2C OIDC',
+     'args' => {
+       'name' => 'openid_connect',
+       'scope' => ['openid'],
+       'response_mode' => 'query',
+       'response_type' => 'id_token',
+       'issuer' =>  'https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/b2c_1a_signup_signin/v2.0/',
+       'client_auth_method' => 'query',
+       'discovery' => true,
+       'send_scope_to_token_endpoint' => true,
+       'client_options' => {
+         'identifier' => '<YOUR APP CLIENT ID>',
+         'secret' => '<YOUR APP CLIENT SECRET>',
+         'redirect_uri' => 'https://gitlab.example.com/users/auth/openid_connect/callback'
+       }
+     }
+   }]
+   ```
+
+#### Troubleshooting Azure B2C
 
-    ```markdown
-    https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/.well-known/openid-configuration
-    ```
+- Ensure all occurrences of `yourtenant.onmicrosoft.com`, `ProxyIdentityExperienceFrameworkAppId`, and `IdentityExperienceFrameworkAppId` match your B2C tenant hostname and
+  the respective client IDs in the XML policy files.
+- Add `https://jwt.ms` as a redirect URI to the app, and use the [custom policy tester](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#test-the-custom-policy).
+  Make sure the payload includes `email` that matches the user's email access.
+- After you enable the custom policy, users might see "Invalid username or password" after they try to sign in. This might be a configuration
+  issue with the `IdentityExperienceFramework` app. See [this Microsoft comment](https://docs.microsoft.com/en-us/answers/questions/50355/unable-to-sign-on-using-custom-policy.html?childToView=122370#comment-122370)
+  that suggests checking that the app manifest contains these settings:
+
+  - `"accessTokenAcceptedVersion": null`
+  - `"signInAudience": "AzureADMyOrg"`
+
+  Note that this configuration corresponds with the `Supported account types` setting used when
+  creating the `IdentityExperienceFramework` app.
+
+#### Keycloak
 
-    For example, if `domain` is `example.b2clogin.com` and tenant ID is `fc40c736-476c-4da1-b489-ee48cee84386`, you can use `curl` and `jq` to
-extract the issuer:
+GitLab works with OpenID providers that use HTTPS. Although a Keycloak
+server can be set up using HTTP, GitLab can only communicate
+with a Keycloak server that uses HTTPS.
 
-    ```shell
-    $ curl --silent "https://example.b2clogin.com/tfp/fc40c736-476c-4da1-b489-ee48cee84386/b2c_1a_signup_signin/v2.0/.well-known/openid-configuration" | jq .issuer
-    "https://example.b2clogin.com/tfp/fc40c736-476c-4da1-b489-ee48cee84386/b2c_1a_signup_signin/v2.0/"
-    ```
+We highly recommend configuring Keycloak to use public key encryption algorithms (for example,
+RSA256, RSA512, and so on) instead of symmetric key encryption algorithms (for example, HS256 or HS358) to
+sign tokens. Public key encryption algorithms are:
 
-1. Configure the issuer URL with the custom policy used for
-`signup_signin`. For example, this is the Omnibus configuration with a
-custom policy for `b2c_1a_signup_signin`:
+- Easier to configure.
+- More secure because leaking the private key has severe security consequences.
+
+The signature algorithm can be configured in the Keycloak administration console under
+**Realm Settings > Tokens > Default Signature Algorithm**.
+
+Example Omnibus configuration block:
 
 ```ruby
 gitlab_rails['omniauth_providers'] = [
-{
-  'name' => 'openid_connect',
-  'label' => 'Azure B2C OIDC',
-  'args' => {
+  {
     'name' => 'openid_connect',
-    'scope' => ['openid'],
-    'response_mode' => 'query',
-    'response_type' => 'id_token',
-    'issuer' =>  'https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/b2c_1a_signup_signin/v2.0/',
-    'client_auth_method' => 'query',
-    'discovery' => true,
-    'send_scope_to_token_endpoint' => true,
-    'client_options' => {
-      'identifier' => '<YOUR APP CLIENT ID>',
-      'secret' => '<YOUR APP CLIENT SECRET>',
-      'redirect_uri' => 'https://gitlab.example.com/users/auth/openid_connect/callback'
+    'label' => 'Keycloak',
+    'args' => {
+      'name' => 'openid_connect',
+      'scope' => ['openid', 'profile', 'email'],
+      'response_type' => 'code',
+      'issuer' =>  'https://keycloak.example.com/auth/realms/myrealm',
+      'client_auth_method' => 'query',
+      'discovery' => true,
+      'uid_field' => 'preferred_username',
+      'client_options' => {
+        'identifier' => '<YOUR CLIENT ID>',
+        'secret' => '<YOUR CLIENT SECRET>',
+        'redirect_uri' => 'https://gitlab.example.com/users/auth/openid_connect/callback'
+      }
     }
   }
-}]
+]
 ```
 
-#### Troubleshooting Azure B2C
+##### Configure Keycloak with a symmetric key algorithm
 
-- Ensure all occurrences of `yourtenant.onmicrosoft.com`, `ProxyIdentityExperienceFrameworkAppId`, and `IdentityExperienceFrameworkAppId` match your B2C tenant hostname and
-the respective client IDs in the XML policy files.
+> Introduced in GitLab 14.2.
 
-- Add `https://jwt.ms` as a redirect URI to the app, and use the [custom policy tester](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#test-the-custom-policy).
-Make sure the payload includes `email` that matches the user's e-mail access.
+WARNING:
+The instructions below are included for completeness, but symmetric key
+encryption should only be used when absolutely necessary.
 
-- After you enable the custom policy, users might see "Invalid username or password" after they try to sign in. This might be a configuration
-issue with the `IdentityExperienceFramework` app. See [this Microsoft comment](https://docs.microsoft.com/en-us/answers/questions/50355/unable-to-sign-on-using-custom-policy.html?childToView=122370#comment-122370)
-that suggests checking that the app manifest contains these settings:
+To use symmetric key encryption:
 
-  - `"accessTokenAcceptedVersion": null`
-  - `"signInAudience": "AzureADMyOrg"`
+1. Extract the secret key from the Keycloak database. Keycloak doesn't expose this value in the Web
+   interface. The client secret seen in the Web interface is the OAuth2 client secret, which is
+   different from the secret used to sign JSON Web Tokens.
+
+   For example, if you're using PostgreSQL as the backend database for Keycloak, log in to the
+   database console and extract the key via this SQL query:
+
+   ```sql
+   $ psql -U keycloak
+   psql (13.3 (Debian 13.3-1.pgdg100+1))
+   Type "help" for help.
+
+   keycloak=# SELECT c.name, value FROM component_config CC INNER JOIN component C ON(CC.component_id = C.id) WHERE C.realm_id = 'master' and provider_id = 'hmac-generated' AND CC.name = 'secret';
+   -[ RECORD 1 ]---------------------------------------------------------------------------------
+   name  | hmac-generated
+   value | lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g
+   -[ RECORD 2 ]---------------------------------------------------------------------------------
+   name  | fallback-HS384
+   value | UfVqmIs--U61UYsRH-NYBH3_mlluLONpg_zN7CXEwkJcO9xdRNlzZfmfDLPtf2xSTMvqu08R2VhLr-8G-oZ47A
+   ```
+
+   In this example, there are two private keys: one for HS256 (`hmac-generated`), and another for
+   HS384 (`fallback-HS384`). We use the first `value` to configure GitLab.
+
+1. Convert `value` to standard base64. As [discussed in the post](https://keycloak.discourse.group/t/invalid-signature-with-hs256-token/3228/9),
+   `value` is encoded in ["Base 64 Encoding with URL and Filename Safe Alphabet" in RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-5).
+   This needs to be converted to [standard base64 as defined in RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045).
+   The following Ruby script does this:
+
+   ```ruby
+   require 'base64'
+
+   value = "lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g"
+   Base64.encode64(Base64.urlsafe_decode64(value))
+   ```
+
+   This results in the following value:
+
+   ```markdown
+   lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62+sqGc8drp3XW+wr93zru8PFsQokH\nZZuJJbaUXvmiOftCZM3C4KW3+g==\n
+   ```
+
+1. Specify this base64-encoded secret in `jwt_secret_base64`. For example:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       'name' => 'openid_connect',
+       'label' => 'Keycloak',
+       'args' => {
+         'name' => 'openid_connect',
+         'scope' => ['openid', 'profile', 'email'],
+         'response_type' => 'code',
+         'issuer' =>  'https://keycloak.example.com/auth/realms/myrealm',
+         'client_auth_method' => 'query',
+         'discovery' => true,
+         'uid_field' => 'preferred_username',
+         'jwt_secret_base64' => '<YOUR BASE64-ENCODED SECRET>',
+         'client_options' => {
+           'identifier' => '<YOUR CLIENT ID>',
+           'secret' => '<YOUR CLIENT SECRET>',
+           'redirect_uri' => 'https://gitlab.example.com/users/auth/openid_connect/callback'
+         }
+       }
+     }
+   ]
+   ```
 
-    Note that this configuration corresponds with the `Supported account types` setting used when creating the `IdentityExperienceFramework` app.
+If after reconfiguring, you see the error `JSON::JWS::VerificationFailed` error message, this means
+the incorrect secret was specified.
 
 ## General troubleshooting
 
diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md
deleted file mode 100644
index 64b42339d19..00000000000
--- a/doc/administration/auth/okta.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-redirect_to: '../../integration/saml.md'
-remove_date: '2021-06-15'
----
-
-This document was moved to [another location](../../integration/saml.md).
-
-<!-- This redirect file can be deleted after 2021-06-15>. -->
-<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->