{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

创建个人访问令牌

个人访问令牌可以作为 OAuth2 的替代方案，并用于：

  • 使用 极狐GitLab API 进行身份验证。
  • 使用 HTTP 基本身份验证进行 Git 身份验证。

在这两种情况下，您使用个人访问令牌进行身份验证，而不是使用您的密码。用户名在身份验证过程中不予评估。

个人访问令牌是：

{{< alert type=”note” >}}

尽管需要，极狐GitLab 用户名在使用个人访问令牌进行身份验证时会被忽略。

{{< /alert >}}

有关如何使用个人访问令牌进行 API 身份验证的示例，请参阅 API 文档。

或者，极狐GitLab 管理员可以使用 API 创建模拟令牌。使用模拟令牌来自动化作为特定用户的身份验证。

创建个人访问令牌

{{< history >}}

  • 在极狐GitLab 15.3 中引入，默认过期时间为 30 天，在 UI 中填充。
  • 在极狐GitLab 16.0 中移除了创建不过期个人访问令牌的能力。
  • 在极狐GitLab 17.6 中将最大允许生命周期限制扩展到 400 天，默认情况下禁用，使用名为 buffered_token_expiration_limit 的功能标志。
  • 在极狐GitLab 17.7 中引入个人访问令牌描述。

{{< /history >}}

{{< alert type=”flag” >}}

扩展最大允许寿命限制的可用性由一个功能标志控制。有关更多信息，请参阅历史记录。

{{< /alert >}}

{{< alert type=”warning” >}}

在极狐GitLab 15.4 中弃用了创建没有过期日期的个人访问令牌的能力，并在极狐GitLab 16.0 中移除。有关个人访问令牌何时过期以及过期日期何时添加到现有令牌的更多信息，请参阅有关访问令牌过期的文档。

{{< /alert >}}

您可以根据需要创建任意数量的个人访问令牌。

  1. 在左侧边栏，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏，选择 访问令牌。
  4. 选择 添加新令牌。
  5. 在 令牌名称 中，为令牌输入一个名称。
  6. 可选。在 令牌描述 中，为令牌输入一个描述。
  7. 在 过期日期 中，输入令牌的过期日期。
    • 令牌在该日期的午夜 UTC 时过期。过期日期为 2024-01-01 的令牌将在 2024-01-01 的 00:00:00 UTC 时过期。
    • 如果您没有输入过期日期，过期日期将自动设置为当前日期后 365 天。
    • 默认情况下，该日期可以是当前日期后的最多 365 天。在极狐GitLab 17.6 或更高版本中，您可以将此限制扩展到 400 天。
  8. 选择所需的范围。
  9. 选择 创建个人访问令牌。

将个人访问令牌保存在安全的地方。离开页面后，您将无法再访问令牌。

预填个人访问令牌名称和范围

您可以直接链接到个人访问令牌页面，并让表单预填名称和范围列表。为此，您可以将 name 参数和逗号分隔的范围列表追加到 URL。例如：

https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry

{{< alert type=”warning” >}}

个人访问令牌必须小心处理。阅读我们的令牌安全注意事项，以获取管理个人访问令牌的指导（例如，设置短的过期时间和使用最小范围）。

{{< /alert >}}

撤销或旋转个人访问令牌

{{< history >}}

  • 在极狐GitLab 17.7 中引入使用 UI 轮换个人访问令牌的能力。

{{< /history >}}

您可以随时使用 UI 撤销或，在极狐GitLab 17.7 及更高版本，旋转个人访问令牌。

  1. 在左侧边栏，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏，选择 访问令牌。
  4. 在 活跃的个人访问令牌 区域，对于相关令牌，选择 撤销 ({{< icon name=”remove” >}}) 或 旋转 ({{< icon name=”retry” >}})。

  5. 在确认对话框中，选择 撤销 或 旋转。

    {{< alert type=”warning” >}}

    这些操作无法撤销。任何依赖于已撤销或旋转的访问令牌的工具将停止工作。

    {{< /alert >}}

禁用个人访问令牌

{{< details >}}

  • Tier: 专业版, 旗舰版
  • Offering: 私有化部署

{{< /details >}}

前提条件：

  • 您必须是管理员。

根据您的极狐GitLab 版本，您可以使用应用程序设置 API 或管理员 UI 禁用个人访问令牌。

使用应用程序设置 API

{{< history >}}

  • 在极狐GitLab 15.7 中引入。

{{< /history >}}

在极狐GitLab 15.7 及更高版本中，您可以使用应用程序设置 API 中的 disable_personal_access_tokens 属性 来禁用个人访问令牌。

{{< alert type=”note” >}}

使用 API 禁用个人访问令牌后，这些令牌无法在后续的 API 调用中用于管理此设置。要重新启用个人访问令牌，您必须使用 极狐GitLab Rails 控制台。您还可以升级到极狐GitLab 17.3 或更高版本，以便可以使用管理员 UI。

{{< /alert >}}

使用管理员 UI

{{< history >}}

  • 在极狐GitLab 17.3 中引入。

{{< /history >}}

在极狐GitLab 17.3 及更高版本中，您可以使用管理员 UI 禁用个人访问令牌：

  1. 在左侧边栏底部，选择 管理员。
  2. 选择 设置 > 通用。
  3. 展开 可见性和访问控制。
  4. 选中 禁用个人访问令牌 复选框。
  5. 选择 保存更改。

为企业用户禁用个人访问令牌

{{< history >}}

  • 在极狐GitLab 16.11 中引入，使用名为 enterprise_disable_personal_access_tokens 的功能标志。默认情况下禁用。
  • 在极狐GitLab 17.2 中在 JihuLab.com 上启用。
  • 在极狐GitLab 17.3 中 GA。功能标志 enterprise_disable_personal_access_tokens 已移除。

{{< /history >}}

前提条件：

  • 您必须具有企业用户所属群组的拥有者角色。

禁用群组企业用户的个人访问令牌：

  • 阻止企业用户创建新的个人访问令牌。即使企业用户也是群组管理员，此行为也适用。
  • 禁用企业用户的现有个人访问令牌。

{{< alert type=”warning” >}}

为企业用户禁用个人访问令牌不会禁用服务帐户的个人访问令牌。

{{< /alert >}}

要禁用企业用户的个人访问令牌：

  1. 在左侧边栏，选择 搜索或转到 并找到您的群组。
  2. 选择 设置 > 通用。
  3. 展开 权限和群组功能。
  4. 在 个人访问令牌 下，选择 禁用个人访问令牌。
  5. 选择 保存更改。

当您删除或阻止企业用户帐户时，他们的个人访问令牌将自动撤销。

查看令牌使用信息

{{< history >}}

  • 在极狐GitLab 16.0 及更早版本中，令牌使用信息每 24 小时更新一次。
  • 在极狐GitLab 16.1 中，令牌使用信息更新频率从 24 小时更改为 10 分钟。
  • 在极狐GitLab 17.8 中引入查看 IP 地址的能力，默认情况下启用名为 pat_ip 的标志。
  • 在极狐GitLab 17.10 中查看 IP 地址的能力 GA。功能标志 pat_ip 已移除。

{{< /history >}}

令牌使用信息定期更新。令牌上次使用的时间每 10 分钟更新一次，最近使用的 IP 地址每分钟更新一次。极狐GitLab 将令牌视为使用过的，当令牌：

  • 使用 REST 或 GraphQL APIs 进行身份验证。
  • 执行 Git 操作。

要查看令牌的最后使用时间以及令牌使用的 IP 地址：

  1. 在左侧边栏，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏，选择 访问令牌。
  4. 在 活跃的个人访问令牌 区域，查看相关令牌的 最后使用 日期和 最后使用的 IP。最后使用的 IP 显示最后五个不同的 IP 地址。

个人访问令牌范围

{{< history >}}

  • 在极狐GitLab 16.0 中引入个人访问令牌不再能够访问容器或软件包注册表。
  • 在极狐GitLab 16.4 中引入，使用名为 k8s_proxy_pat 的功能标志。默认启用。
  • 在极狐GitLab 16.5 中移除功能标志 k8s_proxy_pat。
  • 在极狐GitLab 17.1 中引入 read_service_ping。
  • 在极狐GitLab 17.1 中引入 manage_runner。
  • 在极狐GitLab 17.9 中引入 self_rotate。默认启用。

{{< /history >}}

个人访问令牌可以根据分配的范围执行操作。

范围 访问
api 授予对 API 的完全读/写访问权限，包括所有群组和项目、容器注册表、依赖项代理和软件包注册表。还授予使用 Git over HTTP 的注册表和存储库的完全读/写访问权限。
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 如果项目是私有的并且需要授权，授予对 容器注册表 图像的读写（推送）访问权限。仅在启用容器注册表时可用。
read_virtual_registry 如果项目是私有的并且需要授权，授予通过 依赖项代理 对容器图像的只读（拉取）访问权限。仅在启用依赖项代理时可用。
write_virtual_registry 如果项目是私有的并且需要授权，授予通过 依赖项代理 对容器图像的读（拉取）、写（推送）和删除访问权限。仅在启用依赖项代理时可用。
sudo 授予在系统中作为任何用户执行 API 操作的权限，前提是以管理员身份进行身份验证。
admin_mode 授予在启用 管理员模式 时执行 API 操作的权限。在极狐GitLab 15.8 中引入。仅在极狐GitLab 私有化部署实例上对管理员可用。
create_runner 授予创建 runner 的权限。
manage_runner 授予管理 runner 的权限。
ai_features 此范围：
- 授予执行 API 操作以实现极狐GitLab Duo、代码建议 API 和 Duo 聊天 API 的功能的权限。
- 对于极狐GitLab 私有化部署版本 16.5、16.6 和 16.7 不起作用。
对于 JetBrains 的极狐GitLab Duo 插件，此范围：
- 支持在 JetBrains 的极狐GitLab Duo 插件中启用 AI 功能的用户。
- 解决了 JetBrains IDE 插件中可能暴露个人访问令牌的安全漏洞。
- 旨在通过限制被盗令牌的影响来最大限度地降低极狐GitLab Duo 插件用户的潜在风险。
对于所有其他扩展，请参阅其文档中的单个范围要求。
k8s_proxy 授予使用 Kubernetes 代理执行 Kubernetes API 调用的权限。
self_rotate 授予使用 个人访问令牌 API 旋转此令牌的权限。不允许旋转其他令牌。
read_service_ping 授予在以管理员身份认证时通过 API 下载服务 Ping 负载的权限。

{{< alert type=”warning” >}}

如果您启用了外部授权，个人访问令牌无法访问容器或软件包注册表。如果您使用个人访问令牌访问这些注册表，此措施会破坏这些令牌的使用。禁用外部授权以使用个人访问令牌与容器或软件包注册表。

{{< /alert >}}

访问令牌过期

{{< history >}}

  • 在极狐GitLab 17.6 中引入，使用名为 buffered_token_expiration_limit 的功能标志。默认禁用。

{{< /history >}}

{{< alert type=”flag” >}}

扩展最大允许寿命限制的可用性由一个功能标志控制。有关更多信息，请参阅历史记录。

{{< /alert >}}

个人访问令牌在您定义的日期过期，午夜，00:00 AM UTC。过期日期为 2024-01-01 的令牌将在 2024-01-01 的 00:00:00 UTC 时过期。

  • 极狐GitLab 每天在 UTC 时间 1:00 AM 运行检查，以识别即将过期的个人访问令牌。这些令牌的拥有者会通过电子邮件通知。
  • 极狐GitLab 每天在 UTC 时间 02:00 AM 运行检查，以识别当天过期的个人访问令牌。这些令牌的拥有者会通过电子邮件通知。
  • 在极狐GitLab 旗舰版中，管理员可以限制访问令牌的允许寿命。如果未设置，个人访问令牌的最大允许寿命为 365 天。在极狐GitLab 17.6 或更高版本中，您可以将此限制扩展到 400 天。
  • 在极狐GitLab 基础版和专业版中，个人访问令牌的最大允许寿命为 365 天。在极狐GitLab 17.6 或更高版本中，您可以将此限制扩展到 400 天。
  • 如果您在创建个人访问令牌时没有设置过期日期，则过期日期设置为令牌的最大允许寿命。如果未设置最大允许寿命，则默认过期日期为创建日期后的 365 天。

是否自动为现有个人访问令牌应用过期日期取决于您拥有的极狐GitLab 提供的服务，以及您何时升级到极狐GitLab 16.0 或更高版本：

  • 在 JihuLab.com 上，在 16.0 里程碑期间，现有的没有过期日期的个人访问令牌会自动设置为当前日期后 365 天的过期日期。
  • 在极狐GitLab 私有化部署上，如果您从极狐GitLab 15.11 或更早版本升级到极狐GitLab 16.0 或更高版本：
    • 在 2024 年 7 月 23 日或之前，现有没有过期日期的个人访问令牌会自动设置为当前日期后 365 天的过期日期。这一变化是一个破坏性变化。
    • 在 2024 年 7 月 24 日或之后，现有没有过期日期的个人访问令牌没有设置过期日期。

在极狐GitLab 私有化部署上，如果您安装以下极狐GitLab 版本，您的现有个人访问令牌不会自动应用过期日期：

  • 16.0.9
  • 16.1.7
  • 16.2.10
  • 16.3.8
  • 16.4.6
  • 16.5.9
  • 16.6.9
  • 16.7.9
  • 16.8.9
  • 16.9.10
  • 16.10.9
  • 16.11.7
  • 17.0.5
  • 17.1.3
  • 17.2.1

个人访问令牌过期电子邮件

{{< history >}}

  • 在极狐GitLab 17.6 中引入，使用名为 expiring_pats_30d_60d_notifications 的功能标志。默认禁用。
  • 在极狐GitLab 17.7 中 GA。功能标志 expiring_pats_30d_60d_notifications 已移除。

{{< /history >}}

极狐GitLab 每天在 UTC 时间 1:00 AM 运行检查，以识别即将过期的个人访问令牌。这些令牌的拥有者在这些令牌在某个天数后过期时通过电子邮件通知。天数根据极狐GitLab 的版本而有所不同：

  • 在极狐GitLab 17.6 及更高版本中，个人访问令牌拥有者在检查识别其个人访问令牌将在接下来的 60 天内过期时通过电子邮件通知。另一个电子邮件在检查识别其群组访问令牌将在接下来的 30 天内过期时发送。
  • 个人访问令牌拥有者在检查识别其群组访问令牌将在接下来的七天内过期时通过电子邮件通知。

个人访问令牌过期日历

您可以订阅一个 iCalendar 端点，其中包含每个令牌的过期日期事件。登录后，此端点在 /-/user_settings/personal_access_tokens.ics 中可用。

创建无过期日期的服务帐户个人访问令牌

您可以为服务帐户创建个人访问令牌，无需过期日期。这些个人访问令牌永不过期，与非服务帐户个人访问令牌不同。

{{< alert type=”note” >}}

允许为服务帐户创建无过期日期的个人访问令牌只会影响您在更改此设置后创建的令牌。这不会影响现有的令牌。

{{< /alert >}}

JihuLab.com

前提条件：

  • 您必须拥有顶级群组的拥有者角色。
  1. 在左侧边栏，选择 搜索或转到 并找到您的群组。
  2. 选择 设置 > 通用 > 权限和群组功能。
  3. 清除 服务帐户令牌过期 复选框。

您现在可以为服务帐户用户创建无过期日期的个人访问令牌。

极狐GitLab 私有化部署

前提条件：

  • 您必须是极狐GitLab 私有化部署实例的管理员。
  1. 在左侧边栏底部，选择 管理员。
  2. 选择 设置 > 通用。
  3. 展开 帐户和限制。
  4. 清除 服务帐户令牌过期 复选框。

您现在可以为服务帐户用户创建无过期日期的个人访问令牌。

使用个人访问令牌需要 DPoP 标头

{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

{{< history >}}

  • 在极狐GitLab 17.10 中引入，使用名为 dpop_authentication 的功能标志。默认禁用。

{{< /history >}}

{{< alert type=”flag” >}}

此功能的可用性由一个功能标志控制。有关更多信息，请参阅历史记录。此功能可用于测试，但尚未准备好用于生产环境。

{{< /alert >}}

演示持有证明 (DPoP) 增强了您的个人访问令牌的安全性，并最大限度地降低了意外令牌泄露的影响。当您在帐户上启用此功能时，所有包含 PAT 的 REST 和 GraphQL API 请求还必须提供已签名的 DPoP 标头。创建签名的 DPoP 标头需要您的对应私有 SSH 密钥。

{{< alert type=”note” >}}

如果您启用此功能，所有没有有效 DPoP 标头的 REST 和 GraphQL API 请求将因 DpopValidationError 而失败。

{{< /alert >}}

前提条件：

  • 您必须在帐户上添加至少一个 用法类型 为 签名 或 认证和签名 的公有 SSH 密钥。
  • 您必须为您的极狐GitLab 帐户安装并配置 极狐GitLab CLI。

要在对 REST 和 GraphQL API 的所有调用中需要 DPoP：

  1. 在左侧边栏，选择您的头像。
  2. 选择 编辑个人资料。
  3. 在左侧边栏，选择 访问令牌。
  4. 转到 使用演示持有证明 部分，选择 启用 DPoP。
  5. 选择 保存更改。

  6. 要使用 极狐GitLab CLI 生成 DPoP 标头，请在终端中运行此命令。将 <your_access_token> 替换为您的访问令牌，并将 ~/.ssh/id_rsa 替换为您的私有密钥的位置：

     bin/glab auth dpop-gen --pat "<your_access_token>" --private-key ~/.ssh/id_rsa

您在 CLI 中生成的 DPoP 标头可以用于：

  • 使用 REST API：

    curl --header "Private-Token: <your_access_token>" \
  --header "DPoP: <dpop-from-glab>" \
  "https://gitlab.example.com/api/v4/projects"

  • 使用 GraphQL：

     curl --request POST \
 --header "Content-Type: application/json" \
 --header "Private-Token: <your_access_token>" \
 --header "DPoP: <dpop-from-glab>" \
 --data '{
 "query": "query { currentUser { id } }"
 }' \
 "https://gitlab.example.com/api/graphql"

使用编程方式创建个人访问令牌

{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: 私有化部署

{{< /details >}}

您可以作为测试或自动化的一部分创建预定的个人访问令牌。

前提条件：

要使用编程方式创建个人访问令牌：

  1. 打开一个 Rails 控制台：

    sudo gitlab-rails console

  2. 运行以下命令以引用用户名、令牌和范围。

    令牌必须是 20 个字符长。范围必须有效，并在源代码中可见。

    例如，要创建一个属于用户名 automation-bot 的用户的令牌并在一年后过期：

    user = User.find_by_username('automation-bot')
token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now)
token.set_token('token-string-here123')
token.save!

此代码可以通过使用 Rails runner 缩短为单行 shell 命令：

sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now); token.set_token('token-string-here123'); token.save!"

使用编程方式撤销个人访问令牌

{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

您可以作为测试或自动化的一部分使用编程方式撤销个人访问令牌。

前提条件：

要使用编程方式撤销令牌：

  1. 打开一个 Rails 控制台：

    sudo gitlab-rails console

  2. 要撤销 token-string-here123 的令牌，请运行以下命令：

    token = PersonalAccessToken.find_by_token('token-string-here123')
token.revoke!

此代码可以通过使用 Rails runner 缩短为单行 shell 命令：

sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"

使用个人访问令牌克隆存储库

{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: 私有化部署

{{< /details >}}

要在禁用 SSH 时克隆存储库，请运行以下命令使用个人访问令牌进行克隆：

git clone https://<username>:<personal_token>@gitlab.com/gitlab-org/gitlab.git

此方法将您的个人访问令牌保存在 bash 历史记录中。要避免这种情况，请运行以下命令：

git clone https://<username>@gitlab.com/gitlab-org/gitlab.git

当被要求提供 https://gitlab.com 的密码时，输入您的个人访问令牌。

clone 命令中的 username：

  • 可以是任何字符串值。
  • 必须不是空字符串。

如果您设置了依赖于身份验证的自动化流水线，请记住这一点。

故障排除

取消撤销个人访问令牌

{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: 私有化部署

{{< /details >}}

如果个人访问令牌因任何方法意外撤销，管理员可以取消撤销该令牌。默认情况下，每天凌晨 1:00 系统时间会删除撤销的令牌。

{{< alert type=”warning” >}}

运行以下命令会直接更改数据。如果未正确执行或在正确的条件下执行，这可能会造成损害。您应该首先在具有实例备份准备好恢复的测试环境中运行这些命令，以防万一。

{{< /alert >}}

  1. 打开一个 Rails 控制台。

  2. 取消撤销令牌：

    token = PersonalAccessToken.find_by_token('<token_string>')
token.update!(revoked:false)

    例如，取消撤销 token-string-here123 的令牌：

    token = PersonalAccessToken.find_by_token('token-string-here123')
token.update!(revoked:false)

个人访问令牌的替代方案

对于 Git over HTTPS，个人访问令牌的替代方案是使用 OAuth 凭证助手。