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 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

Catatan: Jika Anda tidak melihat link, atau tidak dapat mengakses URL, pastikan Anda telah memilih project yang benar. Jika Anda tetap 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 dengan Cloud Marketplace.

Untuk mengakses bagian Integrasi frontend:

1. Dalam daftar produk, klik nama produk Anda.

2. 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.

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

Setelah membuat halaman pendaftaran, tambahkan di Producer Portal:

1. Dalam daftar produk, klik nama produk Anda.

2. Di halaman Overview produk Anda, buka bagian Technical integration dan klik Frontend integration.

3. 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.

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

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:

1. Dalam daftar produk, klik nama produk Anda.

2. Di halaman Overview produk Anda, buka bagian Technical integration dan klik Frontend integration.

3. 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:

1. Dalam daftar produk, klik nama produk Anda.

   1. Di halaman Overview produk Anda, buka bagian Technical integration lalu klik Frontend integration.

   2. 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 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 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, seperti example.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, atau

  • project_editor, yang menunjukkan bahwa pengguna adalah Editor (Entitlement Manager), tetapi bukan Administrator Penagihan, project di 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 pengguna yang di-obfuscate, yang dapat digunakan untuk memulai OpenID Connect.

Memverifikasi payload

Saat Anda menerima JWT, Anda harus memverifikasi hal-hal berikut:

1. Pastikan tanda tangan JWT menggunakan kunci publik dari Google.

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

3. Verifikasi bahwa 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 kita mungkin menambahkan kolom baru ke JWT, Anda tidak boleh menganggap JWT tidak valid hanya karena berisi kolom baru yang belum Anda temukan.

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

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 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.