パーソナルアクセストークン

パーソナルアクセストークンは、GitLabへの認証済みアクセストークンを提供します。これらはOAuth2トークンの代替であり、グループアクセストークンおよびプロジェクトアクセストークンと似ていますが、グループまたはプロジェクトではなくユーザーに紐付けられます。

パーソナルアクセストークンを使用して、以下を認証することができます:

• GitLab APIで認証。
• HTTPSを介したGitの場合。使用方法:
  • 任意の空白以外の値をユーザー名として使用します。
  • パーソナルアクセストークンをパスワードとして使用します。

GitLabマネージドTerraformステートバックエンドやコンテナレジストリなど、ユーザー名を必要とする一部のGitLab機能では、GitLabユーザー名とパーソナルアクセストークンを使用します。これらのケースでは、ユーザー名は必須ですが、認証の一部として評価されません。詳細については、イシュー212953を参照してください。

GitLab Self-ManagedおよびGitLab Dedicatedインスタンスでは、管理者はユーザートークンAPIを使用して、特定のユーザーとして認証するための代理トークンを作成できます。

トークンの使用状況情報を表示する

パーソナルアクセストークンページには、アクセストークンに関する情報が表示されます。

このページから、以下の操作を実行できます:

• パーソナルアクセストークンの作成、ローテーション、および失効。
• アクティブおよび非アクティブなすべてのパーソナルアクセストークンを表示します。
• トークン情報（スコープ、割り当てられたロール、有効期限を含む）を表示します。
• 使用状況の情報（使用日、および最後の5つの異なる接続IPアドレスを含む）を表示します。
  GitLabは、トークンがGit操作を実行したり、RESTまたはGraphQL APIで操作を認証したりすると、トークンの使用状況情報を定期的に更新します。トークンの使用時間は10分ごとに、トークン使用IPアドレスは1分ごとに更新されます。

パーソナルアクセストークンを表示するには:

1. 右上隅で、アバターを選択します。
2. プロファイルを編集を選択します。
3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。

詳細パネルを開くには、トークンの名前を選択します。デフォルトでは、アクティブなトークンのみが表示されます。検索バーを使用して、アクセストークンのリストをフィルタリングします。

パーソナルアクセストークンを作成する

パーソナルアクセストークンを作成するには:

1. 右上隅で、アバターを選択します。
2. プロファイルを編集を選択します。
3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。
4. トークンを生成ドロップダウンリストから、レガシートークンを選択します。
5. トークン名に、トークンの名前を入力します。
6. オプション。トークンの説明に、トークンの説明を入力します。
7. 有効期限に、トークンの有効期限を入力します。
   • トークンは、その日のUTC深夜に期限が切れます。
   • 日付を入力しない場合、有効期限は今日から365日後に設定されます。
   • デフォルトでは、有効期限は今日から365日を超えることはできません。GitLab 17.6以降では、管理者はアクセストークンの最大ライフタイムを変更できます。
8. 1つ以上のパーソナルアクセストークンスコープを選択します。
9. トークンを生成を選択します。

パーソナルアクセストークンが表示されます。パーソナルアクセストークンを安全な場所に保存します。ページを離れるか更新すると、再度表示することはできません。

すべてのアクセストークンは、パーソナルアクセストークン用に設定されたデフォルトプレフィックス設定を継承します。

パーソナルアクセストークンの詳細を事前に入力する

名前、説明、およびスコープのリストをURLに付加することで、パーソナルアクセストークンの詳細を事前に入力できます。例:

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

パーソナルアクセストークンのスコープ

スコープは、パーソナルアクセストークンで認証する際に利用できるアクションを定義します。以下のスコープが利用可能です:

パーソナルアクセストークンをローテーションする

トークンをローテーションして、元のトークンと同じ権限とスコープを持つ新しいトークンを作成します。元のトークンは直ちに無効になり、GitLabは監査目的で両方のバージョンを保持します。

パーソナルアクセストークンをローテーションするには:

1. 右上隅で、アバターを選択します。
2. プロファイルを編集を選択します。
3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。
4. アクティブなトークンの横にある縦方向の省略記号（ ）を選択します。
5. ローテーション（ ）を選択します。
6. 確認ダイアログで、ローテーションを選択します。

パーソナルアクセストークンを失効させる

トークンを失効すると、直ちに無効になり、それ以降の使用が防止されます。GitLabは監査目的でトークンを保持します。トークンを完全に削除することはできませんが、トークンリストをフィルタリングしてアクティブなトークンのみを表示できます。

パーソナルアクセストークンを失効するには:

1. 右上隅で、アバターを選択します。
2. プロファイルを編集を選択します。
3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。
4. アクティブなトークンの横にある縦方向の省略記号（ ）を選択します。
5. 取り消し（ ）を選択します。
6. 確認ダイアログで、取り消しを選択します。

アクセストークンの有効期限

パーソナルアクセストークン、グループアクセストークン、およびプロジェクトアクセストークンは、有効期限のUTC深夜に期限が切れます。期限切れになると、それらはリクエストを認証するために使用できなくなります。

GitLab 16.0以降では、新しいアクセストークンには有効期限が必要です。有効期限がトークン作成時に明示的に設定されていない場合、今日から365日間の有効期限が適用されます。Ultimateでは、管理者はアクセストークンの最大許容ライフタイムを設定できます。

あなたのGitLabバージョンと提供内容によっては、GitLabバージョンのアップグレード時に既存のアクセストークンに有効期限が自動的に適用される場合があります。詳細については、期限切れにならないアクセストークンを参照してください。

パーソナルアクセストークンの有効期限に関するメール

GitLabは、まもなく有効期限が切れるパーソナルアクセストークンを特定するために、毎日UTC午前1:00にチェックを実行します。トークンの有効期限が切れる7日前に、ユーザーにメールで通知されます。GitLab 17.6以降では、トークンの期限が切れる30日前と60日前にも通知が送信されます。

パーソナルアクセストークンの有効期限カレンダー

各トークンの有効期限にイベントが設定されたiCalendarエンドポイントをサブスクライブできます。サインイン後、このエンドポイントは/-/user_settings/personal_access_tokens.icsで利用できます。

有効期限のないサービスアカウントのパーソナルアクセストークンを作成する

有効期限のないサービスアカウントのパーソナルアクセストークンを作成できます。これらのパーソナルアクセストークンは、通常のアカウントのパーソナルアクセストークンとは異なり、有効期限切れになることはありません。

GitLab.com

前提条件:

• トップレベルグループのオーナーロールが必要です。

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。
2. 設定 > 一般 > 権限とグループ機能を選択します。
3. サービスアカウントトークンの有効期限チェックボックスをオフにします。

これで、有効期限のないサービスアカウントユーザーのパーソナルアクセストークンを作成できます。

GitLab Self-Managed

前提条件:

• GitLab Self-Managedインスタンスの管理者である必要があります。

1. 右上隅で、管理者を選択します。
2. 設定 > 一般を選択します。
3. アカウントと制限を展開します。
4. サービスアカウントトークンの有効期限チェックボックスをオフにします。

これで、有効期限のないサービスアカウントユーザーのパーソナルアクセストークンを作成できます。

アクセストークンを無効にする

前提条件:

• 管理者アクセス権が必要です。

GitLabインスタンス全体で、ユーザーがアクセストークンで認証するのを防ぐことができます。この設定は、パーソナルアクセストークン、グループアクセストークン、プロジェクトアクセストークン、および代理トークンに影響します。この設定は、サービスアカウントのパーソナルアクセストークンにも適用されます。

アクセストークンを無効にすると、次のルールが適用されます:

• ユーザーはパーソナルアクセストークンを使用してGitLabにサインインできません。
• パーソナルアクセストークンページは、404 Not Foundエラーを返します。
• RSS、Atom、およびカレンダーフィードのフィードトークンは機能しなくなります。
• パーソナルアクセストークンで認証するされたAPIリクエストは拒否されます。

インスタンスのアクセストークンを無効にするには:

1. 右上隅で、管理者を選択します。
2. 設定 > 一般を選択します。
3. アカウントと制限を展開します。
4. アクセストークンを無効にするチェックボックスを選択します。
5. 変更を保存を選択します。

アプリケーション設定APIでdisable_personal_access_tokens属性を使用することもできます。

エンタープライズユーザーのパーソナルアクセストークンを無効にする

前提条件:

• エンタープライズユーザーが所属するグループのオーナーロール。

グループのエンタープライズユーザーのパーソナルアクセストークンを無効にすると、次のようになります。

• エンタープライズユーザーは新しいパーソナルアクセストークンを作成できなくなります。この動作は、エンタープライズユーザーがグループ管理者である場合でも適用されます。
• エンタープライズユーザーの既存のパーソナルアクセストークンが無効になります。

エンタープライズユーザーのパーソナルアクセストークンは、次の手順で無効にできます。

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。
2. 設定 > 一般を選択します。
3. 権限とグループ機能を展開します。
4. エンタープライズのユーザーで、パーソナルアクセストークンを無効にするを選択します。
5. 変更を保存を選択します。

エンタープライズユーザーアカウントを削除またはブロックすると、そのユーザーのパーソナルアクセストークンは自動的に取り消されます。

パーソナルアクセストークンでDPoPを使用する

Demonstrating Proof of Possession（DPoP、所有証明の実証）は、パーソナルアクセストークンのセキュリティを強化し、意図しないトークンの漏洩の影響を最小限に抑えます。アカウントでこの機能を有効にすると、PATを含むすべてのRESTおよびGraphQL APIリクエストで、署名付きDPoPヘッダーも提供する必要が生じます。署名付きDPoPヘッダーを作成するには、対応する秘密SSHキーが必要です。

前提条件:

• 少なくとも1つの公開SSHキーをアカウントに追加します。署名、または認証と署名の使用タイプを設定する必要があります。
  • SSHキータイプはRSAである必要があります。
• GitLabアカウント用にGitLab CLIをインストールして設定する必要があります。

RESTおよびGraphQL APIへのすべての呼び出しで、DPoPを要求するには:

1. 右上隅で、アバターを選択します。

2. プロファイルを編集を選択します。

3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。

4. Demonstrating Proof of Possession (DPoP)の使用セクションに移動し、DPoPを有効にするを選択します。

5. 変更を保存を選択します。

6. ターミナルで次のコマンドを実行して、GitLab CLIでDPoPヘッダーを生成します。<your_access_token>をアクセストークンに、~/.ssh/id_rsaを秘密キーの場所に置き換えます。

    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"

DPoPの詳細については、ブループリント送信者制約パーソナルアクセストークンを参照してください。

プログラムを利用してパーソナルアクセストークンを作成する

テストまたは自動化の一環として、事前に決定されたパーソナルアクセストークンを作成できます。

前提条件:

• GitLabインスタンスでRailsコンソールセッションを実行するための十分なアクセス権が必要です。

プログラムを利用してパーソナルアクセストークンを作成する手順は次のとおりです。

1. Railsコンソールを開きます。

   sudo gitlab-rails console

2. 次のコマンドを実行して、ユーザー名、トークン、スコープを参照します。

   トークンは20文字の長さでなければなりません。スコープは有効である必要があり、ソースコードで表示できます。

   たとえば、ユーザー名がautomation-botのユーザーに属し、1年後に期限切れになるトークンは、次のコマンドで作成できます。

   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を使用して、単一行のシェルコマンドに短縮できます。

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コンソールを開きます。

   sudo gitlab-rails console

2. 次のコマンドを実行して、token-string-here123のトークンを取り消します。

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

このコードは、Rails runnerを使用して、単一行のシェルコマンドに短縮できます。

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

パーソナルアクセストークンを使用してリポジトリをクローンする

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は、次の条件を満たす必要があります。

• 任意の文字列を指定できます。
• 空の文字列は使用できません。

認証に依存する自動化パイプラインを設定する場合は、この条件を必ず守ってください。

パーソナルアクセストークンの代替

HTTPS経由のGitの場合、パーソナルアクセストークンの代替として、OAuth認証ヘルパーを使用できます。

CI/CDジョブでの認証には、以下を考慮してください:

• パイプライン認証のための、CI/CDジョブトークンときめ細かい権限。
• プロジェクト固有の自動化のための、最小限の必要な権限を持つプロジェクトアクセストークン。

関連トピック

• グループアクセストークン
• プロジェクトアクセストークン
• パーソナルアクセストークンAPI
• きめ細かいパーソナルアクセストークンをサポートするREST APIエンドポイント