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 level tinggi, Anda harus menyediakan 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 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:
Dalam daftar produk, klik nama produk Anda.
Di halaman Overview produk Anda, buka bagian Technical integration dan klik Frontend integration.
Tambahkan URL pendaftaran Anda
Saat pengguna membeli produk 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 dapat menyiapkan halaman tersebut sebagai halaman pendaftaran tempat pengguna mendaftar ke akun di sistem Anda, atau sebagai halaman yang menyetujui akun secara otomatis.
Setelah membuat halaman pendaftaran, tambahkan di Producer Portal:
Dalam daftar produk, klik nama produk Anda.
Di halaman Overview produk Anda, buka bagian Technical integration dan klik Frontend integration.
Masukkan URL halaman pendaftaran di kolom URL Pendaftaran.
Memverifikasi informasi pendaftaran pengguna
Jika pengguna belum membuat akun di sistem Anda, mereka harus mengklik tombol Daftar ke YOUR_COMPANY_NAME
di Cloud Marketplace. Saat mereka mengklik tombol tersebut, Google Cloud akan mengirimkan permintaan HTTP POST
ke halaman pendaftaran Anda, dengan Token Web JSON (JWT) di 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 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 informasi mendetail tentang payload JWT dan cara memverifikasinya, lihat Memverifikasi JWT di bawah.
Jika Anda baru pertama kali menggunakan JWT, baca bagian 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:
Dalam daftar produk, klik nama produk Anda.
Di halaman Overview produk Anda, buka bagian Technical integration dan klik Frontend integration.
Masukkan URL untuk halaman login aplikasi Anda ke kolom Login URL.
(Opsional) Mengaktifkan single sign-on (SSO) untuk pelanggan Anda
Untuk mengaktifkan SSO di Producer Portal:
Dalam daftar produk, klik nama produk Anda.
Di halaman Overview produk Anda, buka bagian Technical integration lalu klik Frontend integration.
Di bagian Enable SSO login?, pilih Yes.
Memverifikasi informasi login SSO pelanggan Anda
Ketika pelanggan login ke aplikasi menggunakan SSO, Google Cloud akan mengirimkan permintaan HTTP POST
ke halaman login aplikasi Anda dengan Token Web JSON (JWT) dalam format yang sama seperti yang dikirim JWT 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, melibatkan pengiriman permintaan HTTP POST
dengan Token Web JSON (JWT) yang mungkin perlu Anda verifikasi.
Tabel berikut mencantumkan:
- Peristiwa yang melibatkan pengiriman permintaan HTTP dengan JWT.
- Jenis permintaan HTTP yang dilibatkan.
- Apakah Anda harus memverifikasi JWT atau tidak.
Acara | Jenis permintaan HTTP | Verifikasi JWT diperlukan |
---|---|---|
Mendaftarkan pelanggan baru |
POST |
Ya |
Login pelanggan, tanpa SSO |
GET |
Tidak |
Login pelanggan, dengan SSO |
POST |
Ya |
Payload JWT
Payload JWT dalam format berikut:
Header
{ "alg": "RS256", "kid": "KEY_ID" }
Dengan keterangan:
alg
selaluRS256
.kid
menunjukkan ID kunci yang digunakan untuk mengamankan JWT. Gunakan ID kunci untuk mencari kunci dari objek JSON di atributiss
dalam 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 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 klaimiss
tertaut ke kunci publik dari Google.exp
menunjukkan kapan token berakhir, dan ditetapkan ke 5 menit setelah token dikirim.aud
adalah domain yang menghosting produk Anda, sepertiexample.com
.roles
adalah array string yang mewakili peran pengguna. Dapat berupa:account_admin
, yang menunjukkan bahwa pengguna adalah Administrator Akun Penagihan (Administrator Pesanan) akun penagihan yang membeli produk, atauproject_editor
, yang menunjukkan bahwa pengguna adalah Editor (Entitlement Manager), tetapi bukan Administrator Penagihan, project di akun penagihan tersebut.
user_identity
adalah ID GAIA pengguna yang di-obfuscate, yang dapat digunakan untuk memulai OpenID Connect.
Memverifikasi payload
Saat Anda menerima JWT, Anda harus memverifikasi hal-hal berikut:
Pastikan tanda tangan JWT menggunakan kunci publik dari Google.
Verifikasi bahwa JWT belum habis masa berlakunya, dengan memeriksa klaim
exp
.Verifikasi bahwa klaim
aud
adalah domain yang benar untuk produk Anda.Verifikasi bahwa klaim
iss
adalahhttps://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com
.Pastikan
sub
tidak kosong.
Mulai login dengan Google dengan login_hint
Jika ingin pengguna melalui alur izin OAuth 2.0 dengan situs Anda, Anda dapat menggunakan informasi identitas dari payload untuk menginisialisasi alur tersebut di Akun Google yang mereka gunakan untuk Google Cloud sebelum pengalihan. Untuk melakukannya, berikan user_identity
yang diberikan di JWT sebagai login_hint
.
Untuk informasi selengkapnya, buka
dokumentasi Google OAuth 2.0.
Setelah pengguna menyelesaikan alur OAuth 2.0 dengan situs Anda, sebaiknya verifikasi
bahwa mereka adalah pengguna yang Anda harapkan untuk menyelesaikan alur OAuth. Anda dapat melakukannya dengan menggunakan token akses OAuth 2.0 untuk memanggil Google UserInfo API guna mengambil informasi dasar tentang pengguna. 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 partner engineer 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.
Menyediakan 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 mengaktivasi produk.
Project ID: ID project tempat Anda membuat akun layanan yang mengakses resource pelanggan. Anda harus membuat semua akun layanan yang digunakan produk Anda dalam satu project.
Peran dan alasan IAM: Peran IAM yang diperlukan untuk akun layanan, dan alasan mengapa peran tersebut diperlukan. Tindakan ini dibagikan kepada pelanggan dan dapat memengaruhi apakah pelanggan memberikan akses ke akun layanan.
Jika Anda ingin pelanggan kembali ke situs setelah mereka memberikan
akses ke akun layanan, kirim nama domain konsol Anda kepada
partner engineer. Anda dapat mengirim beberapa nama domain, termasuk subdomain,
seperti staging.example.com
.
Integrasikan halaman pengelolaan akun layanan ke konsol produk Anda
Partner engineer membuat halaman pengelolaan akun layanan agar pelanggan Anda dapat memberikan akses ke akun layanan. Anda kemudian menautkan ke halaman dari konsol Anda.
Setelah partner engineer memberi tahu Anda bahwa halaman pengelolaan akun layanan sudah siap, tambahkan parameter ke URL, lalu tautkan ke halaman tersebut dari konsol Anda.
Anda harus menambahkan dua parameter ke URL:
service-name
: Ini adalah nama layanan yang Anda berikan kepada partner engineer.service-account-email
: Ini adalah alamat email akun layanan yang Anda buat untuk pelanggan. Setiap pelanggan memiliki akun layanan 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 Anda. 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 partner engineer. |
service-account-email | Wajib diisi. Ini adalah alamat email akun layanan yang Anda buat untuk pelanggan. |
single | Jika true (benar), ini menunjukkan bahwa produk Anda memerlukan akses ke satu project. |
hints=project-id-1 | Menetapkan project yang ingin diakses oleh akun layanan. Gunakan koma untuk memisahkan project. |
filter=role1 | Membatasi peran yang diberikan ke akun layanan ke sebagian peran yang Anda berikan kepada partner engineer. Kecualikan roles/ saat menggunakan filter. |
redirect | Menyediakan link bagi pelanggan untuk kembali ke konsol pengelolaan Anda. Nama domain harus didaftarkan ke partner engineer Anda untuk menggunakan parameter ini. |