Membatasi akses API dengan kunci API

OpenAPI | gRPC

Anda dapat menggunakan kunci API untuk membatasi akses ke metode API tertentu atau semua metode dalam API. Halaman ini menjelaskan cara membatasi akses API ke klien tersebut yang memiliki kunci API dan juga menampilkan cara membuat kunci API.

Extensible Service Proxy (ESP) menggunakan Service Control API untuk memvalidasi kunci API dan pengaitannya dengan API yang diaktifkan oleh project. Jika Anda menetapkan persyaratan kunci API di API, permintaan ke metode, class, atau API yang dilindungi akan ditolak kecuali jika memiliki kunci yang dibuat dalam project Anda atau dalam project lain milik developer yang telah Anda berikan akses untuk mengaktifkan API Anda. Project tempat kunci API dibuat tidak dicatat dalam log dan tidak ditambahkan ke header permintaan. Namun, Anda dapat melihat project Google Cloud yang terkait dengan klien di Endpoint > Layanan, seperti yang dijelaskan dalam Memfilter project konsumen tertentu.

Untuk informasi tentang project Google Cloud tempat kunci API harus dibuat, lihat Berbagi API yang dilindungi oleh kunci API.

Membatasi akses ke semua metode API

Untuk mewajibkan kunci API agar dapat mengakses semua metode API:

Buka file openapi.yaml project Anda di editor teks.
Di bagian securityDefinitions:, tambahkan nilai api_key: apiKey, key, query seperti yang ditunjukkan dalam cuplikan kode contoh:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Tindakan ini akan menetapkan "skema keamanan" yang disebut api_key, yang dapat Anda gunakan untuk melindungi API. Untuk opsi definisi api_key lainnya, lihat Batasan definisi kunci API.
Di tingkat atas file (tidak diindentasi atau bertingkat), tambahkan api_key: [] ke perintah security . Anda mungkin perlu menambahkan perintah security atau perintah tersebut mungkin sudah ada:
```
  security:
    - api_key: []
```
Perintah ini menerapkan skema keamanan api_key ke semua metode dalam file. Jangan tempatkan apa pun di dalam kurung. Spesifikasi OpenAPI memerlukan daftar kosong untuk skema keamanan yang tidak menggunakan OAuth.

Membatasi akses ke metode API tertentu

Untuk mewajibkan kunci API untuk metode tertentu:

Buka file openapi.yaml project Anda di editor teks.
Di tingkat atas file (tidak diindentasi atau disarangkan), tambahkan perintah keamanan kosong untuk menerapkannya ke seluruh API:
```
security: []
```
Di bagian securityDefinitions:, tambahkan nilai api_key: apiKey, key, query seperti yang ditunjukkan dalam cuplikan kode contoh:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Tindakan ini akan menetapkan "skema keamanan" yang disebut api_key, yang dapat Anda gunakan untuk melindungi API. Untuk opsi definisi api_key lainnya, lihat Batasan definisi kunci API.
Tambahkan api_key: [] ke perintah security dalam definisi metode:
```
...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security:
  - api_key: []
  produces:
  ...
```
Perintah ini menerapkan skema keamanan api_key ke metode tersebut. Jangan menempatkan apa pun di dalam tanda kurung. Spesifikasi OpenAPI memerlukan daftar kosong untuk skema keamanan yang tidak menggunakan OAuth.

Menghapus pembatasan kunci API untuk metode

Guna menonaktifkan validasi kunci API untuk metode tertentu meskipun Anda telah membatasi akses API untuk API:

Buka file openapi.yaml project Anda di editor teks.

Tambahkan perintah security kosong dalam definisi metode:

...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security: []
  produces:
  ...

Memanggil API menggunakan kunci API

Jika metode API atau API memerlukan kunci API, berikan kunci menggunakan parameter kueri bernama key, seperti yang ditunjukkan dalam contoh curl berikut:

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

dengan ENDPOINTS_HOST dan ENDPOINTS_KEY adalah variabel lingkungan yang masing-masing berisi nama host API dan kunci API Anda.

Membagikan API yang dilindungi oleh kunci API

Kunci API dikaitkan dengan project Google Cloud tempat kunci tersebut dibuat. Jika Anda memutuskan untuk mewajibkan kunci API untuk API, project Google Cloud tempat kunci API dibuat bergantung pada jawaban atas pertanyaan berikut:

Apakah Anda perlu membedakan pemanggil API agar dapat menggunakan fitur Endpoint seperti quotas?
Apakah semua pemanggil API Anda memiliki project Google Cloud-nya sendiri?
Apakah Anda perlu menyiapkan pembatasan kunci API yang berbeda?

Anda dapat menggunakan pohon keputusan berikut sebagai panduan untuk memutuskan project Google Cloud mana yang akan digunakan untuk membuat kunci API.

Memberikan izin untuk mengaktifkan API

Saat perlu membedakan pemanggil API Anda, dan setiap pemanggil memiliki project Google Cloud sendiri, Anda dapat memberikan izin kepada akun utama untuk mengaktifkan API dalam project Google Cloud mereka sendiri. Dengan cara ini, pengguna API Anda dapat membuat kunci API mereka sendiri untuk digunakan dengan API Anda.

Misalnya, tim Anda telah membuat API untuk penggunaan internal oleh berbagai program klien di perusahaan Anda, dan setiap program klien memiliki project Google Cloud-nya sendiri. Untuk membedakan pemanggil API Anda, kunci API untuk setiap pemanggil harus dibuat di project Google Cloud yang berbeda. Anda dapat memberikan izin kepada rekan kerja untuk mengaktifkan API di project Google Cloud yang terkait dengan program klien.

Untuk mengizinkan pengguna membuat kunci API mereka sendiri:

Di project Google Cloud yang mengonfigurasi API Anda, beri setiap pengguna izin untuk mengaktifkan API Anda.
Hubungi pengguna, dan beri tahu bahwa mereka dapat mengaktifkan API Anda di project Google Cloud mereka sendiri dan membuat kunci API.

Membuat project Google Cloud terpisah untuk setiap pemanggil

Jika perlu membedakan pemanggil API, dan tidak semua pemanggil memiliki project Google Cloud, Anda dapat membuat project Google Cloud dan kunci API terpisah untuk setiap pemanggil. Sebelum membuat project, pikirkan nama project tersebut agar Anda dapat dengan mudah mengidentifikasi pemanggil yang terkait dengan project tersebut.

Misalnya, Anda memiliki pelanggan eksternal API, dan Anda tidak tahu bagaimana program klien yang memanggil API Anda dibuat. Mungkin beberapa klien menggunakan layanan Google Cloud dan memiliki project Google Cloud, dan mungkin sebagian tidak. Untuk membedakan pemanggil, Anda harus membuat project Google Cloud dan kunci API terpisah untuk setiap pemanggil.

Untuk membuat project Google Cloud dan kunci API terpisah bagi setiap pemanggil:

Buat project terpisah untuk setiap pemanggil.
Di setiap project, aktifkan API Anda dan buat kunci API.
Berikan kunci API ke setiap pemanggil.

Membuat kunci API untuk setiap pemanggil

Jika tidak perlu membedakan pemanggil API, tetapi ingin menambahkan pembatasan kunci API, Anda dapat membuat kunci API terpisah untuk setiap pemanggil dalam project yang sama.

Untuk membuat kunci API bagi setiap pemanggil dalam project yang sama:

Di project tempat API Anda dikonfigurasi, atau project tempat API Anda diaktifkan, buat kunci API untuk setiap pelanggan yang memiliki pembatasan kunci API yang Anda perlukan.
Berikan kunci API ke setiap pemanggil.

Membuat satu kunci API untuk semua pemanggil

Jika tidak perlu membedakan pemanggil API, dan tidak perlu menambahkan pembatasan API, tetapi masih ingin mewajibkan kunci API (misalnya, untuk mencegah akses anonim), Anda dapat membuat satu kunci API untuk digunakan semua pemanggil.

Untuk membuat satu kunci API bagi semua pemanggil:

Di project tempat API Anda dikonfigurasi, atau project tempat API Anda diaktifkan, buat kunci API untuk semua pemanggil.
Berikan kunci API yang sama ke setiap pemanggil.

Praktik terbaik

Jika Anda mengandalkan kunci API untuk melindungi akses ke API dan data pengguna, pastikan Anda menetapkan tanda --service_control_network_fail_open ke close saat mengonfigurasi Opsi startup Extensible Service Proxy V2 (ESPv2). Nilai default untuk tanda ini adalah open.

ESPv2 memanggil Kontrol Layanan untuk memverifikasi kunci API. Jika ada kegagalan jaringan saat terhubung ke Kontrol Layanan dan ESPv2 tidak dapat memverifikasi kunci API, hal ini memastikan bahwa setiap permintaan potensial yang dibuat ke API Anda dengan kunci penipuan akan ditolak.