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

GitLab APIへのAPIコールの方法については、次の動画をご覧ください。
<!-- blank line -->
<figure class="video_container">
  <iframe src="https://www.youtube.com/embed/0LsMC3ZiXkA?si=vj871YH610jwQdFc" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->
### トークンの使用場所の確認
トークンの使用場所を確認する方法は以下のとおりです。
* **ユーザープロフィール > [アクセストークン](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#view-the-time-at-and-ips-where-a-token-was-last-used)**
* 認証情報インベントリ
* 監査イベント
* API経由
トークンの使用状況に関する情報は、**last_used**は10分ごと、**last_used_ip**は1分ごとに更新されます。
IPアドレスの確認機能はGitLab 17.9で追加され、**:pat_ip**機能フラグにより管理されます。[トークンの最終使用時間](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#view-the-time-at-and-ips-where-a-token-was-last-used)と、そのトークンが使われた最後の5つの異なるIPアドレスを表示する方法は以下のとおりです。
![トークン管理ガイド - パーソナルアクセストークンの設定](https://res.cloudinary.com/about-gitlab-com/image/upload/v1750097435/Blog/Content%20Images/Blog/Content%20Images/image1_aHR0cHM6_1750097434870.png)
## GitLab UIとAPIにおけるトークンの管理
以下の表には、UIにおけるトークン作成の詳細と、APIを介したトークンの使用方法を示すビデオが含まれています。
| トークン | GitLab UI | GitLab API | | ---------- | ---------- | ---------- | | パーソナルアクセストークン | [ドキュメント](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=3) | [ドキュメント](https://docs.gitlab.com/ee/api/personal_access_tokens.html)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=43) |
| グループアクセストークン | [ドキュメント](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html#group-access-tokens)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=120) | [ドキュメント](https://docs.gitlab.com/ee/api/group_access_tokens.html)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=157) |
| プロジェクトアクセストークン | [ドキュメント](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#project-access-tokens)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=254) | [ドキュメント](https://docs.gitlab.com/ee/api/project_access_tokens.html)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=285) |
## トークンのローテーションと有効期限の管理
トークンローテーションと厳格な有効期限管理を実施することで、セキュリティリスクを減らし、セキュリティ基準への準拠を確保できます。定期的なローテーションと有効期限の強制により、期限切れの認証情報がセキュリティの脆弱性となるのを防ぎます。
これまで、グループおよびプロジェクトのアクセストークンは、有効期限が切れると自動的に削除されていました。そのため、無効なトークンの記録が残らず、監査やセキュリティレビューを行う上で課題となっていました。この問題に対応するため、[最近のアップデート](https://gitlab.com/gitlab-org/gitlab/-/issues/462217)により、無効化されたグループおよびプロジェクトのアクセストークンの記録が、無効になってからUI上に30日間保持されるようになりました。これにより、トークンの使用状況や有効期限、取り消しの履歴を追跡しやすくなり、コンプライアンスやモニタリングの強化につながります。
トークンのローテーションと有効期限の管理をより積極的に行うには、次の手順を実行します。
* UIまたはAPIを介してトークンを積極的にローテーションする。APIを使用する場合は、[自動的にトークンの再利用を検知](https://docs.gitlab.com/ee/api/personal_access_tokens.html#automatic-reuse-detection)するセキュリティ機能に注意が必要です。
* インスタンス全体で、[アクセストークンの最大有効期間](https://docs.gitlab.com/ee/administration/settings/account_and_limit_settings.html#limit-the-lifetime-of-access-tokens)を制限する設定を導入。
### トークンローテーションAPI
GitLab 17.7までは、アクセストークンのローテーションはAPIを通じてプログラム上で行う必要がありましたが、現在はUI上でも実行可能になりました。操作方法は以下の表の動画または[ドキュメント](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#use-the-ui)をご確認ください。
### トークンローテーションスニペット
以下の表には、GitLabトークンのローテーションに関する動画のリンクをまとめています。
| トークン | 前提条件 | GitLab UI | GitLab API | | :---: | :---: | ----- | ----- | | パーソナルアクセストークン | スコープ：api  | [ドキュメント](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=76)  | [ドキュメント](https://docs.gitlab.com/ee/api/personal_access_tokens.html#rotate-a-personal-access-token) と[動画](https://youtu.be/v5Nj3Jy4vaI?t=92)  |
| グループアクセストークン | スコープ：apiと役割：オーナー | [ドキュメント](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html#create-a-group-access-token-using-ui)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=203)  | [ドキュメント](https://docs.gitlab.com/ee/api/group_access_tokens.html)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=214)  |
| プロジェクトアクセストークン | スコープ：apiと役割：オーナー、メンテナー | [ドキュメント](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=335)  | [ドキュメント](https://docs.gitlab.com/ee/api/project_access_tokens.html)と[動画](https://youtu.be/v5Nj3Jy4vaI?t=349)  |
## トークン管理のベストプラクティス
### 最小権限の原則
各トークンに割り当てる権限を、それぞれのタスクに必要な最小限に制限することで、リスクを軽減します。これにより、システム内の潜在的な障害箇所を事前に予測・対処しやすくなります。以下のような方法で、この原則を実践できます。
* それぞれのジョブに合った適切なトークンを選ぶ。フローチャートを参照。
* トークンの作成時に必要なスコープのみを割り当てる。たとえば、監査目的のようなジョブには読み取り専用のスコープを使用します。詳細は[ロール](https://docs.gitlab.com/ee/user/permissions.html#roles)を参照。
* 特別な理由がない限り、管理者権限を付与しない。
* インスタンス全体でのデフォルトのトークン[有効期限](https://docs.gitlab.com/ee/administration/settings/account_and_limit_settings.html#set-a-lifetime-1)を設定する。
* トークンの権限を定期的に確認・監査し、運用実態に合っているか見直す。
* タスク完了後は速やかにトークンを無効化する。
### サービスアカウント
[サービスアカウント](https://docs.gitlab.com/ee/user/profile/service_accounts.html)を使用することで、トークンを人間のユーザーではなく非人間エンティティに紐づけることができ、特定ユーザーへの依存を減らせます。自動化にトークンを使う場合、個人アカウントではなく、スコープを制限したサービスアカウントを作成することが推奨されます。サービスアカウントを使用する主なメリットは次のとおりです。
* CI/CDパイプラインでサービスアカウントのトークンを使うことで、ユーザーアカウントの変更による中断を防げる
* 個人アカウントに影響を与えずに、プログラム上でトークンのローテーション処理を自動化できる
* サービスアカウントによる操作のモニタリング・監査がより明確になる 
* [有効期限のない](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-service-account-personal-access-token-with-no-expiry-date)サービスアカウントを作成できる
* [ライセンスシート](https://docs.gitlab.com/user/profile/service_accounts/#create-a-service-account)を消費しない
GitLabでは、サービスアカウントとそのトークンの管理をより簡単にするために、[APIベースでの作成](https://docs.gitlab.com/ee/api/user_service_accounts.html#create-a-service-account-user)に対応する新しい[サービスアカウントUI](https://gitlab.com/groups/gitlab-org/-/epics/9965)の提供を予定しています。以下のデモでは、サービスアカウントをプログラム上で使用する方法を紹介しています。
<!-- blank line -->
<figure class="video_container">
  <iframe src="https://www.youtube.com/embed/oZvjg0SCsqY?si=cj-0LjfeonLGXv9u" frameborder="0" allowfullscreen="true"> </iframe>
</figure>
<!-- blank line -->
### 脆弱性ツール
GitLabに組み込まれたセキュリティツールを活用することで、トークンの使用に関連する脆弱性を特定し、リスクを軽減できます。最大限のカバレッジを得るには、各ツールを併用することを推奨します。
* [シークレット検出](https://docs.gitlab.com/ee/user/application_security/secret_detection/)：リポジトリ内にハードコードされたシークレット（APIトークン、パスワード、その他の機密情報）がないかをスキャンします。[検出されたシークレットの一覧](https://docs.gitlab.com/ee/user/application_security/secret_detection/detected_secrets.html)も確認可能です。
* [静的アプリケーションセキュリティテスト（SAST）](https://docs.gitlab.com/ee/user/application_security/sast/)：ソースコードに存在するセキュリティ上の脆弱性を分析し、[マージリクエスト内でUI上のレポートとして表示](https://docs.gitlab.com/ee/user/application_security/sast/#features)するなどの機能を提供します。
* [依存関係スキャン](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/)：プロジェクトで使用しているサードパーティライブラリに、トークンに関連する脆弱性が含まれていないかを確認します
### 監査ログとモニタリング
インスタンスまたはグループ単位で、監査ログとトークンの使用状況を定期的に確認することで、トークンの健全性を維持できます。
* [監査イベント](https://docs.gitlab.com/ee/user/compliance/audit_events.html)：GitLabの監査イベントログを有効にすると、トークンの作成、使用、削除、不審なAPIコール（ログ内の許可されていないパラメーターやレートリミッターの継続的なトリガーなど）を追跡できます。
* [IP許可リスト](https://docs.gitlab.com/ee/administration/reporting/ip_addr_restrictions.html#configure-ip-address-restrictions)：悪意のあるユーザーが複数のIPアドレスを使ってアクティビティを隠すことを防ぎます。
* [アラート](https://docs.gitlab.com/ee/operations/incident_management/alerts.html)：不審なアクティビティに対してアラートを設定できます（オンコールローテーションに関するページングのトリガーやインシデントの作成に活用可能）。
* [認証情報インベントリ](https://docs.gitlab.com/ee/administration/credentials_inventory.html)：利用可能なすべてのアクセストークンを完全に管理し、必要に応じて取り消すことができます。
* [通知](https://docs.gitlab.com/ee/user/profile/notifications.html)：グループ、プロジェクト、パーソナルの各種トークンについて、有効期限が近づいた際に送信される通知メールを積極的に処理します。お客様からのご要望に応え、この通知機能は従来の7日前に加え、30日前、60日前の通知にも対応しました。
* [Webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#create-a-webhook)：アクセストークンのWebhookをグループとプロジェクトに設定して、トークンの有効期限7日前の通知イベントを送信できるようになりました。この機能も最近、**:extended_expiry_webhook_execution_setting**機能 フラグ（デフォルトでは無効）によって、30日、60日前の通知送信に対応しました。
## 今後の展開
GitLabでは多くの種類のトークンを提供しており、今後はそれらを統合しつつ、トークンの有効期間や細かなスコープ設定、一貫した管理・運用に重点を置いた改善を進めていく[予定](https://gitlab.com/gitlab-org/gitlab/-/issues/502630)です。現在注力しているトークン関連の機能には、サービスアカウント用の完全なUI、認証情報インベントリへの追加認証情報タイプの対応、トークンおよびサービスアカウントの監査強化などが含まれます。
> トークン管理機能を体験するには、[GitLab Ultimateの無料トライアル](https://about.gitlab.com/ja-jp/free-trial/?hosted=saas)にぜひご登録ください。