在极狐GitLab 中配置 SAML 支持
设置身份提供商
基于 SAML 群组成员资格配置用户
自动管理 SAML 群组同步
绕过双重身份验证
验证响应签名
- 使用 idp_cert_fingerprint
- 使用 idp_cert
自定义 SAML 设置
断言加密（可选）
签署 SAML 身份验证请求（可选）
为通过 SAML 创建的用户生成密码
为现有用户关联 SAML 身份
在私有化部署实例上配置群组 SAML SSO
IdP 上 SAML 应用程序的其他配置
常用术语表
故障排产

私有化部署版极狐GitLab 实例的 SAML SSO

本页介绍如何为私有化部署版极狐GitLab 实例，设置实例范围的 SAML 单点登录（SSO）。

您可以将极狐GitLab 配置为 SAML 服务提供商 (SP），允许极狐GitLab 使用来自 SAML 身份提供程序 (IdP)（例如 Okta）的断言（assertions）来对用户进行身份验证。

为了在 JihuLab.com 上配置 SAML 设置，查看为 JihuLab.com 群组配置 SAML SSO。

更多信息：

OmniAuth 提供商设置，查看 OmniAuth 文档。
常用术语，查看常用术语表。

在极狐GitLab 中配置 SAML 支持

::Tabs

:::TabTitle Linux package (Omnibus)

确保极狐GitLab 配置了 HTTPS。
配置通用设置将 saml 添加为单点登录提供商。这将为没有现有极狐GitLab 账户的用户启用即时账户创建。
为了允许您的用户使用 SAML 进行注册，而无需从任一提供商手动创建账户，请将以下值添加到您的配置中。
```
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
```
可选。您应该将首次 SAML 登录的用户与现有极狐GitLab 账户自动链接起来，前提是他们的电子邮件地址匹配。为此，请将以下设置添加到 /etc/gitlab/gitlab.rb 中：
```
gitlab_rails['omniauth_auto_link_saml_user'] = true
```
只有极狐GitLab 账户的主电子邮件地址会与 SAML 响应中的电子邮件进行匹配。

或者，一个用户可以手动将他们的 SAML 身份与现有极狐GitLab 账户相关联，方法是为现有用户启用 OmniAuth。
配置如下属性以让您的 SAML 用户无法更改它们：
- NameID.
- Email when used with omniauth_auto_link_saml_user.
如果用户可以更改这些属性，他们可以作为其他授权用户登录。请参阅您的 SAML IdP 文档，了解如何使这些属性不可更改。

编辑 /etc/gitlab/gitlab.rb 文件并添加提供商配置：

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"
    }
  }
]

其中：

assertion_consumer_service_url：极狐GitLab HTTPS 端点（将 /users/auth/saml/callback 附加在您实例的 URL 后）。
idp_cert_fingerprint：您的 IdP 值。它必须是 SHA1 指纹。关于这些值的更多详情，可以查看 OmniAuth SAML 文档。关于其他配置设置的更多详情，可以查看在您的 IdP 上配置 SAML。
idp_sso_target_url：您的 IdP 值。
issuer：改为独一无二的名称，用来识别 IdP 应用程序。
name_identifier_format：您的 IdP 值。

保存文件并重新配置极狐GitLab。
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

确保极狐GitLab 配置了 HTTPS。
配置通用设置将 saml 添加为单点登录提供商。这将为没有现有极狐GitLab 账户的用户启用即时账户创建。

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

为了允许您的用户使用 SAML 来登录而无需先手动创建账号，编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      enabled: true
      allowSingleSignOn: ['saml']
      blockAutoCreatedUsers: false

可选。通过在 gitlab_values.yaml 中添加以下设置，让首次用 SAML 登录的用户与现有极狐GitLab 账户自动链接起来，前提是他们的电子邮件地址匹配：
```
global:
  appConfig:
    omniauth:
      autoLinkSamlUser: true
```
或者，一个用户可以手动将他们的 SAML 身份与现有极狐GitLab 账户相关联，方法是为现有用户启用 OmniAuth。
配置以下属性以便您的 SAML 用户无法更改它们：
- NameID。
- 使用 omniauth_auto_link_saml_user 的 Email。
如果用户可以更改这些属性，他们可以作为其他授权用户登录。请参阅您的 SAML IdP 文档，了解如何使这些属性不可更改。
将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：
```
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'
```
其中：
- assertion_consumer_service_url：极狐GitLab HTTPS 端点（将 /users/auth/saml/callback 附加在您实例的 URL 后）。
- idp_cert_fingerprint：您的 IdP 值。它必须是 SHA1 指纹。关于这些值的更多详情，可以查看 OmniAuth SAML 文档。关于其他配置设置的更多详情，可以查看在您的 IdP 上配置 SAML。
- idp_sso_target_url：您的 IdP 值。
- issuer：改为独一无二的名称，用来识别 IdP 应用程序。
- name_identifier_format：您的 IdP 值。

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

编辑 gitlab_values.yaml 并添加提供商配置：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

确保极狐GitLab 配置了 HTTPS。
配置通用设置将 saml 添加为单点登录提供商。这将为没有现有极狐GitLab 账户的用户启用即时账户创建。

为了允许用户使用 SAML 登录，而无需先手动创建账号，编辑 docker-compose.yml：

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

可选。通过将如下设置添加到 docker-compose.yml 中，您可以自动让首次用 SAML 登录的用户与现有极狐GitLab 账户相关联，前提是他们的电子邮件地址匹配：
```
version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_auto_link_saml_user'] = true
```
或者，一个用户可以手动将他们的 SAML 身份与现有极狐GitLab 账户相关联，方法是为现有用户启用 OmniAuth。
配置以下属性以便您的 SAML 用户无法更改它们：
- NameID。
- 使用 omniauth_auto_link_saml_user 的 Email。
如果用户可以更改这些属性，他们可以作为其他授权用户登录。请参阅您的 SAML IdP 文档，了解如何使这些属性不可更改。

编辑 docker-compose.yml 并添加提供商配置：

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"
            }
          }
        ]

其中：

assertion_consumer_service_url: 极狐GitLab HTTPS 端点（将 /users/auth/saml/callback 附加在您实例的 URL 后）。
idp_cert_fingerprint：您的 IdP 值。它必须是 SHA1 指纹。关于这些值的更多详情，可以查看 OmniAuth SAML 文档。关于其他配置设置的更多详情，可以查看在您的 IdP 上配置 SAML。
idp_sso_target_url：您的 IdP 值。
issuer：改为独一无二的名称，用来识别 IdP 应用程序。
name_identifier_format：您的 IdP 值。

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

确保极狐GitLab 配置了 HTTPS。
配置通用设置将 saml 添加为单点登录提供商。这将为没有现有极狐GitLab 账户的用户启用即时账户创建。

为了允许用户使用 SAML 登录，而无需先手动创建账号，编辑 /home/git/gitlab/config/gitlab.yml：

production: &base
  omniauth:
    enabled: true
    allow_single_sign_on: ["saml"]
    block_auto_created_users: false

可选。通过将如下设置添加到 /home/git/gitlab/config/gitlab.yml 中，您可以自动让首次用 SAML 登录的用户与现有极狐GitLab 账户相关联，前提是他们的电子邮件地址匹配：
```
production: &base
  omniauth:
    auto_link_saml_user: true
```
或者，一个用户可以手动将他们的 SAML 身份与现有极狐GitLab 账户相关联，方法是为现有用户启用 OmniAuth。
配置以下属性以便您的 SAML 用户无法更改它们：
- NameID。
- 使用 omniauth_auto_link_saml_user 的 Email。
如果用户可以更改这些属性，他们可以作为其他授权用户登录。请参阅您的 SAML IdP 文档，了解如何使这些属性不可更改。

编辑 /home/git/gitlab/config/gitlab.yml 添加提供商信息：

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'
      }
    }

其中：

assertion_consumer_service_url: 极狐GitLab HTTPS 端点（将 /users/auth/saml/callback 附加在您实例的 URL 后）。
idp_cert_fingerprint：您的 IdP 值。它必须是 SHA1 指纹。关于这些值的更多详情，可以查看 OmniAuth SAML 文档。关于其他配置设置的更多详情，可以查看在您的 IdP 上配置 SAML。
idp_sso_target_url：您的 IdP 值。
issuer：改为独一无二的名称，用来识别 IdP 应用程序。
name_identifier_format：您的 IdP 值。

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

在您的 SAML IdP 上注册极狐GitLab

使用在 issuer 中指定的应用程序名称来在您的 SAML IdP 上注册极狐GitLab SP。
向 IdP 提供配置信息，为应用程序构建一个元数据 URL。要为极狐GitLab 构建元数据 URL，将 users/auth/saml/metadata 添加到您的实例 URL 后面，比如：
```
https://gitlab.example.com/users/auth/saml/metadata
```
至少，身份提供商（IdP）必须提供一个包含用户电子邮件地址的声明，使用 email 或 mail。有关其他可用声明的更多信息，请参见配置断言。
在登录页面上，现在应该在常规登录表单下方有一个 SAML 图标。选择该图标开始认证过程。如果认证成功，您将被返回到极狐GitLab 并登录。

在您的 IdP 上配置 SAML

要在 IdP 上配置 SAML 应用程序，您至少需要以下信息：

Assertion Consumer 服务的 URL
Issuer
NameID
电子邮件地址声明

有关示例配置，请参阅设置身份提供商。

您的 IdP 可能需要额外的配置。有关详细信息，请参阅 IdP 上 SAML 应用程序的其他配置。

配置极狐GitLab 使用多个 SAML IdP

如果出现以下情况，您可以将极狐GitLab 配置为使用多个 SAML IdP：

每个提供商都有一个唯一的名称集，与 args 中的名称集相匹配。至少有一个提供商必须具有名称 saml，规避 14.6 及更高版本中的已知问题。
使用以下提供商名称：
- 在基于提供者名称的属性的 OmniAuth 配置中。例如，allowBypassTwoFactor、allowSingleSignOn 和 syncProfileFromProvider。
- 作为附加身份关联到每个现有用户。
assertion_consumer_service_url 匹配提供商名称。
strategy_class 是显式设置的，因为它不能从提供商名称中推断出来。

SAML 群组成员身份和群组同步不支持多个 IdP。

要配置多个 SAML IdP：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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
          },
  }
]

为了允许让您的用户使用 SAML 登录而无需先手动创建用户，在您的配置中添加如下内容：

gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2']

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用作第一个 SAML 提供商的 Kubernetes Secret：

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

将如下内容放入名为 saml.yaml 的文件中，并被用作第二个 SAML 提供商的 Kubernetes Secret：

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

可选。通过下面的相同步骤来设置额外的 SAML 提供商。

创建 Kubernetes Secrets：

kubectl create secret generic -n <namespace> gitlab-saml \
   --from-file=saml=saml.yaml \
   --from-file=saml_2=saml_2.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml
          key: saml
        - secret: gitlab-saml
          key: saml_2

为了允许您的用户使用 SAML 登录而无需先手动创建账号，在您的配置中添加如下内容：

global:
  appConfig:
    omniauth:
      allowSingleSignOn: ['saml', 'saml_2']

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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
                  },
          }
        ]

为了允许您的用户使用 SAML 登录而无需先手动创建账号，在您的配置中添加如下内容：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2']

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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
        },
      }

为了允许您的用户使用 SAML 登录而无需先手动创建账号，在您的配置中添加如下内容：

production: &base
  omniauth:
    allow_single_sign_on: ["saml", "saml_2"]

保存文件并重启极狐GitLab

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

设置身份提供商

极狐GitLab 对 SAML 的支持意味着您可以通过各种 IdP 登录极狐GitLab。

极狐GitLab 提供以下有关设置 Okta 的内容，仅供参考。如果您对配置 IdP 有任何疑问，请联系您的提供商的支持。

设置 Okta

在 Okta 管理员部分中，选择 Applications。
在页面上选择 Create App Integration，然后在下一个页面上选择 SAML 2.0。
可选。添加 Logo，您必须裁剪 Logo 并调整其大小。
完成 SAML 通用配置。输入以下参数：
- "Single sign-on URL"：使用 assertion consumer 服务 URL。
- "Audience URI"：使用 issuer。
- NameID
- 断言（assertions）
在反馈部分，输入您是客户并创建供内部使用的应用程序。
在新应用配置文件的顶部，选择 SAML 2.0 configuration instructions。
注意 Identity Provider Single Sign-On URL。在您的极狐GitLab 配置文件中，将此 URL 用于 idp_sso_target_url。
在您退出 Okta 之前，请确保添加了您的用户和群组（如果有）。

设置其他 IdP

一些 IdP 有关于如何在 SAML 配置中将它们用作 IdP 的文档。例如：

如果您对在 SAML 配置中配置 IdP 有任何疑问，请联系提供商的技术支持。

配置断言

字段	支持的默认键
Email（必需）	`email`、`mail`
Full Name	`name`
First Name	`first_name`、`firstname`、`firstName`
Last Name	`last_name`、`lastname`、`lastName`

请参阅 attribute_statements 了解：

自定义断言配置示例。
如何配置自定义用户名属性。

有关支持断言的完整列表，请参阅 OmniAuth SAML gem。

基于 SAML 群组成员资格配置用户

您可以：

要求用户成为某个群组的成员。
根据群组成员身份，为用户分配外部、管理员或审计员角色。

极狐GitLab 在每次 SAML 登录时检查这些群组，并根据需要更新用户属性。此功能不允许您自动将用户添加到极狐GitLab 群组。

对这些群组的支持取决于：

您的订阅。
SAML 提供商的名称。群组成员身份仅由名为 saml 的单个 SAML 提供商支持。

群组	版本
Required
External
Admin
Auditor

先决条件

您必须告诉极狐GitLab 在哪里寻找群组信息。为此，请确保您的 IdP 服务器发送特定的 AttributeStatement 以及常规 SAML 响应。例如：

<saml:AttributeStatement>
  <saml:Attribute Name="Groups">
    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Freelancers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Admins</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Auditors</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

属性的名称必须包含用户所属的群组。要告诉极狐GitLab 在哪里可以找到这些群组，请将 groups_attribute: 元素添加到您的 SAML 设置中。

Required 群组

您的 IdP 在 SAML 响应中将群组信息传递给极狐GitLab。要使用此响应，请配置极狐GitLab 识别：

使用 groups_attribute 设置在 SAML 响应中查找群组的位置。
有关群组或用户的信息，使用群组设置。

使用 required_groups 设置来配置极狐GitLab，以识别需要哪些组成员身份才能登录。

如果您不设置 required_groups 或将该设置留空，任何具有适当认证的人都可以使用该服务。

如果在 groups_attribute 指定的属性不正确或丢失，则用户将丢失他们的审计访问。

示例配置：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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'
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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'
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

外部群组

您的 IdP 在 SAML 响应中将群组信息传递给极狐GitLab。要使用此响应，请配置极狐GitLab 识别：

使用 groups_attribute 设置在 SAML 响应中查找群组的位置。
有关群组或用户的信息，使用群组设置。

SAML 可以根据 external_groups 设置自动将用户识别为外部用户。

NOTE: 如果 groups_attribute 中指定的属性不正确或丢失，则用户访问会被视为标准用户。

配置示例：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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'
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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'

创建 Kubernetes Secret:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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'
            }
          }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'
           }
         }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

Administrator 群组

您的 IdP 在 SAML 响应中将群组信息传递给极狐GitLab。要使用此响应，请配置极狐GitLab 识别：

使用 groups_attribute 设置在 SAML 响应中查找群组的位置。
有关群组或用户的信息，使用群组设置。

使用 admin_groups 设置配置极狐GitLab，识别哪些群组授予用户管理员访问权限。

If the attribute specified in groups_attribute is incorrect or missing then users will lose their administrator access.

如果 groups_attribute 中指定的属性不正确或丢失，则用户将会丢失他们的管理员访问。

配置示例：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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'
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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'
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

Auditor 群组

您的 IdP 在 SAML 响应中将群组信息传递给极狐GitLab。要使用此响应，请配置极狐GitLab 识别：

使用 groups_attribute 设置在 SAML 响应中查找群组的位置。
有关群组或用户的信息，使用群组设置。

使用 auditor_groups 设置配置极狐GitLab，识别哪些群组包括具有审计员访问权限的用户。

如果 groups_attribute 中指定的属性不正确或丢失，则用户将失去他们的审计者访问。

配置示例：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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'
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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'
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

自动管理 SAML 群组同步

更多关于自动管理极狐GitLab 群组成员关系的信息，可以查看SAML 群组同步。

绕过双重身份验证

要将 SAML 身份验证方法，配置为在每个会话的基础上，算作双重身份验证 (2FA)，请在 upstream_two_factor_authn_contexts 列表中注册该方法。

确保您的 IdP 正在返回 AuthnContext。例如：

<saml:AuthnStatement>
    <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport</saml:AuthnContextClassRef>
    </saml:AuthnContext>
</saml:AuthnStatement>

编辑您的安装配置，在 upstream_two_factor_authn_contexts 列表中注册 SAML 身份验证方法。编辑配置的方式因安装类型而异。

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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
              ),
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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
                       )
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'
                    ]
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

验证响应签名

IdP 必须签署 SAML 响应，来确保断言未被篡改。

这可以防止在需要特定群组成员身份时进行用户模拟和权限升级。

使用 `idp_cert_fingerprint`

您可以使用 idp_cert_fingerprint 配置响应签名验证。

配置示例：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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'
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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'
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

使用 `idp_cert`

如果您的 IdP 不支持通过 idp_cert_fingerprint 来配置，您可以用 idp_cert 来配置极狐GitLab：

配置示例：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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-----
              <redacted>
              -----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'
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert: |
    -----BEGIN CERTIFICATE-----
    <redacted>
    -----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'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值得：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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-----
                       <redacted>
                       -----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'
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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-----
                    <redacted>
                    -----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'
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

如果您没有正确配置响应签名验证，您应该在极狐GitLab 日志中看到如下内容：

密钥验证错误。
摘要（Digest）不匹配。
指纹不匹配

关于解决这些错误的更多详情，可以查看SAML 故障排查指南。

自定义 SAML 设置

将用户重定向到 SAML 服务器进行身份验证

您可以将 auto_sign_in_with_provider 设置添加到极狐GitLab 配置中，自动将您重定向到 SAML 服务器进行身份验证，可以在实际登录之前，取消选择登录方式。

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      autoSignInWithProvider: 'saml'

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

production: &base
  omniauth:
    auto_sign_in_with_provider: 'saml'

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

每次登录尝试都会重定向到 SAML 服务器，因此您无法使用本地凭据登录。确保至少有一个 SAML 用户具有管理员访问权限。

您还可以通过 https://gitlab.example.com/users/sign_in?auto_sign_in=false 绕过自动登录功能。

映射 SAML 响应属性名称

您可以使用 attribute_statements 将 SAML 响应中的属性名称映射到 OmniAuth info 哈希。

仅使用此设置，来映射属于 OmniAuth info 哈希模式的属性。

例如，如果您的 SAMLResponse 包含名为 EmailAddress 的属性，请指定 { email: ['EmailAddress'] } 将属性映射到 info 哈希中的相应键。还支持以 URI 命名的属性，例如，{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }。

使用此设置告诉极狐GitLab 在哪里查找创建账户所需的某些属性。如果您的 IdP 将用户的电子邮件地址发送为 EmailAddress 而不是 email，请通过在您的配置中设置它来让极狐GitLab 知道：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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'] }
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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']

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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'] }
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'] }
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

设置用户名

默认情况下，SAML 响应中，电子邮件地址的本地部分用于生成用户的极狐GitLab 用户名。

在 attribute_statements 中配置 nickname，指定一个或多个包含用户所需用户名的属性：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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'] }
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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']

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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'] }
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'] }
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

这还将您的 SAML 响应中的 username 属性设置为极狐GitLab 中的用户名。

允许时钟漂移

IdP 的时钟可能会稍微超前您的系统时钟。要允许少量时钟漂移，请在您的设置中使用 allowed_clock_drift。您必须以秒数和小数部分的形式输入参数值。给定的值将添加到验证响应的当前时间。

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml:

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
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

为 `uid` 指定一个唯一的属性

默认情况下，uid 在 SAML 响应中设置为 name_id。要为 uid 指定唯一属性，您可以设置 uid_attribute。在以下示例中，SAML 响应中的 uid 属性值设置为 uid_attribute。

在将 uid 设置为唯一属性之前，请确保您已配置以下属性，以便您的 SAML 用户无法更改它们：

NameID
与 omniauth_auto_link_saml_user 一起使用时的 Email

如果用户可以更改这些属性，则他们可以作为其他授权用户登录。有关如何使这些属性不可更改的信息，请参阅您的 SAML IdP 文档。

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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',
            uid_attribute: 'uid'
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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'
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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'
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

断言加密（可选）

极狐GitLab 需要使用 SAML 2.0 的 TLS 加密。有时，极狐GitLab 需要额外的断言加密。例如：

在负载均衡器上尽早终止 TLS 加密。
在您不希望出现在日志中的断言中包含敏感细节。

大多数组织在这一层不需要额外的加密。

您的 IdP 使用极狐GitLab 的公共证书对断言进行加密。极狐GitLab 使用其私钥解密 EncryptedAssertion。

此集成使用 certificate 和 private_key 设置进行断言加密和请求签名。

SAML 集成支持 EncryptedAssertion。要加密您的断言，请在 SAML 设置中定义您的极狐GitLab 实例的私钥和公共证书。

定义密钥和证书时，将密钥文件中的所有换行符替换为 \n。这使得密钥文件成为一个没有换行符的长字符串。

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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<redacted>\n-----END CERTIFICATE-----',
            private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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<redacted>\n-----END CERTIFICATE-----'
  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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<redacted>\n-----END CERTIFICATE-----',
                     private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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<redacted>\n-----END CERTIFICATE-----',
                  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

签署 SAML 身份验证请求（可选）

您可以配置极狐GitLab 来签署 SAML 身份验证请求。此配置是可选的，因为极狐GitLab SAML 请求使用 SAML 重定向绑定。

实施签名：

为您的极狐GitLab 实例创建用于 SAML 的私钥和公共证书。

在配置的 security 部分配置签名设置。例如：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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<redacted>\n-----END CERTIFICATE-----',
            private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
            security: {
              authn_requests_signed: true,  # enable signature on AuthNRequest
              want_assertions_signed: true,  # enable the requirement of signed assertion
              want_assertions_encrypted: false,  # enable the requirement of encrypted 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',
            }
    }
  }
]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

将如下内容放入名为 saml.yaml 的文件中，并被用于 Kubernetes Secret：

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<redacted>\n-----END CERTIFICATE-----'
  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
  security:
    authn_requests_signed: true  # enable signature on AuthNRequest
    want_assertions_signed: true  # enable the requirement of signed assertion
    want_assertions_encrypted: false  # enable the requirement of encrypted 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'

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

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<redacted>\n-----END CERTIFICATE-----',
                     private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
                     security: {
                       authn_requests_signed: true,  # enable signature on AuthNRequest
                       want_assertions_signed: true,  # enable the requirement of signed assertion
                       want_assertions_encrypted: false,  # enable the requirement of encrypted 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',
                     }
             }
           }
        ]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

编辑 /home/git/gitlab/config/gitlab.yml：

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<redacted>\n-----END CERTIFICATE-----',
                  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
                  security: {
                    authn_requests_signed: true,  # enable signature on AuthNRequest
                    want_assertions_signed: true,  # enable the requirement of signed assertion
                    want_assertions_encrypted: false,  # enable the requirement of encrypted 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',
                  }
          }
        }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

然后：

使用提供的私钥签署请求。
在您的 IdP 的元数据中包含配置的公共 x500 证书，以验证收到的请求的签名。

有关此选项的更多信息，请参阅 Ruby SAML gem 文档。

OmniAuth SAML gem 使用 Ruby SAML gem 来实现 SAML 身份验证的客户端。

SAML 重定向绑定不同于 SAML POST 绑定。在 POST 绑定中，需要签名以防止中间人篡改请求。

为通过 SAML 创建的用户生成密码

极狐GitLab 为通过 SAML 创建的用户生成和设置密码。

使用 SSO 或 SAML 进行身份验证的用户不得使用密码通过 HTTPS 进行 Git 操作。这些用户可以：

设置一个个人访问令牌。
使用 Git Credential Manager，它使用 OAuth 进行安全验证。

为现有用户关联 SAML 身份

用户可以按照为现有用户启用 OmniAuth 的步骤，手动将其 SAML 身份关联到现有的极狐GitLab 账户。

在私有化部署实例上配置群组 SAML SSO

如果您必须允许通过私有化部署实例上的多个 SAML IdP 进行访问，请使用群组 SAML SSO。

要配置群组 SAML SSO：

::Tabs

:::TabTitle Linux package (Omnibus)

确保极狐GitLab 配置了 HTTPS。

编辑 /etc/gitlab/gitlab.rb 以启用 OmniAuth 和 group_saml 提供商：

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]

保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

:::TabTitle Helm chart (Kubernetes)

确保极狐GitLab 配置了 HTTPS。
将如下内容放入名为 group_saml.yaml 的文件中，并被用于 Kubernetes Secret：
```
name: 'group_saml'
```

创建 Kubernetes Secret：

kubectl create secret generic -n <namespace> gitlab-group-saml --from-file=provider=group_saml.yaml

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml 以启用 OmniAuth 和 group_saml 提供商：

global:
  appConfig:
    omniauth:
      enabled: true
      providers:
        - secret: gitlab-group-saml

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

确保极狐GitLab 配置了 HTTPS。

编辑 /home/git/gitlab/config/gitlab.yml 以启用 OmniAuth 和 group_saml 提供商：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_enabled'] = true
        gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]

保存文件并重启极狐GitLab：
```
docker compose up -d
```

:::TabTitle Self-compiled (source)

确保极狐GitLab 配置了 HTTPS。

编辑 /home/git/gitlab/config/gitlab.yml 以启用 OmniAuth 和 group_saml 提供商：

production: &base
  omniauth:
    enabled: true
    providers:
      - { name: 'group_saml' }

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

作为多租户解决方案，与推荐的实例范围 SAML 相比，私有化部署实例上的群组 SAML 受到限制。使用实例范围的 SAML 具有以下优势：

LDAP 兼容性。
LDAP 群组同步。
Required 群组。
Administrator 群组。
Auditor 群组。

IdP 上 SAML 应用程序的其他配置

在 IdP 上配置 SAML 应用程序时，您的 IdP 可能需要额外的配置，例如：

字段	值	说明
SAML profile	Web 浏览器 SSO 配置文件	极狐GitLab 使用 SAML 使用户通过浏览器登录。不会直接向 IdP 发出请求。
SAML request binding	HTTP 重定向	极狐GitLab（SP）使用 base64 编码的 `SAMLRequest` HTTP 参数，将用户重定向到您的 IdP。
SAML response binding	HTTP POST	指定您的 IdP 如何发送 SAML 令牌。包括用户浏览器提交回极狐GitLab 的 `SAMLResponse`。
Sign SAML response	Required	防止篡改。
X.509 certificate in response	Required	签署响应并根据提供的指纹检查响应。
Fingerprint algorithm	SHA-1	极狐GitLab 使用证书的 SHA-1 哈希来签署 SAML 响应。
Signature algorithm	SHA-1/SHA-256/SHA-384/SHA-512	确定响应的签名方式。也称为摘要方法，可以在 SAML 响应中指定。
Encrypt SAML assertion	Optional	在您的身份提供上、用户的浏览器和极狐GitLab 之间使用 TLS。
Sign SAML assertion	Optional	验证 SAML 断言的完整性。有效时，签署整个响应。
Check SAML request signature	Optional	检查 SAML 响应上的签名。
Default RelayState	Optional	指定用户在您的 IdP 通过 SAML 成功登录后，最终应该到达的 URL。
NameID format	Persistent
Additional URLs	Optional	可能在某些提供程序的其他字段中包含 issuer、标识符或 assertion consumer 服务 URL。

有关配置示例，请参阅有关特定提供商的说明。

常用术语表

术语	描述
身份提供商（IdP）	管理您的用户身份的服务，例如 Okta 或 OneLogin。
服务提供商（SP）	使用来自 SAML IdP（例如 Okta）的断言来对用户进行身份验证。您可以将极狐GitLab 配置为 SAML 2.0 SP。
断言（Assertion）	有关用户身份的一条信息，例如他们的姓名或角色。也称为声明或属性。
单点登录（SSO）	身份验证方案的名称。
Assertion consumer 服务 URL	极狐GitLab 上的回调，用户在成功通过 IdP 进行身份验证后被重定向。
Issuer	极狐GitLab 如何在 IdP 上标识自己。也称为“依赖方信任标识符”。
Certificate fingerprint	通过检查服务器是否使用正确的证书对通信进行签名，确认基于 SAML 的通信是安全的。也称为证书指纹。

故障排产

查看我们的 SAML 故障排查指南。

私有化部署版极狐GitLab 实例的 SAML SSO

在极狐GitLab 中配置 SAML 支持

在您的 SAML IdP 上注册极狐GitLab

在您的 IdP 上配置 SAML

配置极狐GitLab 使用多个 SAML IdP

设置身份提供商

设置 Okta

设置其他 IdP

配置断言

基于 SAML 群组成员资格配置用户

先决条件

Required 群组

外部群组

Administrator 群组

Auditor 群组

自动管理 SAML 群组同步

绕过双重身份验证

验证响应签名

使用 idp_cert_fingerprint

使用 idp_cert

自定义 SAML 设置

将用户重定向到 SAML 服务器进行身份验证

映射 SAML 响应属性名称

设置用户名

允许时钟漂移

为 uid 指定一个唯一的属性

断言加密（可选）

签署 SAML 身份验证请求（可选）

为通过 SAML 创建的用户生成密码

为现有用户关联 SAML 身份

在私有化部署实例上配置群组 SAML SSO

IdP 上 SAML 应用程序的其他配置

常用术语表

故障排产

使用 `idp_cert_fingerprint`

使用 `idp_cert`

为 `uid` 指定一个唯一的属性