个人访问令牌

创建个人访问令牌#

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

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

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

个人访问令牌是：

• 在启用双因素身份验证 (2FA) 或 SAML 时需要的。
• 与极狐GitLab 用户名一起使用，以进行需要用户名的极狐GitLab 功能的身份验证。例如，极狐GitLab 托管的 Terraform 状态后端 和 Docker 容器镜像仓库。
• 类似于 项目访问令牌 和 群组访问令牌，但附加到用户，而不是项目或群组。

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

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

创建个人访问令牌#

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

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。例如：

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

撤销或旋转个人访问令牌#

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

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

2. 选择 编辑个人资料。

3. 在左侧边栏，选择 访问令牌。

4. 在 活跃的个人访问令牌 区域，对于相关令牌，选择 撤销 (

   ) 或 旋转 (
   )。

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

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

禁用个人访问令牌#

前提条件：

• 您必须是管理员。

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

使用应用程序设置 API#

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

使用管理员 UI#

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

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

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

前提条件：

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

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

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

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

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

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

查看令牌使用信息#

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

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

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

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

个人访问令牌范围#

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

访问令牌过期#

个人访问令牌在您定义的日期过期，午夜，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

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

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

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

个人访问令牌过期日历#

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

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

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

JihuLab.com#

前提条件：

• 您必须拥有顶级群组的拥有者角色。

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

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

极狐GitLab 私有化部署#

前提条件：

• 您必须是极狐GitLab 私有化部署实例的管理员。

1. 在左侧边栏底部，选择 管理员。
2. 选择 设置 > 通用。
3. 展开 帐户和限制。
4. 清除 服务帐户令牌过期 复选框。

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

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

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

前提条件：

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

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

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

2. 选择 编辑个人资料。

3. 在左侧边栏，选择 访问令牌。

4. 转到 使用演示持有证明 部分，选择 启用 DPoP。

5. 选择 保存更改。

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

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

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

• 使用 REST API：

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

• 使用 GraphQL：

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

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

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

前提条件：

• 您需要足够的访问权限来为您的极狐GitLab 实例运行一个 Rails 控制台会话。

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

1. 打开一个 Rails 控制台：

   shell
   sudo gitlab-rails console

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

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

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

   ruby
   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 命令：

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!"

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

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

前提条件：

• 您需要足够的访问权限来为您的极狐GitLab 实例运行一个 Rails 控制台会话。

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

1. 打开一个 Rails 控制台：

   shell
   sudo gitlab-rails console

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

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

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

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

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

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

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

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

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

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

clone 命令中的 username：

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

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

故障排除#

取消撤销个人访问令牌#

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

1. 打开一个 Rails 控制台。

2. 取消撤销令牌：

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

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

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

个人访问令牌的替代方案#

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