GitLabトークンの概要

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

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

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

• トークンはパスワードと同様に扱い、安全に保管してください。
• スコープ付きトークンを作成する場合は、誤って漏洩した場合の影響を軽減するため、可能な限り最も制限されたスコープを使用してください。
  • 個別のプロセスで異なるスコープ（たとえば、readとwrite）が必要な場合は、それぞれのスコープに対応した個別のトークンを使用することを検討してください。そうすれば、1つのトークンが漏洩しても、APIへのフルアクセスのような広いスコープを持つ1つのトークンが漏洩した場合よりもアクセス権が制限されます。
• トークンを作成する際は、次のようにします:
  • GITLAB_API_TOKEN-application1やGITLAB_READ_API_TOKEN-application2のように、トークンを説明する名前を選択してください。GITLAB_API_TOKEN、API_TOKEN、defaultのような一般的な名前は避けてください。
  • タスク完了時に期限切れになるトークンの設定を検討してください。たとえば、1回限りのインポートを実行する必要がある場合は、数時間後にトークンの有効期限が切れるように設定します。
  • 関連するURLを含む、さらに詳しいコンテキストを提供する説明を追加します。
• 作業中のプロジェクトを紹介するためにデモ環境をセットアップし、そのプロジェクトを説明するビデオを録画したりブログ記事を作成したりする場合は、シークレットを誤って漏洩しないように注意してください。デモが終了したら、デモ中に作成したすべてのシークレットを失効させてください。
• URLにトークンを追加すると、セキュリティ上のリスクが生じる可能性があります。代わりに、Private-Tokenのようなヘッダーを使用してトークンを渡します。
  • トークンを含むURLでクローンを作成したりリモートを追加したりすると、GitはそのURLをプレーンテキストで.git/configファイルに書き込みます。
  • URLはプロキシやアプリケーションサーバーによってログに記録されることが多く、これらの認証情報がシステム管理者に漏洩する可能性があります。
• トークンはGit認証情報ストレージを使用して保存できます。
• すべての種類のアクティブなアクセストークンを定期的に確認し、不要なものはすべて失効させてください。

禁止事項:

• プロジェクト内でトークンをプレーンテキストで保存しないでください。トークンがGitLab CI/CD用の外部シークレットである場合は、CI/CDでの外部シークレットの使用方法に関する推奨事項を確認してください。
• イシュー、MRの説明、コメント、またはその他のフリーテキスト入力欄に、コード、コンソールコマンド、ログ出力を貼り付ける際に、トークンを含めないでください。
• 認証情報をコンソールログやアーティファクトに記録しないでください。認証情報の保護とマスキングを検討してください。

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（終了）ワークスペースします。トークンはすぐに削除されます。

使用可能なスコープ

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

Footnotes（脚注）:

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

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

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