認証方法

このページでは、Container Registry で認証を行うようにサードパーティ クライアントを構成する方法について説明します。

Container Registry と統合されている Google Cloud サービスは、同じプロジェクト内のリポジトリにアクセスする権限を使って事前構成されています。これらのサービスに対する認証を構成する必要はありませんが、権限が適切に構成されていることを確認する必要があります。

始める前に

1. Container Registry API が有効になっていて、gcloud CLI がインストールされていることを確認します。手順については、サービスの有効化と無効化をご覧ください。

2. 認証に使用しているアカウントに Container Registry にアクセスするための権限があることを確認します。ユーザー アカウントではなく、サービス アカウントを使用することをおすすめします。

3. Docker をまだインストールしていなければ、インストールします。Docker は Cloud Shell に含まれています。

4. Docker がレジストリを操作するには特権アクセスが必要です。Linux や Windows では、Docker コマンドを実行するユーザーを Docker セキュリティ グループに追加します。Docker Desktop は、root ユーザーとして仮想マシンで実行されるため、この手順は MacOS では不要です。

   Linux

   Docker セキュリティ グループはdockerと呼ばれます。ユーザー名を追加するには、次のコマンドを実行します。

   sudo usermod -a -G docker ${USER}
   

   Windows

   Docker セキュリティ グループはdocker-usersと呼ばれます。管理者のコマンド プロンプトからユーザーを追加するには、次のコマンドを実行します。

   net localgroup docker-users DOMAIN\USERNAME /add
   

   ここでは

   • DOMAIN は Windows ドメインです。
   • USERNAME はユーザー名です。

   ログアウトして再度ログインすると、グループ メンバーシップの変更が反映されます。仮想マシンを使用している場合、メンバーシップの変更を有効にするために、仮想マシンの再起動が必要になることがあります。

   注: Docker セキュリティ グループには root ユーザーまたは管理者ユーザーと同等のアクセス権があります。Docker にアクセスする必要がある信頼できるユーザーのみを追加します。セキュリティへの影響の詳細については、Docker デーモンのセキュリティをご覧ください。

認証方法

Container Registry へのアクセスを必要とするサードパーティ クライアントを構成する必要があります。

使用できる認証方法は、次のとおりです。

gcloud 認証情報ヘルパー（推奨）

Docker で使用するための Container Registry 認証情報を gcloud で直接構成します。可能であればこの方法を使用して、プロジェクト リソースへの安全で短期間のアクセス権を付与します。このオプションでは、Docker バージョン 18.03 以降のみがサポートされます。

スタンドアロン認証情報ヘルパー

このオプションは、主に Google Cloud CLI がない場合に Docker で使用する認証情報を構成するためのものです。このオプションでは、Docker バージョン 18.03 以降のみがサポートされます。

アクセス トークン

アプリケーションのデフォルトの認証情報は、サービス アカウントが Google Cloud リソースへのアクセスに使用する短期間のアクセス トークンを提供します。認証情報ヘルパーとしての gcloud の使用を除いて、最も安全な方法です。

JSON キーファイル

サービス アカウントの認証情報として使用できるユーザー管理の鍵ペア。認証情報は有効期間が長いため、使用できるすべての認証方式の中で最も安全性の低い認証方式です。

可能であれば、アクセス トークンまたは別の利用可能な認証方法を使用して、アーティファクトへの不正アクセスのリスクを軽減します。 サービス アカウント キーが正しく管理されていない場合は、セキュリティ リスクが発生します。可能であれば、サービス アカウント キーよりも安全な代替手段を選択してください。サービス アカウント キーで認証する必要がある場合は、秘密鍵のセキュリティと、サービス アカウント キーを管理するためのベスト プラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービス アカウント キーを作成できない場合は、組織でサービス アカウント キーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。

警告: Docker 認証情報ヘルパーは、Docker 18.03 以降でのみサポートされています。以前のバージョンの Docker クライアントのバグにより、認証情報ヘルパーが構成されていると docker build が大幅に遅くなります。

一部のツールやワークフローでは、認証情報ヘルパーとして gcloud を使用するための適切なサポートがありません。別の方法を使用する場合は、セキュリティへの影響を十分に理解してください。

Docker 構成ファイル内の認証設定

Docker では、認証設定が構成ファイル config.json に保存されます。

• Linux: ~/.docker/config.json
• Windows: %USERPROFILE%\.docker\config.json

ファイルには、さまざまな認証方法に対応する別々のセクションがあります。

credHelpers

認証に Docker 認証情報ヘルパーを使用する場合、Container Registry では、認証ヘルパー設定がファイルの credHelpers セクションに保存されます。

auths

Docker を使用し、パスワードとしてトークンやサービス アカウント キーでログインする場合、Docker では、認証情報がファイルの auths セクションに保存されます。

credStore

認証情報ストアを構成して認証情報を管理する場合、認証情報ストアの設定は、ファイルの credStore セクションに記述されます。

Docker がレジストリに接続すると、まず、ホストに関連付けられている認証情報ヘルパーが確認されます。したがって、config.json の credHelpers セクションと auths セクションの両方に Container Registry の設定が含まれている場合、auths セクションの設定は無視されます。

gcloud 認証情報ヘルパー

可能であれば、この方法を使用することを強くおすすめします。この方法では、プロジェクト リソースに安全で短期間のアクセス権が付与されます。

gcloud CLI を使用して、Cloud Shell または Google Cloud CLI がインストールされている環境で認証を構成します。Cloud Shell には、Docker の最新バージョンが含まれています。

以下により認証を構成します。

1. Docker コマンドを実行するユーザーとして gcloud にログインします。

   • ユーザー認証情報により認証を構成するには、次のコマンドを実行します。

     gcloud auth login
     

   • サービス アカウントの認証情報で認証を構成するには、次のコマンドを実行します。

     gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
     

     ここでは

     • ACCOUNT は [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 形式のサービス アカウント名です。既存のサービス アカウントは、Google Cloud コンソールの [サービス アカウント] ページまたは gcloud iam service-accounts list コマンドを使用して表示できます。
     • KEY-FILE はサービス アカウント鍵ファイルです。鍵の作成については、Identity and Access Management（IAM）のドキュメントをご覧ください。
   注: サービス アカウント キーが正しく管理されていない場合は、セキュリティ リスクが発生します。可能であれば、サービス アカウント キーよりも安全な代替手段を選択してください。サービス アカウント キーで認証する必要がある場合は、秘密鍵のセキュリティと、サービス アカウント キーを管理するためのベスト プラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービス アカウント キーを作成できない場合は、組織でサービス アカウント キーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。

2. 次のコマンドを使用して Docker を構成します。

   gcloud auth configure-docker
   

   認証情報はユーザーのホーム ディレクトリに保存されます。

   • Linux: $HOME/.docker/config.json
   • Windows: %USERPROFILE%/.docker/config.json

注: 通常、sudo を使用して Linux で Docker コマンドを実行すると、Docker は $HOME/.docker/config.json ではなく /root/.docker/config.json で Container Registry 認証情報を検索します。Docker セキュリティ グループではなく docker コマンドで sudo を使用する場合、sudo gcloud auth configure-docker を使用して認証情報を構成します。

スタンドアロン認証情報ヘルパー

スタンドアロンの Docker 認証情報ヘルパーは、gcloud CLI が利用できないシステムで Container Registry で認証されるよう Docker を構成します。

認証ヘルパーは、Container Registry 認証情報を自動的に、または --token-source フラグで指定した場所からフェッチし、それらを Docker の構成ファイルに書き込みます。このように、Docker のコマンドライン ツール docker を使用して、Container Registry と直接対話できます。

以下により認証を構成します。

1. Docker コマンドを実行するユーザーとしてマシンにログインします。

2. docker-credential-gcr を GitHub リリースからダウンロードします。

   必要に応じて、curl コマンドライン ユーティリティを使用します。例:

   VERSION=2.1.23
   OS=linux  # or "darwin" for OSX, "windows" for Windows.
   ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.
   
   curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
   | tar xz docker-credential-gcr \
   && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
   

3. 次のコマンドを使用して Docker を構成します。

   docker-credential-gcr configure-docker
   

   認証情報はユーザーのホーム ディレクトリに保存されます。

   • Linux: $HOME/.docker/config.json
   • Windows: %USERPROFILE%/.docker/config.json

詳細については、GitHub のスタンドアロン Docker 認証情報ヘルパー ドキュメントをご覧ください。

注: 通常、sudo を使用して Linux で Docker コマンドを実行すると、Docker は $HOME/.docker/config.json ではなく /root/.docker/config.json で Container Registry 認証情報を検索します。Docker セキュリティ グループではなく docker コマンドで sudo を使用する場合、sudo docker-credential-gcr configure-docker を使用して認証情報を構成します。

Docker が Container Registry で認証するように構成されました。イメージの push と pull を行う場合は、権限が正しく構成されていることを確認してください。

アクセス トークン

有効時間の短い OAuth アクセス トークンを生成して、Container Registry で認証できます。トークンは 60 分間有効であるため、リクエストしてから 1 時間以内に Container Registry との接続に使用してください。

1. Container Registry とやり取りする新しいサービス アカウントを作成します。

   コンソール

   1. Google Cloud Console で [サービス アカウントの作成] ページに移動します。

      [サービス アカウントの作成] ページに移動

   2. 使用するプロジェクトを選択します。

   3. [サービス アカウント名] フィールドに名前を入力します。

   4. 省略可: [サービス アカウントの説明] フィールドに説明を入力します。

   5. [作成] をクリックします。

   6. [ロールを選択] フィールドをクリックします。[All roles] で、サービス アカウントに付与する権限に基づいて適切な Cloud Storage のロールを選択します。

   7. [完了] をクリックします。

   gcloud

   ローカルマシン上の Google Cloud CLI を使用するか、または Cloud Shell 内で以下のコマンドを実行できます。

   1. サービス アカウントを作成します。NAME をサービス アカウントの名前に置き換えます。

      gcloud iam service-accounts create NAME

   2. サービス アカウントにロールを付与します。PROJECT_ID はプロジェクト ID に、ROLE はサービス アカウントの適切な Cloud Storage のロールに置き換えます。このロールは、プロジェクト内のリポジトリ全体に適用されます。 ロールは後で変更でき、特定のリポジトリのサービス アカウントに対して別のロールを付与することもできます。

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

2. Container Registry とやり取りするサービス アカウントの鍵を取得します。

   注: サービス アカウント キーが正しく管理されていない場合は、セキュリティ リスクが発生します。可能であれば、サービス アカウント キーよりも安全な代替手段を選択してください。サービス アカウント キーで認証する必要がある場合は、秘密鍵のセキュリティと、サービス アカウント キーを管理するためのベスト プラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービス アカウント キーを作成できない場合は、組織でサービス アカウント キーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。

   コンソール

   1. Google Cloud コンソールで、[サービス アカウント] ページに移動します。

      [サービス アカウント] ページに移動

   2. 使用するサービス アカウントのメールアドレスをクリックします。

   3. [キー] をクリックします。

   4. [鍵を追加]、[新しい鍵を作成] の順にクリックします。

   5. [作成] をクリックします。キーが含まれている JSON ファイルがパソコンにダウンロードされます。

      このページの手順では、このキーファイルにファイル名 keyfile.json を使用します。

   6. [閉じる] をクリックします。

   gcloud

   ローカルマシン上の Google Cloud CLI を使用するか、または Cloud Shell 内で以下のコマンドを実行できます。

   このページの手順では、鍵ファイルにファイル名 keyfile.json を使用します。

   gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

3. 次のコマンドを実行して、サービス アカウントとして Google Cloud CLI にログインします。

   gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
   

   ここでは

   • ACCOUNT は [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 形式のサービス アカウント名です。
   • KEY-FILE はサービス アカウント鍵ファイルです。鍵の作成については、IAM のドキュメントをご覧ください。

4. サービス アカウントの権限が正しく構成されていることを確認します。Compute Engine サービス アカウントを使用している場合は、権限とアクセススコープの両方を正しく構成する必要があります。

5. サービス アカウントのアクセス トークンを取得します。トークンは有効期間が短いため、リクエストしてから 1 時間以内に Container Registry との接続に使用してください。

   次のコマンドを実行します。

   Linux

   gcloud auth print-access-token | docker login -u oauth2accesstoken \
       --password-stdin https://HOSTNAME
   

   Windows

   gcloud auth print-access-token |
       docker login -u oauth2accesstoken --password-stdin https://HOSTNAME
   

   ここで、HOSTNAME は gcr.io、us.gcr.io、eu.gcr.io、または asia.gcr.io です。

   注: gcr.io サブドメインでイメージを提供する Google Cloud サービスでは、認証が必要になる可能性があります。たとえば、Google Cloud Marketplace からイメージを pull するには、marketplace.gcr.io への認証が必要です。

これで Docker が Container Registry で認証されるようになりました。

JSON キーファイル

サービス アカウント キーとは、サービス アカウントの認証情報として使用できる有効期間が長い鍵ペアのことです。OAuth アクセス トークンとは異なり、サービス アカウント キーに有効期限はありません。

注: サービス アカウント キーが正しく管理されていない場合は、セキュリティ リスクが発生します。可能であれば、サービス アカウント キーよりも安全な代替手段を選択してください。サービス アカウント キーで認証する必要がある場合は、秘密鍵のセキュリティと、サービス アカウント キーを管理するためのベスト プラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービス アカウント キーを作成できない場合は、組織でサービス アカウント キーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。

サービス アカウントの有効な秘密鍵にアクセスできるユーザーは、サービス アカウントを介してリソースにアクセスできます。たとえば、Google Cloud で自動的に作成されたサービス アカウント（Container Registry サービス アカウントなど）の一部は、親プロジェクトに対して読み書きが許可される Editor 役割が付与されます。Compute Engine のデフォルトのサービス アカウントには、同じプロジェクトのストレージに対する読み取り専用アクセスが構成されます。

さらに、サービス アカウントに対するキーのアクセスのライフサイクル、つまりサービス アカウントがアクセスできるデータは、キーをダウンロードしたユーザーのライフサイクルとは無関係です。

コンテナ イメージへのアクセスを制限するには、次のガイドラインを使用します。

• Container Registry の操作にのみ使用される専用のサービス アカウントを作成します。
• サービス アカウントに必要な最小限のアクセス権に特定の役割を付与します。
• 認証情報管理のおすすめの方法に従います。

Container Registry リポジトリでのみ使用する新しいサービス アカウントとサービス アカウント キーを作成する手順は、次のとおりです。

1. Container Registry とやり取りする新しいサービス アカウントを作成します。

   コンソール

   1. Google Cloud Console で [サービス アカウントの作成] ページに移動します。

      [サービス アカウントの作成] ページに移動

   2. 使用するプロジェクトを選択します。

   3. [サービス アカウント名] フィールドに名前を入力します。

   4. 省略可: [サービス アカウントの説明] フィールドに説明を入力します。

   5. [作成] をクリックします。

   6. [ロールを選択] フィールドをクリックします。[すべてのロール] で、サービス アカウントに対して適切な Cloud Storage のロールを選択します。

   7. [完了] をクリックします。

   gcloud

   ローカルマシン上の Google Cloud CLI を使用するか、または Cloud Shell 内で以下のコマンドを実行できます。

   1. サービス アカウントを作成します。NAME をサービス アカウントの名前に置き換えます。

      gcloud iam service-accounts create NAME

   2. サービス アカウントにロールを付与します。PROJECT_ID はプロジェクト ID に、ROLE はサービス アカウントの適切な Cloud Storage のロールに置き換えます。

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

2. Container Registry とやり取りするサービス アカウントの鍵を取得します。

   コンソール

   1. Google Cloud コンソールで、[サービス アカウント] ページに移動します。

      [サービス アカウント] ページに移動

   2. 使用するサービス アカウントのメールアドレスをクリックします。

   3. [キー] をクリックします。

   4. [鍵を追加]、[新しい鍵を作成] の順にクリックします。

   5. [作成] をクリックします。キーが含まれている JSON ファイルがパソコンにダウンロードされます。

      このページの手順では、このキーファイルにファイル名 keyfile.json を使用します。

   6. [閉じる] をクリックします。

   gcloud

   ローカルマシン上の Google Cloud CLI を使用するか、または Cloud Shell 内で以下のコマンドを実行できます。

   このページの手順では、鍵ファイルにファイル名 keyfile.json を使用します。

   gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

3. サービス アカウントの権限が正しく構成されていることを確認します。Compute Engine サービス アカウントを使用している場合は、権限とアクセススコープの両方を正しく構成する必要があります。

4. サービス アカウント キーをパスワードとして使用して、Docker で認証します。

   Linux / macOS

   cat KEY-FILE | docker login -u _json_key --password-stdin \
   https://HOSTNAME
   

   Windows

   Get-Content KEY-FILE |
   docker login -u _json_key --password-stdin https://HOSTNAME
   

   以下を置き換えます。

   • KEY-FILE は、JSON 形式のサービス アカウント鍵ファイルの名前です。
   • HOSTNAME は gcr.io、us.gcr.io、eu.gcr.io、または asia.gcr.io です。
   Note: gcr.io サブドメインでイメージを提供する Google Cloud サービスでは、認証が必要になる可能性があります。たとえば、Google Cloud Marketplace からイメージを pull するには、marketplace.gcr.io への認証が必要です。

これで Docker が Container Registry で認証されるようになりました。