Mengintegrasikan frontend aplikasi

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

Pada tingkat tinggi, Anda harus memberikan URL pendaftaran untuk menangani pembuatan akun pengguna, yang kemudian dikelola di konsol web Anda. Anda juga harus menyediakan URL bagi pengguna untuk login. Secara opsional, Anda dapat mengintegrasikan single sign-on (SSO).

Menggunakan Producer Portal untuk mengintegrasikan frontend aplikasi

Untuk mengakses semua informasi yang diperlukan guna mengintegrasikan frontend aplikasi dengan Cloud Marketplace dari satu lokasi, Anda dapat menggunakan bagian Integrasi frontend di Portal Produsen.

Link langsung ke Producer Portal adalah:

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

Catatan: Jika Anda tidak melihat link, atau tidak dapat mengakses URL, pastikan Anda telah memilih project yang benar. Jika Anda masih tidak dapat mengakses URL, gunakan Partner Support Desk untuk meminta bantuan, dan sertakan kata "Marketplace" dalam deskripsi Anda. Untuk mengetahui informasi selengkapnya tentang Partner Support Desk, buka Meminta bantuan terkait Cloud Marketplace.

Untuk mengakses bagian Integrasi frontend:

1. Dalam daftar produk, klik nama produk Anda.

2. Di halaman Ringkasan produk Anda, buka bagian Integrasi teknis dan 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 ke akun di sistem Anda, atau sebagai halaman yang menyetujui akun secara otomatis.

Perhatian: Saat menyiapkan halaman pendaftaran, pastikan pengguna dapat mengakses halaman tanpa memasukkan nama pengguna dan sandi terlebih dahulu.

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 untuk 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 pengguna mengklik tombol, Google Cloud akan mengirimkan permintaan HTTP POST ke halaman pendaftaran Anda, dengan Token Web JSON (JWT) dalam parameter x-gcp-marketplace-token. JWT berisi ID akun pengadaan pengguna, yang mengidentifikasinya sebagai pengguna Google Cloud, dan ID yang di-obfuscate, yang mewakili ID Akun Google-nya. Anda harus menggunakan ID akun pengadaan dan ID yang di-obfuscate untuk menautkan Akun Google pengguna ke akun mereka di sistem Anda.

Catatan: Satu pengguna dapat memiliki beberapa ID akun pengadaan, atau beberapa pengguna dapat berbagi ID akun pengadaan yang sama, bergantung pada cara mereka atau organisasi mereka mengonfigurasi penggunaan Google Cloud.

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

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

Jika Anda baru menggunakan JWT, lihat pengantar JWT.

Menambahkan URL login

Anda harus menentukan URL untuk halaman login aplikasi.

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 untuk halaman login aplikasi Anda ke kolom URL Login.

(Opsional) Mengaktifkan single sign-on (SSO) untuk pelanggan

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 Enable SSO login?, pilih Yes.

Memverifikasi informasi login SSO pelanggan

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

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

Memverifikasi JWT

Beberapa proses, seperti mendaftarkan pelanggan baru atau login pelanggan dengan SSO, memerlukan 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.

Acara	Jenis permintaan HTTP	Verifikasi JWT diperlukan
Mendaftarkan pelanggan baru	POST	Ya
Login pelanggan, tanpa SSO	DAPATKAN	Tidak
Login pelanggan, dengan SSO	POST	Ya

Payload JWT

Payload JWT memiliki format berikut:

Header

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

Dengan keterangan:

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

Payload

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/[e-mail]",
  "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 keterangan:

• 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 dalam 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 mewakili peran pengguna. 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, untuk project dalam akun penagihan tersebut.

  Catatan: Jika Anda telah mengaktifkan single sign-on (SSO), pengguna dengan peran account_admin juga harus memiliki peran project_editor.

• user_identity adalah ID GAIA yang di-obfuscate milik pengguna, 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/[e-mail]",
  "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 keterangan:

• 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 informasi selengkapnya tentang cara mengaktifkan beberapa pesanan produk yang sama, lihat Mengaktifkan beberapa pesanan produk yang sama.

Memverifikasi payload

Saat menerima JWT, Anda harus memverifikasi hal berikut:

1. Pastikan 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/[e-mail].

5. Pastikan sub tidak kosong.

Catatan: Karena kami dapat menambahkan kolom baru ke JWT, Anda tidak boleh menganggap JWT tidak valid hanya karena berisi kolom baru yang belum Anda temukan.

Memulai login dengan Google menggunakan login_hint

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

Setelah pengguna menyelesaikan alur OAuth 2.0 dengan situs Anda, Anda harus memverifikasi bahwa mereka 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 dasarnya. Tindakan ini akan menampilkan ID yang diharapkan cocok dengan kolom user_identity dari JWT.

Membuat akun layanan untuk pelanggan Anda

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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 bagi pelanggan Anda untuk memberikan peran Identity and Access Management (IAM) yang diperlukan ke akun layanan.

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

Menyediakan akun layanan

Untuk menyediakan akun layanan, hubungi engineer partner 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 melakukan aktivasi produk.

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

• Peran dan alasan IAM: 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, kirim nama domain konsol Anda ke engineer partner Anda. Anda dapat mengirim beberapa nama domain, termasuk subdomain, seperti staging.example.com.

Mengintegrasikan halaman pengelolaan akun layanan ke konsol produk Anda

Engineer partner membuat halaman pengelolaan akun layanan untuk memungkinkan pelanggan Anda memberikan akses ke akun layanan. Kemudian, Anda akan menautkan ke halaman tersebut dari konsol.

Setelah engineer partner 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 engineer partner.

• service-account-email: Ini adalah alamat email akun layanan yang Anda buat untuk pelanggan. 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 Google Cloud dan bahwa pelanggan dapat kembali ke konsol Anda.

Daftar parameter URL

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

Parameter	Deskripsi
service-name	Wajib diisi. Ini adalah nama layanan yang Anda berikan kepada engineer partner.
service-account-email	Wajib diisi. Ini adalah alamat email akun layanan yang Anda buat untuk pelanggan.
single	Jika benar (true), hal ini menunjukkan bahwa produk Anda memerlukan akses ke satu project.
hints=project-id-1	Menetapkan project yang ingin Anda akses oleh akun layanan. Gunakan koma untuk memisahkan project.
filter=role1	Membatasi peran yang diberikan ke akun layanan ke sebagian peran yang Anda berikan kepada engineer partner. Kecualikan roles/ saat menggunakan filter.
redirect	Memberikan link bagi pelanggan untuk kembali ke konsol pengelolaan Anda. Nama domain harus terdaftar dengan partner engineer Anda untuk menggunakan parameter ini.