公開：2025年2月25日
2分で読めます
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トークンのローテーションに関する動画のリンクをまとめています。
| トークン | 前提条件 | GitLab UI | GitLab API |
|---|---|---|---|
| パーソナルアクセストークン | スコープ：api | ドキュメントと動画 | ドキュメント と動画 |
| グループアクセストークン | スコープ：apiと役割：オーナー | ドキュメントと動画 | ドキュメントと動画 |
| プロジェクトアクセストークン | スコープ：apiと役割：オーナー、メンテナー | ドキュメントと動画 | ドキュメントと動画 |
トークン管理のベストプラクティス
最小権限の原則
各トークンに割り当てる権限を、それぞれのタスクに必要な最小限に制限することで、リスクを軽減します。これにより、システム内の潜在的な障害箇所を事前に予測・対処しやすくなります。以下のような方法で、この原則を実践できます。
- それぞれのジョブに合った適切なトークンを選ぶ。フローチャートを参照。
- トークンの作成時に必要なスコープのみを割り当てる。たとえば、監査目的のようなジョブには読み取り専用のスコープを使用します。詳細はロールを参照。
- 特別な理由がない限り、管理者権限を付与しない。
- インスタンス全体でのデフォルトのトークン有効期限を設定する。
- トークンの権限を定期的に確認・監査し、運用実態に合っているか見直す。
- タスク完了後は速やかにトークンを無効化する。
サービスアカウント
サービスアカウントを使用することで、トークンを人間のユーザーではなく非人間エンティティに紐づけることができ、特定ユーザーへの依存を減らせます。自動化にトークンを使う場合、個人アカウントではなく、スコープを制限したサービスアカウントを作成することが推奨されます。サービスアカウントを使用する主なメリットは次のとおりです。
- 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の60日間無料トライアルにぜひご登録ください。