Integra il frontend della tua app

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

In questa pagina viene descritto come integrare il frontend della tua app con Cloud Marketplace per offrire ai clienti un'esperienza fluida durante il passaggio da Cloud Marketplace al prodotto.

A livello generale, devi fornire un URL di registrazione per gestire la creazione degli account utente, che verranno poi gestiti nella console web. Devi inoltre fornire un URL che consenta agli utenti di accedere. 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 l'integrazione del 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:

  1. Nell'elenco dei prodotti, fai clic sul nome del tuo prodotto.

  2. 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 tuo prodotto. A tale scopo, devi creare una pagina di registrazione per configurare e approvare gli account degli utenti nel tuo sistema. Puoi impostare la pagina come una pagina di registrazione in cui gli utenti registrano un account nel sistema o come pagina che approva automaticamente gli account.

Dopo aver creato la pagina di registrazione, aggiungila in Producer Portal:

  1. Nell'elenco dei prodotti, fai clic sul nome del tuo prodotto.

  2. Nella pagina Panoramica del prodotto, vai alla sezione Integrazione tecnica e fai clic su Integrazione frontend.

  3. 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 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 pagina di registrazione, con un token web JSON (JWT) nel parametro x-gcp-marketplace-token. Il JWT contiene l'ID account di acquisto dell'utente, che lo identifica come utente Google Cloud, e l'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 di approvvigionamento sia l'ID offuscato.

Dopo aver verificato il JWT, la tua pagina di registrazione dovrà inviare una richiesta di approvazione dell'account all'API Partner Procurement, come descritto nei passaggi di integrazione del backend.

Per informazioni dettagliate sul payload JWT e su come verificarlo, consulta la sezione Verificare il JWT riportato di seguito.

Se non hai mai utilizzato JWT, fai riferimento all'introduzione di JWT.

Aggiungi l'URL di accesso

Devi specificare l'URL della pagina di accesso dell'app.

Per inserire l'URL della pagina di accesso della tua app in Producer Portal:

  1. Nell'elenco dei prodotti, fai clic sul nome del tuo prodotto.

  2. Nella pagina Panoramica del prodotto, vai alla sezione Integrazione tecnica e fai clic su Integrazione frontend.

  3. Inserisci l'URL della pagina di accesso dell'app nel campo URL di accesso.

(Facoltativo) Abilita il Single Sign-On (SSO) per i clienti

Per abilitare il servizio SSO in Producer Portal:

  1. Nell'elenco dei prodotti, fai clic sul nome del tuo prodotto.

    1. Nella pagina Panoramica del prodotto, vai alla sezione Integrazione tecnica e fai clic su Integrazione frontend.

    2. In Abilitare l'accesso SSO?, seleziona .

Verifica i dati di accesso SSO dei tuoi 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 JSON Web Token (JWT) dello stesso formato del JWT inviato la prima volta che gli utenti si registrano alla tua app.

Per informazioni dettagliate sul payload JWT e su come verificarlo, consulta la sezione Verificare il JWT riportato di seguito.

Verificare il JWT

Alcuni processi, come la registrazione di un nuovo cliente o l'accesso a un cliente con SSO, prevedono l'invio di una richiesta HTTP POST con un JSON Web Token (JWT) che potresti dover verificare.

La seguente tabella elenca:

  • Eventi che comportano l'invio di una richiesta HTTP con un JWT.
  • Il tipo di richiesta HTTP coinvolta.
  • Che tu debba verificare o meno il JWT.
Evento Tipo di richiesta HTTP Verifica JWT obbligatoria

Registrare un nuovo cliente

POST

Accesso di clienti, senza SSO

GET

No

Accesso del cliente, con SSO

POST

Il payload JWT

Il payload JWT è nel seguente formato:

Intestazione

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

Dove:

  • alg è sempre RS256.
  • kid indica l'ID chiave utilizzato per proteggere il JWT. Utilizza l'ID chiave per cercare la chiave nell'oggetto JSON nell'attributo iss nel payload.

Carico utile

{
  "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 rivendicazione iss rimanda a una chiave pubblica di Google.
  • exp indica quando il token scade e viene impostato su 5 minuti dopo l'invio del token.
  • aud è il dominio che ospita il tuo prodotto, ad esempio example.com.
  • roles è una matrice di stringhe che rappresentano i ruoli dell'utente. Può essere:

  • user_identity è l'ID GAIA oscurato dell'utente, che può essere utilizzato per avviare OpenID Connect.

Verifica il payload

Quando ricevi il JWT, devi verificare quanto segue:

  1. Verifica che la firma JWT utilizzi la chiave pubblica di Google.

  2. Verifica che la JWT non sia scaduta controllando la rivendicazione di exp.

  3. Verifica che la rivendicazione aud sia il dominio corretto per il tuo prodotto.

  4. Verifica che la rivendicazione di iss sia https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com.

  5. Verifica che il campo sub non sia vuoto.

Avvia Accedi con Google con login_hint

Se vuoi che gli utenti seguano un flusso di consenso OAuth 2.0 con il tuo sito, puoi utilizzare le informazioni sull'identità provenienti dal payload per inizializzare tale flusso sull'Account Google che utilizzavano 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 di essere l'utente previsto per il flusso OAuth. A tale scopo, utilizza il token di accesso OAuth 2.0 per chiamare l'API Google UserInfo al fine di recuperare le informazioni utente di base. Questo restituisce 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 Partner Engineer per:

  • Provisioning degli account di servizio per i clienti e
  • Configura una pagina di gestione dell'account di servizio per consentire ai tuoi clienti di concedere i ruoli di Identity and Access Management (IAM) richiesti agli account di servizio.

Devi fornire il link a questa pagina dell'account di servizio ai tuoi clienti, 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 il tuo Partner Engineer e includi le seguenti informazioni:

  • Nome servizio: è un ID prodotto univoco che differenzia il tuo prodotto dagli altri. 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 prodotto all'interno di 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 cliente e può influire sulla concessione dell'accesso all'account di servizio da parte del cliente.

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 i sottodomini, ad esempio staging.example.com.

Integra la pagina di gestione dell'account di servizio nella console del tuo prodotto

Il Partner Engineer crea una pagina di gestione dell'account di servizio per consentire ai tuoi clienti di concedere l'accesso agli account di servizio. e poi a un link alla pagina dalla console.

Quando il tuo Partner Engineer ti avvisa che la pagina di gestione dell'account di servizio è pronta, aggiungi i parametri all'URL e poi esegui il collegamento alla pagina dalla tua 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: questo è l'indirizzo email dell'account di servizio che hai creato per il tuo cliente. Ciascun cliente ha un account di servizio unico.

L'esempio seguente mostra un URL con i parametri obbligatori:

https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email

Puoi aggiungere altri parametri 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 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:

ParametroDescrizione
service-nameCampo obbligatorio. Si tratta del nome del servizio che hai fornito al tuo Partner Engineer.
service-account-emailCampo obbligatorio. Si tratta dell'indirizzo email dell'account di servizio che hai creato per il tuo cliente.
singleSe true, indica che il tuo prodotto richiede l'accesso a un singolo progetto.
hints=project-id-1Imposta il progetto a cui vuoi accedere all'account di servizio. Utilizza le virgole per separare i progetti.
filter=role1Limita i ruoli concessi all'account di servizio a un sottoinsieme di ruoli forniti al tuo Partner Engineer. Escludi l'roles/ quando utilizzi il filtro.
redirectFornisce al cliente un link per tornare alla console di gestione. Per utilizzare questo parametro, il nome di dominio deve essere registrato presso il tuo Partner Engineer.