REST API を使用して認証者を作成する

このページでは、REST API を使用して Binary Authorization で認証者を作成する方法を説明します。この手順は、Google Cloud CLI または Google Cloud Console でも行うことができます。このタスクは、Binary Authorization の設定の一部です。

概要

認証者は、Binary Authorization が証明書の検証で使用する Google Cloud リソースです。証明書の詳細については、Binary Authorization の概要をご覧ください。

認証者を作成するには、次のことを行う必要があります。

Artifact Analysis でメモを作成して、認証プロセスで使用される信頼できるメタデータを保存します。
認証者の ID 確認に使用する PKIX 鍵ペアを設定します。Cloud Key Management Service（Cloud KMS）で生成された非対称鍵ペアは PKIX と互換性があります。PKIX 鍵の代わりに PGP 鍵ペアを使用することもできます。
Binary Authorization で認証者を作成し、作成したメモと公開鍵を関連付けます。

単一プロジェクト設定では、Binary Authorization ポリシーを構成した Google Cloud プロジェクトに認証者を作成します。マルチプロジェクト設定では、多くの場合、デプロイ担当者プロジェクトにポリシーを構成し、それとは別の認証者プロジェクトに認証者を保存します。

デフォルトプロジェクトを設定する

デフォルトの Google Cloud プロジェクトを設定します（まだ行っていない場合）。

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

環境を設定する

プロジェクト名と番号を格納する環境変数を設定します。

DEPLOYER_PROJECT_ID=${PROJECT_ID}
DEPLOYER_PROJECT_NUMBER="$(
    gcloud projects describe "${DEPLOYER_PROJECT_ID}" \
      --format="value(projectNumber)"
)"
ATTESTOR_PROJECT_ID=${PROJECT_ID}
ATTESTOR_PROJECT_NUMBER="$(
    gcloud projects describe "${ATTESTOR_PROJECT_ID}" \
    --format="value(projectNumber)"
)"

証明書とデプロイ担当者のプロジェクトが同じプロジェクトの場合は、両方の変数に同じプロジェクト ID を使用します。

プロジェクトのサービスアカウント名も取得する必要があります。

DEPLOYER_SERVICE_ACCOUNT="service-${DEPLOYER_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
ATTESTOR_SERVICE_ACCOUNT="service-${ATTESTOR_PROJECT_NUMBER}@gcp-sa-binaryauthorization.iam.gserviceaccount.com"

Artifact Analysis メモを作成する

Binary Authorization は、Artifact Analysis を使用して、認証プロセスで使用される信頼できるメタデータを保存します。作成する認証者ごとに、1 つの Artifact Analysis メモを作成する必要があります。それぞれの証明書が、このメモのオカレンスとして保存されます。

Artifact Analysis メモを作成するには:

メモ ID と人が読める形式の説明を保存する環境変数を設定します。
```
NOTE_ID=NOTE_ID
NOTE_URI="projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}"
DESCRIPTION=DESCRIPTION
```
次のように置き換えます。
- NOTE_ID はメモの内部名です。スペースを含まない英数字で指定します（例: test-attestor-note）。
- NOTE_URI は、メモリリソースの完全修飾パスです。
- DESCRIPTION は、人が読める形式のメモ名です（例: Test Attestor Note）。

テキストエディタで、Artifact Analysis メモを記述する JSON ファイルを /tmp/note_payload.json に作成します。

cat > /tmp/note_payload.json << EOM
{
  "name": "${NOTE_URI}",
  "attestation": {
    "hint": {
      "human_readable_name": "${DESCRIPTION}"
    }
  }
}
EOM

HTTP リクエストを Artifact Analysis REST API に送信して、メモを作成します。

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/note_payload.json  \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/?noteId=${NOTE_ID}"

メモが正常に作成されたことを確認するには、次のコマンドを実行します。

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/"

メモに権限を設定する

また、作成した Artifact Analysis メモに権限を設定して、認証者プロジェクトのサービスアカウントにアクセスできるようにする必要があります。これを行うには、メモの IAM ポリシーを更新して、アカウントに containeranalysis.notes.occurrences.viewer ロールを割り当てます。

権限を設定するには:

メモに IAM ポリシーを設定するために必要な情報を含む JSON ファイルを生成します。

cat > /tmp/iam_request.json << EOM
{
  'resource': '${NOTE_URI}',
  'policy': {
    'bindings': [
      {
        'role': 'roles/containeranalysis.notes.occurrences.viewer',
        'members': [
          'serviceAccount:${ATTESTOR_SERVICE_ACCOUNT}'
        ]
      }
    ]
  }
}
EOM

作成したメモのサービスアカウントとリクエストされたアクセスロールを IAM ポリシーに追加します。
```
curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/iam_request.json \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}:setIamPolicy"
```
上記の方法でポリシーにロールを追加すると、メモの既存のロールが置換されます。既存のロールを保持する場合は、ポリシーを設定するときに、それらのロールを JSON データに含めてください。

暗号鍵を設定する

Binary Authorization では、PKIX 鍵を使用して、証明書を作成した署名者の ID を安全に確認できます。これにより、確認済みの当事者のみがコンテナイメージを承認できるようになります。PKIX の代わりに PGP 鍵を使用することもできます。

PKIX 鍵ペアを作成する

Binary Authorization では、非対称 PKIX 鍵ペアを使用して証明書を検証できます。鍵ペアは、署名者がデジタル署名に使用する秘密鍵と、認証者に追加する公開鍵で構成されます。後で、Binary Authorization 施行者は認証者の公開鍵を使用して、証明書が署名者によって作成されたことを確認します。

このガイドでは、PKIX 鍵ペアの生成に推奨の楕円曲線デジタル署名アルゴリズム（ECDSA）を使用していますが、RSA 鍵または PGP 鍵で署名することもできます。署名アルゴリズムの詳細については、鍵の目的とアルゴリズムをご覧ください。

Cloud KMS で生成され、保存されている非対称鍵ペアは PKIX 形式に準拠しています。Binary Authorization で使用する Cloud KMS 鍵を作成する方法については、非対称鍵の作成をご覧ください。鍵を作成する場合は、鍵の目的として非対称署名を必ず選択してください。

PKIX（Cloud KMS）

Cloud KMS で鍵ペアを作成する手順は次のとおりです。

鍵ペアの作成に必要な環境変数を設定するには、次のコマンドを実行します。
```
KMS_KEY_PROJECT_ID=KMS_KEY_PROJECT_ID
KMS_KEY_LOCATION=KMS_KEY_LOCATION
KMS_KEYRING_NAME=KMS_KEYRING_NAME
KMS_KEY_NAME=KMS_KEY_NAME
KMS_KEY_VERSION=KMS_KEY_VERSION
KMS_KEY_PURPOSE=asymmetric-signing
KMS_KEY_ALGORITHM=KMS_KEY_ALGORITHM
KMS_PROTECTION_LEVEL=KMS_PROTECTION_LEVEL
```
次のように置き換えます。
- KMS_KEY_PROJECT_ID: 鍵が保存されているプロジェクトの ID。
- KMS_KEY_LOCATION: 鍵のロケーション
- KMS_KEYRING_NAME: キーリングの名前
- KMS_KEY_NAME: 鍵の名前
- KMS_KEY_VERSION: 鍵のバージョン
- KMS_KEY_ALGORITHM: アルゴリズム（ec-sign-p256-sha256 を推奨）
- KMS_PROTECTION_LEVEL: 保護レベル（software など）

キーリングを作成するには、次のコマンドを実行します。

gcloud kms keyrings create ${KMS_KEYRING_NAME} \
    --location ${KMS_KEY_LOCATION}

鍵を作成するには、次のコマンドを実行します。

gcloud kms keys create ${KMS_KEY_NAME} \
    --location ${KMS_KEY_LOCATION} \
    --keyring ${KMS_KEYRING_NAME}  \
    --purpose ${KMS_KEY_PURPOSE} \
    --default-algorithm ${KMS_KEY_ALGORITHM} \
    --protection-level ${KMS_PROTECTION_LEVEL}

PKIX（ローカル鍵）

新しいローカル非対称 PKIX 鍵ペアを生成してファイルに保存するには:

鍵を生成します。

PRIVATE_KEY_FILE="/tmp/ec_private.pem"
openssl ecparam -genkey -name prime256v1 -noout -out ${PRIVATE_KEY_FILE}

このファイルには公開鍵と秘密鍵が含まれているため、認証者に追加するには公開鍵を別のファイルに抽出する必要があります。
```
PUBLIC_KEY_FILE="/tmp/ec_public.pem"
openssl ec -in ${PRIVATE_KEY_FILE} -pubout -out ${PUBLIC_KEY_FILE}
```

認証者を作成する

次に、関連付けられた Artifact Analysis メモを使用して、Binary Authorization で認証者を作成します。また、暗号公開鍵も追加する必要があります。

認証者を作成するには:

Binary Authorization で定義されている認証者の名前を格納する環境変数を設定します。
```
ATTESTOR_NAME=ATTESTOR_NAME
```
ATTESTOR_NAME は、作成する認証者の名前です（例: build-secure、prod-qa）。

認証者を作成し、公開セキュリティキーを関連付けます。

PKIX（Cloud KMS）

Binary Authorization API の呼び出しの Cloud KMS 鍵ペアに関する情報を格納する追加の環境変数を設定します。

KMS_CRYPTO_KEY_URI="projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}"
KMS_CRYPTO_KEY_VERSION_URI="${KMS_CRYPTO_KEY_URI}/cryptoKeyVersions/${KMS_KEY_VERSION}"
KMS_KEY_ID="//cloudkms.googleapis.com/v1/${KMS_CRYPTO_KEY_VERSION_URI}"

Cloud KMS から公開鍵ファイルをダウンロードし、ローカルシステムの /tmp/kms_public_key.pem というファイルに保存します。

認証者の作成に必要な情報を含む JSON ファイルを生成します。

cat > /tmp/attestor.json << EOM
{
    "userOwnedDrydockNote": {
        "noteReference": "${NOTE_URI}",
        "publicKeys": {
            "id": "${KMS_KEY_ID}",
            "pkixPublicKey": {
                "signatureAlgorithm": "${KMS_KEY_ALGORITHM}",
                "publicKeyPem": $( \
                    python < /tmp/kms_public_key.pem \
                    -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
                )
            }
        }
    }
}
EOM

認証者を作成します。

curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/attestor.json \
"https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors?attestorId=${ATTESTOR_NAME}"

PKIX（ローカル鍵）

認証者の作成に必要な情報を含む JSON ファイルを生成します。

cat > /tmp/attestor.json << EOM
{
   "userOwnedGrafeasNote": {
       "noteReference": "${NOTE_URI}",
       "publicKeys": {
           "pkixPublicKey": {
               "signatureAlgorithm": "ecdsa_p256_sha256",
               "publicKeyPem": $( \
                   python < ${PUBLIC_KEY_FILE} \
                   -c 'import json, sys; print(json.dumps(sys.stdin.read()))' \
               )
           }
       }
   }
}
EOM

認証者を作成します。

curl -X POST  \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
   --data-binary @/tmp/attestor.json \
"https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors?attestorId=${ATTESTOR_NAME}"

デプロイ担当者プロジェクトの IAM ロールバインディングを認証者に追加します。これは、Binary Authorization でポリシーを評価する際に、プロジェクトがその認証者にアクセスする権限を持っているかどうかを判定するために使用されます。

認証者に IAM ポリシーを設定するために必要な情報を含む JSON ファイルを生成します。

cat > /tmp/iam_request.json << EOM
{
  'resource': 'projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}',
  'policy': {
    'bindings': [
      {
        'role': 'roles/binaryauthorization.attestorsVerifier',
        'members': [
          'serviceAccount:${DEPLOYER_SERVICE_ACCOUNT}'
        ]
      }
    ]
  }
}
EOM

作成したメモのサービスアカウントとリクエストされたアクセスロールを IAM ポリシーに追加します。

curl -X POST  \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    --data-binary @/tmp/iam_request.json \
    "https://binaryauthorization.googleapis.com/v1beta1/projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}:setIamPolicy"

認証者が作成されたことを確認する

認証者が作成されたことを確認するには、次のコマンドを実行します。

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors/"

次のステップ

証明書を作成する

REST API を使用して認証者を作成する

概要

デフォルト プロジェクトを設定する

環境を設定する

Artifact Analysis メモを作成する

メモに権限を設定する

暗号鍵を設定する

PKIX 鍵ペアを作成する

PKIX（Cloud KMS）

PKIX（ローカル鍵）

認証者を作成する

PKIX（Cloud KMS）

PKIX（ローカル鍵）

認証者が作成されたことを確認する

次のステップ

デフォルトプロジェクトを設定する