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

GitLab Dedicated 的 OpenID Connect SSO

等级：Ultimate
产品：GitLab Dedicated

为您的 GitLab Dedicated 实例配置 OpenID Connect (OIDC) 单点登录 (SSO)，以便通过您的身份提供商对用户进行身份验证。

当您希望实现以下功能时，请使用 OIDC SSO：

通过您现有的身份提供商集中管理用户身份验证。
为用户减少密码管理开销。
在您组织的所有应用中实施一致的访问控制。
使用具有广泛行业支持的现代身份验证协议。

此配置是为您 GitLab Dedicated 实例的最终用户设置的。要为 Switchboard 管理员配置 SSO，请参阅配置 Switchboard SSO。

配置 OpenID Connect

前提条件：

设置您的身份提供商。您可以使用一个临时的回调 URL，因为 GitLab 会在配置后提供正式的回调 URL。
确保您的身份提供商支持 OpenID Connect 规范。

要为您的 GitLab Dedicated 实例配置 OIDC：

创建支持工单。

在您的支持工单中，提供以下配置：

{
  "label": "Login with OIDC",
  "issuer": "https://accounts.example.com",
  "discovery": true
}

通过一个支持团队可以访问的密钥管理器的临时链接，安全地提供您的 Client ID 和 Client Secret。

如果您的身份提供商不支持自动发现，请包含客户端端点选项。例如：

{
  "label": "Login with OIDC",
  "issuer": "https://example.com/accounts",
  "discovery": false,
  "client_options": {
    "end_session_endpoint": "https://example.com/logout",
    "authorization_endpoint": "https://example.com/authorize",
    "token_endpoint": "https://example.com/token",
    "userinfo_endpoint": "https://example.com/userinfo",
    "jwks_uri": "https://example.com/jwks"
  }
}

GitLab 为您的实例配置好 OIDC 后：

您将在支持工单中收到回调 URL。
使用此回调 URL 更新您的身份提供商。
通过检查您实例登录页面上的 SSO 登录按钮来验证配置是否成功。

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

您可以配置 GitLab，使其根据 OIDC 组成员身份来分配用户角色和访问权限。

前提条件：

您的身份提供商必须在 ID token 或 userinfo 端点中包含组信息。
您必须已经配置了基本的 OIDC 身份验证。

要基于 OIDC 组成员身份配置用户：

添加 groups_attribute 参数，以指定 GitLab 应在何处查找组信息。
根据需要配置相应的组数组。

在您的支持工单中，将组配置包含在您的 OIDC 配置块中。例如：

{
  "label": "Login with OIDC",
  "issuer": "https://accounts.example.com",
  "discovery": true,
  "groups_attribute": "groups",
  "required_groups": [
    "gitlab-users"
  ],
  "external_groups": [
    "external-contractors"
  ],
  "auditor_groups": [
    "auditors"
  ],
  "admin_groups": [
    "gitlab-admins"
  ]
}

配置参数

以下参数可用于为 GitLab Dedicated 实例配置 OIDC。更多信息，请参阅使用 OpenID Connect 作为身份验证提供商。

必需参数

参数	描述
`issuer`	您身份提供商的 OpenID Connect 颁发者 URL。
`label`	登录按钮的显示名称。
`discovery`	是否使用 OpenID Connect 自动发现（推荐：`true`）。

可选参数

参数	描述	默认值
`admin_groups`	具有管理员访问权限的组。	`[]`
`auditor_groups`	具有审计员访问权限的组。	`[]`
`client_auth_method`	客户端身份验证方法。	`"basic"`
`external_groups`	被标记为外部用户的组。	`[]`
`groups_attribute`	在 OIDC 响应中查找组信息的位置。	无
`pkce`	启用 PKCE（代码交换的证明密钥）。	`false`
`required_groups`	访问所必需的组。	`[]`
`response_mode`	授权响应的传递方式。	无
`response_type`	OAuth 2.0 响应类型。	`"code"`
`scope`	请求的 OpenID Connect 范围。	`["openid"]`
`send_scope_to_token_endpoint`	在令牌端点请求中包含 scope 参数。	`true`
`uid_field`	用作唯一标识符的字段。	`"sub"`

特定提供商的示例

Google

{
  "label": "Google",
  "scope": ["openid", "profile", "email"],
  "response_type": "code",
  "issuer": "https://accounts.google.com",
  "client_auth_method": "query",
  "discovery": true,
  "uid_field": "preferred_username",
  "pkce": true
}

Microsoft Azure AD

{
  "label": "Azure AD",
  "scope": ["openid", "profile", "email"],
  "response_type": "code",
  "issuer": "https://login.microsoftonline.com/your-tenant-id/v2.0",
  "client_auth_method": "query",
  "discovery": true,
  "uid_field": "preferred_username",
  "pkce": true
}

Okta

{
  "label": "Okta",
  "scope": ["openid", "profile", "email", "groups"],
  "response_type": "code",
  "issuer": "https://your-domain.okta.com/oauth2/default",
  "client_auth_method": "query",
  "discovery": true,
  "uid_field": "preferred_username",
  "pkce": true
}

故障排查

如果您在配置 OpenID Connect 时遇到问题：

请验证您的身份提供商配置是否正确且可访问。
检查提供给支持团队的 Client ID 和 Client Secret 是否正确。
确保您身份提供商中的重定向 URI 与支持工单中提供的 URI 一致。
验证颁发者 URL 是否正确且可访问。