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

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

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

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

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

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

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

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

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. 確認ダイアログで、取り消しを選択します。

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

前提条件:

• 管理者である必要があります。

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

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

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

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

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

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

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

前提条件:

• エンタープライズユーザーが所属するグループのオーナーロールを持っている必要があります。

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

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

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

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

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

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

トークンの使用状況に関する情報は定期的に更新されます。トークンが最後に使用された時刻は10分ごとに更新され、最後に使用されたIPアドレスは1分ごとに更新されます。GitLabは、次の場合にトークンが使用されたと見なします。

• RESTまたはGraphQL APIで認証した場合。
• Gitオペレーションを実行した場合。

トークンが最後に使用された時刻と、トークンが使用されたIPアドレスは、次の手順で表示できます。

1. 右上隅で、アバターを選択します。
2. プロファイルを編集を選択します。
3. 左側のサイドバーで、アクセス > パーソナルアクセストークンを選択します。
4. 有効なパーソナルアクセストークンエリアで、関連するトークンの最終使用日と最後に使用したIPを確認します。最後に使用したIPには、最後に使用された5つの異なるIPアドレスが表示されます。

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

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

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

パーソナルアクセストークンは、定義した日付の00:00 AM UTCに期限切れになります。有効期限が2024-01-01のトークンは、2024-01-01の00:00:00 UTCに期限切れになります。

• GitLabはUTC午前1時00分にチェックを毎日実行して、間もなく期限切れになるパーソナルアクセストークンを特定します。これらのトークンの所有者はメールで通知されます。
• GitLabはUTC午前2時00分にチェックを毎日実行して、当日期限切れになるパーソナルアクセストークンを特定します。これらのトークンの所有者はメールで通知されます。
• GitLab Ultimateでは、管理者はアクセストークンの許容ライフタイムを制限できます。設定されていない場合、パーソナルアクセストークンの最大許容ライフタイムは365日です。GitLab 17.6以降では、この制限を400日に延長できます。
• GitLab FreeおよびPremiumでは、パーソナルアクセストークンの最大許容ライフタイムは365日です。GitLab 17.6以降では、この制限を400日に延長できます。
• パーソナルアクセストークンを作成するときに有効期限を設定しない場合、有効期限はトークンの最大許容ライフタイムに設定されます。最大許容ライフタイムが設定されていない場合、デフォルトの有効期限は作成日から365日後です。

既存のパーソナルアクセストークンに有効期限が自動的に適用されるかどうかは、お使いのGitLabの提供形態と、GitLab 16.0以降にアップグレードした時期によって異なります。

• GitLab.comでは、16.0のマイルストーン中に、有効期限のない既存のパーソナルアクセストークンに対して、現在の日付から365日後という有効期限が自動的に設定されました。
• GitLab Self-Managedで、GitLab 15.11以前からGitLab 16.0以降にアップグレードした場合:
  • 2024年7月23日以前は、有効期限のない既存のパーソナルアクセストークンに、現在の日付から365日後の有効期限が自動的に付与されました。これは破壊的な変更です。
  • 2024年7月24日以降、有効期限のない既存のパーソナルアクセストークンには、有効期限が設定されていませんでした。

GitLab Self-Managedでは、次の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分にチェックを毎日実行して、近日中に有効期限が切れるパーソナルアクセストークンを特定します。該当トークンのオーナーには、一定の日数で有効期限が切れる旨をメールで通知します。日数は、GitLabのバージョンによって異なります。

• GitLab 17.6以降では、パーソナルアクセストークンが今後60日以内に有効期限切れになることが確認された場合、オーナーにメールで通知されます。グループアクセストークンが今後30日以内に有効期限切れになることが確認された場合、追加のメールが送信されます。
• グループアクセストークンが今後7日以内に有効期限切れになることが確認された場合、オーナーにメールで通知されます。

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

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

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

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

GitLab.com

前提条件:

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

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

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

GitLab Self-Managed

前提条件:

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

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

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

パーソナルアクセストークンで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エンドポイント