Ekstensi Google Authentication

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X.
info

Versi: 1.3.1

Lakukan autentikasi dengan Google untuk mengakses Google API yang Anda tentukan.

Gunakan ekstensi ini untuk mendapatkan token (OAuth atau JWT) untuk layanan Google Cloud, lalu gunakan token tersebut untuk panggilan berikutnya ke Google API, misalnya dengan menggunakan kebijakan ServiceCallout.

Misalnya, di proxy API, Anda mungkin mendapatkan token dengan ekstensi ini, meng-cache token menggunakan kebijakan FillCache, lalu meneruskan token melalui kebijakan ServiceCallout untuk mengakses layanan Google Cloud dari dalam alur proxy API.

Prasyarat

Konten ini menyediakan referensi untuk mengonfigurasi dan menggunakan ekstensi ini. Sebelum menggunakan ekstensi dari proxy API menggunakan kebijakan ExtensionCallout, Anda harus:

  1. Pastikan akun yang akan digunakan ekstensi -- akun yang diwakili oleh akun layanan yang akan Anda gunakan untuk kredensial -- memiliki akses ke layanan Google Cloud yang akan diautentikasi dengan ekstensi tersebut.

  2. Gunakan Google Cloud Console untuk membuat kunci untuk akun layanan.

  3. Gunakan konten file JSON kunci akun layanan yang dihasilkan saat menambahkan dan mengonfigurasi ekstensi menggunakan referensi konfigurasi.

Tentang autentikasi dengan Google Cloud

Ekstensi ini meminta autentikasi dari Google Cloud dengan mewakili anggota tertentu yang ditentukan dalam project Google Cloud Anda. Anda dapat menggunakan file JSON akun layanan anggota project tersebut saat mengonfigurasi ekstensi ini.

Akibatnya, ekstensi ini hanya akan memiliki akses ke resource yang izinnya dimiliki oleh anggota tersebut. Dengan kata lain, autentikasi yang berhasil oleh ekstensi ini bergantung pada kecocokan antara izin yang diberikan di Google Cloud Console dan akses yang diminta oleh ekstensi tersebut (melalui cakupan atau audiens) saat runtime.

Secara umum, langkah-langkah autentikasi untuk akses ke API dari ekstensi ini adalah sebagai berikut:

  1. Pastikan akun layanan anggota yang diwakili oleh ekstensi ini memiliki akses ke resource Google yang ingin Anda akses. Anda dapat menggunakan halaman Cloud Identity and Access Management (Cloud IAM) di Google Cloud Console untuk memberikan peran kepada anggota project yang diwakili oleh ekstensi ini.

  2. Gunakan JSON kunci akun layanan anggota tersebut saat mengonfigurasi ekstensi ini.

  3. Saat mengonfigurasi kebijakan ExtensionCallout untuk menggunakan ekstensi ini, minta autentikasi hanya untuk resource yang aksesnya dimiliki oleh anggota project Anda.

Contoh

Contoh berikut menggambarkan cara melakukan autentikasi dengan Google Cloud menggunakan kebijakan ExtensionCallout.

Mendapatkan token akses

Dalam contoh berikut, tindakan getOauth2AccessToken ekstensi mengambil token untuk digunakan dalam permintaan ke Cloud Translation API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-Access-Token">
    <DisplayName>Get Access Token</DisplayName>
    <Connector>google-auth</Connector>
    <Action>getOauth2AccessToken</Action>
    <Input><![CDATA[{
      "scope" : [
        "https://www.googleapis.com/auth/cloud-translation"
      ]
    }]]></Input>
    <Output>google.credentials</Output>
</ConnectorCallout>

Nilai respons akan terlihat seperti ini:

{
  "access_token":"ya29.c.ElpSB...BMgkALBJ0kou-8",
  "token_type":"Bearer",
  "expiresInSec": 3600
}

KebijakanAssignMessage berikut mengambil nilai respons dari kebijakan ExtensionCallout di atas dan menyalinnya dalam payload respons. Hal ini dapat berguna untuk proses debug. Dalam praktiknya, Anda mungkin tidak ingin mengembalikan token ke klien.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Retrieve-Auth-Token">
    <DisplayName>Retrieve Auth Token</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{google.credentials.access_token}</Payload>
    </Set>
</AssignMessage>

Menyimpan token akses dalam cache

Agar tidak melakukan panggilan yang tidak perlu untuk mengambil token, pertimbangkan untuk menyimpan token yang Anda terima ke dalam cache. Untuk panggilan berikutnya yang memerlukan token, pengambilan token dari cache Apigee Edge akan lebih cepat daripada mendapatkan token baru. Ketika masa berlaku token yang di-cache berakhir, ambil token baru dan refresh cache dengan token tersebut.

Kode berikut dari contoh proxy API mengilustrasikan cara menetapkan dan menggunakan token yang di-cache untuk memanggil Google Translation API dengan kebijakan ServiceCallout. Setiap contoh kode di sini adalah untuk kebijakan berbeda dalam alur.

Kebijakan berikut dijalankan dalam urutan yang dijelaskan oleh XML alur berikut:

  <Request>
    <!-- Attempt to get a token from the cache. -->
    <Step>
        <Name>Get-Cached-Auth-Token</Name>
    </Step>
    <!-- Only execute the following ExtensionCallout policy if the call to the
      cache couldn't retrieve a cached token. -->
    <Step>
        <Name>Google-Auth-Callout</Name>
        <Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
    </Step>
    <!-- Only execute the following PopulateCache policy if the call to the
      cache couldn't retrieve a cached token. -->
    <Step>
        <Name>Cache-Auth-Token</Name>
        <Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
    </Step>
    <!-- Use the ServiceCallout policy to call the translate API. -->
    <Step>
        <Name>Translate-Text</Name>
    </Step>
</Request>
  1. Kebijakan LookupCache berikut mencoba mendapatkan token dari cache. Jika token sudah diperoleh dan di-cache, kebijakan ini akan mendapatkannya untuk digunakan oleh proxy API.

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <LookupCache async="false" continueOnError="false" enabled="true" name="Get-Cached-Auth-Token">
          <DisplayName>Get Cached Auth Token</DisplayName>
          <!-- Give cache key and scope to specify the entry for the cached token. -->
          <CacheKey>
              <Prefix/>
              <KeyFragment>gcp_translate_token_</KeyFragment>
          </CacheKey>
          <Scope>Exclusive</Scope>
          <!-- Assign the retrieved token (if any) to a variable, where it
           can be retrieved by policies. -->
          <AssignTo>cloud.translation.auth.token</AssignTo>
      </LookupCache>
    
  2. Jika pencarian cache tidak mengambil token yang di-cache, kebijakan ExtensionCallout berikut mengambil token OAuth baru, yang menentukan Google Cloud Translation API sebagai cakupan token. Google Cloud menampilkan token yang valid jika kredensial akun layanan yang digunakan saat mengonfigurasi ekstensi Google-Auth-Callout mewakili anggota project yang memiliki akses ke API.

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <ConnectorCallout async="false" continueOnError="true" enabled="true" name="Google-Auth-Callout">
          <DisplayName>Google-Auth-Callout</DisplayName>
          <Connector>example-auth-extension</Connector>
          <Action>getOauth2AccessToken</Action>
          <Input><![CDATA[{
            "scope" : ["https://www.googleapis.com/auth/cloud-translation"]
          }]]></Input>
          <Output parsed="false">cloud.translation.auth.token</Output>
      </ConnectorCallout>
    
  3. Setelah kebijakan ExtensionCallout mengambil token baru, kebijakan FillCache akan menyimpannya dalam cache untuk digunakan nanti oleh kebijakan di proxy API.

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <PopulateCache async="false" continueOnError="false" enabled="true" name="Cache-Auth-Token">
          <DisplayName>Cache Auth Token</DisplayName>
          <Properties/>
          <!-- Set cache key information to specify a unique key for this entry. -->
          <CacheKey>
              <Prefix/>
              <KeyFragment>gcp_translate_token_</KeyFragment>
          </CacheKey>
          <Scope>Exclusive</Scope>
          <ExpirySettings>
              <TimeoutInSec>5</TimeoutInSec>
          </ExpirySettings>
          <!-- Get the token to cache from the variable where the ExtensionCallout put it. -->
          <Source>cloud.translation.auth.token</Source>
      </PopulateCache>
    

Tindakan

getOauth2AccessToken

Mendapatkan token akses OAuth 2.0. Gunakan tindakan ini untuk mendukung OAuth bercabang dua antara proxy API Anda dan Google API saat Google API memerlukan token OAuth.

Dalam OAuth bercabang dua, tindakan ekstensi ini mengambil token OAuth dengan mengautentikasi dengan Google menggunakan JSON akun layanan (Anda menambahkan JSON tersebut saat mengonfigurasi ekstensi ini). Setelah tindakan ini mengambil token OAuth, proxy API Anda dapat menggunakan token tersebut untuk melakukan panggilan ke Google API, yang secara efektif memanggil API atas nama akun layanan Google.

Akses ke Google Cloud API difilter melalui cakupan yang tercantum dalam cakupan OAuth 2.0 untuk Google API.

Untuk informasi selengkapnya tentang interaksi server ke server dengan OAuth 2.0, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server

Sintaksis

<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
  "scope" : [
    "scope1",
    "scope2"
  ]
}]]></Input>

Contoh

Dalam contoh berikut, tindakan getOauth2AccessToken ekstensi mengambil token untuk digunakan dalam permintaan ke Cloud Translation API.

<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
    "scope" : [
      "https://www.googleapis.com/auth/cloud-translation"
  ]
}]]></Input>

Parameter permintaan

Parameter Deskripsi Jenis Default Wajib
cakupan Array cakupan OAuth 2.0. Untuk mengetahui informasi selengkapnya tentang cakupan, lihat Cakupan OAuth 2.0 untuk Google API. Array ["https://www.googleapis.com/auth/cloud-platform"], yang memberikan akses ke semua API yang aksesnya dimiliki akun layanan. Tidak.

Respons

Objek yang berisi token akses, jenisnya, dan tanggal habis masa berlakunya dalam bentuk berikut:

{
  "accessToken": "ewogICJ0eXB...C5jb20iCn0K",
  "token_type": "Bearer",
  "expiresInSec": 3600
}

Properti respons

Parameter Deskripsi Default Wajib
accessToken Token akses OAuth 2.0. Tidak ada Ya
tokenType Jenis token. Operator Ya
expiresInSec Jumlah detik hingga masa berlaku token habis. 3600 Ya

getJWTAccessToken

Mendapatkan token akses token web JSON (JWT). Anda dapat menggunakan token ini untuk mengautentikasi dengan Google API jika API yang ingin Anda panggil memiliki definisi layanan yang dipublikasikan di repositori GitHub Google API.

Dengan beberapa API Google, Anda bisa membuat panggilan API yang diotorisasi menggunakan JWT yang ditandatangani secara langsung sebagai token pembawa, bukan token akses OAuth 2.0. Jika memungkinkan, Anda dapat menghindari keharusan membuat permintaan jaringan ke server otorisasi Google sebelum melakukan panggilan API.

Untuk mengetahui informasi selengkapnya tentang autentikasi dengan token akses JWT, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server.

Sintaksis

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
    "audience" : "audience"
}]]></Input>

Contoh: URL Cloud Function

Dalam contoh berikut, tindakan getOauth2AccessToken ekstensi mengambil token untuk digunakan dalam permintaan ke Cloud Translation API.

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
  "audience" : "https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/FUNCTION_NAME"
}]]></Input>

Contoh: Client ID yang diamankan oleh Cloud IAP

Dalam contoh berikut, tindakan getOauth2AccessToken ekstensi mengambil token untuk digunakan dalam permintaan ke Cloud Translation API.

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
  "audience" : "Cloud-IAP-secured-client-ID"
}]]></Input>

Parameter permintaan

Parameter Deskripsi Default Wajib
audience Penerima token yang dituju. ID ini dapat mencakup client ID yang diamankan oleh Cloud IAP, URL Cloud Functions, dan sebagainya. Tidak ada Ya

Respons

{
  "accessToken": "token",
  "tokenType": "Bearer",
  "expiresInSec": 3600
}

Properti respons

Parameter Deskripsi Default Wajib
accessToken Token akses. Tidak ada Ya
tokenType Jenis token. Operator Ya
expiresInSec Berakhir dalam hitungan detik. 3600 Ya

Referensi konfigurasi

Gunakan hal berikut saat Anda mengonfigurasi dan men-deploy ekstensi ini untuk digunakan di proxy API. Untuk langkah-langkah mengonfigurasi ekstensi menggunakan konsol Apigee, lihat Menambahkan dan mengonfigurasi ekstensi.

Properti ekstensi umum

Properti berikut ada untuk setiap ekstensi.

Properti Deskripsi Default Wajib
name Nama yang Anda berikan pada konfigurasi ekstensi ini. Tidak ada Ya
packageName Nama paket ekstensi seperti yang diberikan oleh Apigee Edge. Tidak ada Ya
version Nomor versi untuk paket ekstensi tempat Anda mengonfigurasi ekstensi. Tidak ada Ya
configuration Nilai konfigurasi khusus untuk ekstensi yang Anda tambahkan. Lihat Properti untuk paket ekstensi ini Tidak ada Ya

Properti untuk paket ekstensi ini

Tentukan nilai untuk properti konfigurasi berikut yang khusus untuk ekstensi ini.

Properti Deskripsi Default Wajib
kredensial Saat dimasukkan di konsol Apigee Edge, ini adalah seluruh isi file JSON kunci akun layanan Anda. Saat dikirim melalui API pengelolaan, nilai tersebut adalah nilai berenkode base64 yang dihasilkan dari seluruh file JSON kunci akun layanan. Tidak ada Ya