docker loginによるコンテナレジストリログインの課題

Docker Clientから各種コンテナレジストリに認証するときは、通常docker loginコマンドを利用します。しかし、以下の課題があります。この記事ではこの課題に対応するDocker Credential Helperを紹介します。

ログインコマンドが複雑
認証トークンがローカルに保存される

一つ目はわかりやすいポイントです。例えばECRなら、以下のようにAWS CLIでDocker Client用の認証トークンを発行してログインしますが、見ての通りパラメータも長く、複雑です。

aws ecr get-login-password --region ap-northeast-1 | docker login --username AWS --password-stdin XXXXX.dkr.ecr.ap-northeast-1.amazonaws.com

一方後者は内部的なので、通常使う分には気づきづらいポイントです。aws ecr get-login-passwordコマンドで発行されたトークンをdocker loginコマンドで受け取ります。このトークンは下記のように~/.docker/config.jsonに記述されます。しかし、認証トークンは以下のように平文で記載されます(authsの部分)。

ECRの認証トークン長は非常に長く、流出リスクは比較的低いと考えられます。とはいえ、12時間利用できるトークンを平文で保存しておくのはセキュリティ上避けたいです。

{
    "auths": {
        "111111111111.dkr.ecr.region.amazonaws.com": {
            "auth": "SOME_VERY_LONG_TOKEN_ABCDE12345"
        }
    },
    "currentContext": "colima",
    "cliPluginsExtraDirs": [
        "/opt/homebrew/lib/docker/cli-plugins"
    ],
    "aliases": {
        "builder": "buildx"
    }
}

Docker Credential Helper

Docker Credential Helperは各コンテナレジストリの認証時に自動的に認証情報を取得してくれる機能で、これを有効化しておくと認証情報が保存されず、毎回使い捨てになります。

Helperはコンテナレジストリごとに提供されますが、ここではECRを例にとって説明していきます。 ECRの場合はAWS公式でAmazon ECR Credential Helperが提供されています。

macOSの場合は以下のHomebrewコマンドでインストールできます。

brew install docker-credential-helper-ecr

GitHub Actionsのubuntuイメージには標準でECR Credential Helperが入っているので、ECRの場合は~/.docker/config.jsonを編集するだけで動きます。

Credential Helperの設定方法

~/.docker/config.jsonファイルの"credHelpers"でレジストリごとのHelperコマンドを指定することで利用できます。

"credHelpers": {
        "レジストリ名": "helperの名前"
}

Credential Helperのコマンド名は"docker-credential-"プレフィックスが必要で、設定ファイルではその後の部分だけ指定します。例えばECRの場合は"docker-credential-ecr-login"というコマンド名なので、"ecr-login"を指定します。

ECR Public

ECR Public Registryを使いたい場合、credHelpersは以下のような設定になります。ECR PublicはIPv4/v6デュアルスタックエンドポイントが提供されています。デュアルスタックエンドポイントはecr-public.aws.comですが、2025/09/22時点でECR Credential Helperはデュアルスタックエンドポイントに対応していません（Issue作成済み）。そのため、ecr-public.aws.comをレジストリとして指定した場合、認証されずに利用するのでご注意ください。 https://docs.aws.amazon.com/AmazonECR/latest/public/public-ecr-requests.html#public-ipv6-access-getting-started

"credHelpers": {
        "public.ecr.aws": "ecr-login"
}

ECR Private

ECR Private Registryの場合は以下のようになります。<アカウントID>.dkr-ecr.<リージョン>.on.awsはPrivate RegistryのIPv4/IPv6デュアルスタックエンドポイントです。ECR Publicと異なり、Private Registryはデュアルスタックエンドポイントにも対応しています。

"credHelpers": {
        "<アカウントID>.dkr.ecr.<リージョン>.amazonaws.com": "ecr-login",
        "<アカウントID>.dkr-ecr.<リージョン>.on.aws": "ecr-login"
}

GitHub Actions環境での設定

GitHub ActionsのUbuntu runnerでは~/.docker/config.jsonはこのようになっています。Docker Hubの認証情報がすでに埋め込まれているので、これに追記する形で設定していきます。

{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "DOCKER_HUB_TOKEN"
        }
    }
}

jqを使ってconfig.jsonへの追記

既存項目を破壊せずにcredHelpersを追記するためにjqコマンドを利用します。GitHub Actions環境では同梱されているので、追加インストールは不要です。例えば111111111111.dkr.ecr.ap-northeast-1.amazonaws.comに設定するなら、次のjqコマンドで追加できます。 Dockerクライアントで利用する設定ファイルなので、編集後にDocker Engineの再起動は不要です。

jq --arg key "111111111111.dkr.ecr.ap-northeast-1.amazonaws.com" --arg value "ecr-login" '.credHelpers |= {($key): $value}' ~/.docker/config.json > /tmp/config.json
mv /tmp/config.json ~/.docker/config.json

このコマンドでcredHelpdersオブジェクトにリポジトリ名とヘルパープログラムをキーバリュー形式で追加しています。

ECR Public/PrivateのIPv4エンドポイントとECR Privateのデュアルスタックエンドポイントを登録する場合はこのようになります。

jq \
  --arg key1 "111111111111.dkr.ecr.ap-northeast-1.amazonaws.com" \
  --arg key2 "111111111111.dkr-ecr.ap-northeast-1.on.aws" \
  --arg key3 "public.ecr.aws" \
  --arg value "ecr-login" \
  '.credHelpers |= (. + {($key1): $value, ($key2): $value, ($key3): $value})' \
  ~/.docker/config.json > /tmp/config.json
mv /tmp/config.json ~/.docker/config.json

GitHub Actions環境でこのコマンドを実行すると、~/.docker/config.jsonはこのようになります。

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "SOME_DOCKER_HUB_TOKEN"
    }
  },
  "credHelpers": {
    "111111111111.dkr.ecr.ap-northeast-1.amazonaws.com": "ecr-login",
    "111111111111.dkr-ecr.ap-northeast-1.on.aws": "ecr-login",
    "public.ecr.aws": "ecr-login"
}

使い方

Credential Helperを使う場合、事前のdocker loginは不要です。docker loginを実行した場合でも保存された認証情報は使われません。その代わりdocker pullなどコマンドを実行するたびにAWS認証が必要です。GitHub Actionsならaws-actions/configure-aws-credentialsワークフローなどを使って事前にログインしておきます。

GitHub Actionsだとこのような設定になります。例示のためアカウントIDなどをそのまま記載していますが、実際に使う場合はActions Secretの利用を推奨します。

GitHub Actionsワークフロー例

name: ECR Credential Helper
on:
  workflow_dispatch:
jobs:
  build:
    name: ECR Login
    runs-on: ubuntu-24.04
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v5
        with:
          role-to-assume: arn:aws:iam::111111111111:role/gh-action-role
          aws-region: ap-northeast-1

      - name: set credential helper
        id: docker-config
        run: |
          tmp_config=$(mktemp)
          jq \
            --arg key1 "111111111111.dkr.ecr.ap-northeast-1.amazonaws.com" \
            --arg key2 "111111111111.dkr-ecr.ap-northeast-1.on.aws" \
            --arg key3 "public.ecr.aws" \
            --arg value "ecr-login" \
            '.credHelpers |= (. + {($key1): $value, ($key2): $value, ($key3): $value})' \
            ~/.docker/config.json > $tmp_config
          mv $tmp_config ~/.docker/config.json

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build Docker images
        uses: docker/build-push-action@v6
        with:
          context: .
          file: ./Dockerfile
          tags: 111111111111.dkr-ecr.ap-northeast-1.on.aws/repo:latest
          push: true

ECR以外のCredential Helper

この記事ではECR Credential Helperを使いましたが、他のクラウドプロバイダーのCredential Helperもあります。

Google Cloud GCR

GCRはgcloudコマンドを利用してconfig.jsonファイルに設定します。GitHub Actions環境にはgcloudコマンドも導入されていますので、追加インストール不要です。 https://cloud.google.com/sdk/gcloud/reference/auth/configure-docker