GitLabトークンの概要

このドキュメントでは、GitLabで使用されるトークン、その目的、および該当する場合のセキュリティガイダンスについて説明します。

セキュリティに関する考慮事項

トークンを安全に保つために、次の点に注意してください。

• トークンはパスワードと同様に扱い、安全に保管してください。
• スコープ付きトークンを作成する場合は、誤って漏洩した場合の影響を軽減するため、可能な限り最も制限されたスコープを使用してください。
  • 個別のプロセスで異なるスコープ（たとえば、readとwrite）が必要な場合は、スコープごとに個別のトークンを使用することを検討してください。1つのトークンが漏洩した場合、完全なAPIアクセスのような広範なスコープを持つ単一のトークンよりもアクセス権限が少なくなります。
• トークンを作成する際は、次のようにします。
  • 以下のトークンの命名規則に従って名前を選択します。
  • タスク完了時に期限切れになるトークンの設定を検討してください。たとえば、1回限りのインポートを実行する必要がある場合は、数時間後にトークンの有効期限が切れるように設定します。
  • 関連するURLを含む、さらに詳しいコンテキストを提供する説明を追加します。
• URLの代わりにヘッダーでトークンを渡します:
  • 個人、プロジェクトアクセストークン、およびグループアクセストークンにはPRIVATE-TOKENを使用します。
  • ジョブトークンにはJOB-TOKENを使用します。
• デモ環境をお持ちの場合は、ビデオを録画したり、プロジェクトに関するブログ記事を公開したりした後、すべてのトークンを失効してください。
• トークンはGit認証情報ストレージを使用して保存できます。
• すべての種類のアクティブなアクセストークンを定期的に確認し、不要なものはすべて失効させてください。

禁止事項:

• URLにトークンを追加します:
  • トークンを含むURLでクローンを作成したりリモートを追加したりすると、GitはそのURLをプレーンテキストで.git/configファイルに書き込みます。
  • URLはプロキシやアプリケーションサーバーによってログに記録されることが多く、これらの認証情報がシステム管理者に漏洩する可能性があります。
• プロジェクト内でトークンをプレーンテキストで保存しないでください。
  • トークンがGitLab CI/CD用の外部シークレットである場合は、CI/CDで外部シークレットを使用する方法を確認してください。
• イシュー、MRの説明、コメント、またはその他のフリーテキスト入力欄に、コード、コンソールコマンド、ログ出力を貼り付ける際に、トークンを含めないでください。
• 認証情報をコンソールログやアーティファクトに記録しないでください。認証情報の保護とマスキングを検討してください。

トークンの命名規則

一貫した命名規則により、アクセストークンの監査、その目的の理解、および各トークンのローテーションまたは失効による影響の評価が容易になります。

命名規則はチームによって異なりますが、有用な規則は次の質問に答えます:

• トークンはどのようなアクションを実行しますか？例: ci-deploy、api-read。
• トークンはどのリソースまたはサービスに対して動作しますか？例: gitlab、terraform。
• トークンはどの環境またはオーナーに関連付けられていますか？例: production、auth-team。

例:

• 具体的にします。test、mytoken、token1、GITLAB_API_TOKEN、API_TOKEN、defaultのような一般的な名前は避けてください。これらでは、監査中にトークンの目的を特定することができません。
• 使用するシステムまたはツールを含めます。特定のアプリケーション、スクリプト、またはインテグレーションでトークンが使用される場合は、その名前を含めます。例: terraform-state-backendまたはgrafana-metrics-reader。
• 環境を含めます。該当する場合は、トークンがproduction、staging、developmentのいずれを対象とするかを示します。これにより、より低い環境で本番環境トークンが誤って使用されることを防ぎます。
• 機密情報の埋め込みは避けてください。トークン名は監査ログとUIに表示されるため、ユーザー名、メールアドレス、またはその他の個人を特定できる情報（PII）をトークン名に含めないでください。
• 大文字と小文字の規則および句読点規則を標準化して設定します。一貫した大文字と小文字の使用および区切り文字により、トークンの読み取りと検索が容易になります。例として、アンダースコア（_）よりもハイフン（-）を使用します。
• 説明フィールドを使用します。トークンの説明フィールドを使用すると、関連するイシューへのリンクや、トークンを使用するチームの名前などの追加の詳細を追加できます。

CI/CDのトークン

パーソナルアクセストークンはスコープが広いため、可能な限りCI/CD変数として使用することは避けてください。CI/CDジョブから他のリソースへのアクセスが必要な場合は、次のいずれかを使用します（アクセススコープの狭い順）。

1. ジョブトークン（最もアクセススコープが狭い）
2. プロジェクトトークン
3. グループトークン

CI/CD変数のセキュリティに関する追加の推奨事項:

• すべての認証情報にシークレットストレージを使用してください。
• 機密情報を含むCI/CD変数は、保護とマスキングを行い、非表示にする必要があります。

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

パーソナルアクセストークンを作成し、以下の認証に使用できます。

• GitLab API。
• GitLabリポジトリ。
• GitLabレジストリ。

パーソナルアクセストークンのスコープを制限し、有効期限を設定できます。デフォルトでは、パーソナルアクセストークンは、トークンを作成したユーザーの権限を継承します。

パーソナルアクセストークンAPIを使用して、パーソナルアクセストークンのローテーションなどの操作をプログラムで実行できます。

パーソナルアクセストークンの有効期限が近づくと、メールが届きます。

トークンによる権限を必要とするCI/CDジョブを検討する際は、特にCI/CD変数として保存する場合、パーソナルアクセストークンの使用は避けてください。CI/CDジョブトークンやプロジェクトアクセストークンを使用すると、リスクを大幅に軽減しながら同様の結果が得られることがよくあります。

OAuth 2.0トークン

GitLabはOAuth 2.0プロバイダーとして機能し、他のサービスがユーザーに代わってGitLab APIにアクセスすることを許可できます。

OAuth 2.0トークンのスコープを制限し、ライフタイムを設定できます。

代理トークン

代理トークンは特殊なパーソナルアクセストークンで、特定のユーザーに対して、管理者のみが作成できます。代理トークンは、特定のユーザーとしてGitLab API、リポジトリ、GitLabレジストリに対して認証するアプリケーションやスクリプトを構築するのに役立ちます。

代理トークンのスコープを制限し、有効期限を設定できます。

プロジェクトアクセストークン

プロジェクトアクセストークンは、プロジェクトにスコープが限定されます。パーソナルアクセストークンと同様に、以下の認証に使用できます。

• GitLab API。
• GitLabリポジトリ。
• GitLabレジストリ。

プロジェクトアクセストークンのスコープを設定し、有効期限を設定できます。プロジェクトアクセストークンを作成すると、GitLabはプロジェクトのボットユーザーを作成します。プロジェクトのボットユーザーはサービスアカウントであり、ライセンスされたシートとしてはカウントされません。

プロジェクトアクセストークンAPIを使用して、プロジェクトアクセストークンのローテーションなどの操作をプログラムで実行できます。

メンテナーまたはオーナーロールを持つプロジェクトのメンバーは、プロジェクトアクセストークンの期限が近づくとメールを受信します。

グループアクセストークン

グループアクセストークンは、グループにスコープが限定されます。パーソナルアクセストークンと同様に、以下の認証に使用できます。

• GitLab API。
• GitLabリポジトリ。
• GitLabレジストリ。

グループアクセストークンのスコープを設定し、有効期限を設定できます。グループアクセストークンを作成すると、GitLabはグループのボットユーザーを作成します。グループのボットユーザーはサービスアカウントであり、ライセンスされたシートとしてはカウントされません。

グループアクセストークンAPIを使用して、グループアクセストークンのローテーションなどの操作をプログラムで実行できます。

グループアクセストークンの有効期限が近づくと、オーナーロールを持つグループのメンバーにメールが届きます。

デプロイトークン

デプロイトークンを使用すると、ユーザーとパスワードなしで、プロジェクトのパッケージとコンテナレジストリイメージをクローン、プッシュ、プルできます。デプロイトークンはGitLab APIでは使用できません。

デプロイトークンを管理するには、少なくともメンテナーロールを持つプロジェクトのメンバーである必要があります。

デプロイキー

デプロイキーを使用すると、SSH公開キーをGitLabインスタンスにインポートすることで、リポジトリへの読み取り専用または読み取り/書き込みアクセスが可能になります。デプロイキーはGitLab APIまたはレジストリでは使用できません。

デプロイキーを使用することで、仮のユーザーアカウントを設定せずに、リポジトリを継続的インテグレーションサーバーにクローンできます。

プロジェクトのデプロイキーを追加または有効にするには、少なくともメンテナーロールが必要です。

Runner認証トークン

GitLab 16.0以降では、Runnerを登録する際に、Runner登録トークンの代わりにRunner認証トークンを使用できます。Runner登録トークンは非推奨となっています。

Runnerとその設定を作成すると、Runnerの登録に使用するRunner認証トークンが付与されます。Runner認証トークンはローカルのconfig.tomlファイルに保存されます。このファイルを使用してRunnerを設定します。

Runnerは、ジョブキューからジョブを取得する際に、Runner認証トークンを使用してGitLabに対して認証します。RunnerがGitLabで認証されると、Runnerはジョブトークンを受け取り、これを使用してジョブを実行します。

Runner認証トークンはRunnerのマシン上に留まります。次のexecutorの実行環境は、ジョブトークンのみにアクセスでき、Runner認証トークンにはアクセスできません。

• Docker Machine
• Kubernetes
• VirtualBox
• Parallels
• SSH

Runnerのファイルシステムへの悪意のあるアクセスにより、config.tomlファイルやRunner認証トークンが漏洩するおそれがあります。攻撃者はそのRunner認証トークンを使用して、Runnerのクローンを作成する可能性があります。

Runners APIを使用して、Runner認証トークンをローテーションまたは失効させることができます。

Runner登録トークン（レガシー）

Runner登録トークンは、RunnerをGitLabに登録するために使用します。グループまたはプロジェクトのオーナー、またはインスタンス管理者は、GitLabのユーザーインターフェースを通じてトークンを取得できます。登録トークンはRunnerの登録に限定されており、それ以上のスコープはありません。

このRunner登録トークンを使用して、プロジェクトまたはグループでジョブを実行するRunnerを追加できます。Runnerはプロジェクトのコードにアクセスできるため、プロジェクトまたはグループへの権限を割り当てる際は注意してください。

CI/CDジョブトークン

CI/CDジョブトークンは、ジョブの実行期間のみ有効な短期間のトークンです。これにより、CI/CDジョブは限られた数のAPIエンドポイントにアクセスできます。API認証では、ジョブをトリガーしたユーザーの権限を使用してジョブトークンを使用します。

ジョブトークンは、そのライフタイムの短さとスコープの制限によって、セキュリティが確保されています。同じマシン上で複数のジョブを実行している（たとえば、Shell Runnerを使用している）場合、このトークンが漏洩する可能性があります。ジョブトークンがアクセスできるものをさらに制限するために、プロジェクト許可リストを使用できます。

Docker Machine Runnerでは、MaxBuilds=1を設定する必要があります。これにより、Runnerマシンは1つのビルドのみを実行し、その後削除されるようになります。プロビジョニングには時間がかかるため、この設定はパフォーマンスに影響を与える可能性があります。

GitLabクラスターエージェントトークン

Kubernetes向けGitLabエージェントを登録すると、GitLabはそのクラスターエージェントがGitLabに対して認証するためのアクセストークンを生成します。

このクラスターエージェントトークンを失効させるには、次のいずれかを実行します。

• エージェントAPIでトークンを失効させる。
• トークンをリセットする。

どちらの方法でも、トークン、エージェント、およびプロジェクトIDを知っている必要があります。この情報を確認するには、Railsコンソールを使用します。

# Find token ID
Clusters::AgentToken.find_by_token('glagent-xxx').id

# Find agent ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.id
=> 1234

# Find project ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.project_id
=> 12345

Railsコンソールでトークンを直接失効させることもできます。

# Revoke token with RevokeService, including generating an audit event
Clusters::AgentTokens::RevokeService.new(token: Clusters::AgentToken.find_by_token('glagent-xxx'), current_user: User.find_by_username('admin-user')).execute

# Revoke token manually, which does not generate an audit event
Clusters::AgentToken.find_by_token('glagent-xxx').revoke!

その他のトークン

フィードトークン

各ユーザーには、有効期限のない長期間有効なフィードトークンが付与されています。このトークンは以下の認証に使用できます。

• パーソナライズされたRSSフィードを読み込むためのRSSリーダー。
• パーソナライズされたカレンダーを読み込むためのカレンダーアプリケーション。

このトークンを使用して他のデータにアクセスすることはできません。

ユーザースコープのフィードトークンは、すべてのフィードに使用できます。ただし、フィードやカレンダーのURLは、それぞれ1つのフィードのみに有効な別のトークンを使用して生成されます。

トークンを持っている人であれば誰でも本人になりすまして、機密性の高いイシューを含むフィードのアクティビティを閲覧できます。トークンが漏洩したと思われる場合は、すぐにトークンをリセットしてください。

フィードトークンを無効にする

前提条件:

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

1. 右上隅で、管理者を選択します。
2. 左側のサイドバーで、設定 > 一般を選択します。
3. 表示レベルとアクセス制御を展開します。
4. フィードトークンで、フィードトークンを無効にするチェックボックスをオンにし、変更を保存を選択します。

受信メールトークン

各ユーザーには、有効期限のない受信メールトークンが付与されています。このトークンは、パーソナルプロジェクトに関連付けられたメールアドレスに含まれており、メールで新しいイシューを作成する際に使用します。

このトークンを使用して他のデータにアクセスすることはできません。トークンを持っている人は誰でも、本人になりすましてイシューとマージリクエストを作成できます。トークンが漏洩したと思われる場合は、すぐにトークンをリセットしてください。

ワークスペーストークン

各workspace（ワークスペース）には、期限切れにならない、内部で自動的に管理されるトークンがあります。これにより、ワークスペースとのHTTPおよびSSH通信が可能になります。これは、ワークスペースが実行中（実行中）状態になるようにリクエストされた場合に存在し、ワークスペースによって自動的に挿入および使用されます。

停止したワークスペースを起動すると、新しいワークスペーストークンが作成されます。実行中のワークスペースを再起動すると、既存のトークンが削除され、新しいトークンが作成されます。

この内部トークンを直接表示または管理することはできません。このトークンを使用して他のデータにアクセスすることはできません。

ワークスペーストークンを失効するには、stop（停止）またはterminate（終了）ワークスペースします。トークンはすぐに削除されます。

使用可能なスコープ

この表は、トークンごとのデフォルトのスコープを示しています。一部のトークンでは、トークンの作成時にスコープをさらに制限できます。

補足説明:

1. 1つのプロジェクトに限定されます。
2. 1つのグループに限定されます。
3. Runner登録およびRunner認証トークンには、リポジトリへの直接アクセス権はありませんが、リポジトリにアクセスできるジョブを実行する新しいRunnerを登録および認証するために使用できます。
4. 特定のエンドポイントのみ。

トークンのプレフィックス

次のテーブルは、トークンの種類ごとのプレフィックスを示しています。パーソナルアクセストークンを除き、これらのプレフィックスは標準識別となるように設計されているため、設定できません。