Mengelola akses untuk agen yang di-deploy

Ada berbagai jenis metode autentikasi yang tersedia untuk berbagai mode akses:

Kasus penggunaan Metode autentikasi Tentang metode autentikasi ini
Mengakses sumber data langsung dari dalam agen. Service account Agen yang di-deploy memiliki akses ke semua resource yang izin aksesnya dimiliki akun layanan mereka.
Mengirim permintaan ke endpoint menggunakan kunci API dari dalam agen. Kunci API Pastikan API yang ingin Anda gunakan mendukung kunci API sebelum menggunakan metode autentikasi ini.
Menangani akun pengguna, pendaftaran, login, atau otorisasi untuk pengguna akhir agen. Client ID OAuth Memerlukan agen Anda untuk meminta dan menerima izin dari pengguna.

Peran

Agen yang Anda deploy di Agent Engine berjalan menggunakan akun layanan AI Platform Reasoning Engine Service Agent yang cocok dengan service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

Akun layanan memiliki peran (roles/aiplatform.reasoningEngineServiceAgent) Vertex AI Reasoning Engine Service Agent yang memberikan izin default yang diperlukan untuk agen yang di-deploy. Anda dapat melihat daftar lengkap izin default di dokumentasi IAM.

Mencantumkan peran agen yang di-deploy

Konsol

  1. Buka halaman IAM, lalu centang kotak "Sertakan pemberian peran yang disediakan Google".

    Buka IAM

  2. Pilih project yang sesuai dengan project Google Cloud Anda.

  3. Temukan Akun utama yang cocok dengan service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  4. Peran agen yang di-deploy dapat ditemukan di kolom Peran.

gcloud

Pertama, instal dan lakukan inisialisasi gcloud CLI. Kemudian, jalankan perintah berikut:

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

di mana

  • PROJECT_ID_OR_NUMBER adalah ID atau nomor untuk project Anda, dan
  • PRINCIPAL didasarkan pada akun layanan yang dibuat saat agen di-deploy di Agent Engine.

Untuk mengetahui detailnya, buka dokumentasi IAM dan referensi CLI.

Python

Pertama, instal library klien dengan menjalankan

pip install google-api-python-client

Kemudian, autentikasi diri Anda, dan jalankan perintah berikut untuk mencantumkan peran agen yang di-deploy:

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

Dengan PRINCIPAL didasarkan pada akun layanan yang dibuat saat agen di-deploy di Agent Engine.

Memberikan peran untuk agen yang di-deploy

  1. Buka halaman IAM, lalu centang kotak "Sertakan pemberian peran yang disediakan Google".

    Buka IAM

  2. Pilih project yang sesuai dengan project Google Cloud Anda.

  3. Temukan Akun utama yang cocok dengan service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  4. Tambahkan peran yang diperlukan ke Prinsipal dengan mengklik tombol edit, menambahkan peran, lalu mengklik tombol simpan.

gcloud

Pertama, instal dan lakukan inisialisasi gcloud CLI. Kemudian, jalankan perintah berikut:

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

di mana

  • PRINCIPAL didasarkan pada akun layanan yang dibuat saat agen di-deploy di Agent Engine.
  • ROLE_NAME adalah nama peran yang ingin Anda berikan. Untuk mengetahui daftar peran bawaan, lihat Memahami peran.

Untuk mengetahui detailnya, buka dokumentasi IAM dan referensi CLI.

Python

Sebaiknya jangan menulis kode Python Anda sendiri untuk memberikan atau mencabut peran untuk agen yang di-deploy. Sebagai gantinya, sebaiknya gunakan konsol Google Cloud atau gcloud untuk operasi satu kali, atau Terraform untuk mengelola kontrol akses IAM secara terprogram. Jika Anda ingin atau perlu melakukannya di Python, lihat dokumentasi untuk library klien IAM.

Mencabut peran dari agen yang di-deploy

  1. Buka halaman IAM, lalu centang kotak "Sertakan pemberian peran yang disediakan Google".

    Buka IAM

  2. Pilih project yang sesuai dengan project Google Cloud Anda.

  3. Temukan Akun utama yang cocok dengan service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

  4. Cabut peran dari Akun utama dengan mengklik tombol edit, menghapus peran yang sesuai, sebelum mengklik tombol simpan.

gcloud

Pertama, instal dan lakukan inisialisasi gcloud CLI. Kemudian, jalankan perintah berikut:

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

di mana

  • PRINCIPAL didasarkan pada akun layanan yang dibuat saat agen di-deploy di Agent Engine.
  • ROLE_NAME adalah nama peran yang ingin Anda cabut. Untuk mengetahui daftar peran bawaan, lihat Memahami peran.

Untuk mengetahui detailnya, buka dokumentasi IAM dan referensi CLI.

Python

Sebaiknya jangan menulis kode Python Anda sendiri untuk memberikan atau mencabut peran untuk agen yang di-deploy. Sebagai gantinya, sebaiknya gunakan konsol Google Cloud atau gcloud untuk operasi satu kali, atau Terraform untuk mengelola kontrol akses IAM secara terprogram. Jika Anda ingin atau perlu melakukannya di Python, lihat dokumentasi untuk library klien IAM.

Rahasia

Secret berisi satu atau beberapa versi secret, beserta metadata seperti label dan informasi replikasi. Payload sebenarnya dari secret disimpan dalam versi secret. Secret dikelola (melalui Secret Manager) di tingkat project, dan dapat dibagikan di seluruh agen yang di-deploy. Untuk mencantumkan secret yang sesuai dengan agen di Secret Manager, Anda dapat menambahkan label dan menggunakannya untuk pemfilteran.

Membuat secret

Konsol

  1. Buka halaman Secret Manager.

    Buka Secret Manager

  2. Di halaman Secret Manager, klik Buat Secret.

  3. Di kolom Name, masukkan nama untuk secret (misalnya, my-secret).

  4. Opsional: Untuk menambahkan versi secret saat membuat secret awal, di kolom Secret value, masukkan nilai untuk secret tersebut (misalnya, abcd1234).

  5. Buka Labels, lalu klik Add label.

  6. Masukkan kunci dan nilai yang sesuai untuk membuat label.

  7. Klik Buat secret.

gcloud

Pertama, instal dan lakukan inisialisasi gcloud CLI. Kemudian, jalankan perintah berikut:

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

di mana

  • SECRET_ID adalah ID secret atau ID yang sepenuhnya memenuhi syarat untuk secret.
  • FILE_PATH adalah jalur lengkap (termasuk nama file) ke file yang berisi detail versi.

Untuk mengetahui detailnya, buka dokumentasi Secret Manager untuk membuat secret dan versi secret, atau referensi CLI untuk membuat secret dan versi secret.

Python

Pertama, instal library klien dengan menjalankan

pip install google-cloud-secret-manager

Kemudian, autentikasi diri Anda, dan jalankan perintah berikut

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

Mendapatkan secret

Konsol

  1. Buka halaman Secret Manager.

    Buka Secret Manager

  2. Di halaman Secret Manager, klik nama secret yang akan dijelaskan.

  3. Halaman Detail secret mencantumkan informasi tentang secret.

gcloud

Pertama, instal dan lakukan inisialisasi gcloud CLI. Kemudian, jalankan perintah berikut:

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

di mana

  • VERSION_ID adalah ID versi secret, dan
  • SECRET_ID adalah ID secret atau ID yang sepenuhnya memenuhi syarat untuk secret.

Untuk mengetahui detailnya, buka dokumentasi Secret Manager, atau referensi CLI.

Python

Pertama, instal library klien dengan menjalankan

pip install google-cloud-secret-manager

Kemudian, autentikasi diri Anda, dan jalankan perintah berikut

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

Mencantumkan rahasia

Konsol

  1. Buka halaman Secret Manager.

    Buka Secret Manager

  2. Di tabel Secrets, klik kolom Filter.

  3. Pilih properti filter dan nilai yang sesuai, misalnya Location:asia-east1.

  4. Tabel akan otomatis difilter berdasarkan nilai yang dimasukkan.

  5. (Opsional) Untuk memfilter versi secret: pilih secret untuk mengakses versinya, lalu gunakan opsi Filter di tabel Versions.

gcloud

Pertama, instal dan lakukan inisialisasi gcloud CLI.

Untuk menampilkan semua secret project, jalankan perintah berikut:

gcloud secrets list --filter="FILTER"

dengan FILTER adalah string (misalnya name:asecret OR name:bsecret) atau ekspresi reguler (misalnya name ~ "secret_ab.*").

Untuk menampilkan semua versi secret, jalankan perintah berikut:

gcloud secrets versions list SECRET_ID

dengan SECRET_ID adalah ID secret atau ID yang sepenuhnya memenuhi syarat untuk secret.

Untuk mengetahui detailnya, buka dokumentasi Secret Manager untuk memfilter secret dan mencantumkan versi secret, atau referensi CLI untuk mencantumkan secret dan versi secret.

Python

Pertama, instal library klien dengan menjalankan

pip install google-cloud-secret-manager

Kemudian, autentikasi diri Anda, dan jalankan perintah berikut

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

Memperbarui secret

Konsol

  1. Buka halaman Secret Manager.

    Buka Secret Manager

  2. Di halaman Secret Manager, klik kotak centang di samping nama secret.

  3. Jika Panel Info ditutup, klik Tampilkan Panel Info untuk menampilkannya.

  4. Di Panel Info, pilih tab Label.

  5. Klik Tambahkan label, lalu masukkan kunci dan nilai untuk label.

  6. Klik Simpan.

gcloud

Pertama, instal dan lakukan inisialisasi gcloud CLI. Kemudian, jalankan perintah berikut:

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

di mana

  • SECRET_ID adalah ID secret atau ID yang sepenuhnya memenuhi syarat untuk secret,
  • KEY adalah kunci label, dan
  • VALUE adalah nilai label yang sesuai.

Untuk mengetahui detailnya, buka dokumentasi Secret Manager atau referensi CLI.

Python

Pertama, instal library klien dengan menjalankan

pip install google-cloud-secret-manager

Kemudian, autentikasi diri Anda, dan jalankan perintah berikut

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

Menghapus secret

Konsol

  1. Buka halaman Secret Manager.

    Buka Secret Manager

  2. Di halaman Secret Manager, di kolom Actions untuk secret, klik View more.

  3. Di menu, pilih Hapus.

  4. Dalam dialog Delete secret, masukkan nama secret.

  5. Klik tombol Hapus secret.

gcloud

Pertama, instal dan lakukan inisialisasi gcloud CLI.

Untuk menghapus versi secret, jalankan perintah berikut:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

di mana

  • VERSION_ID adalah nama resource versi secret, dan
  • SECRET_ID adalah ID secret atau ID yang sepenuhnya memenuhi syarat untuk secret.

Untuk menghapus secret dan semua versinya, jalankan perintah berikut:

gcloud secrets delete SECRET_ID

dengan SECRET_ID adalah ID secret atau ID yang sepenuhnya memenuhi syarat untuk secret

Untuk mengetahui detailnya, buka dokumentasi Secret Manager untuk menghapus secret dan menghancurkan versi secret, atau referensi CLI untuk menghapus secret dan menghancurkan versi secret.

Python

Pertama, instal library klien dengan menjalankan

pip install google-cloud-secret-manager

Kemudian, autentikasi diri Anda, dan jalankan perintah berikut

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

Klien dan kredensial OAuth

Client ID digunakan untuk mengidentifikasi satu agen ke server OAuth Google. Jika agen Anda berjalan di beberapa platform, setiap platform akan memerlukan client ID-nya sendiri. Pada tingkat yang tinggi, untuk mengintegrasikan agen berbasis OAuth, Anda perlu melakukan hal berikut:

  1. Buat klien dan kredensial OAuth.

  2. Simpan client ID dan secret di Secret Manager. (Lihat Membuat secret).

  3. Akses secret di agen Anda selama pengembangan.

Membuat kredensial klien OAuth

  1. Di konsol Google Cloud, buka halaman Google Auth Platform > Clients.

    Buka Google Auth Platform > Klien

  2. (Jika diperlukan) Jika layar menampilkan "Google Auth Platform belum dikonfigurasi", klik Mulai dan isi Konfigurasi Project. (Data tersebut dapat diperbarui nanti.) Untuk mengetahui detail tentang kesiapan produksi, buka Kepatuhan Kebijakan OAuth 2.0.

  3. Klik Buat Klien.

  4. Tetapkan Application type ke Web application.

  5. Tetapkan nama klien OAuth ke OAUTH_CLIENT_DISPLAY_NAME.

  6. Di bagian Authorized redirect URIs, tambahkan URI untuk REDIRECT_URI.

  7. Di bagian Rahasia Klien, klik tombol "download JSON". Tindakan ini akan mendownload file client_secret.json yang memiliki konten berikut:

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}
  1. Simpan client ID dan secret di Secret Manager, misalnya,
from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

Mencantumkan klien OAuth

  1. Di konsol Google Cloud, buka halaman Google Auth Platform > Clients.

    Buka Google Auth Platform > Klien

  2. Halaman ini akan mencantumkan kredensial klien OAuth yang Anda miliki.

Menghapus klien OAuth

  1. Di konsol Google Cloud, buka halaman Google Auth Platform > Clients.

    Buka Google Auth Platform > Klien

  2. Pilih kredensial klien OAuth yang akan dihapus, lalu klik hapus.