- 在极狐GitLab 中配置 SAML 支持
- 设置身份提供商
- 基于 SAML 群组成员资格配置用户
- 自动管理 SAML 群组同步
- 绕过双重身份验证
- 验证响应签名
- 自定义 SAML 设置
- 断言加密(可选)
- 签署 SAML 身份验证请求(可选)
- 为通过 SAML 创建的用户生成密码
- 为现有用户关联 SAML 身份
- 在私有化部署实例上配置群组 SAML SSO
- IdP 上 SAML 应用程序的其他配置
- 常用术语表
私有化部署版极狐GitLab 实例的 SAML SSO
本页介绍如何为私有化部署版极狐GitLab 实例,设置实例范围的 SAML 单点登录(SSO)。
您可以将极狐GitLab 配置为 SAML 服务提供商 (SP),允许极狐GitLab 使用来自 SAML 身份提供程序 (IdP)(例如 Okta)的断言(assertions)来对用户进行身份验证。
更多信息:
- OmniAuth 提供商设置,查看 OmniAuth 文档。
- 常用术语,查看常用术语表。
在极狐GitLab 中配置 SAML 支持
-
确保极狐GitLab 配置了 HTTPS。
-
在您的极狐GitLab 服务器上,打开配置文件。
对于 Omnibus 安装实例:
sudo editor /etc/gitlab/gitlab.rb
对于源安装实例:
cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml
-
编辑初始配置。
-
要允许您的用户使用 SAML 进行注册而无需先手动创建帐户,请将以下值添加到您的配置中。
对于 Omnibus 安装实例:
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] gitlab_rails['omniauth_block_auto_created_users'] = false
对于源安装实例:
omniauth: enabled: true allow_single_sign_on: ["saml"] block_auto_created_users: false
-
可选。如果电子邮件地址匹配,您可以通过添加以下设置,自动将 SAML 用户与现有的极狐GitLab 用户关联。
对于 Omnibus 安装实例:
gitlab_rails['omniauth_auto_link_saml_user'] = true
对于源安装实例:
auto_link_saml_user: true
或者,用户可以通过为现有用户启用 OmniAuth,手动将他们的 SAML 身份关联到现有的极狐GitLab 帐户。
-
配置以下属性,使您的 SAML 用户无法更改:
NameID
- 与
omniauth_auto_link_saml_user
一起使用时的Email
。
如果用户可以更改这些属性,则他们可以作为其他授权用户登录。有关如何使这些属性不可更改的信息,请参阅您的 SAML IdP 文档。
-
添加提供商配置。
对于 Omnibus 安装实例:
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" } } ]
对于源安装实例:
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
附加到您的极狐GitLab 安装实例的 HTTPS URL。 -
更改以下值,匹配您的 IdP:
idp_cert_fingerprint
idp_sso_target_url
name_identifier_format
如果您使用
idp_cert_fingerprint
,它必须是 SHA1 指纹。有关这些值的更多信息,请参阅 OmniAuth SAML 文档。 有关其他配置设置的更多信息,请参阅在您的 IdP 上配置 SAML。 -
将
issuer
的值更改为唯一的名称,该名称在 IdP 中标识应用程序。 -
要使更改生效,如果您安装了:
- Omnibus 实例,需要重新配置极狐GitLab。
- 源安装实例,需要重启极狐GitLab。
在您的 SAML IdP 中注册极狐GitLab
-
使用
issuer
中指定的应用程序名称,在您的 SAML IdP 中注册极狐GitLab SP。 -
要向 IdP 提供配置信息,请为应用程序构建元数据 URL。要为极狐GitLab 构建元数据 URL,请将
users/auth/saml/metadata
附加到极狐GitLab 安装实例的 HTTPS 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
引入于 14.6 版本。
如果出现以下情况,您可以将极狐GitLab 配置为使用多个 SAML IdP:
- 每个提供商都有一个唯一的名称集,与
args
中的名称集相匹配。至少有一个提供商必须具有名称saml
,规避 14.6 及更高版本中的已知问题。 - 使用以下提供商名称:
- 在基于提供者名称的属性的 OmniAuth 配置中。例如,
allowBypassTwoFactor
、allowSingleSignOn
和syncProfileFromProvider
。 - 作为附加身份关联到每个现有用户。
- 在基于提供者名称的属性的 OmniAuth 配置中。例如,
-
assertion_consumer_service_url
匹配提供商名称。 -
strategy_class
是显式设置的,因为它不能从提供商名称中推断出来。
SAML 群组成员身份和群组同步不支持多个 IdP。
提供商配置示例(源安装实例):
omniauth:
providers:
- {
name: 'saml', # This must match the following name configuration parameter
args: {
name: 'saml', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider
... # Put here all the required arguments similar to a single provider
},
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
}
- {
name: 'saml1', # This must match the following name configuration parameter
args: {
name: 'saml1', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
... # Put here all the required arguments similar to a single provider
},
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
}
提供商配置示例(Omnibus 安装实例):
要允许您的用户使用 SAML 进行注册,而无需从任一提供商手动创建帐户,请将以下值添加到您的配置中。
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml1']
gitlab_rails['omniauth_providers'] = [
{
name: 'saml', # This must match the following name configuration parameter
args: {
name: 'saml', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider
... # Put here all the required arguments similar to a single provider
},
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
},
{
name: 'saml1', # This must match the following name configuration parameter
args: {
name: 'saml1', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
... # Put here all the required arguments similar to a single provider
},
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
}
]
设置身份提供商
极狐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
或将设置留空,任何经过适当身份验证的人都可以使用该服务。
配置示例:
{ 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'
} }
External 群组
您的 IdP 在 SAML 响应中将群组信息传递给极狐GitLab。要使用此响应,请配置极狐GitLab 识别:
- 使用
groups_attribute
设置在 SAML 响应中查找群组的位置。 - 有关群组或用户的信息,使用群组设置。
SAML 可以根据 external_groups
设置自动将用户识别为外部用户。
配置示例:
{ 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'
} }
Administrator 群组
您的 IdP 在 SAML 响应中将群组信息传递给极狐GitLab。要使用此响应,请配置极狐GitLab 识别:
- 使用
groups_attribute
设置在 SAML 响应中查找群组的位置。 - 有关群组或用户的信息,使用群组设置。
使用 admin_groups
设置配置极狐GitLab,识别哪些群组授予用户管理员访问权限。
配置示例:
{ 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'
} }
Auditor 群组
您的 IdP 在 SAML 响应中将群组信息传递给极狐GitLab。要使用此响应,请配置极狐GitLab 识别:
- 使用
groups_attribute
设置在 SAML 响应中查找群组的位置。 - 有关群组或用户的信息,使用群组设置。
使用 auditor_groups
设置配置极狐GitLab,识别哪些群组包括具有审计员访问权限的用户。
配置示例:
{ 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'
} }
自动管理 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 身份验证方法。编辑配置的方式因安装类型而异。
Omnibus 安装实例
-
编辑
/etc/gitlab/gitlab.rb
:gitlab_rails['omniauth_providers'] = [ { name: "saml", args: { assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", idp_sso_target_url: "https://login.example.com/idp", issuer: "https://gitlab.example.com", name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", upstream_two_factor_authn_contexts: %w( urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN ) }, label: "Company Login" # optional label for SAML login button, defaults to "Saml" } ]
-
保存文件并重新配置极狐GitLab,使更改生效。
源安装实例
-
编辑
config/gitlab.yml
:omniauth: providers: - { name: 'saml', args: { assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', idp_sso_target_url: 'https://login.example.com/idp', issuer: 'https://gitlab.example.com', name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', upstream_two_factor_authn_contexts: [ 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport', 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS', 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN' ] }, label: 'Company Login' # optional label for SAML login button, defaults to "Saml" }
-
保存文件并重启极狐GitLab,使更改生效。
验证响应签名
IdP 必须签署 SAML 响应,来确保断言未被篡改。
这可以防止在需要特定群组成员身份时进行用户模拟和权限升级。
您可以使用 idp_cert_fingerprint
配置响应签名验证。
配置示例:
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',
}
如果您的 IdP 不支持使用 idp_cert_fingerprint
配置它,您可以直接使用 idp_cert
配置极狐GitLab。配置示例:
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',
}
如果您错误地配置了响应签名验证,您可能会看到如下错误消息:
- 密钥验证错误。
- Digest 不匹配。
- 指纹不匹配。
自定义 SAML 设置
将用户重定向到 SAML 服务器进行身份验证
您可以将 auto_sign_in_with_provider
设置添加到极狐GitLab 配置中,自动将您重定向到 SAML 服务器进行身份验证,可以在实际登录之前,取消选择登录方式。
对于 Omnibus 安装实例:
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
对于源安装实例:
omniauth:
auto_sign_in_with_provider: saml
每次登录尝试都会重定向到 SAML 服务器,因此您无法使用本地凭据登录。确保至少有一个 SAML 用户具有管理员访问权限。
您还可以通过 https://gitlab.example.com/users/sign_in?auto_sign_in=false
绕过自动登录功能。
映射 SAML 响应属性名称
您可以使用 attribute_statements
将 SAML 响应中的属性名称映射到 OmniAuth info
哈希。
info
哈希模式的属性。例如,如果您的 SAMLResponse
包含名为 EmailAddress
的属性,请指定 { email: ['EmailAddress'] }
将属性映射到 info 哈希中的相应键。还支持以 URI 命名的属性,例如,{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }
。
使用此设置告诉极狐GitLab 在哪里查找创建帐户所需的某些属性。如果您的 IdP 将用户的电子邮件地址发送为 EmailAddress
而不是 email
,请通过在您的配置中设置它来让极狐GitLab 知道:
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'] }
}
设置用户名
默认情况下,SAML 响应中,电子邮件地址的本地部分用于生成用户的极狐GitLab 用户名。
在 attribute_statements
中配置 nickname
,指定一个或多个包含用户所需用户名的属性:
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'] }
}
这还将您的 SAML 响应中的 username
属性设置为极狐GitLab 中的用户名。
允许时钟漂移
IdP 的时钟可能会稍微超前您的系统时钟。
要允许少量时钟漂移,请在您的设置中使用 allowed_clock_drift
。您必须以秒数和小数部分的形式输入参数值。
给定的值将添加到验证响应的当前时间。
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: { email: ['EmailAddress'] },
allowed_clock_drift: 1 # for one second clock drift
}
为 uid
指定一个唯一的属性
默认情况下,uid
在 SAML 响应中设置为 name_id
。要为 uid
指定唯一属性,您可以设置 uid_attribute
。 在以下示例中,SAML 响应中的 uid
属性值设置为 uid_attribute
。
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'
}
在将 uid
设置为唯一属性之前,请确保您已配置以下属性,以便您的 SAML 用户无法更改它们:
NameID
- 与
omniauth_auto_link_saml_user
一起使用时的Email
如果用户可以更改这些属性,则他们可以作为其他授权用户登录。 有关如何使这些属性不可更改的信息,请参阅您的 SAML IdP 文档。
断言加密(可选)
极狐GitLab 需要使用 SAML 2.0 的 TLS 加密。有时,极狐GitLab 需要额外的断言加密。例如:
- 在负载均衡器上尽早终止 TLS 加密。
- 在您不希望出现在日志中的断言中包含敏感细节。
大多数组织在这一层不需要额外的加密。
SAML 集成支持 EncryptedAssertion
。要加密您的断言,请在 SAML 设置中定义您的极狐GitLab 实例的私钥和公共证书。
定义密钥和证书时,将密钥文件中的所有换行符替换为 \n
。
这使得密钥文件成为一个没有换行符的长字符串。
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-----'
}
您的 IdP 使用极狐GitLab 的公共证书对断言进行加密。极狐GitLab 使用其私钥解密 EncryptedAssertion
。
certificate
和 private_key
设置进行断言加密和请求签名。签署 SAML 身份验证请求(可选)
您可以配置极狐GitLab 来签署 SAML 身份验证请求。此配置是可选的,因为极狐GitLab SAML 请求使用 SAML 重定向绑定。
实施签名:
- 为您的极狐GitLab 实例创建用于 SAML 的私钥和公共证书。
- 在配置的
security
部分配置签名设置。例如:
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
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',
}
}
然后:
- 使用提供的私钥签署请求。
- 在您的 IdP 的元数据中包含配置的公共 x500 证书,以验证收到的请求的签名。
有关此选项的更多信息,请参阅 Ruby SAML gem 文档。
OmniAuth SAML gem 使用 Ruby SAML gem 来实现 SAML 身份验证的客户端。
为通过 SAML 创建的用户生成密码
极狐GitLab 为通过 SAML 创建的用户生成和设置密码。
使用 SSO 或 SAML 进行身份验证的用户不得使用密码通过 HTTPS 进行 Git 操作。这些用户可以:
- 设置一个个人访问令牌。
- 使用 Git Credential Manager,它使用 OAuth 进行安全验证。
为现有用户关联 SAML 身份
用户可以按照为现有用户启用 OmniAuth 的步骤,手动将其 SAML 身份关联到现有的极狐GitLab 帐户。
在私有化部署实例上配置群组 SAML SSO
如果您必须允许通过私有化部署实例上的多个 SAML IdP 进行访问,请使用群组 SAML SSO。
要配置群组 SAML SSO:
- 使用 HTTPS 配置极狐GitLab。
-
启用 OmniAuth 和
group_saml
提供商。对于 Omnibus 安装实例,编辑
gitlab.rb
:gitlab_rails['omniauth_enabled'] = true gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]
对于源安装实例,编辑
gitlab/config/gitlab.yml
:omniauth: enabled: true providers: - { name: 'group_saml' }
作为多租户解决方案,与推荐的实例范围 SAML 相比,私有化部署实例上的群组 SAML 受到限制。使用实例范围的 SAML 具有以下优势:
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 的通信是安全的。也称为证书指纹。 |