GitLabにおけるトークン管理の究極ガイド

深夜2時、成長中のテック企業でエンジニアとして働いているあなたに、緊急の電話がかかってきました。重要なデプロイパイプラインが失敗し、チームはその原因を突き止めようと必死です。数時間後、1週間前に退職したエンジニアのパーソナルアクセストークンが失効していたことが判明します。そのトークンは複数の重要な自動化プロセスで使用されており、その影響でシステム全体が混乱状態に陥ってしまいました。これを防ぐためには、どのようにトークンを管理すべきなのでしょうか？

このガイドでは、トークンを適切に特定、管理、保護するためのエンドツーエンドのプロセスをご紹介します。このガイドは、プロジェクト内でのトークン管理を徹底したいGitLabの管理者、デベロッパー、セキュリティチームに向けて、トークンに関する詳しい文書を補う参考資料として活用いただけます。

このガイドでは、以下の内容を取り上げています。

ジョブに適したトークンの選び方
トークンの種類
自分が使用しているトークンの把握方法
- 認証情報インベントリ
GitLab UIおよびAPIでのトークン管理
トークンのローテーションと有効期限の管理
トークン管理のベストプラクティス
- サービスアカウント

ジョブに適したトークンの選び方

ユースケースに合ったトークンを選ぶことで、セキュリティと機能性の両面で最適な運用が可能になります。

トークンは、APIリクエストの認証、CI/CDパイプラインの自動化、サードパーティツールとの統合、デプロイやリポジトリの管理など、幅広い場面で活用できます。

トークン管理ガイド -
トークンのフローチャート

わかりやすさを重視し、この図では1人のユーザーがトークンを所有するシンプルなユースケースを例にしています。詳細については、インスタンスまたはトップレベルグループの各ネームスペース（ユーザー/グループ）におけるユーザーロールや権限に関するGitLabの文書をご参照ください。以下のようなユースケースが考えられます。

パーソナルアクセストークン（[PAT] (https://docs.gitlab.com/user/profile/personal_access_tokens/#personal-access-token-scopes)）：デベロッパーがユーザーの個人アクセスや権限を必要とする場合に使えるトークンです。このトークンは、ユーザーのステータスと権限に従って認証情報が管理されるため、ユーザーが特定のプロジェクトやグループへのアクセス権を失った場合や、アカウントが無効化された場合には、自動的にそのトークンも無効になります。

プロジェクト/グループアクセストークン（PrAT/GrAT）：特定のプロジェクトまたはグループ内でのリソースへのアクセスを制限する必要がある場合に適したトークンです。PrAT/GrATを持つユーザーは、割り当てられたスコープを通じてこれらのリソースにアクセスできるようになります。

トークンの種類

こちらは、GitLabトークンの種類と、それぞれのデフォルトのプレフィックスおよびユースケースの一覧です。詳細については、GitLabトークンの概要ページをご覧ください。

| トークン | プレフィックス | 説明 |

| :---: | :---: | :---: |

| パーソナルアクセストークン | glpat | ユーザー固有のデータにアクセス |

| OAuth 2.0トークン | gloas | OAuth2.0 認証プロトコルを使ったサードパーティアプリとの連携 |

| なりすましトークン | glpat | 他のユーザーの代わりに管理操作を実行 |

| プロジェクトアクセストークン | glpat | 特定のプロジェクトのデータにアクセス |

| グループアクセストークン | glpat | 特定のグループのデータにアクセス |

| デプロイトークン | gldt | ユーザー名とパスワードなしでプロジェクトのコンテナイメージをクローン、プッシュ、プル |

| デプロイキー | 該当なし | リポジトリへの読み取り専用または読み書きアクセスを許可 |

| Runner認証トークン | glrt | GitLab Runnerを認証 |

| CI/CDジョブトークン | glcbt | CI/CDプロセスを自動化 |

|トリガートークン| glptt | パイプラインを手動またはプログラムでトリガー |

| フィードトークン | glft | パッケージ/RSSフィードへのアクセス認証 |

| 受信メールトークン | glimt | 受信メールの処理 |

| Kubernetes向けGitLabエージェントトークン | glagent | GitLabGitLabエージェントを通じてKubernetesクラスターを管理 |

| SCIMトークン | glsoat | SCIMを利用したユーザー管理の統合 |

| 機能フラグクライアントトークン | glffct | プログラムで機能フラグを有効化 |

Webhookトークン	該当なし	WebhookのリクエストがGitLabから送信されたことを検証するための秘密トークン（ユーザーが設定）

トークンの確認方法

認証情報インベントリ

GitLab Ultimateでは、GitLab Self-Managedの管理者や、GitLab.com（バージョン17.5以降）における企業組織のトップレベルグループのオーナーが、自身のネームスペース内の認証情報を監視できます。

このインベントリでは、以下のようなトークン情報を確認できます。

トークンの種類
- GitLab.comで利用可能なトークン
- GitLab Self-Managedで利用可能なトークン
関連付けられたユーザーアカウント
トークンのスコープ、および作成日と有効期限
最終使用時のIPアドレス（GitLab 17.10時点）
上記のユーザー定義パラメータに基づくトークンのフィルタリング
トークンの取り消しおよびローテーションの機能

認証情報インベントリを適切に管理することで、権限が過剰なトークンの特定や、ローテーションが必要な認証情報の把握が可能になり、安全かつ効率的な運用が実現します。

認証情報インベントリAPI

UIの機能に加えて、新しい/group/:id/manageエンドポイントを通じて認証情報インベントリAPIをリリースするための開発が進行中です。このエンドポイントでアクセスできる認証情報は企業ユーザーに限定されており、企業組織のトップレベルグループのオーナーが利用可能です。将来のAPIコールの例は以下のとおりです。


curl --header "PRIVATE-TOKEN: <pat>"
"https://verified_domain.com/api/v4/groups/<group_id>/manage/personal_access_tokens"

GitLab API

GitLab APIを使用すると、組織内のトークンをプログラムで一覧表示および管理できます。主要な認証関連エンドポイントは、個人用、グループ用、CI/CDトークンなど、さまざまなトークンの種類をサポートしています。GitLab上で認証済みユーザーがアクセスできるすべてのプロジェクトを一覧表示する際のパーソナルアクセストークンの使用方法は次のとおりです。


curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects"

GitLab APIへのAPIコールの方法については、次の動画をご覧ください。

トークンの使用場所の確認

トークンの使用場所を確認する方法は以下のとおりです。

ユーザープロフィール > アクセストークン
認証情報インベントリ
監査イベント
API経由

トークンの使用状況に関する情報は、last_usedは10分ごと、last_used_ipは1分ごとに更新されます。

IPアドレスの確認機能はGitLab 17.9で追加され、:pat_ip機能フラグにより管理されます。トークンの最終使用時間と、そのトークンが使われた最後の5つの異なるIPアドレスを表示する方法は以下のとおりです。

トークン管理ガイド -
パーソナルアクセストークンの設定

GitLab UIとAPIにおけるトークンの管理

以下の表には、UIにおけるトークン作成の詳細と、APIを介したトークンの使用方法を示すビデオが含まれています。

| トークン | GitLab UI | GitLab API |

| ---------- | ---------- | ---------- |

| パーソナルアクセストークン | ドキュメントと動画 | ドキュメントと動画 |

| グループアクセストークン | ドキュメントと動画 | ドキュメントと動画 |

| プロジェクトアクセストークン | ドキュメントと動画 | ドキュメントと動画 |

トークンのローテーションと有効期限の管理

トークンローテーションと厳格な有効期限管理を実施することで、セキュリティリスクを減らし、セキュリティ基準への準拠を確保できます。定期的なローテーションと有効期限の強制により、期限切れの認証情報がセキュリティの脆弱性となるのを防ぎます。

これまで、グループおよびプロジェクトのアクセストークンは、有効期限が切れると自動的に削除されていました。そのため、無効なトークンの記録が残らず、監査やセキュリティレビューを行う上で課題となっていました。この問題に対応するため、最近のアップデートにより、無効化されたグループおよびプロジェクトのアクセストークンの記録が、無効になってからUI上に30日間保持されるようになりました。これにより、トークンの使用状況や有効期限、取り消しの履歴を追跡しやすくなり、コンプライアンスやモニタリングの強化につながります。

トークンのローテーションと有効期限の管理をより積極的に行うには、次の手順を実行します。

UIまたはAPIを介してトークンを積極的にローテーションする。APIを使用する場合は、自動的にトークンの再利用を検知するセキュリティ機能に注意が必要です。

インスタンス全体で、アクセストークンの最大有効期間を制限する設定を導入。

トークンローテーションAPI

GitLab 17.7までは、アクセストークンのローテーションはAPIを通じてプログラム上で行う必要がありましたが、現在はUI上でも実行可能になりました。操作方法は以下の表の動画またはドキュメントをご確認ください。

トークンローテーションスニペット

以下の表には、GitLabトークンのローテーションに関する動画のリンクをまとめています。

| :---: | :---: | ----- | ----- |

トークン管理のベストプラクティス

最小権限の原則

各トークンに割り当てる権限を、それぞれのタスクに必要な最小限に制限することで、リスクを軽減します。これにより、システム内の潜在的な障害箇所を事前に予測・対処しやすくなります。以下のような方法で、この原則を実践できます。

それぞれのジョブに合った適切なトークンを選ぶ。フローチャートを参照。

トークンの作成時に必要なスコープのみを割り当てる。たとえば、監査目的のようなジョブには読み取り専用のスコープを使用します。詳細はロールを参照。

特別な理由がない限り、管理者権限を付与しない。

インスタンス全体でのデフォルトのトークン有効期限を設定する。

トークンの権限を定期的に確認・監査し、運用実態に合っているか見直す。
タスク完了後は速やかにトークンを無効化する。

サービスアカウント

サービスアカウントを使用することで、トークンを人間のユーザーではなく非人間エンティティに紐づけることができ、特定ユーザーへの依存を減らせます。自動化にトークンを使う場合、個人アカウントではなく、スコープを制限したサービスアカウントを作成することが推奨されます。サービスアカウントを使用する主なメリットは次のとおりです。

CI/CDパイプラインでサービスアカウントのトークンを使うことで、ユーザーアカウントの変更による中断を防げる
個人アカウントに影響を与えずに、プログラム上でトークンのローテーション処理を自動化できる
サービスアカウントによる操作のモニタリング・監査がより明確になる

有効期限のないサービスアカウントを作成できる

ライセンスシートを消費しない

GitLabでは、サービスアカウントとそのトークンの管理をより簡単にするために、APIベースでの作成に対応する新しいサービスアカウントUIの提供を予定しています。以下のデモでは、サービスアカウントをプログラム上で使用する方法を紹介しています。

脆弱性ツール

GitLabに組み込まれたセキュリティツールを活用することで、トークンの使用に関連する脆弱性を特定し、リスクを軽減できます。最大限のカバレッジを得るには、各ツールを併用することを推奨します。

シークレット検出：リポジトリ内にハードコードされたシークレット（APIトークン、パスワード、その他の機密情報）がないかをスキャンします。検出されたシークレットの一覧も確認可能です。

静的アプリケーションセキュリティテスト（SAST）：ソースコードに存在するセキュリティ上の脆弱性を分析し、マージリクエスト内でUI上のレポートとして表示するなどの機能を提供します。

依存関係スキャン：プロジェクトで使用しているサードパーティライブラリに、トークンに関連する脆弱性が含まれていないかを確認します

監査ログとモニタリング

インスタンスまたはグループ単位で、監査ログとトークンの使用状況を定期的に確認することで、トークンの健全性を維持できます。

監査イベント：GitLabの監査イベントログを有効にすると、トークンの作成、使用、削除、不審なAPIコール（ログ内の許可されていないパラメーターやレートリミッターの継続的なトリガーなど）を追跡できます。

IP許可リスト：悪意のあるユーザーが複数のIPアドレスを使ってアクティビティを隠すことを防ぎます。

アラート：不審なアクティビティに対してアラートを設定できます（オンコールローテーションに関するページングのトリガーやインシデントの作成に活用可能）。

認証情報インベントリ：利用可能なすべてのアクセストークンを完全に管理し、必要に応じて取り消すことができます。

通知：グループ、プロジェクト、パーソナルの各種トークンについて、有効期限が近づいた際に送信される通知メールを積極的に処理します。お客様からのご要望に応え、この通知機能は従来の7日前に加え、30日前、60日前の通知にも対応しました。

Webhooks：アクセストークンのWebhookをグループとプロジェクトに設定して、トークンの有効期限7日前の通知イベントを送信できるようになりました。この機能も最近、:extended_expiry_webhook_execution_setting機能フラグ（デフォルトでは無効）によって、30日、60日前の通知送信に対応しました。

今後の展開

GitLabでは多くの種類のトークンを提供しており、今後はそれらを統合しつつ、トークンの有効期間や細かなスコープ設定、一貫した管理・運用に重点を置いた改善を進めていく予定です。現在注力しているトークン関連の機能には、サービスアカウント用の完全なUI、認証情報インベントリへの追加認証情報タイプの対応、トークンおよびサービスアカウントの監査強化などが含まれます。

トークン管理機能を体験するには、GitLab Ultimateの無料トライアルにぜひご登録ください。

GitLabにおけるトークン管理の究極ガイド

ジョブに適したトークンの選び方

トークンの種類