极狐GitLab 令牌概览

本文档列出了极狐GitLab 中使用的令牌、它们的用途，以及适用时的安全指南。

安全注意事项#

为确保令牌安全：

• 像对待密码一样对待令牌，并妥善保管。
• 创建作用域令牌时，请使用尽可能最小范围的作用域，以降低令牌意外泄露造成的影响。
  • 如果不同的进程需要不同的作用域（例如 read 和 write），请考虑为每个作用域使用单独的令牌。 如果一个令牌泄露，它提供的访问权限比具有广泛作用域（如完整 API 访问权限）的单个令牌要少。
• 创建令牌时：
  • 按照下方的令牌命名指南选择名称。
  • 考虑设置一个在任务完成时过期的令牌。 例如，如果您需要执行一次性导入，请将令牌设置为几小时后过期。
  • 添加描述，提供更多上下文，包括任何相关 URL。
• 通过请求头而不是 URL 传递令牌：
  • 个人、项目和群组访问令牌使用 PRIVATE-TOKEN。
  • 作业令牌使用 JOB-TOKEN。
• 如果您有演示环境，在录制视频或发布有关项目的博客文章后，请撤销所有令牌。
• 您可以使用 Git 凭据存储来存储令牌。
• 定期审查所有类型的活跃访问令牌，并撤销任何您不需要的令牌。

请勿：

• 将令牌添加到 URL 中：
  • 在克隆或添加带有令牌的 URL 远程仓库时，Git 会将该 URL 以明文形式写入其 .git/config 文件。
  • URL 通常会被代理和应用服务器记录，这可能会将这些凭据泄露给系统管理员。
• 在项目中以明文形式存储令牌。
  • 如果该令牌是极狐GitLab CI/CD 的外部密钥，请查看如何在 CI/CD 中使用外部密钥。
• 在将代码、控制台命令或日志输出粘贴到议题、合并请求描述、评论或任何其他自由文本输入时包含令牌。
• 在控制台日志或产物中记录凭据。请考虑保护和 掩蔽您的凭据。

令牌命名指南#

一致的命名约定可以更轻松地审计访问令牌、了解其用途，并评估轮换或撤销每个令牌的影响。

命名约定因团队而异，但一个有用的约定应回答以下问题：

• 令牌执行什么操作？例如 ci-deploy 或 api-read。
• 令牌作用于什么资源或服务？例如 gitlab 或 terraform。
• 令牌与哪个环境或所有者关联？例如 production 或 auth-team。

例如：

• 要具体。避免使用 test、mytoken、token1、GITLAB_API_TOKEN、API_TOKEN 或 default 等通用名称。 这些名称会导致在审计期间无法识别令牌的用途。
• 包含使用方系统或工具。如果令牌由特定应用程序、脚本或集成使用，请包含其名称。例如：terraform-state-backend 或 grafana-metrics-reader。
• 包含环境。在适用的情况下，指明令牌的目标是 production、staging 还是 development。这可以防止在较低环境中意外使用 生产令牌。
• 避免嵌入敏感信息。不要在令牌名称中包含用户名、电子邮件地址 或任何其他个人身份信息 (PII)，因为令牌名称 在审计日志和 UI 中可见。
• 设置标准化的大小写和标点规则。使用一致的大小写和分隔符可以更 容易地读取和搜索令牌。例如，使用连字符 (-) 而不是下划线 (_)。
• 使用描述字段。令牌描述字段允许您添加其他详细信息，例如指向相关议题的链接 或使用该令牌的团队名称。

CI/CD 中的令牌#

由于个人访问令牌作用域广泛，请尽可能避免将其用作 CI/CD 变量。如果 CI/CD 作业需要访问其他资源，请使用以下之一，按访问作用域从最小到最大排序：

1. 作业令牌（访问作用域最小）
2. 项目令牌
3. 群组令牌

有关 CI/CD 变量安全的其他建议包括：

• 对任何凭据使用密钥存储。
• 包含敏感信息的 CI/CD 变量应受保护、 被掩蔽并被隐藏。

个人访问令牌#

您可以创建个人访问令牌以通过以下方式进行身份验证：

• 极狐GitLab API。
• 极狐GitLab 代码仓库。
• 极狐GitLab 镜像仓库。

您可以限制个人访问令牌的作用域和过期日期。默认情况下，它们继承创建它们的用户的权限。

您可以使用个人访问令牌 API 以编程方式执行操作，例如轮换个人访问令牌。

当您的个人访问令牌即将过期时，您会收到一封电子邮件。

在考虑需要令牌获取权限的 CI/CD 作业时，请避免使用个人访问令牌，尤其是将其存储为 CI/CD 变量时。CI/CD 作业令牌和项目访问令牌通常可以以低得多的风险实现相同的结果。

OAuth 2.0 令牌#

极狐GitLab 可以作为 OAuth 2.0 提供商， 允许其他服务代表用户访问极狐GitLab API。

您可以限制 OAuth 2.0 令牌的作用域和生命周期。

模拟令牌#

模拟令牌是一种特殊类型的个人访问令牌。它只能由管理员为特定用户创建。模拟令牌可以帮助您构建以特定用户身份通过极狐GitLab API、代码仓库和极狐GitLab 镜像仓库进行身份验证的应用程序或脚本。

您可以限制模拟令牌的作用域并设置过期日期。

项目访问令牌#

项目访问令牌的作用域限定为一个项目。与个人访问令牌一样，您可以使用它们通过以下方式进行身份验证：

• 极狐GitLab API。
• 极狐GitLab 代码仓库。
• 极狐GitLab 镜像仓库。

您可以限制项目访问令牌的作用域和过期日期。当您创建项目访问令牌时，极狐GitLab 会创建一个项目机器人用户。项目机器人用户是服务账号，不计入许可席位。

您可以使用项目访问令牌 API 以编程方式执行操作，例如轮换项目访问令牌。

具有维护者或所有者角色的项目成员在项目访问令牌即将过期时会收到一封电子邮件。

群组访问令牌#

群组访问令牌的作用域限定为一个群组。与个人访问令牌一样，您可以使用它们通过以下方式进行身份验证：

• 极狐GitLab API。
• 极狐GitLab 代码仓库。
• 极狐GitLab 镜像仓库。

您可以限制群组访问令牌的作用域和过期日期。当您创建群组访问令牌时，极狐GitLab 会创建一个群组机器人用户。群组机器人用户是服务账号，不计入许可席位。

您可以使用群组访问令牌 API 以编程方式执行操作，例如轮换群组访问令牌。

具有所有者角色的群组成员在群组访问令牌即将过期时会收到一封电子邮件。

部署令牌#

部署令牌允许您在无需用户和密码的情况下克隆、推送和拉取项目的软件包和容器镜像仓库镜像。部署令牌不能用于 极狐GitLab API。

要管理部署令牌，您必须是具有至少维护者角色的项目成员。

部署密钥#

部署密钥通过将 SSH 公钥导入到您的极狐GitLab 实例，允许对您的代码仓库进行只读或读写访问。部署密钥不能用于 极狐GitLab API 或镜像仓库。

您可以使用部署密钥将代码仓库克隆到您的持续集成服务器，而无需设置虚假用户账号。

要为项目添加或启用部署密钥，您必须至少具有维护者角色。

Runner 认证令牌#

要注册 Runner，您可以使用 Runner 认证令牌 而不是 Runner 注册令牌。Runner 注册令牌 已弃用。

创建 Runner 及其配置后，您会收到一个 Runner 认证令牌，用于注册该 Runner。Runner 认证令牌本地存储在 config.toml 文件中，您可以使用该文件配置 Runner。

Runner 在从作业队列中获取作业时，使用 Runner 认证令牌向极狐GitLab 进行身份验证。Runner 向极狐GitLab 进行身份验证后，会收到一个作业令牌，用于执行作业。

Runner 认证令牌保留在 Runner 机器上。以下执行器的执行环境只能访问作业令牌，而不能访问 Runner 认证令牌：

• Docker Machine
• Kubernetes
• VirtualBox
• Parallels
• SSH

恶意访问 Runner 的文件系统可能会暴露 config.toml 文件和 Runner 认证令牌。攻击者可以使用 Runner 认证令牌 克隆 Runner。

您可以使用 Runner API 轮换或撤销 Runner 认证令牌。

Runner 注册令牌（旧版）#

Runner 注册令牌用于 向极狐GitLab 注册 Runner。群组或 项目所有者或实例管理员可以通过极狐GitLab 用户界面获取它们。注册令牌仅限于 Runner 注册，没有其他作用域。

您可以使用 Runner 注册令牌添加在项目或群组中执行 作业的 Runner。Runner 可以访问项目的 代码，因此在为项目或群组分配权限时要小心。

CI/CD 作业令牌#

CI/CD 作业令牌是一种短期令牌，仅在作业持续期间有效。它使 CI/CD 作业可以访问有限数量的 API 端点。API 身份验证使用作业令牌，通过触发作业的用户的授权进行。

作业令牌因其短暂的生命周期和有限的作用域而受到保护。如果多个作业在同一台机器上运行（例如，使用 shell Runner），此令牌可能会泄露。您可以使用项目允许名单进一步限制作业令牌可以访问的内容。

在 Docker Machine Runner 上，您应配置 MaxBuilds=1 以确保 Runner 机器只运行一个构建并在之后被销毁。预配需要时间，因此此配置可能会影响性能。

极狐GitLab 集群代理令牌#

当您注册极狐GitLab Kubernetes Agent 时，极狐GitLab 会生成一个访问令牌，用于向极狐GitLab 验证集群代理。

要撤销此集群代理令牌，您可以：

• 使用 agents API 撤销令牌。
• 重置令牌。

对于这两种方法，您必须知道令牌、代理和项目 ID。要查找此信息，请使用 Rails 控制台：

ruby
1# Find token ID
2Clusters::AgentToken.find_by_token('glagent-xxx').id
3
4# Find agent ID
5Clusters::AgentToken.find_by_token('glagent-xxx').agent.id
6=> 1234
7
8# Find project ID
9Clusters::AgentToken.find_by_token('glagent-xxx').agent.project_id
10=> 12345

您也可以直接在 Rails 控制台中撤销令牌：

ruby
# Revoke token with RevokeService, including generating an audit event
Clusters::AgentTokens::RevokeService.new(token: Clusters::AgentToken.find_by_token('glagent-xxx'), current_user: User.find_by_username('admin-user')).execute

# Revoke token manually, which does not generate an audit event
Clusters::AgentToken.find_by_token('glagent-xxx').revoke!

其他令牌#

Feed 令牌#

每个用户都有一个长期有效的 Feed 令牌，它不会过期。使用此令牌通过以下方式进行身份验证：

• RSS 阅读器，以加载个性化的 RSS 源。
• 日历应用程序，以加载个性化的日历。

您不能使用此令牌访问任何其他数据。

您可以将用户作用域的 Feed 令牌用于所有源。但是，源和日历 URL 是使用仅对一个源有效的不同令牌生成的。

任何拥有您令牌的人都可以查看您的源活动，包括机密议题，就像他们是您一样。如果您认为您的令牌已泄露，请立即重置令牌。

使用 Feed 令牌的源#

极狐GitLab 在以下位置提供 RSS 源：

• 工作项列表
• 议题列表
• 合并请求列表
• 项目活动
• 群组活动
• 用户活动
• 您的活动仪表板
• 提交
• 标签
• 发布
• 项目主题

禁用 Feed 令牌#

先决条件：

• 您必须是管理员。

1. 在右上角，选择管理员。
2. 在左侧边栏中，选择设置 > 通用。
3. 展开 可见性与访问控制。
4. 在 信息流令牌 下，选中 禁用信息流令牌 复选框，然后选择 保存更改。

传入电子邮件令牌#

每个用户都有一个不会过期的传入电子邮件令牌。该令牌包含在您的个人项目专属电子邮件地址中。您可以使用此令牌通过电子邮件创建议题和合并请求。

重置传入电子邮件令牌#

1. 在右上角，选择您的头像。
2. 选择 编辑个人资料。
3. 在左侧边栏中，选择 访问 > 个人访问令牌。
4. 在 接收电子邮件令牌 下，选择 重置此令牌。

工作区令牌#

每个工作区都有一个内部的、自动管理的令牌，它不会过期。它允许与工作区进行 HTTP 和 SSH 通信。只要请求工作区处于 运行中 状态，它就会存在，并由工作区自动注入和使用。

启动已停止的工作区会创建一个新的工作区令牌。重启正在运行的工作区会删除现有令牌并创建一个新令牌。

您不能直接查看或管理此内部令牌。您不能使用此令牌访问任何其他数据。

要撤销工作区令牌，请停止或终止工作区。该令牌会立即被删除。

可用作用域#

此表显示了每个令牌的默认作用域。对于某些令牌，您可以在创建令牌时进一步限制作用域。

令牌前缀#

下表显示了每种令牌类型的前缀。除个人访问令牌外，这些前缀无法配置，因为它们被设计为标准标识。

Footnotes#

1. 限于一个项目。 ↩ ↩² ↩³

2. 限于一个群组。 ↩ ↩² ↩³

3. Runner 注册和认证令牌不提供对代码仓库的直接访问， 但可用于注册和验证新 Runner， 这些 Runner 可以执行确实可以访问代码仓库的作业。 ↩ ↩²

4. 仅某些端点。 ↩