Menggunakan token ID Google 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 backend API Anda. Extensible Service Proxy (ESP) memvalidasi token atas nama API Anda, sehingga Anda tidak perlu menambahkan kode apa pun di API untuk memproses autentikasi. Namun, Anda harus mengonfigurasi dokumen OpenAPI untuk mendukung metode autentikasi yang Anda pilih.

ESP memvalidasi JWT secara berperforma tinggi dengan menggunakan kunci publik penerbit JWT. ESP menyimpan kunci publik dalam cache selama lima menit. Selain itu, ESP menyimpan JWT yang divalidasi dalam cache selama lima menit atau hingga JWT berakhir, mana pun yang terjadi lebih dulu.

Sebelum memulai

  • Tambahkan kode autentikasi ke aplikasi klien yang memungkinkan pengguna melakukan autentikasi dengan login menggunakan Akun Google.

  • 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 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 menggunakan token ID Google:

OpenAPI 2.0

  1. Tambahkan kode berikut ke spesifikasi OpenAPI Anda: 
    securityDefinitions:
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    # Optional. Replace CLIENT_ID with your client ID
    x-google-audiences: "CLIENT_ID"
  2. Tambahkan bagian keamanan di tingkat API untuk diterapkan ke seluruh API, atau di tingkat metode untuk diterapkan ke metode tertentu. 
    security:
   -   google_id_token: []

OpenAPI 3.x

  1. Tambahkan kode berikut ke spesifikasi OpenAPI Anda: 
    components:
  securitySchemes:
    google_id_token:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: https://accounts.google.com
        jwksUri: https://www.googleapis.com/oauth2/v3/certs
        # Optional. Replace CLIENT_ID with your client ID(s) as a list of strings.
        audiences:
          - CLIENT_ID
  2. Tambahkan bagian keamanan di tingkat API untuk diterapkan ke seluruh API, atau di tingkat metode untuk diterapkan ke metode tertentu. 
    security:
  - google_id_token: []

Anda dapat menentukan beberapa definisi keamanan dalam dokumen OpenAPI, 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 atau audiences tidak wajib diisi. ESP 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 x-google-audiences atau audiences menggunakan nilai yang dipisahkan koma. ESP kemudian menerima JWT dengan salah satu ID klien yang ditentukan dalam klaim aud.

Anda juga dapat menyesuaikan lokasi JWT dengan menambahkan ekstensi x-google. Untuk mengetahui detailnya, lihat Ekstensi OpenAPI 2.0 atau ekstensi OpenAPI 3.x.

Melakukan panggilan terautentikasi ke Endpoints API

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

curl -H "Authorization: Bearer <var>TOKEN</var>" "<var>ENDPOINTS_HOST</var>/echo"

Di sini, ganti variabel ENDPOINTS_HOST dan TOKEN dengan nama host API dan token autentikasi Anda. Lihat Membuat permintaan yang diautentikasi ke Endpoints 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 "<var>ENDPOINTS_HOST</var>/echo?access_token=<var>TOKEN</var>"

Menerima hasil autentikasi di API Anda

ESP biasanya meneruskan semua header yang diterimanya. Namun, header Authorization asli akan diganti jika 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 backend API. Sebaiknya gunakan header ini, bukan header Authorization asli. Header ini adalah string yang mengenkode objek JSON base64url. 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 selengkapnya tentang formatnya.

Langkah berikutnya