将极狐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 来:

  • 使能用户使用他们的 JihuLab.com 账号登录您的应用。
  • 为您的极狐GitLab 实例设置 JihuLab.com 进行身份验证。更多详情,可以查看为您的服务集成 JihuLab.com
  • 应用创建后,外部服务可以使用 OAuth 2 API 管理访问令牌。

创建用户所属的应用程序

要为您的用户添加新的应用程序:

  1. 在右上角,选择您的头像。
  2. 选择 编辑个人资料
  3. 在左侧边栏中,选择 应用程序
  4. 选择 添加新的应用程序
  5. 输入 名称重定向 URI
  6. 选择在授权的应用程序中定义的 OAuth 2 范围。
  7. 重定向 URL 中,输入用户在通过极狐GitLab 授权后被重定向到的 URL。
  8. 选择 保存应用程序。极狐GitLab 提供:

    • 应用程序 ID 字段中的 OAuth 2 客户端 ID。
    • 通过在 密钥 字段选择 拷贝,让 OAuth 2 客户端密钥可访问。
    • 更新密钥 功能在极狐GitLab 15.9 及以后版本中。使用此函数为此应用程序生成并拷贝新的密钥。更新密钥将阻止既有的应用程序工作直到凭据被更新。

创建群组所属的应用程序

要为群组添加新的应用程序:

  1. 导航到所需的群组。
  2. 在左侧边栏中,选择 设置 > 应用程序
  3. 输入 名称重定向 URI
  4. 选择在授权的应用程序中定义的 OAuth 2 范围。
  5. 重定向 URL 中,输入用户在通过极狐GitLab 授权后被重定向到的 URL。
  6. 选择 保存应用程序。极狐GitLab 提供:

    • 应用程序 ID 字段中的 OAuth 2 客户端 ID。
    • 通过在 密钥 字段选择 拷贝,让 OAuth 2 客户端密钥可访问。
    • 更新密钥 功能在极狐GitLab 15.9 及以后版本中。使用此函数为此应用程序生成并拷贝新的密钥。更新密钥将阻止既有的应用程序工作直到凭据被更新。

实例范围的应用程序

为您的极狐GitLab 实例创建应用程序:

  1. 在左侧导航栏底部,选择 管理员
  2. 选择 应用程序
  3. 选择 新建应用程序

管理中心创建应用程序时,您可以将其标记为可信的。此应用程序会自动跳过用户授权步骤。

查看所有的授权应用程序

  • k8s_proxy 引自极狐GitLab 16.4,使用名为 k8s_proxy_pat 的功能标志。默认禁用。
  • 在极狐GitLab 16.5 功能标志 k8s_proxy_pat 已被移除。

如要查看您用您的极狐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 agent 执行 Kubernetes API 调用的权限。

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

访问令牌过期

  • expires_in 上的数据库验证引自极狐GitLab 15.10。当您升级到 15.10 及以上版本时,如果您的极狐GitLab 实例还有任何没有 expires_in 设置的 OAuth 访问令牌,数据库迁移将会发生错误。关于变更解决之法,查看极狐GitLab 15.10.1 升级文档

WARNING: 15.0 版本中移除了选择退出过期访问令牌的功能。所有的既有集成都必须更新来支持访问令牌的刷新。

两小时后访问令牌过期。使用访问令牌的集成必须使用 refresh_token 属性生成新的访问令牌。即使 access_token 过期之后也必须使用刷新令牌。关于如何刷新过期的访问令牌的更多详情,可以查看OAuth 2.0 令牌文档

从 Doorkeeper 中使用 access_token_expires_in 将过期设置在极狐GitLab 代码仓库中,Doorkeeper 库将极狐GitLab 作为 OAuth 提供商。过期设置是不可配置的。

当应用程序被删除,所有与此应用程序相关的权限和令牌都会被删除。

Hashed OAuth 应用程序密钥

  • 引入自 极狐GitLab 15.4,使用名为 hash_oauth_secrets 的功能标志。默认禁用。
  • 在极狐GitLab 15.8 中为 JihuLab.com 启用。
  • 在极狐GitLab 15.9 中为私有化部署实例启用。
  • 在极狐GitLab 15.10 中 GA。功能标志 hash_oauth_secrets 被移除。

默认情况下,极狐GitLab 将 OAuth 应用程序密钥一哈希格式存储在数据库中。这些密钥仅在创建 OAuth 应用程序后为用户可见。在早期的极狐GitLab 版本中,应用程序密钥是以文本存储在数据库中。

在极狐GitLab 中使用 OAuth 的其他两种方法

您可以:

  • 使用应用程序 API 创建和管理 OAuth 2 应用程序。
  • 使能用户使用第三方 OAuth 2 提供商登录极狐GitLb。更多详情,可以查看 OmniAuth 文档
  • 使用具有 OAuth 2 的极狐GitLab 导入器为仓库赋予权限,而无需将用户凭据共享给您的 JihuLab.com 账号。