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

パーソナルアクセストークンは、OAuth2の代替として、次の目的で使用できます:

• GitLab APIで認証する。
• HTTP基本認証を使用してGitで認証する。

どちらの場合も、パスワードの代わりにパーソナルアクセストークンで認証します。ユーザー名は、認証プロセスの一環として評価されません。

パーソナルアクセストークンの特徴は次のとおりです:

• 2要素認証（2FA）またはSAMLが有効になっている場合に必要です。
• ユーザー名を必要とするGitLabの機能でGitLabのユーザー名と併用して認証します。たとえば、GitLab管理のTerraformステート管理バックエンドやDockerコンテナレジストリなどです。
• プロジェクトアクセストークンやグループアクセストークンと似ていますが、プロジェクトやグループではなく、ユーザーに紐付いています。

APIでパーソナルアクセストークンを使用して認証する方法の例については、APIドキュメントを参照してください。

または、GitLab管理者はAPIを使用して、代理トークンを作成できます。特定のユーザーとして認証を自動化するには、代行トークンを使用します。

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

パーソナルアクセストークンは必要な数だけ作成できます。

1. 左側のサイドバーで、自分のアバターを選択します。

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

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

4. 新しいトークンを追加を選択します。

5. トークン名に、トークンの名前を入力します。

6. オプション。トークンの説明に、トークンの説明を入力します。

7. 有効期限に、トークンの有効期限を入力します。

   • トークンは、その日付のUTC午前0時に期限切れになります。有効期限が2024-01-01のトークンは、2024-01-01の00:00:00 UTCに期限切れになります。
   • 有効期限を入力しない場合、有効期限は現在の日付より365日後に自動的に設定されます。
   • デフォルトでは、この日付は現在の日付より最大365日後に設定できます。GitLab 17.6以降では、この制限を400日に延長できます。

8. 必要なスコープを選択します。

9. Create personal access token（パーソナルアクセストークンを作成）を選択します。

パーソナルアクセストークンを安全な場所に保存します。ページを離れると、トークンにアクセスできなくなります。

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

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

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

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

トークンをローテーションすると、以前のバージョンを無効にしながら、新しいトークンが新しい認証情報で作成されます。ローテーションされたトークンは、元のトークンと同じ権限とスコープを維持します。古いトークンはすぐに非アクティブになり、両方のバージョンは監査証跡の目的でシステムに残ります。

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

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

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

トークンを失効すると、すぐに無効になり、認証または認可にそれ以上使用できなくなります。失効されたトークンは、トークンの履歴の監査証跡を維持するためにシステムに残ります。トークンを完全に削除することはできませんが、トークンリストをフィルタリングしてアクティブなトークンのみを表示できます。

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

1. 左側のサイドバーで、自分のアバターを選択します。

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

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

4. アクティブなトークンの横にある縦方向の省略記号（ ）を選択します。

5. 取り消し（ ）を選択します。

6. 確認ダイアログで、取り消しを選択します。

   これらのアクションは元に戻せません。取り消しまたはローテーションされたアクセストークンに依存するツールは動作しなくなります。

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

前提要件:

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

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アドレスは1分ごとに更新されます。GitLabは、次の場合にトークンが使用されたと見なします:

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

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

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

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

パーソナルアクセストークンは、割り当てられたスコープに基づいてアクションを実行できます。

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

パーソナルアクセストークンは、定義した日付のUTC午前0時00分に期限切れになります。有効期限が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. Service account token expiration（サービスアカウントトークンの有効期限）チェックボックスをオフにします。

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

GitLab Self-Managed

前提要件:

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

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 一般を選択します。
3. アカウントと制限を展開します。
4. Service account token expiration（サービスアカウントトークンの有効期限）チェックボックスをオフにします。

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

パーソナルアクセストークンで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は、次の条件を満たす必要があります:

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

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

トラブルシューティング

パーソナルアクセストークンの取り消しを解除する

何らかの方法でパーソナルアクセストークンが誤って取り消された場合、管理者はそのトークンの取り消しを解除できます。デフォルトでは、日次ジョブで午前1:00（システム時間）に、取り消されたトークンが削除されます。

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)

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

HTTPS経由のGitの場合、パーソナルアクセストークンの代替手段として、OAuth認証情報ヘルパーを使用することが可能です。

関連トピック

• グループアクセストークン
• プロジェクトアクセストークン
• パーソナルアクセストークンAPI