Menggunakan autentikasi Google

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Topik ini menjelaskan cara menyiapkan dan men-deploy proxy API yang dikonfigurasi untuk menggunakan autentikasi Google.

Pengguna hybrid Apigee: Jika Anda menggunakan Apigee Hybrid, perhatikan bahwa fitur ini hanya didukung untuk Apigee Hybrid v1.6.x dan versi yang lebih baru.

Pengantar

Apigee mendukung penggunaan token Google OAuth atau token OpenID Connect untuk melakukan autentikasi dengan layanan Google, seperti Cloud Logging dan Secret Manager, serta layanan kustom yang berjalan di produk Google Cloud tertentu seperti Cloud Functions dan Cloud Run.

Untuk menggunakan fitur ini, Anda harus mengonfigurasi elemen XML <Authentication> dalam salah satu konteks berikut:

• Kebijakan InfoLayanan
• Kebijakan ExternalInfo
• Konfigurasi TargetEndpoint

Setelah Anda menyelesaikan beberapa langkah penyiapan dasar (seperti yang dijelaskan dalam topik ini), Apigee melakukan pembuatan token dan melakukan panggilan yang aman ke layanan Google yang ditargetkan atau layanan yang dihosting kustom untuk Anda, tanpa perlu menetapkan header autentikasi secara manual atau mengubah permintaan layanan. Dari sudut pandang developer API, proses panggilan layanan Google dari dalam proxy API yang dikonfigurasi dengan benar ditangani dengan lancar.

Opsi konfigurasi proxy API

Bagian ini menjelaskan tempat Anda dapat menggunakan elemen XML <Authentication> untuk mengaktifkan autentikasi Token Google OAuth atau OpenID Connect:

Opsi konfigurasi	Deskripsi
Kebijakan InfoLayanan	Kebijakan ServiceCallout memungkinkan Anda memanggil layanan internal atau eksternal lainnya dari proxy API. Misalnya, Anda dapat menggunakan ServiceCallout untuk memanggil layanan Google eksternal atau layanan yang dihosting kustom. Untuk mengetahui detail dan contoh penggunaan, lihat kebijakan ServiceCallout.
Kebijakan ExternalInfo	Kebijakan ExternalCallout memungkinkan Anda mengirim permintaan gRPC ke server gRPC untuk menerapkan perilaku kustom yang tidak didukung oleh kebijakan Apigee. Untuk mengetahui detail dan contoh penggunaan, lihat kebijakan ExternalCallout.
TargetEndpoint	Tentukan layanan Google atau layanan yang dihosting khusus sebagai endpoint target proxy API. Untuk mengetahui detail dan contoh penggunaan, lihat Referensi konfigurasi Proxy API.

Konteks yang didukung Token Autentikasi Google

Elemen <Authentication> memiliki dua konfigurasi sub-elemen: <GoogleAccessToken> atau <GoogleIDToken>. Tabel berikut menunjukkan konteks yang mendukung elemen-elemen ini:

Used in	GoogleAccessToken	GoogleIDToken
Kebijakan ServiceCallout	Didukung	Didukung
Kebijakan ExternalCallout	Tidak didukung	Didukung
TargetEndpoint	Didukung	Didukung

Catatan: Kebijakan ExternalCallout tidak dapat memanggil Google API, sehingga token akses Google tidak didukung oleh kebijakan tersebut. Namun, token OpenID Connect didukung, sehingga jika layanan target dihosting di, misalnya, Cloud Run, kebijakan dapat terhubung dengan lancar.

Perhatian: Hindari penggunaan target dinamis non-SSL. Misalnya, hindari mengganti variabel alur target.url agar mengarah ke endpoint target non-SSL. Jika Anda menggunakan target dinamis non-SSL, Token Auth Google akan tetap dibuat; tetapi, token autentikasi akan ditampilkan dalam teks biasa.

Langkah-langkah penerapan

Bagian ini menjelaskan cara men-deploy proxy API yang menggunakan autentikasi Google untuk memanggil layanan Google yang ditargetkan atau layanan yang dihosting secara khusus. Kami menjelaskan langkah-langkah deployment untuk Apigee dan Apigee Hybrid secara terpisah.

Catatan: Deployment alur bersama juga mendukung penggunaan tag Authentication dalam kebijakan dan konfigurasi TargetEndpoint yang didukung. Lihat juga dokumentasi API deployment alur bersama.

Men-deploy di Apigee

Langkah-langkah berikut menjelaskan cara men-deploy proxy API di Apigee, tempat proxy dikonfigurasi untuk melakukan panggilan terautentikasi ke layanan Google atau layanan khusus yang dihosting. Langkah-langkah ini mengasumsikan bahwa Anda telah membuat proxy, dan telah menyertakan elemen <Authentication> dalam salah satu konteks yang didukung yang tercantum.

1. Buat akun layanan Google di project Google Cloud yang sama tempat organisasi Apigee Anda dibuat. Anda harus memberikan nama akun layanan ini saat men-deploy proxy API yang dikonfigurasi untuk menggunakan autentikasi Google, dan token OAuth yang dihasilkan akan mewakili akun layanan. Anda dapat membuat akun layanan di Konsol Google Cloud atau dengan perintah gcloud. Lihat Membuat dan mengelola akun layanan.
2. Berikan izin iam.serviceAccounts.actAs kepada pengguna yang akan melakukan deployment (deployer) di akun layanan. Lihat juga Tentang izin akun layanan.
   Perhatian: Pengguna yang diberi peran Service Account User pada akun layanan dapat menggunakannya untuk secara tidak langsung mengakses semua resource yang dapat diakses oleh akun layanan. Untuk mengetahui detailnya, lihat peran Pengguna Akun Layanan. Sebaiknya konfigurasi akun layanan untuk hak istimewa terendah guna meminimalkan dampak penetapan peran pengguna.
   Catatan: Langkah ini mungkin bersifat opsional jika deployer sudah memiliki izin yang cukup, misalnya, saat men-deploy melalui UI dan pengguna Google Cloud memiliki peran Pemilik pada project.

   gcloud iam service-accounts add-iam-policy-binding \
   SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member="MEMBER" \
     --role="roles/iam.serviceAccountUser"
   

Dengan keterangan:

• PROJECT_ID: ID project. ID sama dengan nama organisasi Anda.
• SA_NAME: Nama yang Anda berikan saat membuat akun layanan.
• MEMBER: Anggota yang akan ditambahi binding. Harus dalam bentuk user|group|serviceAccount:email atau domain:domain.
3. Berikan izin kepada akun layanan yang diperlukan untuk berkomunikasi dengan layanan Google yang ditargetkan. Misalnya, jika Anda ingin memanggil layanan Google Logging, akun layanan ini harus menyertakan izin yang diperlukan untuk berkomunikasi dengan layanan tersebut. Lihat juga Memahami peran.
4. Sebelum men-deploy proxy API yang dikonfigurasi untuk menggunakan autentikasi Google, Anda memerlukan:
   • Nama akun layanan yang Anda buat sebelumnya. Contoh: SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   • Sebagai pengguna yang melakukan deployment (deployment), Anda harus sudah memiliki atau diberi izin iam.serviceAccounts.actAs di akun layanan. Lihat bagian Memberikan, mengubah, dan mencabut akses ke resource.
5. Deploy proxy API yang berisi konfigurasi autentikasi Google yang Anda terapkan. Anda dapat menggunakan UI atau API Apigee untuk men-deploy proxy. Untuk mempelajari lebih lanjut, lihat Men-deploy proxy API.
   • Jika menggunakan UI, Anda akan diminta untuk memberikan nama akun layanan. Gunakan nama akun layanan proxy yang Anda buat pada Langkah 1. Contoh: SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

     

   • Jika Anda memilih untuk men-deploy proxy menggunakan Apigee deployment API, berikut ini contoh perintah cURL yang dapat Anda gunakan. Perhatikan bahwa perintah menyertakan nama akun layanan sebagai parameter kueri. Ini adalah nama akun layanan yang Anda buat di Langkah 1:

     curl -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
     -H "Content-Type: application/json" -X POST

     Dengan keterangan:

     • TOKEN: Token OAuth yang harus Anda dapatkan sebagai ganti kredensial Google Anda. Untuk mengetahui detailnya, lihat Mendapatkan token akses OAuth 2.0.
     • ORG_NAME: Nama organisasi Apigee Anda.
     • ENV_NAME: Nama lingkungan untuk men-deploy proxy API.
     • SA_NAME: Nama yang Anda berikan saat membuat akun layanan.
     • PROJECT_ID: Project ID Google Cloud Anda (sama seperti nama organisasi).
6. Setelah deployment selesai, uji proxy API Anda untuk memastikan layanan Google menampilkan respons yang diharapkan.

Men-deploy pada Apigee Hybrid

Langkah-langkah berikut menjelaskan cara men-deploy proxy API ke Apigee Hybrid, yaitu proxy API yang dikonfigurasi untuk melakukan panggilan terautentikasi ke layanan Google. Langkah-langkah ini mengasumsikan bahwa Anda telah membuat proxy, dan telah menyertakan elemen <Authentication> dalam salah satu konteks yang didukung yang tercantum.

Catatan: Langkah 1-3 di bawah diperlukan, tetapi merupakan langkah penyiapan satu kali saja.

1. Buat akun layanan dan kunci untuk komponen runtime Apigee Hybrid menggunakan salah satu metode berikut:
   Catatan: Jika telah membuat akun layanan apigee-runtime saat menginstal Apigee Hybrid, Anda dapat melewati langkah ini.
   • Gunakan alat create-service-account yang disediakan bersama Apigee Hybrid untuk membuat akun layanan apigee-runtime. Alat ini membuat akun layanan dan menampilkan kunci akun layanan. Lihat create-service-account untuk mengetahui detailnya.
   • Buat akun layanan di Konsol Google Cloud atau dengan perintah gcloud. Lihat Membuat dan mengelola akun layanan. Untuk mengambil kunci akun layanan, lihat Membuat dan mengelola kunci akun layanan.
   Catatan: Anda dapat membuat akun layanan runtime di project Google Cloud mana pun yang memiliki izin untuk melakukannya. Akun ini tidak harus dibuat dalam project yang sama dengan yang digunakan untuk organisasi Apigee Anda.
2. Buka file overrides.yaml Anda dan tentukan jalur ke file kunci akun layanan untuk setiap lingkungan yang memerlukan kemampuan autentikasi Google:

   envs:
     - name: "ENVIRONMENT_NAME"
       serviceAccountPaths:
         runtime: "KEY_FILE_PATH"

   Catatan: Jika Anda memiliki beberapa lingkungan yang memerlukan kemampuan Autentikasi Google, setiap lingkungan dapat memiliki akun layanannya sendiri, atau semuanya dapat berbagi yang sama. Lihat juga Tentang izin akun layanan.

   Contoh:

   envs:
     - name: "test"
       serviceAccountPaths:
         runtime: "./service_accounts/my_runtime_sa.json"

3. Terapkan file penggantian ke cluster Anda menggunakan apigeectl apply.
4. Buat akun layanan kedua, yang kita sebut sebagai akun layanan proxy. Akun layanan ini harus berada dalam project Google Cloud yang sama dengan yang Anda gunakan untuk membuat organisasi Apigee. Anda harus memberikan alamat email akun layanan ini saat men-deploy proxy API yang dikonfigurasi untuk menggunakan autentikasi Google, dan token OAuth yang dihasilkan akan mewakili akun layanan.
5. Berikan izin iam.serviceAccounts.actAs kepada pengguna yang akan melakukan deployment (deployer) di akun layanan. Lihat juga Tentang izin akun layanan.
   Perhatian: Pengguna yang diberi peran Service Account User pada akun layanan dapat menggunakannya untuk secara tidak langsung mengakses semua resource yang dapat diakses oleh akun layanan. Untuk mengetahui detailnya, lihat peran Pengguna Akun Layanan. Sebaiknya konfigurasi akun layanan untuk hak istimewa terendah guna meminimalkan dampak penetapan peran pengguna.
   Catatan: Langkah ini mungkin bersifat opsional jika deployer sudah memiliki izin yang cukup, misalnya, saat men-deploy melalui UI dan pengguna Google Cloud memiliki peran Pemilik pada project.

   gcloud iam service-accounts add-iam-policy-binding \
   SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member="MEMBER" \
     --role="roles/iam.serviceAccountUser"
   

Dengan keterangan:

• PROJECT_ID: ID project. ID sama dengan nama organisasi Anda.
• SA_NAME: Nama yang Anda berikan saat membuat akun layanan.
• MEMBER: Anggota yang akan ditambahi binding. Harus dalam bentuk user|group|serviceAccount:email atau domain:domain.
6. Berikan izin pada akun layanan proxy yang diperlukan untuk berkomunikasi dengan layanan Google yang Anda target. Misalnya, jika Anda ingin memanggil layanan Google Logging, akun layanan ini harus menyertakan izin yang diperlukan untuk berkomunikasi dengan layanan tersebut. Lihat juga Memahami peran.
7. Pastikan runtime dapat meniru identitas akun layanan proxy. Untuk menyediakan kemampuan ini, beri akun layanan runtime peran iam.serviceAccountTokenCreator pada akun layanan proxy. Lihat juga Tentang izin akun layanan. Contoh:

   gcloud iam service-accounts add-iam-policy-binding \
   PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
   

   Dengan keterangan:

   • PROJECT_ID: ID project. ID sama dengan nama organisasi Anda. Perhatikan bahwa Anda tidak perlu menggunakan project yang terkait dengan organisasi Anda untuk membuat akun layanan runtime. Pastikan Anda menggunakan project ID yang benar dalam perintah ini.
   • PROXY_SA_NAME: ID untuk akun layanan proxy.
   • RUNTIME_SA_NAME: ID untuk akun layanan runtime.
8. Sebelum men-deploy proxy API yang dikonfigurasi untuk menggunakan autentikasi Google, Anda memerlukan:
   • Nama akun layanan proxy yang Anda buat sebelumnya. Contoh: PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   • Sebagai pengguna yang melakukan deployment, Anda harus sudah memiliki atau diberi izin iam.serviceAccounts.actAs di Project Google Cloud tempat organisasi Apigee disediakan. Lihat Memberikan, mengubah, dan mencabut akses ke resource.
9. Deploy proxy API yang berisi konfigurasi autentikasi Google yang Anda terapkan. Anda dapat menggunakan UI atau API Apigee untuk men-deploy proxy. Untuk mempelajari lebih lanjut, lihat Men-deploy proxy API.
   • Jika menggunakan UI, Anda akan diminta untuk memberikan nama akun layanan. Gunakan nama akun layanan proxy yang Anda buat sebelumnya. Contoh: PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

     

   • Jika Anda memilih untuk men-deploy proxy menggunakan Apigee deployment API, berikut ini contoh perintah cURL yang dapat Anda gunakan. Perhatikan bahwa perintah menyertakan nama akun layanan sebagai parameter kueri. Ini adalah nama akun layanan proxy:

     curl -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
     -H "Content-Type: application/json" -X POST

     Dengan keterangan:

     • TOKEN: Token OAuth yang harus Anda dapatkan sebagai ganti kredensial Google Anda. Untuk mengetahui detailnya, lihat Mendapatkan token akses OAuth 2.0.
     • ORG_NAME: Nama organisasi Apigee Anda.
     • ENV_NAME: Nama lingkungan untuk men-deploy proxy API.
     • PROXY_SA_NAME: Nama akun layanan proxy.
     • PROJECT_ID: Project ID Google Cloud Anda (sama seperti nama organisasi).
10. Setelah deployment selesai, uji proxy API Anda untuk memastikan layanan Google menampilkan respons yang diharapkan.

Tentang izin akun layanan

Untuk mengonfigurasi proxy API agar menggunakan autentikasi Google, Anda harus membuat akun layanan seperti yang dijelaskan dalam tabel berikut. Lihat juga Membuat dan mengelola akun layanan.

Akun layanan	Wajib untuk	Deskripsi
Proxy	Apigee dan Apigee Hybrid	Memiliki izin yang diperlukan proxy API untuk melakukan panggilan terautentikasi ke layanan Google yang ditargetkan. Harus dibuat dalam project Google Cloud yang sama dengan organisasi Apigee Anda. Pengguna yang melakukan deployment (deploymenter), harus memiliki atau diberi izin iam.serviceAccounts.actAs pada akun layanan proxy. Harus menyertakan izin yang diperlukan untuk berkomunikasi dengan layanan Google target tertentu. Misalnya, jika Anda ingin memanggil layanan Google Logging, akun layanan ini harus menyertakan izin yang diperlukan untuk berkomunikasi dengan layanan tersebut. Lihat juga Memahami peran. Nama akun layanan harus diberikan saat Anda men-deploy proxy yang menggunakan autentikasi Google.
Runtime	Khusus Apigee Hybrid	Mengizinkan runtime Apigee menghasilkan token untuk melakukan autentikasi pada layanan Google yang diminta oleh proxy API. Akun layanan ini "meniru identitas" akun layanan khusus proxy untuk melakukan panggilan yang diautentikasi atas namanya. Agar dapat meniru identitas akun layanan proxy dan membuat token, akun layanan runtime harus diberi peran roles/iam.serviceAccountTokenCreator pada akun layanan proxy. Lihat Mengelola akses ke akun layanan.