Membuat pengesahan

Halaman ini menjelaskan langkah-langkah untuk membuat Otorisasi Biner pengesahan.

Anda menggunakan pengesahan untuk mengotorisasi image container tertentu agar dapat di-deploy di platform, seperti Google Kubernetes Engine (GKE) dan Cloud Run. Untuk menggunakan pengesahan, Anda harus mewajibkan pengesahan dalam aturan yang sesuai dari kebijakan Anda.

Satu pengesahan dapat mengotorisasi image identik yang disimpan di beberapa lokasi berbeda atau registry yang berbeda, seperti Artifact Registry, Container Registry, atau registry container eksternal.

Saat waktu deployment, Otorisasi Biner menggunakan attestor untuk memverifikasi pengesahan.

Untuk menyiapkan Otorisasi Biner di Cloud Run, GKE, Google Distributed Cloud, dan Cloud 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 Memulai menggunakan alat command line atau Memulai menggunakan Google Cloud konsol.

Sebelum memulai

Ringkasan pengesahan memberikan langkah-langkah yang harus diselesaikan sebelum membuat pengesahan.

1. Aktifkan Otorisasi Biner

2. Buat attestor menggunakan Google Cloud konsol, the Google Cloud CLI, atau REST API.

Menyiapkan lingkungan

1. Tentukan ID project 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 di project yang sama dengan attestor, gunakan ID project yang sama untuk kedua variabel. Untuk tutorial menyeluruh yang menunjukkan pemisahan tugas dengan project yang berbeda, lihat Penyiapan multi-project.

2. Tentukan nama attestor dan informasi image:

   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 atau prod-qa.

   • IMAGE_PATH: URI yang mewakili jalur image. Meskipun URI harus terdiri dari domain dan nama image, URI tersebut tidak perlu merujuk ke image sebenarnya. Image tidak diakses selama pembuatan pengesahan Berikut adalah contoh jalur image:

     • us-docker.pkg.dev/google-samples/containers/gke/hello-app
     • gcr.io/example-project/quickstart-image
     • example.com/hello-app.

   • IMAGE_DIGEST: ringkasan manifes image. Misalnya, sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567 adalah ringkasan image yang terkait dengan jalur image us-docker.pkg.dev/google-samples/containers/gke/hello-app contoh. Untuk mempelajari cara mendapatkan ringkasan image di Artifact Registry, lihat Mengelola image; untuk image di Container Registry, lihat Mencantumkan versi image.

Memberikan peran Identity and Access Management

Untuk membuat pengesahan, Anda harus memberikan peran berikut Identity and Access Management (IAM) ke identitas 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 dikaitkan dengan catatan Artifact Analysis. Membuat pengesahan pada gilirannya akan membuat kemunculan Artifact Analysis dan melampirkannya ke catatan.

Pelajari lebih lanjut Cara memberikan akses.

Untuk mempelajari cara membuat pengesahan di pipeline Cloud Build, lihat Membuat pengesahan dengan Cloud Build.

Membuat pengesahan

Catatan: Contoh image dalam panduan ini hanya untuk tujuan demonstrasi. Sebaiknya Anda hanya membuat pengesahan untuk image yang Anda kelola.

Membuat pengesahan menggunakan kunci yang disimpan secara lokal

Untuk membuat pengesahan yang ditandatangani dengan kunci lokal, lakukan hal berikut:

1. 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
   

2. Tandatangani payload dengan kunci pribadi Anda untuk membuat file tanda tangan.

   Panduan ini menggunakan algoritma Elliptic Curve Digital Signature Algorithm (ECDSA) yang direkomendasikan untuk penandatanganan. Anda juga dapat menggunakan algoritma RSA. Untuk mengetahui informasi selengkapnya tentang algoritma penandatanganan, lihat Tujuan dan algoritma kunci. 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.

3. Dapatkan 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)')
   

4. Buat pengesahan:

   gcloud

   Untuk membuat dan memvalidasi pengesahan, masukkan perintah 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 dalam kebijakan Anda.

   Catatan: ID kunci dapat berupa string apa pun.

   REST API

   Untuk membuat pengesahan:

   1. Ambil attestor yang terkait dengan pengesahan dan ekstrak ID kunci publik yang disimpan:

      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 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": "[e-mail]"
        },
        "updateTime": "2019-06-26T16:58:33.977438Z"
      }
      

      Kunci publik dapat ditemukan di kolom id.

   2. 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
      

   3. 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/"
      

      Perhatian: Otorisasi Biner tidak mendukung regional penyimpanan atau regional endpoint Artifact Analysis. Sebaiknya gunakan endpoint API global Artifact Analysis (https://containeranalysis.googleapis.com/).

Membuat pengesahan menggunakan Cloud KMS

Untuk membuat pengesahan dengan menggunakan Cloud Key Management Service:

1. 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 Anda 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

2. Tandatangani 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}" \
       --validate
   

   Flag validate memeriksa apakah pengesahan dapat diverifikasi oleh attestor yang Anda konfigurasi dalam kebijakan Anda.

   REST API

   1. 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
      

   2. Tandatangani 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 algoritma untuk mencerna input. Contoh dalam panduan ini menggunakan ringkasan sha256. Anda dapat menggunakan sha256, sha384, atau sha512.

      Dalam contoh ini, outputnya akan 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 yang dienkode base64.

   3. Simpan tanda tangan dalam variabel lingkungan:

      PAYLOAD_SIGNATURE=PAYLOAD_SIGNATURE
      

   4. Ambil attestor yang atas nama Anda menandatangani pengesahan dan ekstrak ID kunci publik dan ID catatan yang disimpan:

      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 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": "[e-mail]"
        },
        "updateTime": "2019-06-26T16:58:33.977438Z"
      }
      

      Anda dapat menemukan ID kunci publik di kolom id dan ID catatan di kolom noteReference.

   5. 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.

   6. 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
      

   7. 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/"
      

      Perhatian: Otorisasi Biner tidak mendukung regional penyimpanan atau regional endpoint Artifact Analysis. Sebaiknya gunakan endpoint API global Artifact Analysis (https://containeranalysis.googleapis.com/).

Anda telah membuat pengesahan.

Catatan: Saat waktu deployment, penegak hanya menggunakan ringkasan image untuk memverifikasi pengesahan. Oleh karena itu, pengesahan ini dapat digunakan untuk men-deploy image identik di beberapa lokasi, termasuk yang disimpan secara lokal, di Artifact Registry, Container Registry, dan di registry eksternal.

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, sebagai 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, berarti tidak ada lagi hasil.

Menghapus pengesahan

Perhatian: Anda tidak boleh menghapus pengesahan untuk workload produksi. Menghapus pengesahan dapat menyebabkan perilaku yang tidak terduga. Petunjuk ini adalah untuk menghapus pengesahan pengujian, seperti yang dibuat sebelumnya dalam dokumen ini.

Sebelum menghapus pengesahan, Anda harus melakukan hal berikut:

1. Pahami konsekuensi dari penghapusannya. Menghapus pengesahan pada akhirnya akan memblokir image container yang terkait dengan pengesahan agar tidak di-deploy.

2. Hentikan semua container yang berjalan dan terkait dengan pengesahan yang ingin Anda hapus.

3. Hapus semua salinan pengesahan di mana pun pengesahan tersebut berada, misalnya pengesahan di repositori Artifact Registry dan Artifact Analysis.

4. Pastikan image yang terpengaruh benar-benar diblokir untuk di-deploy dengan mencoba men-deploy ulang.

Catatan: Untuk keamanan tambahan, pertimbangkan untuk menghapus pasangan kunci dan attestor terkait.

Untuk menghapus pengesahan, jalankan perintah berikut:

1. Cantumkan pengesahan:

   gcloud container binauthz attestations list \
     --attestor-project=${ATTESTOR_PROJECT_ID} \
     --attestor=${ATTESTOR_NAME}
   

   Pengesahan berisi ID kemunculan. Outputnya akan terlihat mirip dengan berikut ini:

   projects/ATTESTOR_PROJECT_ID/occurrences/OCCURRENCE_ID
   

2. Simpan ID kemunculan.

   Simpan ID kemunculan pengesahan yang ingin Anda hapus.

   OCCURRENCE_ID=OCCURRENCE_ID
   

3. 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 berikutnya

• Pelajari lebih lanjut Pemisahan tugas dan peran Identity and Access Management.
• Terapkan pemisahan tugas dalam tutorial Penyiapan multi-project (GKE) ini.
• Deploy image container (GKE) ke cluster tempat Otorisasi Biner diaktifkan.
• Deploy image container (Cloud Run) ke cluster tempat Otorisasi Biner diaktifkan.