Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Pengelolaan dan Keamanan Kunci API

1. Pengantar

Sebelumnya, kunci API Google digunakan untuk mengakses Google API saat metode lain tidak tersedia atau dianggap tidak praktis. Kasus penggunaan yang populer adalah akses ke Google Maps API dan Google API yang diekspos oleh Firebase. Dengan diperkenalkannya model AI, agen AI seperti Gemini, serta framework pengembangan Agen dan AI Studio seperti Agent Development Kit, kunci API telah menjadi metode utama untuk mengakses Model Bahasa Besar Google.

Kunci API menawarkan tingkat perlindungan yang rendah. Meskipun Google Cloud menyediakan beberapa metode untuk mencegah penyalahgunaan kunci, kepemilikan kunci API aktif memungkinkan akses ke Google API tanpa validasi autentikasi atau otorisasi tambahan. Metode untuk membatasi penggunaan kunci API dijelaskan dalam dokumentasi. Postingan Mengamankan Kunci Gemini dan Google API Anda di Cloud Blog memberikan rekomendasi tambahan tentang pemeliharaan kunci API. Dalam Codelab ini, Anda akan mempraktikkan rekomendasi ini.

Yang akan Anda lakukan

Meninjau pembatasan yang diterapkan saat membuat kunci API baru di Google Cloud
Buat katalog semua kunci API Anda, dan temukan kunci yang tidak memiliki perlindungan keamanan
Menerapkan batasan pada kunci API yang ada berdasarkan penggunaannya
Menentukan otomatisasi yang menghapus kunci jika terjadi penggunaan yang tidak normal

Yang Anda butuhkan

Browser web modern (seperti Chrome).
Akun Google

2. Penyiapan

Petunjuk dalam Codelab ini mengasumsikan bahwa Anda menjalankan perintah di Cloud Shell di Konsol Google Cloud. Jika memiliki gcloud CLI di lingkungan lokal, Anda dapat menjalankan perintah di sana.

Meskipun operasi dalam langkah-langkah dapat dilakukan menggunakan UI Konsol Cloud, metodenya berbeda. Codelab ini menggunakan antarmuka command line untuk menyederhanakan interaksi dan memungkinkan integrasi yang lebih mudah dengan agen AI modern (seperti Antigravity CLI).

Mulai terminal Cloud Shell

Buka konsol Google Cloud menggunakan https://console.cloud.google.com/ di jendela browser baru. Sebaiknya gunakan Chrome untuk mendapatkan pengalaman pengguna terbaik.
Login ke Akun Google Anda di Google Cloud.
Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
Jika ditampilkan, klik jendela berikut:
- Lanjutkan melalui jendela informasi Cloud Shell.
- Beri otorisasi ke Cloud Shell untuk menggunakan kredensial Anda guna melakukan panggilan Google Cloud API.

Pilih project Google Cloud

Setelah membuka Konsol Cloud, Anda akan diautentikasi, dan biasanya ada pilihan project untuk pekerjaan Anda. Project ID adalah urutan 6 hingga 30 karakter yang terdiri dari huruf kecil, angka, dan simbol tanda hubung, misalnya qwiklabs-gcp-04-3075fc9fd77f. Terminal Cloud Shell mengonfigurasi CLI gcloud dengan project yang dipilih. Anda akan melihat output yang mirip dengan berikut ini:

Your Cloud Platform project in this session is set to qwiklabs-gcp-04-3075fc9fd77f

Artinya, perintah Anda selanjutnya ke gcloud akan menggunakan project ID qwiklabs-gcp-04-3075fc9fd77f.

Tetapkan project ID sebagai variabel lingkungan PROJECT_ID. Anda dapat melihat daftar semua project Anda menggunakan perintah berikut:

gcloud projects list

Ganti your-project-id dan jalankan perintah jika Anda ingin menggunakan project ID yang berbeda dari yang dikonfigurasi di gcloud.
```
export PROJECT_ID="your-project-id"
```
Contoh:
```
export PROJECT_ID="qwiklabs-gcp-04-3075fc9fd77f"
```
Jalankan perintah berikut jika Anda ingin menggunakan project ID yang dipilih:
```
export PROJECT_ID=$(gcloud config get project)
```

3. Membatasi Kunci API Baru

Sebelumnya, pengguna dapat membuat kunci API yang tidak dibatasi sepenuhnya. Kunci yang tidak dibatasi dapat digunakan untuk memanggil API Google APA PUN yang diaktifkan di project tempat kunci dibuat. Meskipun konsol Google Cloud mencegah pengguna membuat kunci yang tidak dibatasi, hal ini masih dapat dilakukan menggunakan gcloud CLI atau menggunakan panggilan API langsung.

Langkah-langkah berikut menunjukkan cara membuat kunci API terbatas yang membatasi penggunaan ke API tertentu dan oleh situs yang ditentukan.

Untuk membuat kunci API baru yang dibatasi untuk digunakan dengan Google Maps Geolocation API saja, jalankan perintah berikut di terminal shell:
```
gcloud services api-keys create --key-id=restricted-api-key \
  --display-name="restricted api key" \
  --api-target=service=geolocation.googleapis.com \
  --project=${PROJECT_ID}
```
Perintah ini membuat kunci API baru yang dapat digunakan HANYA untuk memanggil layanan geolokasi Google Maps.
ℹ️ Catatan: Anda dapat menambahkan beberapa API ke dalam daftar yang dibatasi. Gunakan beberapa parameter --api-target dengan nilai =service=SERVICE.googleapis.com, dengan SERVICE adalah salah satu layanan Google.
Tingkatkan keamanan kunci dengan menambahkan pembatasan aplikasi. Batasi penggunaan kunci ke semua jalur dalam situs example.com saja. Jalankan perintah berikut untuk menambahkan batasan aplikasi ke kunci:
```
gcloud services api-keys update restricted-api-key \
  --location=global \
  --allowed-referrers="example.com/*" \
  --project=${PROJECT_ID}
```
Daripada mengizinkan penggunaan kunci ke situs tertentu, Anda dapat menggunakan --allowed-application untuk menentukan aplikasi Android yang diizinkan atauallowed-ips untuk menentukan alamat IP yang diizinkan. Lihat dokumentasi lengkap untuk mengetahui semua opsi.
ℹ️ Catatan: Anda dapat menambahkan lebih dari satu pembatasan aplikasi dengan jenis SAMA dengan memberikan beberapa parameter (misalnya, --allowed-referrers). Menambahkan beberapa jenis pembatasan aplikasi hanya akan menyimpan jenis terbaru dalam daftar parameter.

Pembersihan

Hapus kunci API yang Anda buat kecuali jika Anda berencana menggunakannya:

gcloud services api-keys delete --key-id=restricted-api-key \
  --project=${PROJECT_ID}

4. Mengatalogkan Kunci API Anda

Pada langkah ini, Anda akan menggunakan gcloud CLI untuk mendapatkan inventaris kunci API Anda. Daftar yang dihasilkan menampilkan semua kunci API yang aktif (tidak dihapus) yang dapat Anda akses.

Jalankan perintah berikut untuk melihat semua nama kunci, ID, dan tanggal pembuatan:
```
gcloud services api-keys list --project=${PROJECT_ID} \
  --format='value(displayName,name.basename(),createTime.date())'
```
Output akan menampilkan nama kunci yang mudah dibaca, ID kunci, dan tanggal kunci dibuat. Tampilannya akan terlihat seperti berikut:
```
api key 1	api-key-1	2024-05-10T07:53:24
api key 2	api-key-2	2025-06-12T14:47:57
```
Pilih salah satu ID utama dan tempel perintah berikut untuk memeriksa apakah kunci memiliki batasan. Ganti your-key-id dengan nilai ID kunci yang dipilih:
```
gcloud services api-keys describe "your-key-id" --project=${PROJECT_ID}
```

Output (dalam YAML) akan berisi daftar batasan di bagian restrictions.

createTime: '2024-05-10T07:53:24.986528Z'
displayName: api key 1
etag: W/"u1WuY41K2tPKUZd7cfLoKg=="
name: projects/123456789012/locations/global/keys/api-key-1
restrictions:
  apiTargets:
  - service: geolocation.googleapis.com
  browserKeyRestrictions:
    allowedReferrers:
    - https://example.com/*
uid: 1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6
updateTime: '2024-05-10T07:53:24.071228Z'

Perhatikan bahwa jika kunci tidak pernah diperbarui, kolom createTime dan updateTime akan memiliki stempel waktu yang sama.

Download dan jalankan skrip yang akan memeriksa semua project Anda dan mencetak semua kunci API yang TIDAK memiliki batasan:

curl -fsSL -o unrestricted_api_keys.sh \
  "https://github.com/GoogleCloudPlatform/devrel-demos/blob/main/security/api-key-audit/unrestricted_api_keys.sh"
chmod +x unrestricted_api_keys.sh
./unrestricted_api_keys.sh

Setelah menjalankan skrip, Anda akan melihat output dalam bentuk:

DISPLAY NAME    KEY ID    PROJECT ID    CREATION DATE
Key 1    1a2b3c4d-1234-abcd-1234-a1b2c3d4e5f6    my-project-1    2024-05-10T07:53:24.071228Z

Anda dapat menemukan semua skrip yang digunakan dalam CodeLab ini di folder Security di repositori devrel-demos di GitHub.

5. Menemukan Penggunaan Kunci API

Pada langkah ini, Anda akan membuat kueri metrik Google Cloud yang membantu Anda menemukan API yang dipanggil menggunakan kunci API Anda. Dengan informasi ini, Anda dapat meninjau penggunaan kunci saat ini dan menerapkan pembatasan API pada kunci berdasarkan informasi sebenarnya, bukan menebak-nebak.

Gunakan ID kunci yang sama dengan yang Anda gunakan pada langkah sebelumnya atau pilih ID kunci lain. Ganti your-key-id dengan ID kunci yang dipilih dalam perintah berikut:
```
export KEY_UID=$(
   gcloud services api-keys describe "your-key-id" \
   --format='value(uid)' \
   --project=${PROJECT_ID})
```
Setel penelusuran untuk melihat kembali histori penggunaan selama satu tahun. Jika Anda ingin mencari jangka waktu yang lebih lama atau lebih singkat, ganti 365 (jumlah hari) dengan angka positif lain.
```
export DAYS=365
```
Perbarui Kredensial Default Aplikasi (ADC) untuk mengaktifkan panggilan langsung ke Cloud Monitoring API. Jalankan perintah berikut dan ikuti petunjuk di terminal:
```
gcloud auth application-default login
```
Jalankan perintah berikut untuk mengirim permintaan data metrik penggunaan layanan ke Cloud Monitoring API:

curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  --data-urlencode "filter=metric.type=\"serviceruntime.googleapis.com/api/request_count\" AND resource.labels.credential_id=\"apikey:${KEY_UID}\"" \
  --data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)" \
  --data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  "https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries" \
  | jq -r '.timeSeries[]?.resource.labels.service' | sort -u

Perintah ini mengkueri metrik bawaan serviceruntime/api/request_count untuk titik data dengan label credential_id yang cocok dengan ID unik kunci API yang dipilih. Kemudian, kode tersebut mengambil nilai untuk label service dan mencetak nilai sambil menghilangkan pengulangan.

Memperkuat keamanan kunci API

Pada langkah ini, Anda akan menggunakan informasi yang dikumpulkan pada langkah sebelumnya untuk memperbarui konfigurasi pembatasan kunci API berdasarkan info penggunaan.

Anda akan menggunakan kunci API yang sama dengan yang digunakan pada langkah sebelumnya. Jika perlu, jalankan kembali petunjuk dari langkah-langkah sebelumnya untuk memastikan variabel lingkungan PROJECT_ID, KEY_UID, dan DAYS telah ditetapkan.

Jalankan perintah berikut untuk mengambil daftar Google API yang dipanggil menggunakan kunci API:

SERVICES=$(curl -s -G -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
–data-urlencode "filter=metric.type="serviceruntime.googleapis.com/api/request_count" AND resource.labels.credential_id="apikey:${KEY_UID}""
–data-urlencode "interval.startTime=$(date -u -d "${DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)"
–data-urlencode "interval.endTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
"https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries"
| jq -r ‘.timeSeries[]?.resource.labels.service' | sort -u)

1. Build the list of arguments to restrict the API usage for the API key based
on the retrieved list.

```shell
API_TARGET_ARGS=()
for SERVICE in $SERVICES; do
  API_TARGET_ARGS+=("--api-target=service=${SERVICE}")
done

Mengganti daftar API yang dibatasi untuk daftar yang tidak kosong:

if [ ${#API_TARGET_ARGS[@]} -gt 0 ]; then
    gcloud services api-keys update "projects/${PROJECT_ID}/locations/global/keys/${KEY_UID}" \
    ${API_TARGET_ARGS}
fi

6. Mendefinisikan Deteksi Penggunaan Anomali

Langkah-langkah sebelumnya menunjukkan cara menjelajahi dan memperkuat kunci API. Langkah ini menunjukkan cara mengotomatiskan respons terhadap lonjakan penggunaan kunci yang tidak terduga dengan bantuan Pemberitahuan Monitoring.

Petunjuk berikut membuat pemberitahuan yang dipicu saat rasio panggilan API yang menggunakan kunci API meningkat lebih dari 10% selama 5 menit terakhir. Peringatan dikonfigurasi untuk memicu skrip Cloud Build yang menghapus kunci API untuk mencegah penggunaan lebih lanjut. Kunci dapat dipulihkan selama 30 hari ke depan. Lihat dokumentasi untuk mempelajari cara mengurungkan penghapusan kunci.

Petunjuk ini menggunakan kembali variabel PROJECT_ID dan KEY_UID yang Anda gunakan di langkah sebelumnya. Jika Anda ingin memilih kunci dan/atau project lain, tetapkan nilai baru untuk variabel ini seperti yang dijelaskan dalam langkah-langkah Penyiapan dan Temukan Penggunaan Kunci API.

Jalankan skrip berikut untuk membuat file kebijakan pemberitahuan:

cat <<EOF > alert_policy.json
{
  "displayName": "Credential API Request Count Increase Alert (Project: ${PROJECT_ID})",
  "combiner": "OR",
  "conditions": [
    {
      "displayName": "API Request Count Increase > 10% in 5m with Min Volume",
      "conditionPrometheusQueryLanguage": {
        "query": "(sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) / (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m] offset 5m)) or on() vector(1)) > 1.10) and (sum(increase(serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\\"apikey:${KEY_UID}\\"}[5m])) > 50)",
        "duration": "0s",
        "evaluationInterval": "60s"
      }
    }
  ],
  "enabled": true
}
EOF

Kebijakan pemberitahuan menggunakan filter PromQL berikut untuk memicu pemberitahuan:

 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m])
 ) /
 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id="API_KEY_UID"}[5m] offset 5m)
 ) or on() vector(1)) > 1.10)
and
 (sum(
   increase(
     serviceruntime_googleapis_com:api_request_count{metric_label_credential_id=\"YOUR_CREDENTIAL_ID_HERE\"}[5m])) > 50)

Metrik ini menghitung tingkat peningkatan dan membandingkannya dengan jangka waktu sebelumnya. Pemberitahuan hanya dipicu jika nilainya lebih besar 10%. Untuk menghindari pemicuan pemberitahuan saat jumlah total panggilan dapat diabaikan, pemicuan ini dikondisikan agar memiliki lebih dari 50 panggilan API dalam periode tersebut. Untuk menghindari perhitungan NaN (hapus dengan nol) saat rasio 5 menit sebelumnya adalah 0, penyebut diganti dengan 1 jika rasio periode sebelumnya adalah nol.Anda dapat mengubah parameter pemberitahuan seperti panjang periode (5m), nilai minimum (50), atau nilai minimum peningkatan 10% (1.10).Parameter kebijakan tambahan menentukan bahwa setelah kondisi tercapai, pemberitahuan harus dipicu (duration) dan kondisi harus diselidiki setiap 60 detik (evaluationInterval).

Jalankan perintah berikut untuk membuat topik PubSub yang akan digunakan untuk memposting notifikasi pemberitahuan:
```
gcloud pubsub topics create api-key-alert-notifications --project=$PROJECT_ID
```

Jalankan perintah berikut untuk membuat saluran notifikasi untuk pemberitahuan yang menggunakan PubSub.

CHANNEL_NAME=$(gcloud beta monitoring channels create \
  --display-name="Pub/Sub Alert Channel" \
  --type="pubsub" \
  --channel-labels="topic=projects/$PROJECT_ID/topics/api-key-alert-notifications" \
  --format='value(name)' \
  --project=$PROJECT_ID)

Anda akan menggunakan variabel lingkungan CHANNEL_NAME di langkah Pembersihan.

Jalankan perintah berikut untuk membuat pemberitahuan pemantauan baru:

gcloud monitoring policies create --policy-from-file=alert_policy.json \
  --project=$PROJECT_ID

Jalankan perintah berikut untuk memberikan izin layanan Cloud Build agar dapat menghapus kunci API di project.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/apikeys.admin"

Anda dapat membatasi peran apikeys.admin agar hanya memanipulasi instance kunci API tertentu. Lihat kondisi IAM untuk mengetahui detail selengkapnya.

Jalankan skrip berikut untuk membuat pemicu Cloud Build yang menghapus kunci API.

cat <<EOF > trigger_config.yaml
name: "delete-compromised-api-key"
description: "Triggered by Pub/Sub alert to automatically delete the leaking API Key"
pubsubConfig:
  topic: "projects/${PROJECT_ID}/topics/api-key-alert-notifications"
build:
  steps:
  - name: "gcr.io/google.com/cloudsdktool/cloud-sdk:slim"
    args:
    - "gcloud"
    - "services"
    - "api-keys"
    - "delete"
    - "${KEY_UID}"
    - "--quiet"
EOF

Jalankan perintah berikut untuk membuat pemicu Pemberitahuan Pemantauan baru:

gcloud builds triggers create pubsub \
  --trigger-config=trigger_config.yaml \
  --project=$PROJECT_ID

Sekarang Anda dapat menghapus file konfigurasi pemicu Cloud Build dan kebijakan pemberitahuan:

rm alert_policy.json trigger_config.yaml

Atau, Anda dapat menyiapkan otomatisasi ini menggunakan rencana Terraform. Download file Terraform dari folder abnormal-usage-detection di repositori Google Cloud DevRel. Paket ini menerima project ID dan UID Kunci API sebagai parameter input serta menyiapkan resource dan konfigurasi yang Anda lihat di langkah ini.

7. Pembersihan

Untuk menghindari biaya yang tidak terduga pada akun Google Cloud Anda, jangan lupa untuk menghapus topik Pub/Sub, pemicu Cloud Build, dan kebijakan pemberitahuan yang dibuat selama latihan ini.

Jalankan perintah berikut untuk menghapus semua resource yang Anda buat:

gcloud builds triggers delete delete-compromised-api-key \
  --project=$PROJECT_ID
gcloud beta monitoring channels delete $CHANNEL_NAME \
  --project=$PROJECT_ID \
  --quiet
gcloud pubsub topics delete api-key-alert-notifications \
  --project=$PROJECT_ID
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/apikeys.admin"

8. Ringkasan

Dalam codelab ini, Anda telah menerapkan framework keamanan dan otomatisasi end-to-end yang andal untuk kunci API Google Cloud:

Konfigurasi Default yang Diperkuat: Anda membuat dan membatasi kunci API untuk membatasi akses secara eksklusif ke API yang diperlukan dan platform tepercaya (seperti perujuk HTTP tertentu).
Mengaudit Inventaris Kunci Anda: Anda memindai lingkungan project untuk mendeteksi dan mengisolasi kunci tidak terbatas yang menimbulkan risiko keamanan langsung.
Data Penggunaan yang Dianalisis: Anda secara terprogram mengkueri data metrik Cloud Monitoring untuk memprofilkan penggunaan kunci historis, sehingga Anda dapat membatasi kunci berdasarkan jejak penggunaan yang terverifikasi.
Automated Threat Mitigation: Anda membuat "pemutus sirkuit" reaktif dengan menghubungkan kebijakan pemberitahuan Cloud Monitoring ke topik Pub/Sub dan pemicu Cloud Build, sehingga Anda dapat menghapus kunci yang disusupi secara otomatis selama lonjakan traffic yang tidak normal.

Langkah Berikutnya

Menerapkan batasan pada semua kunci API Anda: Gunakan apa yang Anda pelajari di lab ini untuk mendeteksi semua kunci API yang dibatasi sebagian atau tidak dibatasi, lalu terapkan pembatasan API dan klien.
Menyiapkan "pemutus arus listrik" pada kunci API: Lindungi lebih lanjut kunci API Anda dari penggunaan yang tidak terduga dengan menyiapkan penghapusan kunci otomatis jika terjadi peningkatan konsumsi yang tiba-tiba. Gunakan perintah gcloud atau Terraform yang ditampilkan di lab. Pertimbangkan untuk memperketat izin dengan memanfaatkan kondisi IAM
Jelajahi Pemberitahuan Monitoring: Pelajari lebih lanjut cara menyiapkan pemberitahuan menggunakan layanan Google Cloud Monitoring.
Pelajari lebih lanjut kontrol akses yang tersedia di Google Cloud: Tinjau Kebijakan Batas Akses dan propagasi perubahan akses.