Halaman ini menjelaskan langkah-langkah untuk membuat pengesahan Otorisasi Biner.
Anda menggunakan pengesahan untuk mengizinkan image container tertentu di-deploy di platform, seperti Google Kubernetes Engine (GKE) dan Cloud Run. Untuk menggunakan pengesahan, Anda harus mewajibkan pengesahan dalam aturan yang sesuai dalam kebijakan Anda.
Satu pengesahan dapat mengizinkan image identik yang disimpan di beberapa lokasi atau registry yang berbeda, seperti Artifact Registry, Container Registry, atau container registry eksternal.
Pada waktu deployment, Otorisasi Biner menggunakan attestor untuk memverifikasi pengesahan.
Untuk menyiapkan Otorisasi Biner di Cloud Run, GKE, cluster GKE, dan Anthos Service Mesh, lihat Menyiapkan berdasarkan platform dan pilih platform Anda.
Pengguna GKE: Untuk tutorial menyeluruh yang menjelaskan penerapan berbasis pengesahan menggunakan Otorisasi Biner dan Google Kubernetes Engine (GKE), lihat bagian Memulai penggunaan alat command line atau Mulai menggunakan Konsol Google Cloud.
Sebelum memulai
Ringkasan pengesahan menyediakan langkah-langkah yang harus diselesaikan sebelum membuat pengesahan.
Menyiapkan lingkungan
Tentukan project ID Anda:
ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID
Ganti kode berikut:
- ATTESTOR_PROJECT_ID: nama project tempat Anda menyimpan attestor
- ATTESTATION_PROJECT_ID: nama project tempat Anda menyimpan pengesahan
Jika Anda ingin pengesahan dibuat dalam project yang sama dengan attestor, gunakan project ID yang sama untuk kedua variabel. Untuk tutorial menyeluruh yang menunjukkan pemisahan tugas dengan berbagai project, lihat Penyiapan multi-project.
Tentukan nama attestor dan informasi gambar:
ATTESTOR_NAME=ATTESTOR_NAME IMAGE_PATH=IMAGE_PATH IMAGE_DIGEST=IMAGE_DIGEST IMAGE_TO_ATTEST="${IMAGE_PATH}@${IMAGE_DIGEST}"
Ganti kode berikut:
- ATTESTOR_NAME: nama attestor, misalnya,
build-secure
atauprod-qa
. IMAGE_PATH: URI yang mewakili jalur gambar. Meskipun URI harus terdiri dari nama domain dan gambar, URI tidak perlu merujuk ke gambar sebenarnya. Gambar tidak diakses selama pembuatan pengesahan. Berikut adalah contoh jalur gambar:
us-docker.pkg.dev/google-samples/containers/gke/hello-app
gcr.io/example-project/quickstart-image
example.com/hello-app
.
IMAGE_DIGEST: ringkasan manifes gambar. Misalnya,
sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567
adalah ringkasan gambar yang terkait dengan contoh jalur gambarus-docker.pkg.dev/google-samples/containers/gke/hello-app
. Untuk mempelajari cara mendapatkan ringkasan image di Artifact Registry, lihat Mengelola image; untuk image di Container Registry, lihat Mencantumkan versi image.
- ATTESTOR_NAME: nama attestor, misalnya,
Memberikan peran Identity and Access Management
Untuk membuat pengesahan, Anda harus memberikan peran Identity and Access Management (IAM) berikut kepada identity yang membuat attestor, sebagai berikut:
roles/containeranalysis.notes.attacher
pada resource catatan yang terkait dengan attestor.roles/containeranalysis.occurrences.editor
pada resource project pengesahan.
Anda membuat pengesahan berdasarkan attestor. Attestor terkait dengan catatan Artifact Analysis. Dengan membuat pengesahan, kemunculan Artifact Analysis akan dibuat dan dilampirkan ke catatan.
Pelajari lebih lanjut cara Memberikan akses.
Untuk mempelajari cara membuat pengesahan di pipeline Cloud Build, lihat Membuat pengesahan menggunakan Kritis Signer.
Membuat pengesahan
Membuat pengesahan menggunakan kunci yang disimpan secara lokal
Untuk membuat pengesahan yang ditandatangani dengan kunci lokal, lakukan hal berikut:
Buat file payload tanda tangan:
gcloud
Untuk membuat file payload tanda tangan, masukkan perintah berikut:
gcloud container binauthz create-signature-payload \ --artifact-url="${IMAGE_TO_ATTEST}" > /tmp/generated_payload.json
File payload berformat JSON akan terlihat mirip dengan output berikut:
{ "critical": { "identity": { "docker-reference": "us-docker.pkg.dev/google-samples/containers/gke/hello-app" }, "image": { "docker-manifest-digest": "sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567" }, "type": "Google cloud binauthz container signature" } }
REST API
Buat file payload bernama
/tmp/generated_payload.json
menggunakan variabel lingkungan yang Anda tetapkan sebelumnya dalam dokumen ini:cat > /tmp/generated_payload.json << EOM { "critical": { "identity": { "docker-reference": "${IMAGE_PATH}" }, "image": { "docker-manifest-digest": "${IMAGE_DIGEST}" }, "type": "Google cloud binauthz container signature" } } EOM
Tanda tangani payload dengan kunci pribadi Anda untuk menghasilkan file tanda tangan.
Panduan ini menggunakan algoritme Elliptic Curve Digital Signing Algorithm (ECDSA) yang direkomendasikan untuk penandatanganan. Anda juga dapat menggunakan algoritma RSA. Untuk informasi selengkapnya tentang algoritma penandatanganan, lihat Tujuan dan algoritma utama. Panduan ini juga menggunakan format tanda tangan Public-Key Infrastructure (X.509) (PKIX). Anda juga dapat menggunakan PGP.
PRIVATE_KEY_FILE=PRIVATE_KEY_FILE openssl dgst -sha256 -sign ${PRIVATE_KEY_FILE} /tmp/generated_payload.json > /tmp/ec_signature
Ganti PRIVATE_KEY_FILE dengan jalur ke kunci pribadi yang Anda buat saat membuat attestor.
Mendapatkan ID kunci publik.
Anda dapat mengambil ID kunci publik dari attestor dengan memasukkan perintah berikut:
PUBLIC_KEY_ID=$(gcloud container binauthz attestors describe ${ATTESTOR_NAME} \ --format='value(userOwnedGrafeasNote.publicKeys[0].id)')
Buat pengesahan:
gcloud
Untuk membuat dan memvalidasi pengesahan, masukkan string berikut:
gcloud container binauthz attestations create \ --project="${ATTESTATION_PROJECT_ID}" \ --artifact-url="${IMAGE_TO_ATTEST}" \ --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \ --signature-file=/tmp/ec_signature \ --public-key-id="${PUBLIC_KEY_ID}" \ --validate
Flag
validate
memeriksa apakah pengesahan dapat diverifikasi oleh attestor yang Anda konfigurasi di kebijakan.Catatan: ID kunci dapat berupa string apa pun.
REST API
Untuk membuat pengesahan:
Ambil attestor yang terkait dengan pengesahan dan ekstrak ID kunci publik yang tersimpan:
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/"
Otorisasi Biner menampilkan objek JSON yang mirip dengan yang berikut ini:
{ "name": "projects/example-project/attestors/test-attestor", "userOwnedGrafeasNote": { "noteReference": "projects/example-project/notes/test-attestor", "publicKeys": [ { "id": "ni:///sha-256;EwVxs8fNUAHq9FI2AMfh8WNIXVBuuTMeGtPH72U-I70", "pkixPublicKey": { "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXnpuYEfvLl1kj4fjxViFRwY1a+zC\n5qzlf9LJIK+rnjq42tiKGyyXMbnZKJiYPPdMDGyltnkrABnztg2jJ48aYQ==\n-----END PUBLIC KEY-----\n", "signatureAlgorithm": "ECDSA_P256_SHA256" } } ], "delegationServiceAccountEmail": "service-363451293945@gcp-sa-binaryauthorization.iam.gserviceaccount.com" }, "updateTime": "2019-06-26T16:58:33.977438Z" }
Kunci publik dapat ditemukan di kolom
id
.Buat file JSON di
/tmp/attestation.json
yang menjelaskan pengesahan:cat > /tmp/attestation.json << EOM { "resourceUri": "${IMAGE_TO_ATTEST}", "note_name": "${NOTE_URI}", "attestation": { "serialized_payload": "$(base64 --wrap=0 /tmp/generated_payload.json)", "signatures": [ { "public_key_id": "${PUBLIC_KEY_ID}", "signature": "$(base64 --wrap=0 /tmp/ec_signature)" } ] } } EOM
Buat pengesahan:
curl -X POST \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: ${ATTESTATION_PROJECT_ID}" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ --data-binary @/tmp/attestation.json \ "https://containeranalysis.googleapis.com/v1/projects/${ATTESTATION_PROJECT_ID}/occurrences/"
Membuat pengesahan menggunakan Cloud KMS
Untuk membuat pengesahan dengan menggunakan Cloud Key Management Service:
Buat variabel lingkungan:
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
Ganti kode berikut:
- KMS_KEY_PROJECT_ID: ID project tempat kunci Cloud Key Management Service disimpan
- KMS_KEY_LOCATION: lokasi kunci (
global
adalah default) - KMS_KEYRING_NAME: nama key ring
- KMS_KEY_NAME: nama kunci
- KMS_KEY_VERSION: versi kunci
Tanda tangani dan buat pengesahan:
gcloud
Masukkan perintah berikut:
gcloud beta container binauthz attestations sign-and-create \ --project="${ATTESTATION_PROJECT_ID}" \ --artifact-url="${IMAGE_TO_ATTEST}" \ --attestor="${ATTESTOR_NAME}" \ --attestor-project="${ATTESTOR_PROJECT_ID}" \ --keyversion-project="${KMS_KEY_PROJECT_ID}" \ --keyversion-location="${KMS_KEY_LOCATION}" \ --keyversion-keyring="${KMS_KEYRING_NAME}" \ --keyversion-key="${KMS_KEY_NAME}" \ --keyversion="${KMS_KEY_VERSION}"
REST API
Buat file payload bernama
/tmp/generated_payload.json
menggunakan variabel lingkungan yang Anda tetapkan di atas:cat > /tmp/generated_payload.json << EOM { "critical": { "identity": { "docker-reference": "${IMAGE_PATH}" }, "image": { "docker-manifest-digest": "${IMAGE_DIGEST}" }, "type": "Google cloud binauthz container signature" } } EOM
Tanda tangani file payload:
curl \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $(gcloud auth print-access-token)" \ --header "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \ --data '{"digest": {"DIGEST_ALGORITHM": "'$(openssl dgst -sha256 -binary /tmp/generated_payload.json | openssl base64)'" }}' \ https://cloudkms.googleapis.com/v1/projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}/cryptoKeyVersions/${KMS_KEY_VERSION}:asymmetricSign?alt=json
Ganti DIGEST_ALGORITHM dengan algoritme untuk memahami input. Contoh dalam panduan ini menggunakan ringkasan
sha256
. Anda dapat menggunakansha256
,sha384
, atausha512
.Dalam contoh ini, output-nya terlihat mirip dengan berikut ini:
{ "signature": "<var>SIGNATURE</var>": "996305066", "name": "projects/<var>KMS_KEY_PROJECT_ID</var>/locations/<var>KMS_KEY_LOCATION</var>/keyRings/<var>KMS_KEYRING_NAME</var>/cryptoKeys/<var>KMS_KEY_NAME</var>/cryptoKeyVersions/<var>KMS_KEY_VERSION</var>" }
Dalam output ini, SIGNATURE adalah tanda tangan file payload berenkode base64.
Simpan tanda tangan dalam variabel lingkungan:
PAYLOAD_SIGNATURE=PAYLOAD_SIGNATURE
Ambil attestor yang atas namanya Anda menandatangani pengesahan dan ekstrak ID kunci publik dan ID catatan yang tersimpan:
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/"
Otorisasi Biner menampilkan objek JSON yang mirip dengan yang berikut ini:
{ "name": "projects/example-project/attestors/test-attestor", "userOwnedGrafeasNote": { "noteReference": "projects/example-project/notes/test-attestor", "publicKeys": [ { "id": "ni:///sha-256;EwVxs8fNUAHq9FI2AMfh8WNIXVBuuTMeGtPH72U-I70", "pkixPublicKey": { "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXnpuYEfvLl1kj4fjxViFRwY1a+zC\n5qzlf9LJIK+rnjq42tiKGyyXMbnZKJiYPPdMDGyltnkrABnztg2jJ48aYQ==\n-----END PUBLIC KEY-----\n", "signatureAlgorithm": "ECDSA_P256_SHA256" } } ], "delegationServiceAccountEmail": "service-363451293945@gcp-sa-binaryauthorization.iam.gserviceaccount.com" }, "updateTime": "2019-06-26T16:58:33.977438Z" }
Anda dapat menemukan ID kunci publik di kolom
id
dan ID catatan di kolomnoteReference
.Simpan ID kunci publik dalam variabel lingkungan:
PUBLIC_KEY_ID="PUBLIC_KEY_ID" NOTE_URI="NOTE_URI"
Ganti kode berikut:
- PUBLIC_KEY_ID: ID kunci publik attestor.
- NOTE_URI: URI catatan Artifact Analysis yang terkait dengan attestor.
Buat file JSON di
/tmp/attestation.json
yang menjelaskan pengesahan:cat > /tmp/attestation.json << EOM { "resourceUri": "${IMAGE_TO_ATTEST}", "note_name": "${NOTE_URI}", "attestation": { "serialized_payload": "$(base64 --wrap=0 /tmp/generated_payload.json)", "signatures": [ { "public_key_id": "${PUBLIC_KEY_ID}", "signature": "${PAYLOAD_SIGNATURE}" } ] } } EOM
Buat pengesahan:
curl -X POST \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: ${ATTESTATION_PROJECT_ID}" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ --data-binary @/tmp/attestation.json \ "https://containeranalysis.googleapis.com/v1/projects/${ATTESTATION_PROJECT_ID}/occurrences/"
Anda telah membuat pengesahan.
Memverifikasi bahwa pengesahan telah dibuat
Untuk memverifikasi bahwa pengesahan telah dibuat, Anda dapat mencantumkan pengesahan yang terkait dengan image.
gcloud
Untuk mengambil daftar pengesahan, masukkan perintah berikut:
gcloud container binauthz attestations list\ --project="${ATTESTATION_PROJECT_ID}"\ --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}"\ --artifact-url="${IMAGE_TO_ATTEST}"
REST API
Untuk meminta daftar pengesahan, masukkan perintah berikut:
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}/occurrences?filter=resourceUrl%3D%22https%3A%2F%2F$(jq -rn --arg x ${IMAGE_TO_ATTEST} '$x|@uri')%22
Jika ada banyak pengesahan, respons mungkin berisi nilai
nextPageToken
. Dalam hal ini, Anda dapat mengambil halaman hasil berikutnya dengan mengulangi
permintaan, menambahkan parameter kueri pageToken
, seperti berikut:
NEXT_PAGE_TOKEN=NEXT_PAGE_TOKEN curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}/occurrences?filter=resourceUrl%3D%22https%3A%2F%2F$(jq -rn --arg x ${IMAGE_TO_ATTEST} '$x|@uri')%22&pageToken=${NEXT_PAGE_TOKEN}
Ganti NEXT_PAGE_TOKEN dengan nilai nextPageToken
dalam respons dari permintaan sebelumnya.
Jika nextPageToken
kosong, itu berarti tidak ada hasil lagi.
Menghapus pengesahan
Sebelum menghapus pengesahan, Anda harus melakukan hal berikut:
Pahami konsekuensi penghapusannya. Menghapus pengesahan pada akhirnya akan memblokir image container yang terkait dengan pengesahan agar tidak di-deploy.
Hentikan semua container yang sedang berjalan dan terkait dengan pengesahan yang ingin Anda hapus.
Hapus semua salinan pengesahan di mana pun salinan tersebut berada, misalnya pengesahan di repositori Artifact Registry dan Artifact Analysis.
Pastikan image yang terpengaruh benar-benar diblokir agar tidak dapat di-deploy dengan mencoba men-deploy ulang gambar tersebut.
Untuk menghapus pengesahan, jalankan perintah berikut:
Cantumkan pengesahan:
gcloud container binauthz attestations list \ --attestor-project=${ATTESTOR_PROJECT_ID} \ --attestor=${ATTESTOR_NAME}
Pengesahan berisi ID kejadian. Output-nya terlihat mirip dengan berikut:
projects/ATTESTOR_PROJECT_ID/occurrences/OCCURRENCE_ID
Simpan ID kejadian.
Simpan ID kemunculan pengesahan yang ingin Anda hapus.
OCCURRENCE_ID=OCCURRENCE_ID
Hapus pengesahan:
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X DELETE \ https://containeranalysis.googleapis.com/v1beta1/projects/${ATTESTATION_PROJECT_ID}/occurrences/${OCCURRENCE_ID}
Verifikasi bahwa pengesahan telah dihapus dengan mencantumkan pengesahan lagi.
Langkah selanjutnya
- Pelajari lebih lanjut Pemisahan tugas dan peran Identity and Access Management.
- Terapkan pemisahan tugas dalam tutorial Penyiapan multi-project (GKE).
- Deploy image container (GKE) ke cluster tempat Otorisasi Biner diaktifkan.
- Deploy image container (Cloud Run) ke cluster tempat Otorisasi Biner diaktifkan.