Help us learn about your current experience with the documentation. Take the survey.

GitLab 自托管版的 SAML 单点登录（SSO）

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

对于 GitLab.com，请参阅 GitLab.com 群组的 SAML SSO。

本页介绍如何为 GitLab 自托管版设置实例级 SAML 单点登录（SSO）。

你可以将 GitLab 配置为 SAML 服务提供者（SP）。这允许 GitLab 从 SAML 身份提供者（IdP）（例如 Okta）获取断言来验证用户身份。

有关更多信息：

OmniAuth 提供程序设置，请参阅 OmniAuth 文档。
常用术语，请参阅术语表。

在 GitLab 中配置 SAML 支持

确保 GitLab 已通过 HTTPS 配置。
配置通用设置，将 saml 添加为单点登录提供程序。这可为没有现有 GitLab 账户的用户启用即时账户预配。

若允许用户无需先手动创建账户即可使用 SAML 注册，请编辑 /etc/gitlab/gitlab.rb：

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 响应中的邮箱。

或者，用户可通过为现有用户启用 OmniAuth，手动将其 SAML 身份关联至现有 GitLab 账户。
配置以下属性，使 SAML 用户无法修改它们：
- NameID。
- 与 omniauth_auto_link_saml_user 一同使用时的 Email。
若用户可修改这些属性，他们可能会以其他授权用户的身份登录。有关如何将这些属性设为不可修改的信息，请参阅你的 SAML IdP 文档。

编辑 /etc/gitlab/gitlab.rb 并添加提供程序配置：

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml", # 必须为小写。
    label: "Provider name", # 登录按钮的可选标签，默认为 "Saml"
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6",
      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 端点（在你的 GitLab 安装 HTTPS URL 后附加 `/users/auth/saml/callback`）。
`idp_cert_fingerprint`	你的 IdP 值。若要从证书生成 SHA256 指纹，请参阅计算指纹。
`idp_sso_target_url`	你的 IdP 值。
`issuer`	更改为唯一名称，用于向 IdP 标识应用程序。
`name_identifier_format`	你的 IdP 值。

有关这些值的更多信息，请参阅OmniAuth SAML 文档。有关其他配置设置的更多信息，请参阅在 IdP 上配置 SAML。

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

确保 GitLab 已通过 HTTPS 配置。
配置通用设置，将 saml 添加为单点登录提供程序。这可为没有现有 GitLab 账户的用户启用即时账户预配。

导出 Helm 值：

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
```
或者，用户可通过为现有用户启用 OmniAuth，手动将其 SAML 身份关联至现有 GitLab 账户。
配置以下属性，使 SAML 用户无法修改它们：
- NameID。
- 与 omniauth_auto_link_saml_user 一同使用时的 Email。
若用户可修改这些属性，他们可能会以其他授权用户的身份登录。

请参阅您的 SAML IdP 文档，了解如何使这些属性变为不可更改。

将以下内容放入名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: 'Provider name' # 登录按钮的可选标签，默认为 "Saml"
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 端点（在您的 GitLab 安装 HTTPS URL 后附加 `/users/auth/saml/callback`）。
`idp_cert_fingerprint`	您的 IdP 值。若要从证书生成 SHA256 指纹，请参阅计算指纹。
`idp_sso_target_url`	您的 IdP 值。
`issuer`	更改为唯一名称，用于向 IdP 标识应用程序。
`name_identifier_format`	您的 IdP 值。

有关这些值的更多信息，请参阅 OmniAuth SAML 文档。有关其他配置设置的更多信息，请参阅在您的 IdP 上配置 SAML。

创建 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

确保 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

可选。如果用户的电子邮件地址匹配，您可以自动将 SAML 用户与现有 GitLab 用户关联，方法是在 docker-compose.yml 中添加以下设置：
```
version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_auto_link_saml_user'] = true
```
或者，用户可以通过为现有用户启用 OmniAuth 手动将其 SAML 身份关联到现有 GitLab 账户。
配置以下属性，以防止您的 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", # 登录按钮的可选标签，默认为 "Saml"
            args: {
              assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
              idp_cert_fingerprint: "2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6",
              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"
            }
          }
        ]

参数	说明

有关这些值的更多信息，请参阅OmniAuth SAML文档。有关其他配置设置的更多信息，请参阅在您的IdP上配置SAML。

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

确保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

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

编辑/home/git/gitlab/config/gitlab.yml并添加提供商配置：

omniauth:
  providers:
    - {
      name: 'saml',
      label: 'Provider name', # 登录按钮的可选标签，默认为"Saml"
      args: {
        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
        idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
        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端点（在您的GitLab安装的HTTPS URL后附加`/users/auth/saml/callback`）。
`idp_cert_fingerprint`	您的IdP值。若要从证书生成SHA256指纹，请参阅计算指纹。
`idp_sso_target_url`	您的IdP值。
`issuer`	更改为唯一名称，用于向IdP标识应用程序。
`name_identifier_format`	您的IdP值。

有关这些值的更多信息，请参阅OmniAuth SAML文档。有关其他配置设置的更多信息，请参阅在您的IdP上配置SAML。

保存文件并重启GitLab：

# 对于运行systemd的系统
sudo systemctl restart gitlab.target

# 对于运行SysV init的系统
sudo service gitlab restart

在您的SAML身份提供者中注册GitLab

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

在您的身份提供者上配置SAML

要在您的身份提供者上配置SAML应用，您需要至少以下信息：

断言消费者服务URL。
发行者。
NameID。
电子邮件地址声明。

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

您的身份提供者可能需要额外配置。更多信息，请参阅身份提供者上的SAML应用额外配置。

配置 GitLab 以使用多个 SAML 身份提供者

如果满足以下条件，您可以配置 GitLab 使用多个 SAML 身份提供者：

每个身份提供者都有一个唯一名称，该名称与 args 中设置的名称匹配。
身份提供者的名称用于：
- 在基于身份提供者名称的属性 OmniAuth 配置中。例如，allowBypassTwoFactor、allowSingleSignOn 和 syncProfileFromProvider。
- 作为额外身份关联到每个现有用户。
assertion_consumer_service_url 与身份提供者名称匹配。
strategy_class 显式设置，因为它无法从身份提供者名称推断得出。

当您配置多个 SAML 身份提供者时，为确保 SAML 组链接正常工作，您必须配置所有 SAML 身份提供者在 SAML 响应中包含组属性。更多信息请参见 SAML 组链接。

要设置多个 SAML 身份提供者：

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml', # 此处必须与下方 name 配置参数匹配
    label: '提供者 1' # 在界面中区分不同按钮和提供者
    args: {
            name: 'saml', # 必需，且必须与身份提供者名称匹配
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL 必须与身份提供者名称匹配
            strategy_class: 'OmniAuth::Strategies::SAML',
            # 包含与单个提供者类似的所需参数
          },
  },
  {
    name: 'saml_2', # 此处必须与下方 name 配置参数匹配
    label: '提供者 2' # 在界面中区分不同按钮和提供者
    args: {
            name: 'saml_2', # 必需，且必须与身份提供者名称匹配
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL 必须与身份提供者名称匹配
            strategy_class: 'OmniAuth::Strategies::SAML',
            # 包含与单个提供者类似的所需参数
          },
  }
]

若允许用户通过 SAML 注册而无需手动创建账户，向配置添加以下值：

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

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

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

name: 'saml' # 至少一个提供者必须命名为 'saml'
label: '提供者 1' # 在界面中区分不同按钮和提供者
args:
  name: 'saml' # 必需，且必须与身份提供者名称匹配
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' # URL 必须与身份提供者名称匹配
  strategy_class: 'OmniAuth::Strategies::SAML' # 必需
  # 包含与单个提供者类似的所需参数

将以下内容放入名为 saml_2.yaml 的文件中，用作第二个 SAML 提供者的 Kubernetes Secret：

name: 'saml_2'
label: '提供者 2' # 在界面中区分不同按钮和提供者
args:
  name: 'saml_2' # 必需，且必须与身份提供者名称匹配
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL 必须与身份提供者名称匹配
  strategy_class: 'OmniAuth::Strategies::SAML' # 必需
  # 包含与单个提供者类似的所需参数

可选。按相同步骤设置更多 SAML 提供者。

创建 Kubernetes Secrets：

kubectl create secret generic -n <命名空间> gitlab-saml \
   --from-file=saml=saml.yaml \
   --from-file=saml_2=saml_2.yaml

导出 Helm 值：

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

编辑 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', # 这必须与以下名称配置参数匹配
            label: 'Provider 1' # 在界面中区分两个按钮和提供商
            args: {
                    name: 'saml', # 这是必需的，必须与提供商名称匹配
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL 必须与提供商名称匹配
                    strategy_class: 'OmniAuth::Strategies::SAML',
                    # 包含所有必需的参数，类似于单个提供商
                  },
          },
          {
            name: 'saml_2', # 这必须与以下名称配置参数匹配
            label: 'Provider 2' # 在界面中区分两个按钮和提供商
            args: {
                    name: 'saml_2', # 这是必需的，必须与提供商名称匹配
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL 必须与提供商名称匹配
                    strategy_class: 'OmniAuth::Strategies::SAML',
                    # 包含所有必需的参数，类似于单个提供商
                  },
          }
        ]

要允许用户使用 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
```

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

production: &base
  omniauth:
    providers:
      - {
        name: 'saml', # 这必须与以下名称配置参数匹配
        label: 'Provider 1' # 在界面中区分两个按钮和提供商
        args: {
          name: 'saml', # 这是必需的，必须与提供商名称匹配
          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL 必须与提供商名称匹配
          strategy_class: 'OmniAuth::Strategies::SAML',
          # 包含所有必需的参数，类似于单个提供商
        },
      }
      - {
        name: 'saml_2', # 这必须与以下名称配置参数匹配
        label: 'Provider 2' # 在界面中区分两个按钮和提供商
        args: {
          name: 'saml_2', # 这是必需的，必须与提供商名称匹配
          strategy_class: 'OmniAuth::Strategies::SAML',
          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL 必须与提供商名称匹配
          # 包含所有必需的参数，类似于单个提供商
        },
      }

要允许用户使用 SAML 注册而无需从任一提供商手动创建账户，请将以下值添加到您的配置中：

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

保存文件并重启 GitLab:

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

设置身份提供者

GitLab 对 SAML 的支持意味着你可以通过多种身份提供者 (IdP) 登录 GitLab。

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

设置 Okta

在 Okta 管理员界面中选择 Applications。
在应用页面，选择 Create App Integration，然后在下一页选择 SAML 2.0。
可选。从 GitLab Press 选择并添加一个 logo。您必须裁剪并调整 logo 大小。
完成通用 SAML 配置。输入：
- "Single sign-on URL"：使用断言消费者服务 URL。
- "Audience URI"：使用发行者。
- NameID。
- Assertions。
在反馈部分，输入您是客户，正在为内部使用创建应用。
在新应用的资料页顶部，选择 SAML 2.0 configuration instructions。
记下 Identity Provider Single Sign-On URL。将该 URL 用于 GitLab 配置文件中的 idp_sso_target_url。
在退出 Okta 前，确保添加您的用户和组（如果有的话）。

设置 Google Workspace

前提条件：

请确保您拥有 Google Workspace 超级管理员账户的访问权限。

要设置 Google Workspace：

使用以下信息，并遵循在 Google Workspace 中设置自定义 SAML 应用中的说明。

	典型值	说明
SAML 应用的名称	GitLab	其他名称也可接受。
ACS URL	`https://<GITLAB_DOMAIN>/users/auth/saml/callback`	断言消费者服务 URL。
`GITLAB_DOMAIN`	`gitlab.example.com`	您的 GitLab 实例域名。
实体 ID	`https://gitlab.com`	唯一标识您的 SAML 应用的值。将其设置为 GitLab 配置中的 `issuer`。
名称 ID 格式	`EMAIL`	必需值。也称为 `name_identifier_format`。
名称 ID	主邮箱地址	您的邮箱地址。确保有人能收到发送至该地址的内容。
名字	`first_name`	名字。与 GitLab 通信所需的必需值。
姓氏	`last_name`	姓氏。与 GitLab 通信所需的必需值。

设置以下 SAML 属性映射：

Google 目录属性	应用属性
基本信息 > 邮箱	`email`
基本信息 > 名字	`first_name`
基本信息 > 姓氏	`last_name`

您可能在配置 GitLab 中的 SAML 支持时用到这些信息。

在配置 Google Workspace SAML 应用时，记录以下信息：

	值	说明
SSO URL	取决于	Google 身份提供者详情。设置为 GitLab 的 `idp_sso_target_url` 设置。
证书	可下载	Google SAML 证书。
SHA256 指纹	取决于	下载证书时可获取。要生成证书的 SHA256 指纹，请参阅计算指纹。

Google Workspace 管理员还会提供 IdP 元数据、实体 ID 和 SHA-256 指纹。但是，GitLab 连接 Google Workspace SAML 应用不需要这些信息。

设置 Microsoft Entra ID

登录到 Microsoft Entra 管理中心。
创建非库应用程序。

为该应用程序配置 SSO。

您 gitlab.rb 文件中的以下设置对应 Microsoft Entra ID 字段：

`gitlab.rb` 配置项	Microsoft Entra ID 字段
`issuer`	标识符（实体 ID）
`assertion_consumer_service_url`	回复 URL（断言消费者服务 URL）
`idp_sso_target_url`	登录 URL
`idp_cert_fingerprint`	指纹

设置以下属性：
- 唯一用户标识符（名称 ID） 设为 user.objectID。
  - 名称标识符格式 设为 persistent。有关更多信息，请参阅如何管理用户 SAML 身份。
- 其他声明 设为支持的属性。

有关更多信息，请参阅示例配置页面。

设置其他身份提供者（IdPs）

部分身份提供者（IdP）有关于如何在 SAML 配置中使用它们作为 IdP 的文档。例如：

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

配置断言

提供：GitLab.com, GitLab 自托管

这些属性区分大小写。

字段	支持的默认键
电子邮件（必填）	`email`, `mail`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress`
全名	`name`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/name`
名字	`first_name`, `firstname`, `firstName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/givenname`
姓氏	`last_name`, `lastname`, `lastName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/surname`

当 GitLab 收到来自 SAML SSO 提供商的 SAML 响应时，GitLab 会查找以下值在属性 name 字段中：

"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
firstname
lastname
email

你必须将这些值正确包含在属性 Name 字段中，以便 GitLab 能解析 SAML 响应。例如，GitLab 可以解析以下 SAML 响应片段：

这是可接受的，因为 Name 属性设置为前述表中所需的某个值。

       <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
           <AttributeValue>Alvin</AttributeValue>
       </Attribute>
       <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
           <AttributeValue>Test</AttributeValue>
       </Attribute>
       <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
           <AttributeValue>[email protected]</AttributeValue>
       </Attribute>

这是可接受的，因为 Name 属性匹配前述表中的某个值。

       <Attribute Name="firstname">
           <AttributeValue>Alvin</AttributeValue>
       </Attribute>
       <Attribute Name="lastname">
           <AttributeValue>Test</AttributeValue>
       </Attribute>
       <Attribute Name="email">
           <AttributeValue>[email protected]</AttributeValue>
       </Attribute>

但是，GitLab 无法解析以下 SAML 响应片段：

这不会被接受，因为 Name 属性中的值不在前述表的受支持值范围内。

       <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname">
           <AttributeValue>Alvin</AttributeValue>
       </Attribute>
       <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname">
           <AttributeValue>Test</AttributeValue>
       </Attribute>
       <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mail">
           <AttributeValue>[email protected]</AttributeValue>
       </Attribute>

这会失败，因为即使 FriendlyName 有受支持的值，Name 属性也没有。

       <Attribute FriendlyName="firstname" Name="urn:oid:2.5.4.42">
           <AttributeValue>Alvin</AttributeValue>
       </Attribute>
       <Attribute FriendlyName="lastname" Name="urn:oid:2.5.4.4">
           <AttributeValue>Test</AttributeValue>
       </Attribute>
       <Attribute FriendlyName="email" Name="urn:oid:0.9.2342.19200300.100.1.3">
           <AttributeValue>[email protected]</AttributeValue>
       </Attribute>

参见 attribute_statements 了解：

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

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

基于SAML组成员身份配置用户

您可以：

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

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

对这些组的支持取决于：

组	层级	仅限GitLab企业版（EE）？
必需	Free, Premium, Ultimate	是
外部	Free, Premium, Ultimate	否
管理员	Free, Premium, Ultimate	是
审计员	Premium, Ultimate	是

先决条件：

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

<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在这些组中的位置，请在SAML设置中添加一个groups_attribute:元素。此属性区分大小写。

必需的组

您的身份提供者（IdP）会在 SAML 响应中向 GitLab 传递组信息。若要使用此响应，请配置 GitLab 以识别：

在 SAML 响应中查找组的路径，使用 groups_attribute 设置。
关于组或用户的信息，使用组设置。

使用 required_groups 设置可配置 GitLab，使其识别哪些组成员资格是登录所必需的。

如果您未设置 required_groups 或将其留空，则任何拥有有效认证的用户均可使用该服务。

如果 groups_attribute 中指定的属性不正确或缺失，所有用户都将被阻止访问。

编辑 /etc/gitlab/gitlab.rb 文件：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供者',
    groups_attribute: 'Groups',
    required_groups: ['开发者', '自由职业者', '管理员', '审计员'],
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

将以下内容放入名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供者'
groups_attribute: 'Groups'
required_groups: ['开发者', '自由职业者', '管理员', '审计员']
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 配置值：

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

编辑 docker-compose.yml 文件：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供者',
             groups_attribute: 'Groups',
             required_groups: ['开发者', '自由职业者', '管理员', '审计员'],
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

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

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的 SAML 提供者',
          groups_attribute: 'Groups',
          required_groups: ['开发者', '自由职业者', '管理员', '审计员'],
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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：

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统

sudo service gitlab restart

外部组

您的身份提供者（IdP）会在 SAML 响应中向 GitLab 传递组信息。若要使用此响应，请配置 GitLab 以识别：

在 SAML 响应中查找组的字段，使用 groups_attribute 设置。
使用组设置获取有关组或用户的信息。

基于 external_groups 设置，SAML 可自动将用户识别为外部用户。

如果 groups_attribute 中指定的属性不正确或缺失，则用户将以标准用户身份访问。

示例配置：

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [

  { name: 'saml',
    label: '我们的 SAML 提供者',
    groups_attribute: 'Groups',
    external_groups: ['Freelancers'],
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            # 或
            # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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
```

将以下内容放入名为 saml.yaml 的文件中，用作Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供者'
groups_attribute: 'Groups'
external_groups: ['Freelancers']
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  # 或
  # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 值：

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

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
          { name: 'saml',
            label: '我们的 SAML 提供者',
            groups_attribute: 'Groups',
            external_groups: ['Freelancers'],
            args: {
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                    idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                    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
```

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

production: &base
  omniauth:
    providers:
       - { name: 'saml',
           label: '我们的 SAML 提供者',
           groups_attribute: 'Groups',
           external_groups: ['Freelancers'],
           args: {
                   assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                   idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                   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

管理员组

您的身份提供者（IdP）会在 SAML 响应中传递群组信息给 GitLab。若要使用此响应，请配置 GitLab 以识别：

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

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

如果 groups_attribute 中指定的属性不正确或缺失，则用户将失去其管理员访问权限。

示例配置：

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供者',
    groups_attribute: 'Groups',
    admin_groups: ['Admins'],
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            # 或
            # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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
```

将以下内容放入名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供者'
groups_attribute: 'Groups'
admin_groups: ['Admins']
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 值：

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

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供者',
             groups_attribute: 'Groups',
             admin_groups: ['Admins'],
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

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

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的 SAML 提供者',
          groups_attribute: 'Groups',
          admin_groups: ['Admins'],
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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：

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

审计员组

层级：Premium, Ultimate
提供方式：GitLab Self-Managed, GitLab Dedicated

您的身份提供者（IdP）在SAML响应中向GitLab传递群组信息。要使用此响应，需配置GitLab以识别：

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

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

若 groups_attribute 中指定的属性不正确或缺失，用户将失去审计员访问权限。

示例配置：

编辑 /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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',  
            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  
```

将以下内容放入名为 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'  
  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值：

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

编辑 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',  
                     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  
```

编辑 /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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',  
                  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：

# 对于运行systemd的系统  
sudo systemctl restart gitlab.target  

# 对于运行SysV init的系统  
sudo service gitlab restart  

自动管理SAML组同步

有关自动管理GitLab组成员资格的信息，请参阅SAML组同步。

自定义SAML会话超时时间

默认情况下，GitLab会在24小时后结束SAML会话。您可以使用SAML2 AuthnStatement中的SessionNotOnOrAfter属性来自定义此持续时间。该属性包含一个ISO 8601时间戳值，指示何时结束用户会话。当指定此值时，它会覆盖默认的24小时SAML会话超时时间。

如果实例配置了自定义的会话时长，且该时长早于SessionNotOnOrAfter时间戳，则当用户的GitLab用户会话结束时，必须重新进行身份验证。

绕过双因素认证

若要将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>

编辑您的安装配置，将SAML认证方法注册到upstream_two_factor_authn_contexts列表中。您必须输入SAML响应中的AuthnContext。

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的SAML提供商',
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

将以下内容放入名为saml.yaml的文件中，用作Kubernetes Secret：

name: 'saml'
label: '我们的SAML提供商'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出Helm值：

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

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的SAML提供商',
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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

（注：原文此处未完整显示，按需补充剩余内容）

编辑 /etc/gitlab/gitlab.rb：
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    label: '我们的SAML提供商',
    args: {
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
      idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
      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：
sudo gitlab-ctl reconfigure
编辑 /home/git/gitlab/config/gitlab.yml：
production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的SAML提供商',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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：
# 对于使用 systemd 的系统
sudo systemctl restart gitlab.target

# 对于使用 SysV init 的系统
sudo service gitlab restart

验证响应签名

身份提供者（IdP）必须对 SAML 响应进行签名，以确保断言未被篡改。

这可防止在需要特定组成员资格时出现用户冒名顶替和权限提升的情况。

使用 `idp_cert_fingerprint`

你可以通过 idp_cert_fingerprint 配置响应签名的验证。示例如下：

编辑 /etc/gitlab/gitlab.rb 文件：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供商',
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

将以下内容放入名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供商'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 值：

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

编辑 docker-compose.yml 文件：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供商',
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

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

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的 SAML 提供商',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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：

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

使用 `idp_cert`

你也可以直接通过 idp_cert 配置 GitLab。示例配置：

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供商',
    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
```

将以下内容放入名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供商'
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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 值：

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

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供商',
             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
```

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

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的 SAML 提供商',
          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：

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

如果响应签名验证配置不正确，可能会看到类似以下的错误消息：

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

有关解决这些错误的更多信息，请参阅 SAML 故障排除指南。

自定义 SAML 设置

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

你可以将 auto_sign_in_with_provider 设置添加到你的 GitLab 配置中，以自动将你重定向到 SAML 服务器进行身份验证。这消除了在真正登录前选择元素的必要。

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'

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

导出 Helm 值：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    omniauth:
      autoSignInWithProvider: 'saml'

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

编辑 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
```

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

production: &base
  omniauth:
    auto_sign_in_with_provider: 'saml'

保存文件并重启 GitLab：

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

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

若要绕过自动登录设置，请在登录 URL 中附加 ?auto_sign_in=false，例如：https://gitlab.example.com/users/sign_in?auto_sign_in=false。

映射 SAML 响应属性名称

层级：Free、Premium、Ultimate
提供方案：GitLab 自托管、GitLab 专用

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

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

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

使用此设置告知 GitLab 在何处查找创建账户所需的特定属性。例如，如果你的 IdP 将用户的电子邮件地址作为 EmailAddress 而非 email 发送，请在配置中设置它：

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供方',
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

将以下内容放入名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供方'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 值：

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

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供方',
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

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

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的 SAML 提供方',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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：

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

设置用户名

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

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

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供商',
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

将以下内容放入名为 saml.yaml 的文件中，用作Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供商'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 值：

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

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供商',
             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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

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

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的 SAML 提供商',
          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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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：

# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

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

映射配置文件属性

若要从 SAML 提供商同步配置文件信息，需配置 attribute_statements 以映射这些属性。

支持的配置文件属性包括：

job_title
organization

这些属性无默认映射，除非显式配置否则不会同步。

配置 OmniAuth 同步所需属性

编辑 /etc/gitlab/gitlab.rb 文件：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供商',
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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: {
              organization: ['organization'],
              job_title: ['job_title']
            }
    }
  }
]

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

配置 OmniAuth 同步所需属性

将以下 YAML 内容保存至名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供商'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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:
    organization: ['organization']
    job_title: ['job_title']

创建 Kubernetes Secret：

kubectl create secret generic -n <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 配置值：

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

配置 OmniAuth 同步所需属性

编辑 docker-compose.yml 文件：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供商',
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: {
                       organization: ['organization'],
                       job_title: ['job_title']
                     }
             }
           }
        ]

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

配置 OmniAuth 同步所需属性

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

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的 SAML 提供商',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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: { organization: [‘organization’], job_title: [‘job_title’] } }


1. 保存文件并重启 GitLab：

```shell
# 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

允许时钟漂移

身份提供者（IdP）的时钟可能会略微领先于您的系统时钟。为了允许少量的时钟漂移，请在设置中使用 allowed_clock_drift。您必须以秒数和小数的形式输入参数值。给定的值会添加到验证响应时的当前时间中。

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供者',
    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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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  # 允许一秒钟的时钟漂移
    }
  }
]

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

将以下内容放入名为 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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  # 允许一秒钟的时钟漂移

创建 Kubernetes Secret：

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

导出 Helm 值：

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

编辑 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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  # 允许一秒钟的时钟漂移
             }
           }
        ]

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

编辑 /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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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  # 允许一秒钟的时钟漂移
          }
        }

保存文件并重启 GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

为 `uid` 指定唯一属性（可选）

默认情况下，用户的 uid 会被设为 SAML 响应中的 NameID 属性。若要为 uid 指定其他属性，可设置 uid_attribute。

在将 uid 设为唯一属性前，请确保已配置以下属性，以防止 SAML 用户修改它们：

[NameID](../user/group/saml_sso/_index.md#管理用户 SAML 身份)。
使用 omniauth_auto_link_saml_user 时需配置 Email。

如果用户能修改这些属性，他们可能冒充其他授权用户登录。有关如何使这些属性不可修改的信息，请参阅您的 SAML IdP 文档。

以下示例展示了如何在 SAML 响应中将 uid 属性值设为 uid_attribute。

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供商',
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

将以下内容放入名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供商'
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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 配置值：

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

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供商',
             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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

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

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '我们的 SAML 提供商',
          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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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. 保存文件并重启 GitLab：

   ```shell
   # 对于运行 systemd 的系统
   sudo systemctl restart gitlab.target

   # 对于运行 SysV init 的系统
   sudo service gitlab restart

断言加密（可选）

对 SAML 断言进行加密是可选操作，但我们建议启用此功能。这能为数据增加一层额外保护，防止未加密的数据被记录或在传输过程中被恶意行为者截获。

此集成使用 certificate 和 private_key 设置来同时实现断言加密和请求签名。

若要对 SAML 断言进行加密，需在 GitLab 的 SAML 设置中定义私钥和公钥证书。您的身份提供者（IdP）会使用公钥证书对断言进行加密，而 GitLab 则通过私钥解密该断言。

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

编辑 /etc/gitlab/gitlab.rb 文件：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的 SAML 提供方',
    groups_attribute: 'Groups',
    required_groups: ['开发者', '自由职业者', '管理员', '审计员'],
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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-----
            <已省略>
            -----END CERTIFICATE-----,
            private_key:|
            -----BEGIN PRIVATE KEY-----
            <已省略>
            -----END PRIVATE KEY-----
    }
  }
]

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

将以下内容放入名为 saml.yaml 的文件中，用作 Kubernetes Secret：

name: 'saml'
label: '我们的 SAML 提供方'
groups_attribute: 'Groups'
required_groups: ['开发者', '自由职业者', '管理员', '审计员']
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-----
  <已省略>
  ----END CERTIFICATE-----,
  private_key:|
  -----BEGIN PRIVATE KEY-----
  <已省略>
  -----END PRIVATE KEY-----

创建 Kubernetes Secret：

kubectl create secret generic -n <命名空间> gitlab-saml --from-file=provider=saml.yaml

导出 Helm 值：

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

编辑 docker-compose.yml 文件：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的 SAML 提供方',
             groups_attribute: 'Groups',
             required_groups: ['开发者', '自由职业者', '管理员', '审计员'],
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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-----
                     <已省略>
                     -----END CERTIFICATE-----,
                     private_key:|
                     -----BEGIN PRIVATE KEY-----
                     <已省略>
                     -----END PRIVATE KEY-----
             }
           }
        ]

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

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


```yaml
   production: &base
     omniauth:
       providers:
         - { name: 'saml',
             label: '我们的SAML提供者',
             groups_attribute: 'Groups',
             required_groups: ['开发者', '自由职业者', '管理员', '审计员'],
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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：

# 对于运行systemd的系统
sudo systemctl restart gitlab.target

# 对于运行SysV init的系统
sudo service gitlab restart

签署SAML认证请求（可选）

你可以配置GitLab来签署SAML认证请求。此配置是可选的，因为GitLab的SAML请求使用SAML重定向绑定。

要实现签名：

为你的GitLab实例创建一个用于SAML的私钥和公证书对。

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

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '我们的SAML提供者',
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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,  # 启用AuthNRequest上的签名
              want_assertions_signed: true,  # 启用对已签名断言的要求
              want_assertions_encrypted: false,  # 启用对加密断言的要求
              metadata_signed: false,  # 启用元数据上的签名
              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
```

将以下内容放入名为saml.yaml的文件中，用作Kubernetes Secret：

name: 'saml'
label: '我们的SAML提供者'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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  # 启用AuthNRequest上的签名
    want_assertions_signed: true  # 启用对已签名断言的要求
    want_assertions_encrypted: false  # 启用对加密断言的要求
    metadata_signed: false  # 启用元数据上的签名
    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值：

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

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '我们的SAML提供者',
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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身份提供者（IdP）

描述：

以下示例展示了如何配置SAML身份提供者（IdP）集成。根据你的安装方式选择对应的选项卡。

编辑 docker-compose.yaml 文件中的 gitlab_rails['omniauth_providers'] 部分：

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
      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,  # 启用AuthNRequest上的签名
        want_assertions_signed: true,  # 启用对签名断言的要求
        want_assertions_encrypted: false,  # 启用对加密断言的要求
        metadata_signed: false,  # 启用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
```

编辑 /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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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,  # 启用AuthNRequest上的签名
                    want_assertions_signed: true,  # 启用对签名断言的要求
                    want_assertions_encrypted: false,  # 启用对加密断言的要求
                    metadata_signed: false,  # 启用Metadata上的签名
                    signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                    digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
                  }
          }
        }

保存文件并重启GitLab：

# 对于运行systemd的系统
sudo systemctl restart gitlab.target

# 对于运行SysV init的系统
sudo service gitlab restart

之后GitLab会：

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

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

Ruby SAML gem 被 OmniAuth SAML gem 用于实现SAML认证的客户端部分。

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


```markdown
## 通过SAML创建用户的密码生成

GitLab会为通过SAML创建的用户[生成并设置密码](../security/passwords_for_integrated_authentication_methods.md)。

使用SSO或SAML认证的用户不能对HTTPS方式的Git操作使用密码。这些用户可以改为：

- 设置[个人](../user/profile/personal_access_tokens.md)、[项目](../user/project/settings/project_access_tokens.md)或[组](../user/group/settings/group_access_tokens.md)访问令牌。
- 使用[OAuth凭证助手](../user/profile/account/two_factor_authentication.md#oauth-credential-helpers)。

## 为现有用户关联SAML身份

管理员可以配置GitLab自动将SAML用户与现有GitLab用户关联。更多信息请参见[在GitLab中配置SAML支持](#configure-saml-support-in-gitlab)。

用户可手动将其SAML身份关联到现有GitLab账户。更多信息请参见[为现有用户启用OmniAuth](omniauth.md#enable-omniauth-for-an-existing-user)。

## 在GitLab自托管实例上配置组级SAML SSO

层级：Premium, Ultimate
提供方式：GitLab Self-Managed, GitLab Dedicated



如果你的GitLab自托管实例需要通过多个SAML身份提供商（IdP）允许访问，请使用组级SAML SSO。

要配置组级SAML SSO：


  


  
  
  
    
    
    
    
    

确保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



  




  
  
  
    
    
    
    
    

确保GitLab已配置HTTPS。


将以下内容放入名为group_saml.yaml的文件中，用作Kubernetes Secret：


  
name: 'group_saml'


创建Kubernetes Secret：


  
kubectl create secret generic -n <命名空间> gitlab-group-saml --from-file=provider=group_saml.yaml


导出Helm值：


  
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



  




  
  
  
    
    
    
    
    

确保GitLab已配置HTTPS。


编辑docker-compose.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



  




  
  
  
    
    
    
    
    

确保GitLab已配置HTTPS。


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


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


保存文件并重启GitLab：


  
# 对于运行systemd的系统
sudo systemctl restart gitlab.target

# 对于运行SysV init的系统
sudo service gitlab restart



  







作为多租户解决方案，GitLab自托管实例上的组级SAML相比推荐的[实例级SAML](saml.md)功能有限。使用实例级SAML可利用以下优势：

- [LDAP兼容性](../administration/auth/ldap/_index.md)。
- [LDAP组同步](../user/group/access_and_permissions.md#manage-group-memberships-with-ldap)。
- [必需组](#required-groups)。
- [管理员组](#administrator-groups)。
- [审计员组](#auditor-groups)。

在身份提供者（IdP）上配置SAML应用的其他设置

当在身份提供者（IdP）上配置SAML应用时，您的IdP可能需要额外的配置，例如以下内容：

字段	值	说明
SAML配置文件	浏览器单点登录配置文件	GitLab通过用户的浏览器使用SAML进行用户登录。不会直接向IdP发送请求。
SAML请求绑定	HTTP重定向	GitLab（SP）将用户重定向到您的IdP，附带base64编码的`SAMLRequest` HTTP参数。
SAML响应绑定	HTTP POST	指定您的IdP如何发送SAML令牌。包含`SAMLResponse`，用户的浏览器将其提交回GitLab。
对SAML响应签名	必需	防止篡改。
响应中的X.509证书	必需	对响应进行签名，并根据提供的指纹检查响应。
指纹算法	SHA-1	GitLab使用证书的SHA-1哈希对SAML响应进行签名。
签名算法	SHA-1/SHA-256/SHA-384/SHA-512	确定如何对响应进行签名。也称为摘要方法，可在SAML响应中指定。
加密SAML断言	可选	在您的身份提供者、用户的浏览器和GitLab之间使用TLS。
对SAML断言签名	可选	验证SAML断言的完整性。激活后，会对整个响应进行签名。
检查SAML请求签名	可选	检查SAML响应上的签名。
默认RelayState	可选	指定用户通过您的IdP成功通过SAML登录后应到达的基础URL子路径。
NameID格式	持久化	参见NameID格式详情。
其他URL	可选	在某些提供商的其他字段中可能包括发行者、标识符或断言消费者服务URL。

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

使用Geo配置SAML

若要通过Geo配置SAML，请参阅配置实例级SAML。

更多信息，请参见带有单点登录（SSO）的Geo。

术语表

术语	描述
身份提供者（IdP）	管理用户身份的服务，例如Okta或OneLogin。
服务提供者（SP）	从SAML IdP（如Okta）消费断言以验证用户身份。您可以将GitLab配置为SAML 2.0 SP。
断言	关于用户身份的信息片段，例如其姓名或角色。也称为声明或属性。
单点登录（SSO）	认证方案的名称。
断言消费者服务URL	用户成功通过IdP认证后被重定向到的GitLab回调地址。
发行者	GitLab向IdP标识自身的方式。也称为“依赖方信任标识符”。
证书指纹	通过检查服务器是否使用正确的证书对通信进行签名来确认SAML通信的安全。也称为证书指纹。

故障排除

请参阅我们的排查SAML指南。

GitLab 自托管版的 SAML 单点登录（SSO）

在 GitLab 中配置 SAML 支持

在您的SAML身份提供者中注册GitLab

在您的身份提供者上配置SAML

配置 GitLab 以使用多个 SAML 身份提供者

设置身份提供者

设置 Okta

设置 Google Workspace

设置 Microsoft Entra ID

设置其他身份提供者（IdPs）

配置断言

基于SAML组成员身份配置用户

必需的组

外部组

管理员组

审计员组

自动管理SAML组同步

自定义SAML会话超时时间

绕过双因素认证

验证响应签名

使用 idp_cert_fingerprint

使用 idp_cert

自定义 SAML 设置

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

映射 SAML 响应属性名称

设置用户名

映射配置文件属性

允许时钟漂移

为 uid 指定唯一属性（可选）

断言加密（可选）

签署SAML认证请求（可选）

标题：配置SAML身份提供者（IdP）

描述：

在身份提供者（IdP）上配置SAML应用的其他设置

使用Geo配置SAML

术语表

故障排除

使用 `idp_cert_fingerprint`

使用 `idp_cert`

为 `uid` 指定唯一属性（可选）