In questa pagina viene descritto come integrare il frontend della tua app con Cloud Marketplace per offrire ai clienti un'esperienza senza problemi quando passano da Cloud Marketplace al tuo prodotto.
A livello generale, devi fornire un URL di registrazione per gestire la creazione degli account utente, che vengono poi gestiti nella console web. Devi inoltre fornire un URL per l'accesso degli utenti. Facoltativamente, puoi integrare il servizio Single Sign-On (SSO).
Usa Producer Portal per integrare il frontend della tua app
Per accedere a tutte le informazioni necessarie per integrare il frontend della tua app con Cloud Marketplace da un'unica posizione, puoi utilizzare la sezione Integrazione frontend di Producer Portal.
Il link diretto al Producer Portal è:
https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID
Per accedere alla sezione Integrazione frontend:
Nell'elenco dei prodotti, fai clic sul nome del tuo prodotto.
Nella pagina Panoramica del prodotto, vai alla sezione Integrazione tecnica e fai clic su Integrazione frontend.
Aggiungi l'URL di registrazione
Quando gli utenti acquistano il tuo prodotto da Cloud Marketplace, devi creare un account con il prodotto per loro. Per farlo, devi creare una pagina di registrazione per configurare e approvare gli account degli utenti nel tuo sistema. Puoi impostare la pagina come pagina di registrazione in cui gli utenti possono creare un account nel tuo sistema o come pagina che approva automaticamente gli account.
Dopo aver creato la pagina di registrazione, aggiungila in Producer Portal:
Nell'elenco dei prodotti, fai clic sul nome del tuo prodotto.
Nella pagina Panoramica del tuo prodotto, vai alla sezione Integrazione tecnica e fai clic su Integrazione frontend.
Inserisci l'URL della pagina di registrazione nel campo URL di registrazione.
Verificare le informazioni di registrazione dell'utente
Se un utente non ha ancora creato un account nel tuo sistema, deve fare clic sul pulsante Registrati con YOUR_COMPANY_NAME
in Cloud Marketplace. Quando fanno clic sul pulsante, Google Cloud invia una
richiesta HTTP POST
alla tua pagina di registrazione, con un
token web JSON (JWT) nel
parametro x-gcp-marketplace-token
. Il JWT contiene l'ID account approvvigionamento dell'utente, che lo identifica come utente Google Cloud, e un ID offuscato, che rappresenta l'ID del suo Account Google. Devi utilizzare sia l'ID account di approvvigionamento sia l'ID offuscato per collegare l'Account Google dell'utente al suo account nel sistema.
Dopo aver verificato il JWT, la pagina di registrazione deve inviare una richiesta di approvazione dell'account all'API Partner Procurement, descritta nella procedura di integrazione backend.
Per informazioni dettagliate sul payload JWT e su come verificarlo, consulta la sezione Verificare il JWT di seguito.
Se non hai mai utilizzato i JWT, consulta l'introduzione a JWT.
Aggiungi l'URL di accesso
Devi specificare l'URL della pagina di accesso della tua app.
Per inserire l'URL della pagina di accesso della tua app in Producer Portal:
Nell'elenco dei prodotti, fai clic sul nome del tuo prodotto.
Nella pagina Panoramica del tuo prodotto, vai alla sezione Integrazione tecnica e fai clic su Integrazione frontend.
Inserisci l'URL della pagina di accesso dell'app nel campo URL di accesso.
(Facoltativo) Attivare il servizio Single Sign-On (SSO) per i clienti
Per attivare l'accesso SSO in Producer Portal:
Nell'elenco dei prodotti, fai clic sul nome del tuo prodotto.
Nella pagina Panoramica del tuo prodotto, vai alla sezione Integrazione tecnica e fai clic su Integrazione frontend.
In Abilitare l'accesso SSO?, seleziona Sì.
Verificare le informazioni di accesso SSO dei clienti
Quando i clienti accedono alla tua app utilizzando SSO, Google Cloud invia una
richiesta HTTP POST
alla pagina di accesso dell'app, con un
token web JSON (JWT)
dello stesso formato del JWT inviato quando gli utenti si registrano per la prima volta all'app.
Per informazioni dettagliate sul payload JWT e su come verificarlo, consulta la sezione Verificare il JWT di seguito.
Verifica il JWT
Alcuni processi, come la registrazione di un nuovo cliente o l'accesso di un cliente con
SSO, prevedono l'invio di una richiesta HTTP POST
con un
token web JSON (JWT) che potresti dover verificare.
Nella tabella seguente sono elencati:
- Eventi che prevedono l'invio di una richiesta HTTP con un JWT.
- Il tipo di richiesta HTTP interessata.
- Indica se devi verificare il JWT.
Evento | Tipo di richiesta HTTP | Verifica JWT obbligatoria |
---|---|---|
Registrare un nuovo cliente |
POST |
Sì |
Accesso cliente, senza SSO |
GET |
No |
Accesso cliente, con SSO |
POST |
Sì |
Il payload JWT
Il payload JWT è nel formato seguente:
Intestazione
{ "alg": "RS256", "kid": "KEY_ID" }
Dove:
alg
è sempreRS256
.kid
indica l'ID chiave utilizzato per proteggere il JWT. Utilizza l'ID chiave per cercare la chiave nell'oggetto JSON nell'attributoiss
del 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 } }
Dove:
sub
è l'ID dell'Account Google dell'utente. Devi utilizzare questo ID per collegare l'Account Google dell'utente al suo account nel sistema.iss
identifica il mittente del JWT. L'URL nella dichiarazioneiss
rimanda a una chiave pubblica di Google.exp
indica quando scade il token ed è impostato su 5 minuti dopo l'invio del token.aud
è il dominio che ospita il tuo prodotto, ad esempioexample.com
.roles
è un array di stringhe che rappresenta i ruoli dell'utente. Può essere:account_admin
, che indica che l'utente è un amministratore dell'account di fatturazione (amministratore degli ordini) dell'account di fatturazione che ha acquistato il prodotto oppureproject_editor
, che indica che l'utente è un editor (Gestione diritti), ma non un amministratore della fatturazione, del progetto in quell'account di fatturazione.
user_identity
è l'ID GAIA offuscato dell'utente, che può essere utilizzato per avviare OpenID Connect.
Payload per più ordini dello stesso prodotto
Se hai abilitato più ordini dello stesso prodotto, il payload include un oggetto orders
aggiuntivo. È incluso l'ID ordine univoco corrispondente all'ID diritto per ogni ordine. Assicurati che la pagina di accesso della tua app possa rispondere a questo nuovo campo orders
.
{ "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] } }
Dove:
ORDER_ID
è un elenco di ID ordine univoci per ogni ID diritto che indica le diverse offerte per lo stesso prodotto. Questo campo è disponibile soltanto se sono abilitati più ordini dello stesso prodotto.
Per ulteriori informazioni su come attivare più ordini dello stesso prodotto, vedi Attivare più ordini per lo stesso prodotto.
Verifica il payload
Quando ricevi il JWT, devi verificare quanto segue:
Verifica che la firma JWT utilizzi la chiave pubblica di Google.
Verifica che il JWT non sia scaduto controllando la rivendicazione
exp
.Verifica che la rivendicazione
aud
sia il dominio corretto per il tuo prodotto.Verifica che la rivendicazione
iss
siahttps://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com
.Verifica che il campo
sub
non sia vuoto.
Avvia Accedi con Google con login_hint
Se vuoi che i tuoi utenti eseguano un flusso di consenso OAuth 2.0 con il tuo sito,
puoi utilizzare le informazioni sull'identità del payload per inizializzare il flusso sull'Account Google che stavano utilizzando per Google Cloud prima del reindirizzamento. Per farlo, devi fornire il user_identity
fornito nel JWT come login_hint
.
Per ulteriori informazioni, consulta la documentazione di Google OAuth 2.0.
Dopo che l'utente ha completato il flusso OAuth 2.0 con il tuo sito, devi verificare
che sia l'utente che avevi previsto per completare il flusso OAuth. A tale scopo, utilizza il token di accesso OAuth 2.0 per chiamare l'API UserInfo di Google e recuperare le informazioni di base dell'utente. Questo restituisce un ID che dovrebbe corrispondere al campo user_identity
del JWT.
Crea account di servizio per i tuoi clienti
Se il tuo prodotto richiede un account di servizio, puoi collaborare con un Partner Engineer per:
- Esegui il provisioning degli account di servizio per i tuoi clienti e
- Configura una pagina di gestione degli account di servizio in modo che i tuoi clienti concedano i ruoli IAM (Identity and Access Management) richiesti agli account di servizio.
Devi fornire ai tuoi clienti il link a questa pagina dell'account di servizio, in genere tramite la console di gestione del prodotto.
Esegui il provisioning degli account di servizio
Per eseguire il provisioning degli account di servizio, contatta il tuo Partner Engineer e includi le seguenti informazioni:
Nome servizio: si tratta di un ID prodotto univoco che differenzia il tuo prodotto dagli altri. Ti consigliamo di utilizzare il nome del servizio che hai creato al momento dell'onboarding del prodotto.
ID progetto: l'ID del progetto in cui crei gli account di servizio che accedono alle risorse dei tuoi clienti. Devi creare tutti gli account di servizio utilizzati dal prodotto in un singolo progetto.
Ruoli e ragionamento IAM: i ruoli IAM richiesti per gli account di servizio e il motivo per cui sono necessari. Questa informazione viene condivisa con il tuo cliente e può influire sulla sua concessione dell'accesso all'account di servizio.
Se vuoi che il cliente torni sul tuo sito dopo aver concesso
l'accesso all'account di servizio, invia il nome di dominio della console al
tuo Partner Engineer. Puoi inviare più nomi di dominio, inclusi sottodomini,
ad esempio staging.example.com
.
Integra la pagina di gestione dell'account di servizio nella console del prodotto
Il Partner Engineer crea una pagina di gestione degli account di servizio per consentire ai clienti di concedere l'accesso agli account di servizio. Quindi, crei un link alla pagina dalla console.
Dopo che il Partner Engineer ti ha avvisato che la pagina di gestione dell'account di servizio è pronta, aggiungi parametri all'URL e inserisci un link alla pagina dalla console.
Devi aggiungere due parametri all'URL:
service-name
: si tratta del nome del servizio che hai fornito al tuo Partner Engineer.service-account-email
: si tratta dell'indirizzo email dell'account di servizio che hai creato per il tuo cliente. Ogni cliente ha un account di servizio univoco.
Nell'esempio seguente viene mostrato un URL con i parametri richiesti:
https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email
Puoi aggiungere ulteriori parametri a seconda delle esigenze dei clienti. Ad esempio:
https://console.google.com/marketplace-saas/service-account/service-name/service-account-email;single=true;redirect=https%3A%2F%2Fexample.com
I parametri dell'URL indicano che il prodotto richiede l'accesso a un singolo progetto Google Cloud e che il cliente può tornare alla tua console.
Elenco dei parametri URL
Di seguito è riportato un elenco dei parametri URL che puoi inviare alla pagina di gestione dell'account di servizio:
Parametro | Descrizione |
---|---|
service-name | Campo obbligatorio. Si tratta del nome del servizio che hai fornito al tuo Partner Engineer. |
service-account-email | Campo obbligatorio. Si tratta dell'indirizzo email dell'account di servizio che hai creato per il tuo cliente. |
single | Se impostato su true, indica che il prodotto richiede l'accesso a un singolo progetto. |
hints=project-id-1 | Imposta il progetto a cui vuoi accedere l'account di servizio. Utilizza le virgole per separare i progetti. |
filter=role1 | Limita i ruoli concessi all'account di servizio a un sottoinsieme dei ruoli forniti al tuo Partner Engineer. Escludi roles/ quando utilizzi il filtro. |
redirect | Fornisce al cliente un link per tornare alla tua console di gestione. Per utilizzare questo parametro, il nome di dominio deve essere registrato presso il tuo Partner Engineer. |