Menggunakan metode kustom untuk mengautentikasi pengguna

Halaman ini menjelaskan cara mendukung autentikasi pengguna di Cloud Endpoints.

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

ESP memvalidasi JWT secara optimal menggunakan kunci publik penerbit JWT. ESP menyimpan kunci publik dalam cache selama lima menit. Selain itu, ESP menyimpan cache JWT yang divalidasi selama lima menit atau hingga masa berlaku JWT berakhir, mana saja yang terjadi lebih dahulu.

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 ESP untuk mendukung autentikasi klien

Anda harus memiliki objek persyaratan keamanan dan objek definisi keamanan dalam dokumen OpenAPI agar ESP dapat memvalidasi klaim dalam JWT yang ditandatangani.

Untuk mendukung autentikasi kustom:

  1. Tambahkan hal berikut ke definisi keamanan di dokumen OpenAPI Anda:

     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"

  2. 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 dokumen OpenAPI, 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. ESP menerima semua JWT dengan nama layanan backend dalam bentuk https://SERVICE_NAME dalam klaim aud. 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. ESP kemudian menerima JWT dengan client ID apa pun yang ditentukan dalam klaim aud.

ESP 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.

Jika Anda menghapus x-google-jwks_uri, ESP akan mengikuti protokol OpenID Connect Discovery untuk otomatis menemukan URI JWKS untuk penyedia OpenID tertentu. ESP akan membuat permintaan ke x-google-issuer/.well-known/openid-configuration, mengurai respons JSON, dan membaca URI JWKS dari kolom jwks_uri tingkat atas.

Perlu diketahui bahwa menghapus x-google-jwks_uri akan mengakibatkan waktu cold start yang lebih tinggi, karena ESP harus membuat panggilan jarak jauh tambahan saat startup. Oleh karena itu, sebaiknya hapus kolom ini jika URI JWKS sering berubah. Sebagian besar penyedia OpenID tersertifikasi (seperti Google, Auth0, dan Okta) memiliki URI JWKS yang stabil.

Anda juga dapat menyesuaikan lokasi JWT dengan menambahkan x-google-extensions. Untuk mengetahui detailnya, lihat ekstensi openAPI.

Melakukan panggilan terautentikasi ke Endpoints API

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

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"

Di sini, ENDPOINTS_HOST dan TOKEN adalah variabel lingkungan yang masing-masing berisi nama host API dan token autentikasi. Lihat Membuat permintaan yang diautentikasi ke Endpoints API. untuk mengetahui kode contoh 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 "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"

Menerima hasil yang diautentikasi di API Anda

ESP biasanya meneruskan semua header yang diterimanya. Namun, metode ini akan menggantikan header Authorization asli saat alamat backend ditentukan oleh x-google-backend dalam spesifikasi OpenAPI atau BackendRule dalam konfigurasi layanan gRPC.

ESP akan mengirimkan hasil autentikasi di X-Endpoint-API-UserInfo ke API backend. Sebaiknya gunakan header ini, bukan header Authorization asli. Header ini adalah string yang base64url mengenkode objek JSON. Format objek JSON berbeda antara ESPv2 dan ESP. Untuk ESPv2, objek JSON persis sama dengan payload JWT asli. Untuk ESP, objek JSON menggunakan nama kolom yang berbeda dan menempatkan payload JWT asli di kolom claims. Lihat Menangani JWT di layanan backend untuk mengetahui informasi format selengkapnya.

Langkah selanjutnya