Menambahkan batasan ke kunci API

Kunci API mengidentifikasi aplikasi atau situs Anda ke Google Cloud. Pembatasan kunci API memastikan bahwa hanya aplikasi dan situs Anda yang dapat menggunakan kunci Anda. Untuk alasan keamanan, sebaiknya tambahkan batasan yang menentukan:

Klien atau situs mana yang dapat menggunakan kunci API Anda.
Google Cloud API yang dapat dipanggil aplikasi Anda menggunakan kunci API Anda.

Jika klien menggunakan kunci API yang dibatasi untuk mengeluarkan permintaan yang tidak memenuhi pembatasan kunci API, permintaan akan gagal. Misalnya, jika kunci API memerlukan permintaan HTTP dikeluarkan dari domain tertentu, tetapi permintaan HTTP diterima dari domain lain, permintaan akan ditolak dengan error.

Anda dapat menambahkan batasan saat membuat kunci API dengan metode CreateKey, atau Anda dapat menambahkan batasan setelah kunci dibuat menggunakan metode UpdateKey. Halaman ini menjelaskan batasan yang dapat Anda tambahkan ke kunci API, dan menunjukkan cara menambahkan batasan tersebut.

Sebelum memulai

Halaman ini menggunakan curl dan Google Cloud CLI untuk mengirim permintaan ke API Keys API. Lihat Mulai menggunakan API Kunci API untuk mengetahui detail tentang cara menyiapkan eksperimen dengan API.

Menambahkan batasan klien

Pembatasan klien menentukan situs, alamat IP, atau aplikasi mana yang dapat menggunakan kunci API. Anda menambahkan pembatasan klien berdasarkan jenis klien yang memanggil API Anda. Anda dapat menentukan salah satu jenis batasan klien berikut:

browserKeyRestrictions: Perujuk HTTP (situs) yang diizinkan untuk menggunakan kunci.
serverKeyRestrictions: Alamat IP penelepon yang diizinkan untuk menggunakan kunci.
androidKeyRestrictions: Aplikasi Android yang diizinkan untuk menggunakan kunci.
iosKeyRestrictions: Aplikasi iOS yang diizinkan untuk menggunakan kunci.

Menambahkan batasan browser

Contoh berikut menunjukkan cara memanggil metode UpdateKey untuk membatasi perujuk HTTP ke www.example.com:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions \
  --request PATCH \
  --data '{
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": "www.example.com"
      }
    },
    "etag": "ETAG"
  }'

Jika respons dari operations.get berisi "done": true, response berisi Key yang diperbarui dengan batasan.

Contoh berikut menunjukkan cara membuat kunci API baru yang hanya mengizinkan permintaan HTTP dari daftar URL tertentu.

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys \
  --request POST \
  --data '{
    "displayName" : "API key with browser restrictions",
    "restrictions" : {
      "browserKeyRestrictions": {
        "allowedReferrers": ["www.example.com", "www.example-2.com"]
      }
    }
  }'

Tabel berikut menunjukkan beberapa skenario contoh dan pembatasan browser:

Skenario	Pembatasan
Izinkan URL apa pun di situs Anda	Anda harus menetapkan dua URL dalam daftar `allowedReferers`. URL untuk domain, tanpa subdomain, dan dengan karakter pengganti untuk jalur. Contoh: `example.com/` URL kedua yang menyertakan karakter pengganti untuk subdomain dan karakter pengganti untuk jalur. Contoh: `.example.com/*`
Mengizinkan URL tertentu	Menambahkan URL dengan jalur yang tepat. Contoh: `www.example.com/path` `www.example.com/path/path`
Mengizinkan URL apa pun pada subdomain tunggal atau domain tanpa awalan www	Anda harus menetapkan dua URL dalam daftar `allowedReferers` untuk mengizinkan seluruh domain. URL untuk domain, tanpa garis miring setelahnya. Contoh: `www.example.com` `sub.example.com` `example.com` URL kedua untuk domain yang menyertakan karakter pengganti untuk jalur. Contoh: `www.example.com/` `sub.example.com/` `example.com/*`

Menambahkan batasan server

Anda dapat menentukan satu atau beberapa alamat IP pemanggil, misalnya server web atau cron job, yang diizinkan untuk menggunakan kunci API Anda. Anda dapat menentukan alamat IP dalam salah satu format berikut:

IPv4 (198.51.100.1)
IPv6 (2001:db8::1)
Subnet yang menggunakan notasi CIDR (198.51.100.0/24, 2001:db8::/64)

Contoh berikut menunjukkan cara membuat kunci API dengan daftar allowedIps:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with server restrictions with IPv4, IPv6 and CIDR",
    "restrictions" : {
      "serverKeyRestrictions": {
        "allowedIps": ["198.51.100.1","198.51.100.0/24","2001:db8::1","2001:db8::/64"]
      }
    }
  }'

Menambahkan batasan Android

Anda dapat membatasi penggunaan kunci API hanya untuk aplikasi Android Anda. Saat membuat atau memperbarui kunci API, berikan nama paket dan sidik jari SHA-1 20 byte untuk setiap aplikasi.

Misalnya, asumsikan bahwa Anda menjalankan utilitas keytool dan utilitas tersebut membuat sidik jari berikut:

  Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Contoh berikut menunjukkan cara membuat kunci API dengan sidik jari dan nama paket ke androidKeyRestrictions:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with Android restrictions",
    "restrictions" : {
      "androidKeyRestrictions": {
        "allowedApplications": [
          {
            "sha1Fingerprint": "DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09",
            "packageName": "com.example.my.app"
          }
        ]
      }
    }
  }'

Menambahkan batasan iOS

Anda dapat membatasi penggunaan kunci API hanya untuk aplikasi iOS Anda dengan memberikan ID paket setiap aplikasi saat Anda membuat atau memperbarui kunci. Contoh berikut menunjukkan cara menyetel iosKeyRestrictions saat membuat kunci API:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data  '{
    "displayName" : "API key with iOS restrictions",
    "restrictions" : {
      "iosKeyRestrictions": {
        "allowedBundleIds": ["com.example.my.app1", "com.example.my.app2"]
      }
    }
  }'

Menambahkan pembatasan API

Pembatasan API memungkinkan Anda menentukan API mana yang dapat dipanggil menggunakan kunci API. Google Cloud Sebaiknya tambahkan pembatasan klien dan API ke semua kunci API Anda.

Anda dapat menentukan satu atau beberapa layanan dalam pembatasan API. Contoh berikut menunjukkan cara membatasi penggunaan kunci API baru hanya untuk layanan translate.googleapis.com dan datastore.googleapis.com:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys  \
  --request POST \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
  }'

Untuk mendapatkan daftar layanan yang diaktifkan di projectGoogle Cloud Anda, gunakan perintah gcloud services list.

Selain membatasi penggunaan kunci API untuk layanan tertentu, Anda juga dapat menentukan metode di setiap layanan untuk lebih membatasi kunci API. Contoh berikut menunjukkan cara membatasi kunci sebelumnya hanya untuk metode translate.googleapis.com yang diizinkan:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=restrictions  \
  --request PATCH \
  --data '{
    "restrictions": {
      "api_targets": [
        {
          "service": "translate.googleapis.com"
          "methods": [
            "Get*",
            "DetectLanguage"
          ]
        },
        {
          "service" : "datastore.googleapis.com"
        }
      ]
    },
    "etag": "ETAG"
  }'