Menggunakan JWT untuk mengautentikasi pengguna

Halaman ini menjelaskan cara mendukung autentikasi pengguna di Gateway API.

Untuk mengautentikasi pengguna, aplikasi klien harus mengirim Token Web JSON (JWT) di header otorisasi permintaan HTTP ke API backend Anda. Gateway API memvalidasi token atas nama API, sehingga Anda tidak perlu menambahkan kode apa pun di API untuk memproses autentikasi. Namun, Anda perlu mengonfigurasi konfigurasi API untuk gateway Anda agar mendukung metode autentikasi yang dipilih.

API Gateway memvalidasi JWT secara optimal menggunakan JSON Web Key Set (JWKS) dari penerbit JWT. Lokasi JWKS ditentukan di kolom x-google-jwks_uri pada konfigurasi API gateway. Gateway API menyimpan JWKS dalam cache selama lima menit dan memperbaruinya setiap lima menit.

Sebelum memulai

Tambahkan kode autentikasi ke aplikasi klien dengan mengikuti dokumentasi penyedia autentikasi.

Saat aplikasi klien Anda mengirimkan permintaan HTTP, header otorisasi dalam permintaan tersebut harus berisi klaim JWT berikut:
- iss (penerbit)
- sub (subjek)
- aud (audiens)
- iat (diterbitkan pada)
- exp (waktu habis masa berlaku)

Mengonfigurasi Gateway API untuk mendukung autentikasi klien

Anda harus memiliki objek persyaratan keamanan dan objek definisi keamanan dalam konfigurasi API agar Gateway API dapat memvalidasi klaim dalam JWT yang ditandatangani.

Untuk mendukung autentikasi JWT:

Tambahkan hal berikut ke definisi keamanan di konfigurasi API Anda, yang mengikuti skema keamanan OpenAPI 2.0:

 securityDefinitions:
   your_custom_auth_id:
     authorizationUrl: ""
     flow: "implicit"
     type: "oauth2"
     # The value below should be unique
     x-google-issuer: "issuer of the token"
     x-google-jwks_uri: "url to the public key"
     # Optional. Replace YOUR-CLIENT-ID with your client ID
     x-google-audiences: "YOUR-CLIENT-ID"

Menambahkan bagian keamanan pada API level untuk diterapkan ke seluruh API, atau pada level metode untuk diterapkan ke metode tertentu.
```
 security:
   - your_custom_auth_id: []
```

Anda dapat menentukan beberapa definisi keamanan dalam konfigurasi API, tetapi setiap definisi harus memiliki penerbit yang berbeda. Jika Anda menggunakan bagian keamanan di API level dan pada level metode, setelan tingkat metode akan menggantikan setelan level API.

Kolom x-google-audiences tidak wajib diisi. Gateway API menerima semua JWT dengan nama layanan backend dalam bentuk https://SERVICE_NAME dalam klaim aud.

Catatan: Gateway API tidak menerima jenis URI berikut dalam klaim aud:

Alamat internal
Alamat IPv4 atau IPv6

Untuk mengizinkan client ID tambahan mengakses layanan backend, Anda dapat menentukan client ID yang diizinkan di kolom x-google-audiences menggunakan nilai yang dipisahkan koma. Gateway API kemudian menerima JWT dengan client ID apa pun yang ditentukan dalam klaim aud.

Kolom x-google-jwks_uri wajib. Gateway API mendukung dua format kunci publik asimetris yang ditentukan oleh ekstensi OpenAPI x-google-jwks_uri:

Format kumpulan JWK. Contoh:

x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

X509. Contoh:

x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Jika Anda menggunakan format kunci simetris, tetapkan x-google-jwks_uri ke URI file yang berisi string kunci yang dienkode base64url.

Catatan: Saat Gateway API mengirim permintaan ke x-google-jwks_uri, permintaan tersebut akan berisi header x-forwarded-proto.

Melakukan panggilan yang diautentikasi ke API Gateway API

Saat Anda mengirim permintaan menggunakan token autentikasi, sebaiknya tempatkan token tersebut di header Authorization:Bearer. Misalnya:

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

Di sini, GATEWAY_URL dan TOKEN adalah variabel lingkungan yang masing-masing berisi URL gateway dan token autentikasi yang di-deploy. Lihat Membuat permintaan yang diautentikasi ke API Gateway API untuk mengetahui contoh kode yang mengirim permintaan menggunakan header Authorization:Bearer.

Jika tidak dapat menggunakan header saat mengirim permintaan, Anda dapat meletakkan token autentikasi dalam parameter kueri yang disebut access_token. Contoh:

curl "${GATEWAY_URL}/echo?access_token=${TOKEN}"

Menerima hasil yang diautentikasi di API Anda

Gateway API biasanya meneruskan semua header yang diterimanya. Namun, metode ini akan menggantikan header Authorization asli saat alamat backend ditentukan oleh x-google-backend dalam konfigurasi API.

Gateway API akan mengirimkan hasil autentikasi di X-Apigateway-Api-Userinfo ke API backend. Sebaiknya gunakan header ini, bukan header Authorization asli. Header ini dienkode base64url dan berisi payload JWT.

Langkah selanjutnya

Autentikasi antar-layanan