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

将 GitLab 配置为 OAuth 2.0 认证身份提供商

OAuth 2.0 提供安全的委托式服务器资源访问，允许客户端应用代表资源所有者访问资源。OAuth 2 允许授权服务器在获得资源所有者或最终用户批准后，向第三方客户端颁发访问令牌。

您可以通过将以下类型的 OAuth 2 应用添加到实例中，将 GitLab 用作 OAuth 2 认证身份提供商：

这些方法仅在权限级别上有所不同。默认回调 URL 是 SSL URL https://your-gitlab.example.com/users/auth/gitlab/callback。您可以使用非 SSL URL，但建议使用 SSL URL。

将 OAuth 2 应用添加到实例后，您可以使用 OAuth 2 来：

  • 让用户使用其 GitLab.com 账户登录您的应用
  • 当关联群组配置了 SAML 时，让用户使用 SAML SSO 登录您的应用
  • 设置 GitLab.com 用于认证您的 GitLab 实例。更多信息请参见将您的服务器与 GitLab.com 集成
  • 应用创建后，外部服务可以使用 OAuth 2 API 管理访问令牌

创建用户拥有的应用

为您的用户创建新应用：

  1. 在左侧边栏，选择您的头像

  2. 选择 编辑个人资料

  3. 在左侧边栏，选择 应用

  4. 选择 添加新应用

  5. 输入名称和重定向 URI

  6. 选择 OAuth 2 作用域，如授权应用中定义

  7. 在重定向 URI中，输入用户授权后 GitLab 将其发送到的 URL

  8. 选择保存应用。GitLab 提供：

    • 应用 ID 字段中的 OAuth 2 客户端 ID
    • 密钥字段中选择复制可访问的 OAuth 2 客户端密钥
    • GitLab 15.9 及更高版本中的更新密钥功能。使用此功能为该应用生成并复制新密钥。更新密钥会导致现有应用在凭据更新前无法正常工作

创建群组拥有的应用

为群组创建新应用：

  1. 转到目标群组

  2. 在左侧边栏，选择 设置 > 应用

  3. 输入名称和重定向 URI

  4. 选择 OAuth 2 作用域，如授权应用中定义

  5. 在重定向 URI中，输入用户授权后 GitLab 将其发送到的 URL

  6. 选择保存应用。GitLab 提供：

    • 应用 ID 字段中的 OAuth 2 客户端 ID
    • 密钥字段中选择复制可访问的 OAuth 2 客户端密钥
    • GitLab 15.9 及更高版本中的更新密钥功能。使用此功能为该应用生成并复制新密钥。更新密钥会导致现有应用在凭据更新前无法正常工作

创建实例级应用

  • 版本：免费版、高级版、旗舰版
  • 提供：GitLab 自托管

为您的 GitLab 实例创建应用：

  1. 在左侧边栏底部，选择管理员
  2. 选择应用
  3. 选择新应用

在管理员区域创建应用时，将其标记为受信任。此应用将自动跳过用户授权步骤。

查看所有授权应用

查看您使用 GitLab 凭据授权的所有应用：

  1. 在左侧边栏，选择您的头像
  2. 选择编辑个人资料，然后选择应用
  3. 查看授权应用部分

GitLab OAuth 2 应用支持作用域，允许应用执行不同的操作。所有可用作用域请参见下表。

作用域 描述
api 授予对 API 的完整读写权限，包括所有群组和项目、容器注册表、依赖代理和包注册表
read_user 授予通过 /user API 端点对已认证用户资料的只读权限，包括用户名、公开邮箱和全名。还授予对 /users 下只读 API 端点的访问权限
read_api 授予对 API 的只读权限，包括所有群组和项目、容器注册表和包注册表
read_repository 授予使用 Git-over-HTTP 或存储库文件 API 对私有项目存储库的只读访问权限
write_repository 授予使用 Git-over-HTTP（不使用 API）对私有项目存储库的读写访问权限
read_registry 授予对私有项目容器注册表镜像的只读访问权限
write_registry 授予对私有项目容器注册表镜像的读写访问权限
sudo 当以管理员用户身份认证时，授予代表系统中的任何用户执行 API 操作的权限
openid 授予使用 OpenID Connect 认证 GitLab 的权限。还授予对用户资料和群组成员关系的只读访问权限
profile 授予使用 OpenID Connect 对用户资料的只读访问权限
email 授予使用 OpenID Connect 对用户主邮箱地址的只读访问权限
create_runner 授予创建 runner 的权限
manage_runner 授予管理 runner 的权限
k8s_proxy 授予使用 Kubernetes 代理执行 Kubernetes API 调用的权限

您可以随时通过选择撤销来撤销任何访问权限。

访问令牌过期

在 GitLab 15.0 中，移除了选择不使访问令牌过期的功能。所有现有集成都必须更新以支持访问令牌刷新。

访问令牌在两小时后过期。使用访问令牌的集成必须使用 refresh_token 属性生成新令牌。即使 access_token 本身过期，也可以使用刷新令牌。有关如何刷新过期访问令牌的详细信息，请参见 OAuth 2.0 令牌文档。

此过期设置在 GitLab 代码库中使用 Doorkeeper 库的 access_token_expires_in 配置设置，该库提供 GitLab 作为 OAuth 提供商的功能。过期设置不可配置。

当应用被删除时，与应用关联的所有授权和令牌也会被删除。

哈希 OAuth 应用密钥

默认情况下，GitLab 在数据库中以哈希格式存储 OAuth 应用密钥。这些密钥仅在用户创建 OAuth 应用后立即可用。在 GitLab 的早期版本中，应用密钥以明文形式存储在数据库中。

在 GitLab 中使用 OAuth 2 的其他方式

您可以：

  • 使用应用 API创建和管理 OAuth 2 应用
  • 让用户使用第三方 OAuth 2 提供商登录 GitLab。更多信息请参见 OmniAuth 文档
  • 使用 GitLab 导入器与 OAuth 2 结合使用，为您的 GitLab.com 账户提供存储库访问权限，而无需共享用户凭据