Integrazione del frontend dell'app

In questa pagina vengono descritti i passaggi per integrare il frontend dell'app con Google Cloud Marketplace. L'integrazione del frontend contribuisce a offrire ai clienti un'esperienza fluida quando passano da Google Cloud Marketplace alla tua app.

Creare una pagina di attivazione dell'account per i nuovi utenti

Quando gli utenti scelgono il tuo prodotto da Google Cloud Marketplace, devono attivare i propri account nella tua app. Devi creare una pagina di attivazione per configurare e approvare gli account del tuo sistema. Puoi impostare la pagina come una pagina di registrazione in cui gli utenti devono registrare un account nel sistema oppure come pagina che approva automaticamente gli account. Quando configuri la pagina di attivazione, assicurati che gli utenti possano accedervi senza inserire un nome utente e una password.

In Google Cloud Marketplace, quando gli utenti fanno clic sul link per registrarsi alla tua app, Google invia una richiesta HTTP POST alla pagina di attivazione e invia un JSON Web Token (JWT) nel parametro x-gcp-marketplace-token. Il JWT contiene l'ID account di approvvigionamento dell'utente, che lo identifica come utente Google Cloud. Devi utilizzare questo ID per collegare l'Account Google dell'utente al suo account nel tuo sistema.

Dopo aver verificato il JWT, la pagina di attivazione deve inviare una richiesta di approvazione dell'account all'API Partner Procurement, descritta nella sezione Passaggi per l'integrazione del backend.

Se non hai mai utilizzato JWT, consulta questa introduzione.

Aggiunta della pagina di attivazione dell'account al portale

Puoi utilizzare Producer Portal per aggiungere l'URL della pagina di attivazione dell'account.

Producer Portal

Il link diretto al Producer Portal è:

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

Per aggiungere la pagina di attivazione dell'account a 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 FRONTENDA.

  3. Inserisci l'URL della pagina di attivazione dell'account nel campo URL di registrazione.

Portale partner

Il link diretto al Portale partner è il seguente:

https://console.cloud.google.com/partner/solutions?project=YOUR_PROJECT_ID

Per aggiungere la pagina per l'attivazione dell'account al Portale partner:

  1. Nell'elenco delle soluzioni, fai clic sull'ID soluzione che hai creato.

  2. Nella pagina Piani e funzionalità, fai clic per modificare la pagina.

  3. Inserisci l'URL della pagina di attivazione dell'account nel campo URL di registrazione.

Verifica del JWT

Il payload JWT è nel seguente formato:

Intestazione

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

Dove:

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

Carico di lavoro

{
  "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 rivendicazione iss rimanda a una chiave pubblica di Google.
  • exp indica quando scade il token e viene impostato su 5 minuti dopo l'invio del token.
  • aud è il dominio che ospita il tuo prodotto, come ad esempio example-pro.com.
  • roles è un array di stringhe che rappresentano i ruoli dell'utente. In questo momento, può essere: ** account_admin, che indica che l'utente è un amministratore dell'account di fatturazione che ha acquistato il prodotto, o ** project_editor, che indica che l'utente è un editor di progetto, ma non un amministratore di fatturazione, del progetto in tale account di fatturazione.
  • user_identity è l'ID GAIA offuscato dell'utente, che può essere utilizzato per avviare Open ID Connect.

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 di 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/cloud-commerce-partner@system.gserviceaccount.com.

  5. Verifica che il campo sub non sia vuoto.

Avvio dell'accesso a Google con login_hint

Se vuoi che gli 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 utilizzano 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 su Google OAuth2.0.

Dopo che l'utente ha completato il flusso OAuth 2.0 con il tuo sito, devi verificare di essere l'utente previsto per completare il flusso OAuth. A tale scopo, devi utilizzare il token di accesso OAuth 2.0 per chiamare l'API Google UserInfo e recuperare le informazioni utente di base. Restituisce un ID che deve corrispondere al campo user_identity di JWT.

Integrazione del Single Sign-On (SSO) per i clienti

Quando i clienti si registrano al tuo prodotto, devono essere in grado di registrare un account nella tua pagina di attivazione senza inserire prima un nome utente e una password.

L'integrazione SSO utilizza JWT per autenticare gli utenti. Se non hai mai utilizzato JWT, consulta questa introduzione.

Producer Portal

Per configurare l'integrazione SSO:

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

  2. Per creare un collegamento alla tua dashboard, inserisci l'URL della dashboard nel campo URL di accesso.

  3. Per utilizzare il servizio SSO di Google, fai clic su Attiva l'accesso SSO (facoltativo), quindi inserisci l'URL di accesso SSO nel campo URL SSO.

  4. Aggiungi il codice dell'interfaccia web dell'app per verificare il payload JWT che viene inviato alla tua app quando gli utenti accedono da Google Cloud Marketplace.

    Il formato di JWT per l'autenticazione è lo stesso di quello inviato quando gli utenti si registrano per la prima volta alla tua app, descritto nella sezione Verificare il JWT.

Portale partner

Per configurare l'integrazione SSO:

  1. Vai alla pagina Piani e funzionalità del tuo prodotto e scegli di MODIFICARE i piani e le funzionalità del tuo prodotto.

  2. Per collegare la dashboard, inserisci l'URL della dashboard nel campo URL dashboard.

  3. Per utilizzare lo SLO di Google, in Accesso SSO (facoltativo), fai clic su Abilita SSO, quindi inserisci l'URL di accesso SSO nel campo URL di accesso SSO. Inserisci l'URL delle tue chiavi API SSO nel campo URL chiavi API SSO.

  4. Aggiungi il codice dell'interfaccia web dell'app per verificare il payload JWT che viene inviato alla tua app quando gli utenti accedono da Google Cloud Marketplace.

    Il formato di JWT per l'autenticazione è lo stesso di quello inviato quando gli utenti si registrano per la prima volta alla tua app, descritto nella sezione Verificare il JWT.

Provisioning degli account di servizio per i clienti

Se la tua app richiede un account di servizio, puoi collaborare con un Partner Engineer per eseguire il provisioning degli account di servizio per i tuoi clienti e configurare una pagina per consentire ai clienti di concedere i ruoli richiesti di gestione di identità e accessi (IAM) agli account di servizio. Devi fornire il link alla pagina, di solito attraverso la console di gestione dell'app.

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 distingue la tua app dagli altri prodotti. Ti consigliamo di utilizzare il nome del servizio creato quando hai approvato la tua app.

  • ID progetto: l'ID del progetto in cui crei gli account di servizio che accedono alle risorse dei tuoi clienti. Tutti gli account di servizio utilizzati dall'app devono essere creati in un unico progetto.

  • Ruoli IAM e ragionamento: 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 sua possibilità di concedere l'accesso all'account di servizio.

Se vuoi che il cliente torni nel 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.

Il Partner Engineer crea una pagina per consentire ai clienti di concedere l'accesso agli account di servizio. Dopodiché esegui il collegamento alla pagina dalla tua console.

Integrazione dell'URL nella tua console

Quando il tuo Partner Engineer ti ha comunicato che la pagina è pronta, aggiungi i parametri all'URL e poi collega la 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 cliente. Ogni cliente ha un account di servizio unico.

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 in base alle esigenze del tuo cliente. 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 nell'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 accesso:

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 impostato su vero, significa che il 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 che hai fornito al tuo Partner Engineer. Escludi l'elemento 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.