Mengintegrasikan frontend aplikasi

Halaman ini menjelaskan cara mengintegrasikan frontend aplikasi Anda dengan Cloud Marketplace untuk memberikan pengalaman yang lancar kepada pelanggan Anda saat mereka beralih dari Cloud Marketplace ke produk Anda.

Secara umum, Anda harus memberikan URL pendaftaran untuk menangani pembuatan akun pengguna, yang kemudian dikelola di konsol web Anda. Anda juga harus memberikan URL bagi pengguna untuk login. Secara opsional, Anda dapat mengintegrasikan Single Sign-On (SSO).

Menggunakan Producer Portal untuk mengintegrasikan frontend aplikasi Anda

Untuk mengakses semua informasi yang Anda butuhkan untuk mengintegrasikan frontend aplikasi dengan Cloud Marketplace dari satu lokasi, Anda dapat menggunakan bagian Integrasi frontend di Producer Portal.

Link langsung ke Producer Portal adalah:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

Untuk mengakses bagian Integrasi frontend:

1. Dalam daftar produk, klik nama produk Anda.

2. Di halaman Ringkasan produk Anda, buka bagian Integrasi teknis, lalu klik Integrasi frontend.

Tambahkan URL pendaftaran Anda

Saat pengguna membeli produk Anda dari Cloud Marketplace, Anda harus membuat akun dengan produk Anda untuk mereka. Untuk melakukannya, Anda harus membuat halaman pendaftaran untuk menyiapkan dan menyetujui akun pengguna di sistem Anda. Anda dapat menyiapkan halaman sebagai halaman pendaftaran tempat pengguna mendaftar akun di sistem Anda, atau sebagai halaman yang menyetujui akun secara otomatis.

Setelah membuat halaman pendaftaran, tambahkan halaman tersebut di Producer Portal:

1. Dalam daftar produk, klik nama produk Anda.

2. Di halaman Ringkasan produk Anda, buka bagian Integrasi teknis, lalu klik Integrasi frontend.

3. Masukkan URL halaman pendaftaran Anda ke kolom URL pendaftaran.

Memverifikasi informasi pendaftaran pengguna

Jika pengguna belum membuat akun di sistem Anda, mereka harus mengklik tombol Daftar dengan YOUR_COMPANY_NAME di Cloud Marketplace. Saat mengklik tombol, Google Cloud mengirimkan permintaan HTTP POST ke halaman pendaftaran Anda, dengan JSON Web Token (JWT) di parameter x-gcp-marketplace-token. JWT berisi ID akun pengadaan pengguna, yang mengidentifikasi mereka sebagai pengguna Google Cloud , dan ID yang di-obfuscate, yang merepresentasikan ID Akun Google mereka. Anda harus menggunakan ID akun pengadaan dan ID yang di-obfuscate untuk menautkan Akun Google pengguna ke akunnya di sistem Anda.

Setelah memverifikasi JWT, halaman pendaftaran Anda harus mengirimkan permintaan persetujuan akun ke Partner Procurement API, yang dijelaskan dalam langkah-langkah integrasi backend.

Untuk mengetahui informasi mendetail tentang payload JWT dan cara memverifikasinya, lihat Verifikasi JWT di bawah.

Jika Anda baru menggunakan JWT, lihat pengantar JWT.

Tambahkan URL login Anda

Anda harus menentukan URL untuk halaman login aplikasi Anda.

Untuk memasukkan URL halaman login aplikasi Anda di Producer Portal:

1. Dalam daftar produk, klik nama produk Anda.

2. Di halaman Ringkasan produk Anda, buka bagian Integrasi teknis, lalu klik Integrasi frontend.

3. Masukkan URL halaman login aplikasi Anda ke kolom URL Login.

(Opsional) Mengaktifkan Single Sign-On (SSO) untuk pelanggan Anda

Untuk mengaktifkan SSO di Producer Portal:

1. Dalam daftar produk, klik nama produk Anda.

   1. Di halaman Ringkasan produk Anda, buka bagian Integrasi teknis, lalu klik Integrasi frontend.

   2. Di bagian Aktifkan login SSO?, pilih Ya.

Memverifikasi informasi login SSO pelanggan Anda

Saat pelanggan login ke aplikasi Anda menggunakan SSO, Google Cloud mengirim permintaan HTTP POST ke halaman login aplikasi Anda, dengan Token Web JSON (JWT) dengan format yang sama seperti JWT yang dikirim saat pengguna pertama kali mendaftar ke aplikasi Anda.

Untuk mengetahui informasi mendetail tentang payload JWT dan cara memverifikasinya, lihat Verifikasi JWT di bawah.

Verifikasi JWT

Beberapa proses, seperti mendaftarkan pelanggan baru atau login pelanggan dengan SSO, melibatkan pengiriman permintaan HTTP POST kepada Anda dengan JSON Web Token (JWT) yang mungkin perlu Anda verifikasi.

Tabel berikut mencantumkan:

• Peristiwa yang melibatkan pengiriman permintaan HTTP dengan JWT.
• Jenis permintaan HTTP yang terlibat.
• Apakah Anda harus memverifikasi JWT atau tidak.

Payload JWT

Payload JWT memiliki format berikut:

Header

{
  "alg": "RS256",
  "kid": "KEY_ID"
}

Dengan:

• alg selalu RS256.
• kid menunjukkan ID kunci yang digunakan untuk mengamankan JWT. Gunakan ID kunci untuk mencari kunci dari objek JSON dalam atribut iss di payload.

Payload

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_ID
  }
}

Dengan:

• sub adalah ID Akun Google pengguna. Anda harus menggunakan ID ini untuk menautkan Akun Google pengguna ke akunnya di sistem Anda.
• iss mengidentifikasi pengirim JWT. URL di klaim iss ditautkan ke kunci publik dari Google.
• exp menunjukkan kapan masa berlaku token berakhir, dan ditetapkan ke 5 menit setelah token dikirim.
• aud adalah domain yang menghosting produk Anda, seperti example.com.

• roles adalah array string yang merepresentasikan peran pengguna. Hal ini dapat berupa:

  • account_admin, yang menunjukkan bahwa pengguna adalah Billing Account Administrator (Order Administrator) dari akun penagihan yang membeli produk, atau

  • project_editor, yang menunjukkan bahwa pengguna adalah Editor (Pengelola Hak), tetapi bukan Administrator Penagihan, project dalam akun penagihan tersebut.

• user_identity adalah ID GAIA pengguna yang di-obfuscate, yang dapat digunakan untuk memulai OpenID Connect.

Payload untuk beberapa pesanan produk yang sama

Jika Anda telah mengaktifkan beberapa pesanan produk yang sama, payload akan menyertakan objek orders tambahan. Hal ini mencakup ID pesanan unik yang sesuai dengan ID hak untuk setiap pesanan. Pastikan halaman login aplikasi Anda dapat merespons kolom orders baru ini.

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_ID,
    "orders": [ORDER_ID1, ORDER_ID2]
  }
}

Dengan:

• ORDER_ID adalah daftar ID pesanan unik untuk setiap ID hak yang menunjukkan berbagai penawaran pada produk yang sama. Kolom ini hanya tersedia jika beberapa pesanan produk yang sama diaktifkan.

Untuk mengetahui informasi selengkapnya tentang cara mengaktifkan beberapa pesanan produk yang sama, lihat Mengaktifkan beberapa pesanan produk yang sama.

Verifikasi payload

Saat menerima JWT, Anda harus memverifikasi hal berikut:

1. Verifikasi bahwa tanda tangan JWT menggunakan kunci publik dari Google.

2. Pastikan JWT belum habis masa berlakunya, dengan memeriksa klaim exp.

3. Pastikan klaim aud adalah domain yang benar untuk produk Anda.

4. Verifikasi bahwa klaim iss adalah https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com.

5. Pastikan sub tidak kosong.

Mulai login dengan Google menggunakan login_hint

Jika Anda ingin pengguna melewati alur izin OAuth 2.0 dengan situs Anda, Anda dapat menggunakan informasi identitas dari payload untuk memulai alur tersebut di Akun Google yang mereka gunakan untuk Google Cloud sebelum pengalihan. Untuk melakukannya, Anda memberikan user_identity yang disediakan di JWT sebagai login_hint. Untuk mengetahui informasi selengkapnya, buka dokumentasi Google OAuth 2.0.

Setelah pengguna menyelesaikan alur OAuth 2.0 dengan situs Anda, Anda harus memverifikasi bahwa pengguna tersebut adalah pengguna yang Anda harapkan untuk menyelesaikan alur OAuth. Anda melakukannya dengan menggunakan token akses OAuth 2.0 untuk memanggil Google UserInfo API guna mengambil informasi pengguna dasar mereka. Tindakan ini akan menampilkan ID yang diharapkan cocok dengan kolom user_identity dari JWT.

Membuat akun layanan untuk pelanggan Anda

Jika produk Anda memerlukan akun layanan, Anda dapat bekerja sama dengan engineer partner untuk:

• Menyediakan akun layanan untuk pelanggan Anda, dan
• Siapkan halaman pengelolaan akun layanan agar pelanggan Anda dapat memberikan peran Identity and Access Management (IAM) yang diperlukan ke akun layanan.

Anda harus memberikan link ke halaman akun layanan ini kepada pelanggan Anda, biasanya melalui konsol pengelolaan produk Anda.

Sediakan akun layanan

Untuk menyediakan akun layanan, hubungi Partner Engineer Anda dan sertakan informasi berikut:

• Nama layanan: Ini adalah ID produk unik yang membedakan produk Anda dari produk lain. Sebaiknya gunakan nama layanan yang Anda buat saat Anda mengaktifkan produk Anda.

• Project ID: ID project tempat Anda membuat akun layanan yang mengakses resource pelanggan Anda. Anda harus membuat semua akun layanan yang digunakan produk Anda dalam satu project.

• Peran IAM dan alasan: Peran IAM yang diperlukan untuk akun layanan, dan alasan mengapa peran tersebut diperlukan. Informasi ini dibagikan kepada pelanggan Anda dan dapat memengaruhi apakah pelanggan Anda memberikan akses ke akun layanan.

Jika Anda ingin pelanggan kembali ke situs Anda setelah mereka memberikan akses ke akun layanan, kirimkan nama domain konsol Anda kepada partner engineer Anda. Anda dapat mengirim beberapa nama domain, termasuk subdomain, seperti staging.example.com.

Mengintegrasikan halaman pengelolaan akun layanan ke konsol produk Anda

Partner engineer membuat halaman pengelolaan akun layanan untuk memungkinkan pelanggan Anda memberikan akses ke akun layanan. Kemudian, Anda menautkan ke halaman dari konsol.

Setelah partner engineer memberi tahu Anda bahwa halaman pengelolaan akun layanan sudah siap, tambahkan parameter ke URL, lalu tautkan ke halaman dari konsol Anda.

Anda harus menambahkan dua parameter ke URL:

• service-name: Ini adalah nama layanan yang Anda berikan kepada partner engineer Anda.

• service-account-email: Ini adalah alamat email akun layanan yang Anda buat untuk pelanggan Anda. Setiap pelanggan memiliki akun layanan yang unik.

Contoh berikut menunjukkan URL dengan parameter yang diperlukan:

https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email

Anda dapat menambahkan parameter tambahan bergantung pada kebutuhan pelanggan. Misalnya:

https://console.google.com/marketplace-saas/service-account/service-name/service-account-email;single=true;redirect=https%3A%2F%2Fexample.com

Parameter URL menunjukkan bahwa produk Anda memerlukan akses ke satu project dan pelanggan dapat kembali ke konsol Anda.Google Cloud

Daftar parameter URL

Berikut adalah daftar parameter URL yang dapat Anda kirim ke halaman pengelolaan akun layanan: