Mengonfigurasi akses berbasis sertifikat untuk Workload Identity Federation

Dokumen ini menjelaskan cara mengonfigurasi akses berbasis sertifikat untuk Workload Identity Federation menggunakan sertifikat X.509.

Akses berbasis sertifikat menggunakan Mutual TLS (mTLS) untuk mengautentikasi klien dan server selama handshake TLS. Dalam proses ini, binding mTLS menggabungkan kebijakan berdasarkan konteks transportasi dan menggunakan status sertifikat klien dalam sesi TLS untuk membuat keputusan otorisasi.

Untuk workload identity federation X.509, binding mTLS memastikan bahwa seluruh alur autentikasi terikat dengan aman ke workload tepercaya. Hal ini mengurangi risiko pencurian kredensial, karena autentikasi terikat ke endpoint tepercaya tertentu.

Ringkasan konfigurasi akses berbasis sertifikat untuk Workload Identity Federation

Berikut adalah ringkasan tingkat tinggi dari proses untuk mengonfigurasi akses berbasis sertifikat untuk Workload Identity Federation:

  1. Buat workload identity federation dengan mengonfigurasi kepercayaan dengan trust anchor sertifikat X.509.

  2. Buat tingkat akses untuk akses berbasis sertifikat.

  3. Tambahkan tingkat akses ke kebijakan Akses Kontekstual yang menerapkan binding mTLS.

Sebelum memulai

Pastikan Anda memiliki prasyarat berikut:

  • Google Cloud CLI versi terbaru

    Untuk mengupdate ke Google Cloud CLI versi terbaru, jalankan perintah berikut:

    gcloud components update

    Jika Anda perlu menginstal Google Cloud CLI, lihat Menginstal Google Cloud CLI.

  • Konfigurasi Workload Identity Federation yang menggunakan trust anchor sertifikat X.509

  • Untuk menggunakan fitur ini, isi formulir berikut agar ditambahkan ke daftar yang diizinkan: Formulir permintaan daftar yang diizinkan. Anda akan dihubungi setelah ditambahkan ke daftar yang diizinkan.

Membuat tingkat akses untuk sertifikat

  1. Buat tingkat akses mTLS. Tingkat akses mTLS memvalidasi sertifikat saat menentukan akses ke resource.

    Konsol

    Di Access Context Manager, buat tingkat akses kustom dan masukkan ekspresi berikut di kolom ekspresi CEL: request.auth.matchesMtlsTokens(origin) == true.

    gcloud

    Untuk membuat tingkat akses kustom, jalankan perintah berikut:

    gcloud access-context-manager levels create ACCESS_LEVEL_NAME \
    --title=TITLE \
    --custom-level-spec=FILE \
    --description=DESCRIPTION \
    --policy=POLICY_NAME

    Ganti kode berikut:

    • ACCESS_LEVEL_NAME: nama tingkat akses.
    • TITLE: judul tingkat akses.
    • FILE: file YAML dengan konten berikut: expression: "request.auth.matchesMtlsTokens(origin) == true".
    • DESCRIPTION: deskripsi tingkat akses.
    • POLICY_NAME: nama kebijakan akses.

  2. Ekspor tingkat akses yang Anda buat ke variabel lingkungan. Variabel ini digunakan pada langkah-langkah berikutnya.

      export ACCESS_LEVEL_ID=ACCESS_LEVEL_ID

    Ganti ACCESS_LEVEL_ID dengan nama tingkat akses —misalnya, accessPolicies/12345/accessLevels/acl_1.

Membuat binding Akses Kontekstual untuk workload identity pool

  1. Tetapkan variabel lingkungan berikut.

    export ORG_ID=ORG_ID
export CALLER_PROJECT_ID=CALLER_PROJECT_ID
export FEDERATED_PRINCIPAL=FEDERATED_PRINCIPAL

    Ganti kode berikut:

    • ORG_ID: ID organisasi Anda.
    • CALLER_PROJECT_ID: ID project yang akan digunakan untuk memanggil API.

    • FEDERATED_PRINCIPAL: nama principal identitas di workload identity pool yang mematuhi kebijakan Akses Kontekstual. Anda dapat menggunakan salah satu opsi berikut:

      satu identitas dengan format - principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE

      ATAU

      semua identitas dalam pool dengan format - principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

    gcloud 

    gcloud alpha access-context-manager cloud-bindings create \
--organization=ORG_ID \
--federated-principal=FEDERATED_PRINCIPAL \
--level=ACCESS_LEVEL_ID
--dry-run-level=DRY_RUN_ACCESS_LEVEL_ID

    Ganti kode berikut:

    • ACCESS_LEVEL_ID: nama tingkat akses.
    • DRY_RUN_ACCESS_LEVEL_ID: nama tingkat akses uji coba. Sebaiknya aktifkan binding kebijakan uji coba terlebih dahulu untuk memahami potensi dampaknya terhadap traffic yang ada.

    curl

    1. Buat file JSON dengan binding Akses Kontekstual.

      Anda hanya dapat memberikan satu tingkat akses dalam permintaan, meskipun kolomnya diulang. Anda dapat menggunakan jenis principal gabungan berikut:

      • Identitas tunggal: principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
      • Semua identitas dalam pool: principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
      echo { \
  \"principal\": { \
    \"federatedPrincipal\": \"${FEDERATED_PRINCIPAL:?}\" \
  },\
  \"accessLevels\": [\"${ACCESS_LEVEL_ID:?}\"] \
} \
>> request.json

    2. Gunakan curl untuk mengirim permintaan HTTP berikut.

      curl -H "X-Goog-User-Project: ${CALLER_PROJECT_ID:?}" -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" \
   -d @request.json \
 "https://accesscontextmanager.googleapis.com/v1alpha/organizations/${ORG_ID:?}/gcpUserAccessBindings"

Memberikan otorisasi menggunakan library klien Cloud de Confiance

Untuk mengotorisasi workload Workforce Identity Federation menggunakan Cloud de Confiance library klien, selesaikan langkah-langkah berikut.

  1. Buat file Kredensial Default Aplikasi (ADC) yang dikonfigurasi untuk autentikasi Workforce Identity Federation.

    gcloud iam workload-identity-pools create-cred-config IDENTITY_POOL_ID \
--credential-cert-path WORKLOAD_CERTIFICATE_PATH \
--credential-cert-private-key-path WORKLOAD_KEY_PATH \
--output-file ADC_FILE_OUTPUT_PATH

    Ganti kode berikut:

    • IDENTITY_POOL_ID: ID workload identity pool Anda.
    • WORKLOAD_CERTIFICATE_PATH: jalur ke file sertifikat workload Anda.
    • WORKLOAD_KEY_PATH: jalur ke file kunci pribadi workload Anda.
    • ADC_FILE_OUTPUT_PATH: jalur output untuk file ADC.

    Perintah ini juga menghasilkan file konfigurasi sertifikat di direktori konfigurasi default Google Cloud CLI Anda. File konfigurasi sertifikat mendukung autentikasi awal dan membuat handshake mTLS untuk permintaan berikutnya ke resource. Cloud de Confiance

  2. Tetapkan variabel lingkungan agar mengarah ke file ADC. Hal ini membuat kredensial Anda dapat ditemukan oleh library klien Google.

    export GOOGLE_APPLICATION_CREDENTIALS=${application_default_credentials.json}

    Langkah ini bersifat opsional jika Anda menghapus argumen --output-file saat membuat file ADC. Jika Anda menghapus argumen, file ADC akan dibuat dan dibaca dari direktori konfigurasi default Google Cloud CLI Anda.

  3. Fitur ini mendukung library klien di Go, Python, dan Java. Anda harus menetapkan variabel lingkungan untuk mengaktifkan mTLS untuk Python dan Java.

  4. Untuk membuat dan menguji akses mTLS ke Cloud de Confiance API, Anda dapat menggunakan contoh kode berikut.

    Go

    1. Gunakan contoh berikut untuk membuat file Go, seperti golang_test.go.

      package golang_test

import (
     "io"
     "log"
     "testing"

     "cloud.google.com/go/auth/credentials"
     "cloud.google.com/go/auth/httptransport"
)

func TestGoExample(t *testing.T) {

     scopes := []string{
             "https://www.googleapis.com/auth/pubsub", // Scope for Pub/Sub access
             // Add other scopes as needed
     }

     dopts := credentials.DetectOptions{
             Scopes: scopes,
     }

     // Create httptransport.Options with the scopes
     opts := &httptransport.Options{
             DetectOpts: &dopts,
     }
     hc, err := httptransport.NewClient(opts)
     if err != nil {
             t.Fatalf("NewHTTPClient: %v", err)
     }

     resp, err := hc.Get("https://pubsub.mtls.googleapis.com/v1/projects/PROJECT_ID/topics")
     if err != nil {
             t.Fatalf("Get: %v", err)
     }
     t.Logf("Status: %s", resp.Status)

     t.Cleanup(func() {
            resp.Body.Close()
     })

     b, err := io.ReadAll(resp.Body)
     if err != nil {
            t.Fatal(err)
     }
     log.Println(string(b))
}

      Ganti PROJECT_ID dengan ID project Google Cloud CLI Anda.

    2. Untuk menjalankan pengujian pada VM Compute Engine, gunakan perintah berikut.

    go mod init example.com
go mod tidy
go test -v golang_test.go --count=1

    Python

    1. Gunakan contoh berikut untuk membuat file pengujian, seperti python_test.py.

      import google.auth
import google.auth.transport.requests
import requests

def test_go_example():
# Define the required scopes for your application
scopes = [
   "https://www.googleapis.com/auth/pubsub",  # Scope for Pub/Sub access
   # Add other scopes as needed
]

# Obtain Application Default Credentials (ADC) with the specified scopes
credentials, _ = google.auth.default(scopes=scopes)

# Create an authorized HTTP session using the ADC credentials
authed_session = google.auth.transport.requests.AuthorizedSession(credentials)

try:
# Make a GET request to the Pub/Sub API endpoint
response = authed_session.get(
    "https://pubsub.mtls.googleapis.com/v1/projects/PROJECT_ID/topics"
)

# Check if the request was successful
response.raise_for_status()  # Raise an exception for error statuses

# Log the response status and content
print(f"Status: {response.status_code}")
print(response.text)

except requests.exceptions.RequestException as e:
print(f"Error making the request: {e}")

if __name__ == "__main__":
test_go_example()

      Ganti PROJECT_ID dengan ID project Google Cloud CLI Anda.

    2. Untuk menjalankan pengujian pada VM Compute Engine, selesaikan langkah-langkah berikut.

      1. Siapkan lingkungan virtual Python.

      2. Instal library yang diperlukan.

        pip install google-auth google-auth-httplib2 requests

      3. Jalankan pengujian:

        python3 python_test.py

Memberikan otorisasi menggunakan permintaan HTTP biasa

Untuk mengotorisasi workload Workforce Identity Federation menggunakan permintaan HTTP biasa, selesaikan langkah-langkah berikut.

  1. Dapatkan token akses yang terikat sertifikat dari Cloud de Confiance Security Token Service melalui handshake mTLS standar.

  2. Panggil layanan dengan token akses yang Anda dapatkan dari Security Token Service. Cloud de Confiance Contoh ini mengkueri Cloud Storage.

    $ curl --key ${workload_key.pem} --cert ${workload_cert.pem} -X GET 'https://storage.mtls.googleapis.com/{replace_with_your_resources}' -H "Authorization: Bearer $ACCESS_TOKEN"

  3. Binding mTLS menerapkan penggunaan mTLS. Jalankan perintah berikut untuk memverifikasi bahwa koneksi non-mTLS gagal dengan error tidak sah.

    $ curl -X GET 'https://storage.googleapis.com/{replace_with_your_resources}' -H "Authorization: Bearer $ACCESS_TOKEN"

Mencantumkan binding kebijakan

Untuk mencantumkan binding kebijakan untuk Workload Identity Federation, jalankan perintah berikut.

gcloud

Perintah berikut mencantumkan binding tertentu dalam organisasi tertentu, memfilter binding yang berlaku untuk principal gabungan.

gcloud alpha access-context-manager cloud-bindings list \
--organization=ORG_ID \
--filter='principal:federatedPrincipal'

curl 

curl -H "X-Goog-User-Project: ${CALLER_PROJECT_ID:?}" -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://accesscontextmanager.googleapis.com/v1alpha/organizations/${ORG_ID:?}/gcpUserAccessBindings?filter=principal%3Afederated_principal"

Memperbarui binding kebijakan

Untuk memperbarui binding kebijakan, tambahkan tingkat akses baru ke file JSON dan jalankan perintah berikut.

gcloud 

gcloud alpha access-context-manager cloud-bindings update \
--binding=BINDING_ID \
--level=NEW_ACCESS_LEVEL_ID

curl 

curl -H "X-Goog-User-Project: ${CALLER_PROJECT_ID:?}" -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -d @request.json \
"https://accesscontextmanager.googleapis.com/v1alpha/organizations/${ORG_ID:?}/gcpUserAccessBindings/${BINDING_ID:?}?updateMask=access_levels"

Menghapus binding kebijakan

Untuk menghapus binding kebijakan, jalankan perintah berikut.

gcloud 

gcloud alpha access-context-manager cloud-bindings delete \
--binding=BINDING_ID

curl 

curl -H "X-Goog-User-Project: ${CALLER_PROJECT_ID:?}" -X DELETE \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://accesscontextmanager.googleapis.com/v1alpha/organizations/${ORG_ID:?}/gcpUserAccessBindings/${BINDING_ID:?}"

Pemecahan masalah

Berikut adalah beberapa masalah umum dan tindakan yang disarankan untuk menyelesaikannya:

  • Error: 403 Forbidden, user does not have permission.

    Tindakan: Periksa kebijakan IAM untuk memverifikasi bahwa workload identity pool memiliki akses ke resource Anda. Cloud de Confiance

  • Error: Unauthorized_client: Could not obtain a value for google.subject from the given credential.

    Tindakan: Backend tidak dapat mengekstrak nilai untuk google.subject dari sertifikat klien Anda berdasarkan pemetaan atribut. Periksa sertifikat klien Anda untuk memverifikasi bahwa kolom yang Anda gunakan untuk melakukan pemetaan memiliki nilai.

  • Jika Anda mengalami penolakan akses yang tidak terduga setelah mengaktifkan Akses Kontekstual, Anda dapat dengan cepat membatalkan pemblokiran traffic dengan menghapus binding Akses Kontekstual menggunakan perintah berikut:

    gcloud alpha access-context-manager cloud-bindings delete

    Setelah akses dipulihkan, tinjau log audit untuk menentukan alasan permintaan ditolak.