From dd8c199e989482245c58ee49b5f7169bdd9073eb Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Mon, 30 Jan 2023 21:09:38 +0000 Subject: Add latest changes from gitlab-org/gitlab@master --- doc/integration/arkose.md | 24 +- doc/integration/omniauth.md | 23 +- doc/integration/saml.md | 3100 ++++++++++++++++++++++++++++++++++++------- 3 files changed, 2684 insertions(+), 463 deletions(-) (limited to 'doc/integration') diff --git a/doc/integration/arkose.md b/doc/integration/arkose.md index 9c8f6cdfb6a..36c0784cb94 100644 --- a/doc/integration/arkose.md +++ b/doc/integration/arkose.md @@ -93,17 +93,25 @@ To check if a user failed to sign in because the ArkoseLabs challenge was not so KQL: json.message:"Challenge was not solved" AND json.username:replace_username_here` ``` -## QA tests caveat +## Allowlists -Several GitLab QA test suites need to sign in to the app to test its features. This can conflict -with Arkose Protect as it would identify QA users as being malicious because they are being run with -a headless browser. To work around this, ArkoseLabs has allowlisted the unique token -that serves as QA session's User Agent. While this doesn't guarantee that the session is not -flagged as malicious, the Arkose API returns a specific telltale when we verify the sign in -attempt's token. We are leveraging this telltale to bypass the verification step entirely so that the -test suite doesn't fail. This bypass is done in the `UserVerificationService` class. +To ensure end-to-end QA test suites can pass during staging and production, we've [allowlisted](https://developer.arkoselabs.com/docs/verify-api-v4#creating-allowlists-and-denylists) the [GITLAB_QA_USER_AGENT](https://start.1password.com/open/i?a=LKATQYUATRBRDHRRABEBH4RJ5Y&v=6gq44ckmq23vqk5poqunurdgay&i=u2wvs63affaxzi22gnfbjjw2zm&h=gitlab.1password.com). Each QA user receives an `ALLOWLIST` [risk category](https://developer.arkoselabs.com/docs/risk-score). + +You can find the usage of the allowlist telltale in our [Arkose::VerifyResponse](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/arkose/verify_response.rb#L38) class. ## Feedback Job To help Arkose improve their protection service, we created a daily background job to send them the list of blocked users by us. This job is performed by the `Arkose::BlockedUsersReportWorker` class. + +## Additional resources + + +The [Anti-abuse team](https://about.gitlab.com/handbook/engineering/development/data-science/anti-abuse/#team-members) owns the ArkoseLabs Protect feature. You can join our ArkoseLabs/GitLab collaboration channel on Slack: [#ext-gitlab-arkose](https://gitlab.slack.com/archives/C02SGF6RLPQ). + + +ArkoseLabs also maintains the following resources: + +- [ArkoseLabs portal](https://portal.arkoselabs.com/) +- [ArkoseLabs Zendesk](https://support.arkoselabs.com/) +- [ArkoseLabs documentation](https://developer.arkoselabs.com/docs/documentation-guide) diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 07dbe46691b..1dfd9c95a73 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -43,7 +43,7 @@ GitLab supports the following OmniAuth providers. Before you configure the OmniAuth provider, configure the settings that are common for all providers. -Omnibus, Docker, and source | Helm chart | Description | Default value +Linux package, Docker, and self-compiled | Helm chart | Description | Default value ----------------------------|------------|-------------|----------- `allow_single_sign_on` | `allowSingleSignOn` | List of providers that automatically create a GitLab account. The provider names are available in the **OmniAuth provider name** column in the [supported providers table](#supported-providers). | `false`, which means that signing in using your OmniAuth provider account without a pre-existing GitLab account is not allowed. You must create a GitLab account first, and then connect it to your OmniAuth provider account through your profile settings. `auto_link_ldap_user` | `autoLinkLdapUser` | Creates an LDAP identity in GitLab for users that are created through an OmniAuth provider. You can enable this setting if you have [LDAP integration](../administration/auth/ldap/index.md) enabled. Requires the `uid` of the user to be the same in both LDAP and the OmniAuth provider. | `false` @@ -104,6 +104,27 @@ To change the OmniAuth settings: 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['omniauth_allow_single_sign_on'] = ['saml', 'twitter'] + gitlab_rails['omniauth_auto_link_ldap_user'] = true + gitlab_rails['omniauth_block_auto_created_users'] = true + ``` + + 1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + :::TabTitle Self-compiled (source) 1. Edit `/home/git/gitlab/config/gitlab.yml`: diff --git a/doc/integration/saml.md b/doc/integration/saml.md index b210a9b9888..24b5e6152a5 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -23,62 +23,29 @@ For more information on: ## Configure SAML support in GitLab -1. Make sure GitLab is [configured with HTTPS](../install/installation.md#using-https). - -1. On your GitLab server, open the configuration file. - - For Omnibus installations: - - ```shell - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```shell - cd /home/git/gitlab +::Tabs - sudo -u git -H editor config/gitlab.yml - ``` +:::TabTitle Linux package (Omnibus) +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/). 1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) to add `saml` as a single sign-on provider. This enables Just-In-Time account provisioning for users who do not have an existing GitLab account. - 1. To allow your users to use SAML to sign up without having to manually create - an account first, add the following values to your configuration. - - For Omnibus installations: + an account first, 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: - - ```yaml - omniauth: - enabled: true - allow_single_sign_on: ["saml"] - block_auto_created_users: false - ``` - 1. Optional. You can automatically link SAML users with existing GitLab users if their - email addresses match by adding the following setting. - - For Omnibus installations: + email addresses match by adding the following setting in `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['omniauth_auto_link_saml_user'] = true ``` - For installations from source: - - ```yaml - auto_link_saml_user: true - ``` - Alternatively, a user can manually link their SAML identity to an existing GitLab account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). @@ -91,9 +58,7 @@ For more information on: See your SAML IdP documentation for information on how to make these attributes unchangeable. -1. Add the provider configuration. - - For Omnibus installations: +1. Edit `/etc/gitlab/gitlab.rb` and add the provider configuration: ```ruby gitlab_rails['omniauth_providers'] = [ @@ -111,7 +76,244 @@ For more information on: ] ``` - For installations from source: + Where: + + - `assertion_consumer_service_url`: The GitLab HTTPS endpoint + (append `/users/auth/saml/callback` to the HTTPS URL of your GitLab installation). + - `idp_cert_fingerprint`: Your IdP value. It must be a SHA1 fingerprint. + For more information on these values, see the + [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). + For more information on other configuration settings, see + [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `idp_sso_target_url`: Your IdP value. + - `issuer`: Change to a unique name, which identifies the application to the IdP. + - `name_identifier_format`: Your IdP value. + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/charts/installation/tls.html). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `saml` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. To allow your users to use SAML to sign up without having to manually create + an account first, edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + enabled: true + allowSingleSignOn: ['saml'] + blockAutoCreatedUsers: true + ``` + +1. Optional. You can automatically link SAML users with existing GitLab users if their + email addresses match by adding the following setting in `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + autoLinkSamlUser: true + ``` + + Alternatively, a user can manually link their SAML identity to an existing GitLab + account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). + +1. Configure the following attributes so your SAML users cannot change them: + + - [`NameID`](../user/group/saml_sso/index.md#nameid). + - `Email` when used with `omniauth_auto_link_saml_user`. + + If users can change these attributes, they can sign in as other authorized users. + See your SAML IdP documentation for information on how to make these attributes + unchangeable. + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Provider name' # optional label for login button, defaults to "Saml" + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + + Where: + + - `assertion_consumer_service_url`: The GitLab HTTPS endpoint + (append `/users/auth/saml/callback` to the HTTPS URL of your GitLab installation). + - `idp_cert_fingerprint`: Your IdP value. It must be a SHA1 fingerprint. + For more information on these values, see the + [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). + For more information on other configuration settings, see + [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `idp_sso_target_url`: Your IdP value. + - `issuer`: Change to a unique name, which identifies the application to the IdP. + - `name_identifier_format`: Your IdP value. + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Edit `gitlab_values.yaml` and add the provider configuration: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `saml` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. +1. To allow your users to use SAML to sign up without having to manually create + an account first, edit `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] + gitlab_rails['omniauth_block_auto_created_users'] = false + ``` + +1. Optional. You can automatically link SAML users with existing GitLab users if their + email addresses match by adding the following setting in `docker-compose.yml`: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_auto_link_saml_user'] = true + ``` + + Alternatively, a user can manually link their SAML identity to an existing GitLab + account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). + +1. Configure the following attributes so your SAML users cannot change them: + + - [`NameID`](../user/group/saml_sso/index.md#nameid). + - `Email` when used with `omniauth_auto_link_saml_user`. + + If users can change these attributes, they can sign in as other authorized users. + See your SAML IdP documentation for information on how to make these attributes + unchangeable. + +1. Edit `docker-compose.yml` and add the provider configuration: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { + name: "saml", + label: "Provider name", # optional label for login button, defaults to "Saml" + args: { + assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", + idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", + idp_sso_target_url: "https://login.example.com/idp", + issuer: "https://gitlab.example.com", + name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" + } + } + ] + ``` + + Where: + + - `assertion_consumer_service_url`: The GitLab HTTPS endpoint + (append `/users/auth/saml/callback` to the HTTPS URL of your GitLab installation). + - `idp_cert_fingerprint`: Your IdP value. It must be a SHA1 fingerprint. + For more information on these values, see the + [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). + For more information on other configuration settings, see + [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `idp_sso_target_url`: Your IdP value. + - `issuer`: Change to a unique name, which identifies the application to the IdP. + - `name_identifier_format`: Your IdP value. + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Make sure GitLab is [configured with HTTPS](../install/installation.md#using-https). +1. Edit the [common configuration file settings](omniauth.md#configure-common-settings) + to add `saml` as a single sign-on provider. This enables Just-In-Time + account provisioning for users who do not have an existing GitLab account. +1. To allow your users to use SAML to sign up without having to manually create + an account first, edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + enabled: true + allow_single_sign_on: ["saml"] + block_auto_created_users: false + ``` + +1. Optional. You can automatically link SAML users with existing GitLab users if their + email addresses match by adding the following setting in `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + auto_link_saml_user: true + ``` + + Alternatively, a user can manually link their SAML identity to an existing GitLab + account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). + +1. Configure the following attributes so your SAML users cannot change them: + + - [`NameID`](../user/group/saml_sso/index.md#nameid). + - `Email` when used with `omniauth_auto_link_saml_user`. + + If users can change these attributes, they can sign in as other authorized users. + See your SAML IdP documentation for information on how to make these attributes + unchangeable. + +1. Edit `/home/git/gitlab/config/gitlab.yml` and add the provider configuration: ```yaml omniauth: @@ -129,26 +331,30 @@ For more information on: } ``` -1. Match the value for `assertion_consumer_service_url` to the HTTPS endpoint - of GitLab. To generate the correct value, append `users/auth/saml/callback` to the - HTTPS URL of your GitLab installation. + Where: -1. Change the following values to match your IdP: - - `idp_cert_fingerprint`. - - `idp_sso_target_url`. - - `name_identifier_format`. - If you use a `idp_cert_fingerprint`, it must be a SHA1 fingerprint. For more - information on these values, see the - [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). - For more information on other configuration settings, see - [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `assertion_consumer_service_url`: The GitLab HTTPS endpoint + (append `/users/auth/saml/callback` to the HTTPS URL of your GitLab installation). + - `idp_cert_fingerprint`: Your IdP value. It must be a SHA1 fingerprint. + For more information on these values, see the + [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml). + For more information on other configuration settings, see + [configuring SAML on your IdP](#configure-saml-on-your-idp). + - `idp_sso_target_url`: Your IdP value. + - `issuer`: Change to a unique name, which identifies the application to the IdP. + - `name_identifier_format`: Your IdP value. -1. Change the value of `issuer` to a unique name, which identifies the application - to the IdP. +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 + ``` -1. For the changes to take effect, if you installed: - - Using Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - From source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +::EndTabs ### Register GitLab in your SAML IdP @@ -204,65 +410,229 @@ You can configure GitLab to use multiple SAML IdPs if: [SAML group memberships](#configure-users-based-on-saml-group-membership) and [Group Sync](../user/group/saml_sso/group_sync.md) do not support multiple IdPs. For more information, see [issue 386605](https://gitlab.com/gitlab-org/gitlab/-/issues/386605). -Example provider's configuration for installations from source: - -```yaml -omniauth: - providers: - - { - name: 'saml', # This must match the following name configuration parameter - args: { - name: 'saml', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 1' # Differentiate the two buttons and providers in the UI - } - - { - name: 'saml1', # This must match the following name configuration parameter - args: { - name: 'saml1', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 2' # Differentiate the two buttons and providers in the UI - } -``` - -Example provider's configuration for Omnibus GitLab installations: - -To allow your users to use SAML to sign up without having to manually create an account from either of the providers, add the following values to your configuration. - -```ruby -gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml1'] -``` - -```ruby -gitlab_rails['omniauth_providers'] = [ - { - name: 'saml', # This must match the following name configuration parameter - args: { - name: 'saml', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 1' # Differentiate the two buttons and providers in the UI - }, - { - name: 'saml1', # This must match the following name configuration parameter - args: { - name: 'saml1', # This is mandatory and must match the provider name - strategy_class: 'OmniAuth::Strategies::SAML', - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider - ... # Put here all the required arguments similar to a single provider - }, - label: 'Provider 2' # Differentiate the two buttons and providers in the UI - } -] -``` +To set up multiple SAML IdPs: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: 'saml', # This must match the following name configuration parameter + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + }, + { + name: 'saml_2', # This must match the following name configuration parameter + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml_2', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + } + ] + ``` + + To allow your users to use SAML to sign up without having to manually create an + account from either of the providers, add the following values to your configuration: + + ```ruby + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2'] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers) + for the first SAML provider: + + ```yaml + name: 'saml' # At least one provider must be named 'saml' + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + args: + name: 'saml' # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory + ... # Put here all the required arguments similar to a single provider + ``` + +1. Put the following content in a file named `saml_2.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers) + for the second SAML provider: + + ```yaml + name: 'saml_2' + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + args: + name: 'saml_2' # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory + ... # Put here all the required arguments similar to a single provider + ``` + +1. Optional. Set additional SAML providers by following the same steps. +1. Create the Kubernetes Secrets: + + ```shell + kubectl create secret generic -n gitlab-saml \ + --from-file=saml=saml.yaml \ + --from-file=saml_2=saml_2.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + - key: saml + - secret: gitlab-saml + - key: saml_2 + ``` + + To allow your users to use SAML to sign up without having to manually create an + account from either of the providers, add the following values to your configuration: + + ```yaml + global: + appConfig: + omniauth: + allowSingleSignOn: ['saml', 'saml_2'] + ``` + +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['omniauth_allow_single_sign_on'] = ['saml', 'saml1'] + gitlab_rails['omniauth_providers'] = [ + { + name: 'saml', # This must match the following name configuration parameter + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + }, + { + name: 'saml_2', # This must match the following name configuration parameter + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml_2', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + } + ] + ``` + + To allow your users to use SAML to sign up without having to manually create an + account from either of the providers, add the following values to your configuration: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2'] + ``` + +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 + omniauth: + providers: + - { + name: 'saml', # This must match the following name configuration parameter + label: 'Provider 1' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml', # This is mandatory and must match the provider name + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider + strategy_class: 'OmniAuth::Strategies::SAML', + ... # Put here all the required arguments similar to a single provider + }, + } + - { + name: 'saml_2', # This must match the following name configuration parameter + label: 'Provider 2' # Differentiate the two buttons and providers in the UI + args: { + name: 'saml_2', # This is mandatory and must match the provider name + strategy_class: 'OmniAuth::Strategies::SAML', + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider + ... # Put here all the required arguments similar to a single provider + }, + } + ``` + + To allow your users to use SAML to sign up without having to manually create an + account from either of the providers, add the following values to your configuration: + + ```yaml + production: &base + omniauth: + allow_single_sign_on: ["saml", "saml_2"] + ``` + +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 ## Set up identity providers @@ -388,26 +758,26 @@ Support for these groups depends on: | [Admin](#administrator-groups) | **(FREE SELF)** | Yes | | [Auditor](#auditor-groups) | **(PREMIUM SELF)** | Yes | -### Prerequisites - -You must tell GitLab where to look for group information. To do this, make sure -that your IdP server sends a specific `AttributeStatement` along with the regular -SAML response. For example: - -```xml - - - Developers - Freelancers - Admins - Auditors - - -``` +Prerequisites: -The name of the attribute must contain the groups that a user belongs to. -To tell GitLab where to find these groups, add a `groups_attribute:` -element to your SAML settings. +- You must tell GitLab where to look for group information. To do this, make sure + that your IdP server sends a specific `AttributeStatement` along with the regular + SAML response. For example: + + ```xml + + + Developers + Freelancers + Admins + Auditors + + + ``` + + The name of the attribute must contain the groups that a user belongs to. + To tell GitLab where to find these groups, add a `groups_attribute:` + element to your SAML settings. ### Required groups @@ -423,388 +793,1977 @@ membership is required to sign in. If you do not set `required_groups` or leave the setting empty, anyone with proper authentication can use the service. -Example configuration: - -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - } } -``` +::Tabs -### External groups +:::TabTitle Linux package (Omnibus) -Your IdP passes group information to GitLab in the SAML response. To use this -response, configure GitLab to identify: +1. Edit `/etc/gitlab/gitlab.rb`: -- Where to look for the groups in the SAML response, using the `groups_attribute` setting. -- Information about a group or user, using a group setting. + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` -SAML can automatically identify a user as an -[external user](../user/admin_area/external_users.md), based on the `external_groups` -setting. +1. Save the file and reconfigure GitLab: -Example configuration: + ```shell + sudo gitlab-ctl reconfigure + ``` -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - external_groups: ['Freelancers'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - } } -``` +:::TabTitle Helm chart (Kubernetes) -### Administrator groups +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): -Your IdP passes group information to GitLab in the SAML response. To use this -response, configure GitLab to identify: + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` -- Where to look for the groups in the SAML response, using the `groups_attribute` setting. -- Information about a group or user, using a group setting. +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +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 + +### External groups + +Your IdP passes group information to GitLab in the SAML response. To use this +response, configure GitLab to identify: + +- Where to look for the groups in the SAML response, using the `groups_attribute` setting. +- Information about a group or user, using a group setting. + +SAML can automatically identify a user as an +[external user](../user/admin_area/external_users.md), based on the `external_groups` +setting. + +Example configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + external_groups: ['Freelancers'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + external_groups: ['Freelancers'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + external_groups: ['Freelancers'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + external_groups: ['Freelancers'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +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 + +### Administrator groups + +Your IdP passes group information to GitLab in the SAML response. To use this +response, configure GitLab to identify: + +- Where to look for the groups in the SAML response, using the `groups_attribute` setting. +- Information about a group or user, using a group setting. Use the `admin_groups` setting to configure GitLab to identify which groups grant the user administrator access. -Example configuration: +Example configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + admin_groups: ['Admins'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + admin_groups: ['Admins'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + admin_groups: ['Admins'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + admin_groups: ['Admins'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +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 + +### Auditor groups **(PREMIUM SELF)** + +> Introduced in GitLab 11.4. + +Your IdP passes group information to GitLab in the SAML response. To use this +response, configure GitLab to identify: + +- Where to look for the groups in the SAML response, using the `groups_attribute` setting. +- Information about a group or user, using a group setting. + +Use the `auditor_groups` setting to configure GitLab to identify which groups include +users with [auditor access](../administration/auditor_users.md). + +Example configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + auditor_groups: ['Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + auditor_groups: ['Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + auditor_groups: ['Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + auditor_groups: ['Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +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 + +## Automatically manage SAML Group Sync + +For information on automatically managing GitLab group membership, see [SAML Group Sync](../user/group/saml_sso/group_sync.md). + +## Bypass two-factor authentication + +To configure a SAML authentication method to count as two-factor authentication +(2FA) on a per session basis, register that method in the `upstream_two_factor_authn_contexts` +list. + +1. Make sure that your IdP is returning the `AuthnContext`. For example: + + ```xml + + + urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport + + + ``` + +1. Edit your installation configuration to register the SAML authentication method + in the `upstream_two_factor_authn_contexts` list. + + ::Tabs + + :::TabTitle Linux package (Omnibus) + + 1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + upstream_two_factor_authn_contexts: + %w( + urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN + ), + } + } + ] + ``` + + 1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + + :::TabTitle Helm chart (Kubernetes) + + 1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + upstream_two_factor_authn_contexts: + - 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport' + - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS' + - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN' + ``` + + 1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + + 1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + + 1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + + 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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + upstream_two_factor_authn_contexts: + %w( + urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS + urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN + ) + } + } + ] + ``` + + 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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + upstream_two_factor_authn_contexts: + [ + 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport', + 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS', + 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN' + ] + } + } + ``` + + 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 + +## Validate response signatures + +IdPs must sign SAML responses to ensure that the assertions are not tampered with. + +This prevents user impersonation and privilege escalation when specific group +membership is required. + +### Using `idp_cert_fingerprint` + +You configure the response signature validation using `idp_cert_fingerprint`. +An example configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +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 + +### Using `idp_cert` + +If your IdP does not support configuring this using `idp_cert_fingerprint`, you +can instead configure GitLab directly using `idp_cert`. +An example configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert: '-----BEGIN CERTIFICATE----- + + -----END CERTIFICATE-----', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert: | + -----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert: '-----BEGIN CERTIFICATE----- + + -----END CERTIFICATE-----', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ] + ``` + +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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert: '-----BEGIN CERTIFICATE----- + + -----END CERTIFICATE-----', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + } + } + ``` + +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 + +If you have configured the response signature validation incorrectly, you might see +error messages such as: + +- A key validation error. +- Digest mismatch. +- Fingerprint mismatch. + +For more information on solving these errors, see the [troubleshooting SAML guide](../user/group/saml_sso/troubleshooting.md). + +## Customize SAML settings + +### Redirect users to SAML server for authentication + +You can add the `auto_sign_in_with_provider` setting to your GitLab configuration +to automatically redirect you to your SAML server for authentication. This removes +the requirement to select an element before actually signing in. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' + ``` + +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: + omniauth: + autoSignInWithProvider: 'saml' + ``` + +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['omniauth_auto_sign_in_with_provider'] = 'saml' + ``` + +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 + omniauth: + auto_sign_in_with_provider: 'saml' + ``` + +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 + +Every sign in attempt redirects to the SAML server, so you cannot sign in using +local credentials. Make sure at least one of the SAML users has administrator access. + +NOTE: +To bypass the auto sign-in setting, append `?auto_sign_in=false` in the sign in +URL, for example: `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. + +### Map SAML response attribute names **(FREE SELF)** + +You can use `attribute_statements` to map attribute names in a SAML response to entries +in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). + +NOTE: +Only use this setting to map attributes that are part of the OmniAuth `info` hash schema. + +For example, if your `SAMLResponse` contains an Attribute called `EmailAddress`, +specify `{ email: ['EmailAddress'] }` to map the Attribute to the +corresponding key in the `info` hash. URI-named Attributes are also supported, for example, +`{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. + +Use this setting to tell GitLab where to look for certain attributes required +to create an account. For example, if your IdP sends the user's email address as `EmailAddress` +instead of `email`, let GitLab know by setting it on your configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { email: ['EmailAddress'] } + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + attribute_statements: + email: ['EmailAddress'] + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { email: ['EmailAddress'] } + } + } + ] + ``` + +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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { email: ['EmailAddress'] } + } + } + ``` + +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 + +#### Set a username + +By default, the local part of the email address in the SAML response is used to +generate the user's GitLab username. + +Configure `nickname` in `attribute_statements` to specify one or more attributes that contain a user's desired username: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { nickname: ['username'] } + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + attribute_statements: + nickname: ['username'] + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + +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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { nickname: ['username'] } + } + } + ] + ``` + +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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + attribute_statements: { nickname: ['username'] } + } + } + ``` + +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 + +This also sets the `username` attribute in your SAML Response to the username in GitLab. + +### Allow for clock drift + +The clock of the IdP may drift slightly ahead of your system clocks. +To allow for a small amount of clock drift, use `allowed_clock_drift` in +your settings. You must enter the parameter's value in a number and fraction of seconds. +The value given is added to the current time at which the response is validated. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + allowed_clock_drift: 1 # for one second clock drift + } + } + ] + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + allowed_clock_drift: 1 # for one second clock drift + ``` + +1. Create the Kubernetes Secret: -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - admin_groups: ['Admins'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - } } -``` + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` -### Auditor groups **(PREMIUM SELF)** +1. Export the Helm values: -> Introduced in GitLab 11.4. + ```shell + helm get values gitlab > gitlab_values.yaml + ``` -Your IdP passes group information to GitLab in the SAML response. To use this -response, configure GitLab to identify: +1. Edit `gitlab_values.yaml`: -- Where to look for the groups in the SAML response, using the `groups_attribute` setting. -- Information about a group or user, using a group setting. + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` -Use the `auditor_groups` setting to configure GitLab to identify which groups include -users with [auditor access](../administration/auditor_users.md). +1. Save the file and apply the new values: -Example configuration: + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - auditor_groups: ['Auditors'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' - } } -``` +:::TabTitle Docker -## Automatically manage SAML Group Sync +1. Edit `docker-compose.yml`: -For information on automatically managing GitLab group membership, see [SAML Group Sync](../user/group/saml_sso/group_sync.md). + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + allowed_clock_drift: 1 # for one second clock drift + } + } + ] + ``` -## Bypass two-factor authentication +1. Save the file and restart GitLab: -To configure a SAML authentication method to count as two-factor authentication -(2FA) on a per session basis, register that method in the `upstream_two_factor_authn_contexts` -list. + ```shell + docker compose up -d + ``` -1. Make sure that your IdP is returning the `AuthnContext`. For example: +:::TabTitle Self-compiled (source) -```xml - - - urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport - - -``` +1. Edit `/home/git/gitlab/config/gitlab.yml`: -1. Edit your installation configuration to register the SAML authentication method - in the `upstream_two_factor_authn_contexts` list. How you edit your configuration - differs depending on your installation type. + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + allowed_clock_drift: 1 # for one second clock drift + } + } + ``` + +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 + +### Designate a unique attribute for the `uid` + +Before setting the `uid` to a unique attribute, make sure that you have configured +the following attributes so your SAML users cannot change them: + +- [`NameID`](../user/group/saml_sso/index.md#nameid). +- `Email` when used with `omniauth_auto_link_saml_user`. + +If users can change these attributes, they can sign in as other authorized users. +See your SAML IdP documentation for information on how to make these attributes +unchangeable. + +By default, the `uid` is set as the `name_id` in the SAML response. To designate +a unique attribute for the `uid`, you can set the `uid_attribute`. In the following +example, the value of `uid` attribute in the SAML response is set as the `uid_attribute`. + +::Tabs -### Omnibus GitLab installations +:::TabTitle Linux package (Omnibus) 1. Edit `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['omniauth_providers'] = [ - { - name: "saml", + { name: 'saml', + label: 'Our SAML Provider', args: { - assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", - idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", - idp_sso_target_url: "https://login.example.com/idp", - issuer: "https://gitlab.example.com", - name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", - upstream_two_factor_authn_contexts: - %w( - urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport - urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS - urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN - ) - }, - label: "Company Login" # optional label for SAML login button, defaults to "Saml" + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + uid_attribute: 'uid' + } } ] ``` -1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - GitLab for the changes to take effect. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` -### Installations from source +:::TabTitle Helm chart (Kubernetes) -1. Edit `config/gitlab.yml`: +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): ```yaml - omniauth: - providers: - - { - name: 'saml', - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - upstream_two_factor_authn_contexts: - [ - 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport', - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS', - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN' - ] - }, - label: 'Company Login' # optional label for SAML login button, defaults to "Saml" - } + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + uid_attribute: 'uid' ``` -1. Save the file and [restart GitLab](../administration/restart_gitlab.md#installations-from-source) - for the changes to take effect. +1. Create the Kubernetes Secret: -## Validate response signatures + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` -IdPs must sign SAML responses to ensure that the assertions are not tampered with. +1. Export the Helm values: -This prevents user impersonation and privilege escalation when specific group -membership is required. + ```shell + helm get values gitlab > gitlab_values.yaml + ``` -You configure the response signature validation using `idp_cert_fingerprint`. -An example configuration: +1. Edit `gitlab_values.yaml`: -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', -} -``` + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` -If your IdP does not support configuring this using `idp_cert_fingerprint`, you -can instead configure GitLab directly using `idp_cert`. An example configuration: - -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert: '-----BEGIN CERTIFICATE----- - - -----END CERTIFICATE-----', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', -} -``` +1. Save the file and apply the new values: -If you have configured the response signature validation incorrectly, you might see -error messages such as: + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` -- A key validation error. -- Digest mismatch. -- Fingerprint mismatch. +:::TabTitle Docker -For more information on solving these errors, see the [troubleshooting SAML guide](../user/group/saml_sso/troubleshooting.md). +1. Edit `docker-compose.yml`: -## Customize SAML settings + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + uid_attribute: 'uid' + } + } + ] + ``` -### Redirect users to SAML server for authentication +1. Save the file and restart GitLab: -You can add the `auto_sign_in_with_provider` setting to your GitLab configuration -to automatically redirect you to your SAML server for authentication. This removes -the requirement to select an element before actually signing in. + ```shell + docker compose up -d + ``` -For Omnibus GitLab installations: +:::TabTitle Self-compiled (source) -```ruby -gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' -``` +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + uid_attribute: 'uid' + } + } + ``` -For installations from source: +1. Save the file and restart GitLab: -```yaml -omniauth: - auto_sign_in_with_provider: saml -``` + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target -Every sign in attempt redirects to the SAML server, so you cannot sign in using -local credentials. Make sure at least one of the SAML users has administrator access. + # For systems running SysV init + sudo service gitlab restart + ``` -You can also bypass the auto sign-in feature by -`https://gitlab.example.com/users/sign_in?auto_sign_in=false`. +::EndTabs -### Map SAML response attribute names **(FREE SELF)** +## Assertion encryption (optional) -You can use `attribute_statements` to map attribute names in a SAML response to entries -in the OmniAuth [`info` hash](https://github.com/omniauth/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). +GitLab requires the use of TLS encryption with SAML 2.0. Sometimes, GitLab needs +additional assertion encryption. For example, if you: + +- Terminate TLS encryption early at a load balancer. +- Include sensitive details in assertions that you do not want appearing in logs. + +Most organizations should not need additional encryption at this layer. + +Your IdP encrypts the assertion with the public certificate of GitLab. +GitLab decrypts the `EncryptedAssertion` with its private key. NOTE: -Only use this setting to map attributes that are part of the OmniAuth `info` hash schema. +This integration uses the `certificate` and `private_key` settings for both +assertion encryption and request signing. -For example, if your `SAMLResponse` contains an Attribute called `EmailAddress`, -specify `{ email: ['EmailAddress'] }` to map the Attribute to the -corresponding key in the `info` hash. URI-named Attributes are also supported, for example, -`{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. +The SAML integration supports `EncryptedAssertion`. To encrypt your assertions, +define the private key and the public certificate of your GitLab instance in the +SAML settings. -Use this setting to tell GitLab where to look for certain attributes required -to create an account. If your IdP sends the user's email address as `EmailAddress` -instead of `email`, let GitLab know by setting it on your configuration: +When you define the key and certificate, replace all line feeds in the key file with `\n`. +This makes the key file one long string with no line feeds. -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - attribute_statements: { email: ['EmailAddress'] } -} -``` +::Tabs -#### Set a username +:::TabTitle Linux package (Omnibus) -By default, the local part of the email address in the SAML response is used to -generate the user's GitLab username. +1. Edit `/etc/gitlab/gitlab.rb`: -Configure `nickname` in `attribute_statements` to specify one or more attributes that contain a user's desired username: + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----' + } + } + ] + ``` -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - attribute_statements: { nickname: ['username'] } -} -``` +1. Save the file and reconfigure GitLab: -This also sets the `username` attribute in your SAML Response to the username in GitLab. + ```shell + sudo gitlab-ctl reconfigure + ``` -### Allow for clock drift +:::TabTitle Helm chart (Kubernetes) -The clock of the IdP may drift slightly ahead of your system clocks. -To allow for a small amount of clock drift, use `allowed_clock_drift` in -your settings. You must enter the parameter's value in a number and fraction of seconds. -The value given is added to the current time at which the response is validated. +1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - attribute_statements: { email: ['EmailAddress'] }, - allowed_clock_drift: 1 # for one second clock drift -} -``` + ```yaml + name: 'saml' + label: 'Our SAML Provider' + groups_attribute: 'Groups' + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'] + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----' + private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----' + ``` -### Designate a unique attribute for the `uid` +1. Create the Kubernetes Secret: -By default, the `uid` is set as the `name_id` in the SAML response. To designate -a unique attribute for the `uid`, you can set the `uid_attribute`. In the following -example, the value of `uid` attribute in the SAML response is set as the `uid_attribute`. + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - uid_attribute: 'uid' -} -``` +1. Export the Helm values: -Before setting the `uid` to a unique attribute, make sure that you have configured -the following attributes so your SAML users cannot change them: + ```shell + helm get values gitlab > gitlab_values.yaml + ``` -- [`NameID`](../user/group/saml_sso/index.md#nameid). -- `Email` when used with `omniauth_auto_link_saml_user`. +1. Edit `gitlab_values.yaml`: -If users can change these attributes, they can sign in as other authorized users. -See your SAML IdP documentation for information on how to make these attributes -unchangeable. + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` -## Assertion encryption (optional) +1. Save the file and apply the new values: -GitLab requires the use of TLS encryption with SAML 2.0. Sometimes, GitLab needs -additional assertion encryption. For example, if you: + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` -- Terminate TLS encryption early at a load balancer. -- Include sensitive details in assertions that you do not want appearing in logs. +:::TabTitle Docker -Most organizations should not need additional encryption at this layer. +1. Edit `docker-compose.yml`: -The SAML integration supports `EncryptedAssertion`. To encrypt your assertions, -define the private key and the public certificate of your GitLab instance in the -SAML settings. + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----' + } + } + ] + ``` -When you define the key and certificate, replace all line feeds in the key file with `\n`. -This makes the key file one long string with no line feeds. +1. Save the file and restart GitLab: -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----', - private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----' -} -``` + ```shell + docker compose up -d + ``` -Your IdP encrypts the assertion with the public certificate of GitLab. -GitLab decrypts the `EncryptedAssertion` with its private key. +:::TabTitle Self-compiled (source) -NOTE: -This integration uses the `certificate` and `private_key` settings for both -assertion encryption and request signing. +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + production: &base + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----' + } + } + ``` + +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 ## Sign SAML authentication requests (optional) @@ -818,24 +2777,173 @@ To implement signing: 1. Configure the signing settings in the `security` section of the configuration. For example: -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', - certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----', - private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----', - security: { - authn_requests_signed: true, # enable signature on AuthNRequest - want_assertions_signed: true, # enable the requirement of signed assertion - metadata_signed: false, # enable signature on Metadata - signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', - digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256', - } -} -``` + ::Tabs + + :::TabTitle Linux package (Omnibus) + + 1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----', + security: { + authn_requests_signed: true, # enable signature on AuthNRequest + want_assertions_signed: true, # enable the requirement of signed assertion + metadata_signed: false, # enable signature on Metadata + signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', + digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256', + } + } + } + ] + ``` + + 1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + + :::TabTitle Helm chart (Kubernetes) + + 1. Put the following content in a file named `saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'saml' + label: 'Our SAML Provider' + args: + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8' + idp_sso_target_url: 'https://login.example.com/idp' + issuer: 'https://gitlab.example.com' + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' + certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----' + private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----' + security: + authn_requests_signed: true # enable signature on AuthNRequest + want_assertions_signed: true # enable the requirement of signed assertion + metadata_signed: false # enable signature on Metadata + signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256' + digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256' + ``` + + 1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-saml --from-file=provider=saml.yaml + ``` + + 1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + + 1. Edit `gitlab_values.yaml`: + + ```yaml + global: + appConfig: + omniauth: + providers: + - secret: gitlab-saml + ``` + + 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['omniauth_providers'] = [ + { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----', + security: { + authn_requests_signed: true, # enable signature on AuthNRequest + want_assertions_signed: true, # enable the requirement of signed assertion + metadata_signed: false, # enable signature on Metadata + signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', + digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256', + } + } + } + ] + ``` + + 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 + omniauth: + providers: + - { name: 'saml', + label: 'Our SAML Provider', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + certificate: '-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----', + private_key: '-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----', + security: { + authn_requests_signed: true, # enable signature on AuthNRequest + want_assertions_signed: true, # enable the requirement of signed assertion + metadata_signed: false, # enable signature on Metadata + signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256', + digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256', + } + } + } + ``` + + 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 GitLab then: @@ -877,24 +2985,108 @@ self-managed instance. To configure group SAML SSO: -1. [Configure GitLab with HTTPS](../install/installation.md#using-https). -1. Enable OmniAuth and the `group_saml` provider. +::Tabs + +:::TabTitle Linux package (Omnibus) - To do this for Omnibus GitLab installations, edit `gitlab.rb`: +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/). +1. Edit `/etc/gitlab/gitlab.rb` to enable OmniAuth and the `group_saml` provider: ```ruby gitlab_rails['omniauth_enabled'] = true gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }] ``` - For installations from source, edit `gitlab/config/gitlab.yml`: +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/charts/installation/tls.html). +1. Put the following content in a file named `group_saml.yaml` to be used as a + [Kubernetes Secret](https://docs.gitlab.com/charts/charts/globals.html#providers): + + ```yaml + name: 'group_saml' + ``` + +1. Create the Kubernetes Secret: + + ```shell + kubectl create secret generic -n gitlab-group-saml --from-file=provider=group_saml.yaml + ``` + +1. Export the Helm values: + + ```shell + helm get values gitlab > gitlab_values.yaml + ``` + +1. Edit `gitlab_values.yaml` to enable OmniAuth and the `group_saml` provider: + + ```yaml + global: + appConfig: + omniauth: + enabled: true + providers: + - secret: gitlab-group-saml + ``` + +1. Save the file and apply the new values: + + ```shell + helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab + ``` + +:::TabTitle Docker + +1. Make sure GitLab is [configured with HTTPS](https://docs.gitlab.com/omnibus/settings/ssl/). +1. Edit `docker-compose.yml` to enable OmniAuth and the `group_saml` provider: + + ```yaml + version: "3.6" + services: + gitlab: + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['omniauth_enabled'] = true + gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }] + ``` + +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. Make sure GitLab is [configured with HTTPS](../install/installation.md#using-https). +1. Edit `/home/git/gitlab/config/gitlab.yml` to enable OmniAuth and the `group_saml` provider: + + ```yaml + production: &base + omniauth: + enabled: true + providers: + - { name: 'group_saml' } + ``` + +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 + ``` - ```yaml - omniauth: - enabled: true - providers: - - { name: 'group_saml' } - ``` +::EndTabs As a multi-tenant solution, group SAML on a self-managed instance is limited compared to the recommended [instance-wide SAML](../user/group/saml_sso/index.md). Use -- cgit v1.2.3