Menggunakan JWT untuk mengautentikasi pengguna

Halaman ini menjelaskan cara mendukung autentikasi pengguna di API Gateway.

Untuk mengautentikasi pengguna, aplikasi klien harus mengirim Token Web JSON (JWT) di header otorisasi permintaan HTTP ke backend API Anda. API Gateway memvalidasi token atas nama API Anda, 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 berperforma tinggi dengan menggunakan JSON Web Key Set (JWKS) penerbit JWT. Lokasi JWKS ditentukan dalam konfigurasi API gateway. API Gateway menyimpan JWKS dalam cache selama lima menit dan memperbaruinya setiap lima menit.

Sebelum memulai

  • Tambahkan kode autentikasi ke aplikasi klien Anda, dengan mengikuti dokumentasi penyedia autentikasi.

  • Saat aplikasi klien Anda mengirim permintaan HTTP, header otorisasi dalam permintaan harus berisi klaim JWT berikut:
    • iss (penerbit)
    • sub (subjek)
    • aud (audiens)
    • iat (dikeluarkan di)
    • exp (waktu habis masa berlaku)

Mengonfigurasi API Gateway untuk mendukung autentikasi klien

Anda harus memiliki bagian keamanan dalam konfigurasi API agar API Gateway dapat memvalidasi klaim dalam JWT yang ditandatangani. Skema yang digunakan untuk menentukan metode keamanan bergantung pada versi spesifikasi OpenAPI yang Anda gunakan.

Untuk mendukung autentikasi JWT:

OpenAPI 2.0

  1. Tambahkan kode berikut ke konfigurasi API Anda: 
    securityDefinitions:
  your_custom_auth_id:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # The issuer value should be unique
    x-google-issuer: "ISSUER"
    x-google-jwks_uri: "URL_PUBLIC_KEY"
    # Optional.
    x-google-audiences: "CLIENT_ID"

    Dengan:

    • ISSUER adalah penerbit token.
    • URL_PUBLIC_KEY adalah URL ke kunci publik.
    • CLIENT_ID adalah ID klien.
  2. Tambahkan bagian keamanan di tingkat API untuk diterapkan ke seluruh API, atau di tingkat metode untuk diterapkan ke metode tertentu. 
    security:
  - your_custom_auth_id: []

OpenAPI 3.x

  1. Tambahkan kode berikut ke konfigurasi API Anda: 
    components:
  securitySchemes:
    SCHEME_NAME:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: ISSUER
        jwksUri: URL_PUBLIC_KEY
        # Optional. Replace CLIENT_ID with your client ID(s) as a list of strings.
        audiences:
          - CLIENT_ID
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "

    Dengan:

    • ISSUER adalah penerbit token.
    • URL_PUBLIC_KEY adalah URL ke kunci publik.
    • CLLIENT_ID adalah daftar ID klien sebagai string.
  2. Tambahkan bagian keamanan di tingkat API untuk diterapkan ke seluruh API, atau di tingkat metode untuk diterapkan ke metode tertentu. 
    security:
  - SCHEME_NAME: []

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

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

Untuk mengizinkan ID klien tambahan mengakses layanan backend, Anda dapat menentukan ID klien yang diizinkan di kolom audiences yang berlaku. Beberapa audiens ditentukan sebagai nilai yang dipisahkan koma di OpenAPI 2.0 dan dengan daftar di OpenAPI 3.x. dengan menggunakan nilai yang dipisahkan koma. Kemudian, Gateway API menerima JWT dengan salah satu ID klien yang ditentukan dalam klaim aud.

Kolom x-google-jwks_uri (OpenAPI 2.0) atau jwksUri (OpenAPI 3.x) diperlukan. API Gateway mendukung dua format kunci publik asimetris yang ditentukan oleh ekstensi OpenAPI ini:

  • Format set JWK. Contoh:

    OpenAPI 2.0

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

    OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Contoh:

    OpenAPI 2.0

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

    OpenAPI 3.x

    jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Jika Anda menggunakan format kunci simetris, tetapkan x-google-jwks_uri (OpenAPI 2.0) atau jwksUri (OpenAPI 3.x) ke URI file yang berisi string kunci berenkode base64url.

Melakukan panggilan terautentikasi ke API Gateway API

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

curl -H "Authorization: Bearer TOKEN" "GATEWAY_URL/hello"

Di sini, GATEWAY_URL dan TOKEN harus diganti dengan URL gateway yang di-deploy dan token autentikasi Anda. Lihat Membuat permintaan yang diautentikasi ke API Gateway API untuk contoh kode yang mengirim permintaan menggunakan header Authorization:Bearer.

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

curl "GATEWAY_URL/hello?access_token=TOKEN"

Menerima hasil yang diautentikasi di API Anda

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

API Gateway 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 berikutnya