Merge branch 'docs/google-workspace-saml' into 'master'

Add Google Workspace SAML docs

See merge request gitlab-org/gitlab!51831

doc/administration/auth/README.md

@@ -22,7 +22,8 @@ providers:
 - [Facebook](../../integration/facebook.md)
 - [GitHub](../../integration/github.md)
 - [GitLab.com](../../integration/gitlab.md)
-- [Google](../../integration/google.md)
+- [Google OAuth](../../integration/google.md)
+- [Google Workspace SSO](../../integration/google_workspace_saml.md)
 - [JWT](jwt.md)
 - [Kerberos](../../integration/kerberos.md)
 - [LDAP](ldap/index.md): Includes Active Directory, Apple Open Directory, Open LDAP,

doc/integration/google_workspace_saml.md

+---
+type: reference
+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
+---
+
+# Google Workspace SSO provider
+
+Google Workspace (formerly G Suite) is a [Single Sign-on provider](https://support.google.com/a/answer/60224?hl=en) that can be used to authenticate
+with GitLab.
+
+The following documentation enables Google Workspace as a SAML provider for GitLab.
+
+## Configure the Google Workspace SAML app
+
+The following guidance is based on this Google Workspace article, on how to [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en):
+
+Make sure you have access to a Google Workspace [Super Admin](https://support.google.com/a/answer/2405986#super_admin) account.
+   Follow the instructions in the linked Google Workspace article, where you'll need the following information:
+
+|                  | Typical value                                    | Description                                              |
+|------------------|--------------------------------------------------|----------------------------------------------------------|
+| Name of SAML App | GitLab                                           | Other names OK.                                          |
+| ACS URL          | `https://<GITLAB_DOMAIN>/users/auth/saml/callback` | ACS is short for Assertion Consumer Service.             |
+| GITLAB_DOMAIN    | `gitlab.example.com`                             | Set to the domain of your GitLab instance.               |
+| Entity ID        | `https://gitlab.example.com`                     | A value unique to your SAML app, you'll set it to the `issuer` in your GitLab configuration.                         |
+| Name ID format   | EMAIL                                            | Required value. Also known as `name_identifier_format`                    |
+| Name ID          | Primary email address                            | Make sure someone receives content sent to that address                |
+| First name       | `first_name`                                     | Required value to communicate with GitLab.               |
+| Last name        | `last_name`                                      | Required value to communicate with GitLab.               |
+
+You will also need to setup the following SAML attribute mappings:
+
+| Google Directory attributes       | App attributes |
+|-----------------------------------|----------------|
+| Basic information > Email         | `email`        |
+| Basic Information > First name    | `first_name`   |
+| Basic Information > Last name     | `last_name`    |
+
+You may also use some of this information when you [Configure GitLab](#configure-gitlab).
+
+When configuring the Google Workspace SAML app, be sure to record the following information:
+
+|             | Value        | Description                                                                       |
+|-------------|--------------|-----------------------------------------------------------------------------------|
+| SSO URL     | Depends      | Google Identity Provider details. Set to the GitLab `idp_sso_target_url` setting. |
+| Certificate | Downloadable | Run `openssl x509 -in <your_certificate.crt> -noout -fingerprint` to generate the SHA1 fingerprint that can be used in the `idp_cert_fingerprint` setting.                         |
+
+While the Google Workspace Admin provides IDP metadata, Entity ID and SHA-256 fingerprint,
+GitLab does not need that information to connect to the Google Workspace SAML app.
+
+---
+
+Now that the Google Workspace SAML app is configured, it's time to enable it in GitLab.
+
+## Configure GitLab
+
+1. See [Initial OmniAuth Configuration](../integration/omniauth.md#initial-omniauth-configuration)
+   for initial settings.
+
+1. To allow people to register for GitLab, through their Google accounts, add the following
+   values to your configuration:
+
+   **For Omnibus GitLab installations**
+
+   Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
+   gitlab_rails['omniauth_block_auto_created_users'] = false
+   ```
+
+   ---
+
+   **For installations from source**
+
+   Edit `config/gitlab.yml`:
+
+   ```yaml
+   allow_single_sign_on: ["saml"]
+   block_auto_created_users: false
+   ```
+
+1. If an existing GitLab user has the same email address as a Google Workspace user, the registration
+   process automatically links their accounts, if you add the following setting:
+   their email addresses match by adding the following setting:
+
+   **For Omnibus GitLab installations**
+
+   Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['omniauth_auto_link_saml_user'] = true
+   ```
+
+   ---
+
+   **For installations from source**
+
+   Edit `config/gitlab.yml`:
+
+   ```yaml
+   auto_link_saml_user: true
+   ```
+
+1. Add the provider configuration.
+
+For guidance on how to set up these values, see the [SAML General Setup steps](saml.md#general-setup).
+Pay particular attention to the values for:
+
+- `assertion_consumer_service_url`
+- `idp_cert_fingerprint`
+- `idp_sso_target_url`
+- `issuer`
+- `name_identifier_format`
+
+   **For Omnibus GitLab installations**
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       name: 'saml',
+       args: {
+                assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback',
+                idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00',
+                idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000',
+                issuer: 'https://<GITLAB_DOMAIN>',
+                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress'
+              },
+       label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml"
+     }
+   ]
+   ```
+
+   **For installations from source**
+
+   ```yaml
+   - {
+       name: 'saml',
+       args: {
+              assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback',
+              idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00',
+              idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000',
+              issuer: 'https://<GITLAB_DOMAIN>',
+              name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress'
+            },
+       label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml"
+     }
+   ```
+
+1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for Omnibus and installations
+   from source respectively for the changes to take effect.
+
+To avoid caching issues, test the result on an incognito or private browser window.
+
+## Troubleshooting
+
+The Google Workspace documentation on [SAML app error messages](https://support.google.com/a/answer/6301076?hl=en) is helpful for debugging if you are seeing an error from Google while signing in.
+Pay particular attention to the following 403 errors:
+
+- `app_not_configured`
+- `app_not_configured_for_user`