Questa pagina descrive come integrare il frontend dell'app con Cloud Marketplace per offrire ai clienti un'esperienza fluida durante il passaggio da Cloud Marketplace al tuo prodotto.
A grandi linee, devi fornire un URL di registrazione per gestire la creazione degli account degli utenti, che vengono poi gestiti nella tua console web. Devi anche fornire un URL per consentire agli utenti di accedere. Se vuoi, puoi integrare il Single Sign-On (SSO).
Utilizzare Producer Portal per integrare il frontend dell'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 del Producer Portal.
Il link diretto al Producer Portal è:
https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID
Per accedere alla sezione Integrazione del frontend:
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.
Aggiungi l'URL di registrazione
Quando gli utenti acquistano il tuo prodotto da Cloud Marketplace, devi creare un account per il tuo prodotto. Per farlo, devi creare una pagina di registrazione per configurare e approvare gli account degli utenti nel tuo sistema. Puoi configurare la pagina come pagina di registrazione in cui gli utenti registrano 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 registrazione.
Verificare i dati 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 l'utente fa 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 acquisti dell'utente, che lo identifica come utente Google Cloud, e un ID offuscato, che rappresenta il suo ID Account Google. Per collegare l'Account Google dell'utente al suo account nel tuo sistema, devi utilizzare sia l'ID account acquisti sia l'ID offuscato.
Dopo aver verificato il token JWT, la pagina di registrazione deve inviare una richiesta di approvazione dell'account all'API Partner Procurement, descritta nei passaggi di integrazione del 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 ai 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 della tua app nel campo URL di accesso.
(Facoltativo) Attivare il Single Sign-On (SSO) per i clienti
Per attivare l'SSO nel 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ì.
Verifica i dati di accesso SSO dei tuoi clienti
Quando i clienti accedono alla tua app utilizzando l'accessoSSO, 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 alla tua app.
Per informazioni dettagliate sul payload JWT e su come verificarlo, consulta la sezione Verificare il JWT di seguito.
Verificare il JWT
Alcune procedure, come la registrazione di un nuovo cliente o l'accesso di un cliente con la gestione dell'autenticazione singola, richiedono l'invio di una richiesta HTTP POST
con un
token JWT (JSON Web Token) che potresti dover verificare.
La tabella seguente elenca:
- Eventi che comportano l'invio di una richiesta HTTP con un JWT.
- Il tipo di richiesta HTTP coinvolta.
- Se devi o meno verificare il JWT.
Evento | Tipo di richiesta HTTP | Verifica JWT obbligatoria |
---|---|---|
Registra un nuovo cliente |
POST |
Sì |
Accesso dei clienti senza SSO |
GET |
No |
Accesso dei clienti con SSO |
POST |
Sì |
Il payload JWT
Il payload JWT ha il seguente formato:
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
nel 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 Account Google dell'utente. Devi utilizzare questo ID per collegare l'Account Google dell'utente al suo account nel tuo sistema.iss
identifica il mittente del JWT. L'URL nella rivendicazioneiss
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 rappresentano i ruoli dell'utente. Può essere:account_admin
, che indica che l'utente è un amministratore account di fatturazione (amministratore dell'ordine) dell'account di fatturazione che ha acquistato il prodotto oppureproject_editor
, che indica che l'utente è un editor (gestore dei diritti), ma non un amministratore della fatturazione, del progetto nell'account di fatturazione in questione.
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 attivato più ordini dello stesso prodotto, il payload include un oggetto orders
aggiuntivo. Sono inclusi 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 sullo stesso prodotto. Questo campo è disponibile solo se sono attivati più ordini dello stesso prodotto.
Per ulteriori informazioni su come attivare più ordini dello stesso prodotto, consulta Attivare più ordini dello 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 token JWT non sia scaduto controllando l'affermazione
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
sub
non sia vuoto.
Avvia l'accesso con Google con login_hint
Se vuoi che i tuoi utenti completino un flusso di consenso OAuth 2.0 sul 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, fornisci il user_identity
fornito nel JWT come login_hint
.
Per ulteriori informazioni, consulta la
documentazione di Google OAuth 2.0.
Una volta che l'utente ha completato il flusso OAuth 2.0 con il tuo sito, devi verificare che sia l'utente che ti aspettavi di completare il flusso OAuth. Per farlo,
utilizza il token di accesso OAuth 2.0 per chiamare l'API UserInfo di Google e recuperare le informazioni di base sull'utente. Viene restituito un ID che dovrebbe corrispondere al campo user_identity
del JWT.
Creare account di servizio per i clienti
Se il tuo prodotto richiede un account di servizio, puoi collaborare con un ingegnere partner per:
- Esegui il provisioning degli account di servizio per i tuoi clienti e
- Configura una pagina di gestione degli account di servizio per consentire ai clienti di concedere agli account di servizio i ruoli IAM (Identity and Access Management) richiesti.
Devi fornire ai clienti il link a questa pagina dell'account di servizio, solitamente tramite la console di gestione del tuo prodotto.
Esegui il provisioning degli account di servizio
Per eseguire il provisioning degli account di servizio, contatta l'ingegnere del partner e includi le seguenti informazioni:
Nome del servizio: si tratta di un ID prodotto univoco che distingue il tuo prodotto da altri prodotti. Ti consigliamo di utilizzare il nome del servizio che hai creato durante l'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 tuo prodotto all'interno di un unico progetto.
Ruoli IAM e motivazione: i ruoli IAM richiesti per gli account di servizio e il motivo per cui sono necessari. Questo viene condiviso con il cliente e può influire sul fatto che il cliente conceda o meno l'accesso all'account di servizio.
Se vuoi che il cliente torni al tuo sito dopo aver concesso l'accesso all'account di servizio, invia il nome di dominio della tua console al tuo tecnico partner. Puoi inviare più nomi di dominio, inclusi i sottodomini, come staging.example.com
.
Integrare la pagina di gestione dell'account di servizio nella console del prodotto
L'ingegnere partner crea una pagina di gestione degli account di servizio per consentire ai clienti di concedere l'accesso agli account di servizio. Poi, fai clic sul link alla pagina dalla console.
Quando l'ingegnere del partner ti comunica che la pagina di gestione dell'account di servizio è pronta, aggiungi i parametri all'URL e poi collega la pagina dalla console.
Devi aggiungere due parametri all'URL:
service-name
: il nome del servizio che hai fornito all'ingegnere partner.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.
L'esempio seguente mostra un URL con i parametri richiesti:
https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email
Puoi aggiungere parametri aggiuntivi in base alle esigenze dei tuoi 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 tuo prodotto richiede l'accesso a un singolo progetto Google Cloud e che il cliente può tornare alla tua console.
Elenco di 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 all'ingegnere partner. |
service-account-email | Campo obbligatorio. Si tratta dell'indirizzo email dell'account di servizio che hai creato per il cliente. |
single | Se il valore è true, indica che il tuo prodotto richiede l'accesso a un singolo progetto. |
hints=project-id-1 | Imposta il progetto a cui vuoi che acceda 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 che hai fornito all'ingegnere partner. Escludi roles/ quando utilizzi il filtro. |
redirect | Fornisce un link per consentire al cliente di tornare alla tua console di gestione. Per utilizzare questo parametro, il nome di dominio deve essere registrato con il Partner Engineer. |