- パーソナルアクセストークン
- OAuth2 トークン
- なりすましトークン
- プロジェクトアクセストークン
- グループアクセストークン
- デプロイトークン
- デプロイキー
- ランナー登録トークン（非推奨）
- ランナー認証トークン
- CI/CDジョブトークン
- その他のトークン
- 利用可能なスコープ
- セキュリティに関する考慮事項
GitLab トークンの概要
この文書では、GitLabで使用されるトークンとその目的、そして該当する場合はセキュリティガイダンスを示します。
パーソナルアクセストークン
個人アクセストークンを作成して認証することができます：
- GitLab API.
- GitLab リポジトリ.
- GitLabレジストリ。
個人アクセストークンの範囲と有効期限を制限することができます。デフォルトでは、作成したユーザーの権限を継承します。
個人アクセストークン API を使用して、個人アクセストークンをローテーションするなどのアクションをプログラムで実行できます。
OAuth2 トークン
GitLabはOAuth2プロバイダとして、ユーザーに代わって他のサービスがGitLab APIにアクセスできるようにすることができます。
OAuth2トークンのスコープと有効期間を制限することができます。
なりすましトークン
なりすましトークンは、特別なタイプの個人アクセストークンです。特定のユーザーのために管理者のみが作成することができます。Impersonationトークンは、特定のユーザーとしてGitLab API、リポジトリ、GitLabレジストリで認証するアプリケーションやスクリプトを構築するのに役立ちます。
インパーソネーショントークンの範囲を制限したり、有効期限を設定したりすることができます。
プロジェクトアクセストークン
プロジェクトアクセストークンは、プロジェクトにスコープされます。個人アクセストークンと同様に、認証に使用することができます：
- GitLab API.
- GitLab リポジトリ.
- GitLabレジストリ。
プロジェクトアクセストークンの範囲と有効期限を制限することができます。プロジェクトアクセストークンを作成すると、GitLabはプロジェクト用のボットユーザーを作成します。プロジェクトのボットユーザーはサービスアカウントであり、ライセンスシートとしてカウントされません。
プロジェクトアクセストークン APIを使って、プロジェクトアクセストークンをローテーションするなどのアクションをプログラムで行うことができます。
グループアクセストークン
グループアクセストークンはグループにスコープされます。個人アクセストークンと同様に、認証に使用できます：
- GitLab API.
- GitLab リポジトリ.
- GitLabレジストリ。
グループアクセストークンの範囲と有効期限を制限することができます。グループアクセストークンを作成すると、GitLabはグループ用のボットユーザーを作成します。グループ用ボットユーザーはサービスアカウントであり、ライセンスシートとしてカウントされません。
グループアクセストークンAPIを使って、グループアクセストークンをローテーションするなどのアクションをプログラムで行うことができます。
デプロイトークン
デプロイトークンは、プロジェクトのパッケージやコンテナレジストリイメージを、ユーザーとパスワードなしでダウンロード(git clone)またはプッシュ＆プルできるようにします。デプロイトークンは GitLab API では使用できません。
デプロイトークンはプロジェクトのメンテナーとオーナーが管理できます。
デプロイキー
デプロイキーは、SSH公開キーをGitLabインスタンスにインポートすることで、リポジトリへの読み取り専用または読み取り/書き込みアクセスを可能にします。デプロイキーはGitLab APIやレジストリでは使用できません。
これは例えば、継続的インテグレーション(CI) サーバにリポジトリをクローンするのに便利です。デプロイキーを使うことで、偽のユーザーアカウントを設定する必要はありません。
プロジェクトのメンテナーとオーナーは、プロジェクトリポジトリのデプロイキーを追加したり有効にしたりできます。
ランナー登録トークン（非推奨）
ランナー登録トークンは、GitLabにランナーを 登録するために使用されます。グループやプロジェクトのオーナー、インスタンスの管理者は、GitLabのユーザーインターフェイスから取得することができます。登録トークンはランナー登録に限定され、それ以上のスコープはありません。
ランナー登録トークンを使って、プロジェクトやグループでジョブを実行するランナーを追加することができます。Runner はプロジェクトのコードにアクセスできるので、プロジェクトやグループレベルの権限を割り当てるときには注意しましょう。
ランナー認証トークン
いったん作成されると、ランナーはランナー認証トークンを受け取り、ジョブキューからジョブをピックアップするときに GitLab と認証するために使用します。ランナー認証トークンは、ランナーのconfig.toml ファイルに内部保存されます。
GitLab での認証が終わると、Runner はジョブの実行に使うジョブトークンを受け取ります。
Docker Machine/Kubernetes/VirtualBox/Parallels/SSH Executorの場合、実行環境はランナー認証トークンにアクセスできません。実行環境はジョブの実行に必要なジョブトークンのみにアクセスできます。
ランナーのファイルシステムへの悪意のあるアクセスにより、config.toml ファイルとランナー認証トークンが公開され、攻撃者がランナーのクローンを作成できる可能性があります。
GitLab 16.0以降では、登録トークンの代わりに認証トークンを使ってランナーを登録することができます。ランナー登録トークンは非推奨となりました。
ランナー認証トークンを生成するには、GitLab UIでランナーを作成し、登録トークンの代わりに認証トークンを使用します。
| プロセス | 登録コマンド |
|---|---|
| 登録トークン（非推奨） | gitlab-runner register --registration-token $RUNNER_REGISTRATION_TOKEN <runner configuration arguments> |
| 認証トークン | gitlab-runner register --token $RUNNER_AUTHENTICATION_TOKEN |
CI/CDジョブトークン
CI/CDジョブトークンは、ジョブの間だけ有効な短期間のトークンです。CI/CDジョブが限られたAPIエンドポイントにアクセスできるようになります。API認証は、ジョブをトリガーするユーザーの作成者を使用することで、ジョブトークンを使用します。
ジョブトークンはその短い寿命と限られた範囲によってセキュリティが確保されています。複数のジョブが同じマシン上で実行された場合、（Shell Runnerのように）漏えいする可能性があります。Docker Machineランナーでは、MaxBuilds=1 を設定して、Runnerマシンが一度だけビルドを実行し、その後破棄されるようにすることを推奨します。マシンのプロビジョニングには時間がかかるため、パフォーマンスに影響する可能性があります。
その他のトークン
フィードトークン
各ユーザーは、期限切れのないフィードトークンを持っています。このトークンによって、次のような認証が可能となります：
- RSSリーダーによるパーソナライズされたRSSフィードの読み込み。
- パーソナライズされたカレンダーを読み込むカレンダーアプリケーション。
このトークンを使用して他のデータにアクセスすることはできません。
ユーザが設定したフィードトークンはすべてのフィードで使用できますが、 フィードや Calendar の URL は別のトークンで生成されます。
トークンを持っている人は、アクティビティやイシューのRSSフィードやカレンダーフィードを、あたかも自分であるかのように読むことができます。そのような場合は、トークンをリセットしてください。
受信メールトークン
各ユーザーは、有効期限のない受信メール・トークンを持っています。このトークンを使用すると、ユーザーは電子メールで新しいイシューを作成することができ、ユーザー個人のプロジェクト固有の電子メールアドレスに含まれます。このトークンを使用して他のデータにアクセストークンすることはできません。あなたのトークンを持っている人は、あたかもあなたであるかのようにイシューやマージリクエストを作成することができます。そのような場合は、トークンをリセットしてください。
利用可能なスコープ
この表は、トークンごとに利用可能なスコープを示しています。トークン作成時にスコープをさらに制限することができます。
| APIアクセス | レジストリへのアクセス | リポジトリへのアクセス | |
|---|---|---|---|
| 個人アクセストークン | ✅ | ✅ | ✅ |
| OAuth2 トークン | ✅ | 🚫 | ✅ |
| なりすましトークン | ✅ | ✅ | ✅ |
| プロジェクトアクセストークン | ✅(1) | ✅(1) | ✅(1) |
| グループアクセストークン | ✅(2) | ✅(2) | ✅(2) |
| デプロイトークン | 🚫 | ✅ | ✅ |
| デプロイキー | 🚫 | 🚫 | ✅ |
| ランナー登録トークン | 🚫 | 🚫 | ✴️(3) |
| ランナー認証トークン | 🚫 | 🚫 | ✴️(3) |
| ジョブ・トークン | ✴️(4) | 🚫 | ✅ |
- つのプロジェクトに限定。
- つのグループに限定。
- ランナーの登録と認証トークンはリポジトリへの直接アクセスを提供しませんが、リポジトリにアクセスできるジョブを実行する新しいランナーの登録と認証に使用できます。
- 特定のエンドポイントに限定されます。
セキュリティに関する考慮事項
- アクセストークンをパスワードのように扱い、安全に保管してください。
- スコープ付きトークンを作成する場合は、トークンが誤って漏えいした場合の影響を軽減するために、可能な限り限定的なスコープを使用することを検討してください。
- トークンを作成するときは、タスクが完了したときに失効するトークンを設定することを検討してください。たとえば、1 回限りのインポートを行う場合は、数時間後または 1 日後にトークンが失効するように設定します。こうすることで、有効期限が切れたトークンは使えなくなるため、トークンが誤って流出した場合の影響を減らすことができます。
- 取り組んでいるプロジェクトを紹介するためにデモ環境をセットアップし、そのプロジェクトについてビデオを録画したり、ブログ記事を書いたりしている場合、そのプロセス中に機密シークレット（たとえば、パーソナルアクセストークン(PAT)、フィードトークン、トリガートークンなど）が漏れないように注意してください。デモが終了したら、デモ中に作成したシークレットをすべて破棄しなければなりません。詳細はPAT の破棄 を参照ください。
- URLにアクセストークンを追加することはセキュリティリスクとなります。特に、リモートのクローンやリモートの追加を行う際には、GitがURLを
.git/configファイルにプレーンテキストで書き込んでしまうからです。また、URL は一般的にプロキシやアプリケーションサーバーによってログに記録されるため、システム管理者がその認証情報を見ることになります。その代わりに、APIコールでアクセストークンを渡すにはPrivate-Tokenヘッダのようなヘッダを使います。 - Git のクレデンシャル・ストレージを使ってトークンを保存することもできます。
- To-Do：
- トークンをプレーンテキストでプロジェクトに保存すること。
- コード、コンソールコマンド、ログ出力をイシュー、MRの説明、コメントに貼り付ける際にトークンを含めます。CI で外部シークレットを使用するなどのアプローチを検討してください。
- コンソールログやアーティファクトに認証情報を記録しないでください。認証情報の保護と マスキングを検討してください。
- すべてのタイプのアクティブなアクセストークンを定期的にレビューし、不要になったアクセストークンを失効させます。これには以下が含まれます：
- 個人、プロジェクト、グループのアクセストークン。
- フィードトークン。
- トリガートークン。
- ランナー登録トークン。
- その他のシークレットなど