Integrare il frontend dell'app

Questa pagina descrive come integrare il frontend dell'app con Cloud Marketplace per consentirti di offrire ai clienti un'esperienza fluida durante il passaggio da Cloud Marketplace al tuo prodotto.

A livello generale, 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. Facoltativamente, 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 dell'app con Cloud Marketplace da un'unica posizione, puoi utilizzare la sezione Integrazione del frontend di Producer Portal.

Il link diretto al Producer Portal è:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

Nota: se non vedi il link o non riesci ad accedere all'URL, verifica di aver selezionato il progetto corretto. Se non riesci ancora ad accedere all'URL, utilizza il Partner Support Desk per richiedere assistenza, e includi la parola "Marketplace" nella descrizione. Per ulteriori informazioni sul Partner Support Desk, visita Richiedere assistenza con Cloud Marketplace.

Per accedere alla sezione Integrazione del frontend:

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

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

Aggiungere l'URL di registrazione

Quando gli utenti acquistano il tuo prodotto da Cloud Marketplace, devi creare un account con il tuo prodotto per loro. 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 si registrano per un account nel tuo sistema o come pagina che approva automaticamente gli account.

**Attenzione** :quando configuri la pagina di registrazione, assicurati che gli utenti possano accedere alla pagina senza prima inserire un nome utente e una password.

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 tuo prodotto, vai alla sezione Integrazione tecnica e fai clic su Integrazione del frontend.

3. Inserisci l'URL della pagina di registrazione nel campo URL di 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 fa clic sul pulsante, Google Cloud invia una HTTP POST richiesta alla pagina di registrazione, con un token JWT (JSON Web Token) nel x-gcp-marketplace-token parametro. Il JWT contiene l' ID account di acquisto dell'utente, che lo identifica come Google Cloud utente, e un ID offuscato, che rappresenta l'ID del suo Account Google. Devi utilizzare sia l'ID account di acquisto sia l'ID offuscato per collegare l'Account Google dell'utente al suo account nel tuo sistema.

Nota: è possibile che un singolo utente abbia più ID account di acquisto, o che più utenti condividano un ID account di acquisto comune, a seconda di come loro o la loro organizzazione hanno configurato l'utilizzo di Google Cloud.

Dopo aver verificato il 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.

Aggiungere l'URL di accesso

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

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

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

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

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

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

Per attivare l'SSO in Producer Portal:

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

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

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

Verificare i dati di accesso SSO dei clienti

Quando i clienti accedono alla tua app utilizzando l'SSO, Google Cloud invia una HTTP POST richiesta alla pagina di accesso dell'app, con un token JWT (JSON Web Token) 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

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 JWT (JSON Web Token) che potrebbe essere necessario verificare.

La tabella seguente elenca:

• Eventi che prevedono 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 richiesta
Registrare un nuovo cliente	POST	Sì
Accesso cliente, senza SSO	GET	No
Accesso cliente, con SSO	POST	Sì

Il payload JWT

Il payload JWT ha il 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 dall'oggetto JSON nell'attributo iss nel 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
  }
}

Dove:

• sub è l'ID dell'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 scade il token ed è impostato su 5 minuti dopo l'invio del token.
• aud è il dominio che ospita il tuo prodotto, ad esempio example.com.

• roles è un array di stringhe che rappresentano i ruoli dell'utente. Può essere:

  • account_admin, che indica che l'utente è un Billing Account Administrator (amministratore degli ordini) dell'account di fatturazione che ha acquistato il prodotto oppure

  • project_editor, che indica che l'utente è un editor (gestore dei diritti), ma non un amministratore della fatturazione, del progetto nell'account di fatturazione.

  Nota: Se hai attivato il Single Sign-On (SSO), gli utenti con il ruolo account_admin devono avere anche il ruolo project_editor.

• user_identity è un riferimento utente offuscato, che può essere utilizzato come login_hint per avviare un flusso di consenso OAuth 2.0. Per ulteriori dettagli, consulta Avviare l'accesso con Google con login_hint.

Payload per più ordini dello stesso prodotto

Se hai attivato più ordini dello stesso prodotto, il payload include un oggetto orders aggiuntivo. Questo include l'ID ordine univoco corrispondente all'ID diritto per ogni ordine. Assicurati che la pagina di accesso dell'app possa rispondere a questo nuovo campo orders.

{
  "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,
    "orders": [ORDER_ID1, ORDER_ID2]
  }
}

Dove:

• ORDER_ID è un elenco di ID ordine univoci per ogni ID diritto che indica le diverse offerte dello 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.

Verificare 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 il JWT non sia scaduto, controllando la rivendicazione exp.

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

4. Verifica che la rivendicazione iss sia https://www.googleapis.com/robot/v1/metadata/x509/[e-mail].

5. Verifica che sub non sia vuoto.

Nota: poiché potremmo aggiungere nuovi campi al JWT, non devi considerare un JWT non valido solo perché contiene nuovi campi che non hai ancora incontrato.

Avviare l'accesso con Google con login_hint

Se vuoi che i tuoi utenti seguano 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 utilizzavano per Google Cloud prima del reindirizzamento. Per farlo, fornisci 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 ti aspettavi che completasse il flusso OAuth. Per farlo, utilizza il token di accesso OAuth 2.0 per chiamare l'API UserInfo di Google per recuperare le informazioni utente di base. Viene restituito un ID che dovrebbe corrispondere al campo user_identity del JWT.

Creare account di servizio per i clienti

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Se il tuo prodotto richiede un account di servizio, puoi collaborare con un Partner Engineer per:

• Fornire account di servizio per i clienti e
• Configurare una pagina di gestione degli account di servizio per consentire ai clienti di concedere i ruoli IAM (Identity and Access Management) richiesti agli account di servizio.

Devi fornire il link a questa pagina dell'account di servizio ai tuoi clienti, in genere tramite la console di gestione del prodotto.

Fornire gli account di servizio

Per fornire gli account di servizio, contatta il partner engineer e includi le seguenti informazioni:

• Nome del servizio: un ID prodotto univoco che distingue 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 tuo prodotto in un unico progetto.

• Ruoli IAM e motivazione: i ruoli IAM richiesti per gli account di servizio e il motivo per cui i ruoli sono necessari. Queste informazioni vengono condivise con il cliente e possono influire sulla concessione o meno dell'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 Partner Engineer. Puoi inviare più nomi di dominio, inclusi i sottodomini, ad esempio staging.example.com.

Integrare la pagina di gestione degli 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. Poi, devi collegare la pagina dalla tua console.

Dopo che il Partner Engineer ti ha comunicato che la pagina di gestione dei account di servizio è pronta, aggiungi i parametri all'URL e poi collega la pagina dalla tua console.

Devi aggiungere due parametri all'URL:

• service-name: il nome del servizio che hai fornito al partner engineer.

• service-account-email: l'indirizzo email del account di servizio che hai creato per il 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 altri parametri a seconda delle esigenze dei clienti. Ad esempio:

https://console.cloud.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 Google Cloud progetto 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 degli account di servizio:

Parametro	Descrizione
service-name	Campo obbligatorio. Il nome del servizio che hai fornito al partner engineer.
service-account-email	Campo obbligatorio. L'indirizzo email dell'account di servizio che hai creato per il cliente.
single	Se è 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 al Partner Engineer. 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 presso il partner engineer.