Collegare il componente aggiuntivo di Google Workspace a un servizio di terze parti

Se il componente aggiuntivo di Google Workspace si connette a un servizio o a un'API di terze parti che richiede l'autorizzazione, il componente aggiuntivo può richiedere agli utenti di accedere e autorizzare l'accesso.

Questa pagina spiega come autenticare gli utenti utilizzando un flusso di autorizzazione (come OAuth), che include i seguenti passaggi:

1. Rileva quando è richiesta l'autorizzazione.
2. Restituire un'interfaccia a scheda che richiede agli utenti di accedere al servizio.
3. Aggiorna il componente aggiuntivo in modo che gli utenti possano accedere al servizio o alla risorsa protetta.

Se il componente aggiuntivo richiede solo l'identità dell'utente, puoi autenticare direttamente gli utenti utilizzando il loro ID o indirizzo email di Google Workspace. Per utilizzare l'indirizzo email per l'autenticazione, vedi Convalida delle richieste JSON. Se hai creato il componente aggiuntivo utilizzando Google Apps Script, consulta la documentazione di Apps Script per informazioni su come collegare il componente aggiuntivo a un servizio di terze parti.

Rileva che l'autorizzazione è richiesta

Quando utilizzi il componente aggiuntivo, gli utenti potrebbero non essere autorizzati ad accedere a una risorsa protetta per diversi motivi, tra cui:

• Un token di accesso per la connessione al servizio di terze parti non è stato ancora generato o è scaduto.
• Il token di accesso non copre la risorsa richiesta.
• Il token di accesso non copre gli ambiti richiesti della richiesta.

Il componente aggiuntivo dovrebbe rilevare questi casi in modo che gli utenti possano accedere e accedere al tuo servizio.

Chiedere agli utenti di accedere al servizio

Quando il componente aggiuntivo rileva che è richiesta l'autorizzazione, deve restituire un'interfaccia di scheda per richiedere agli utenti di accedere al servizio. La scheda di accesso deve reindirizzare gli utenti al processo di autenticazione e autorizzazione di terze parti sulla tua infrastruttura.

Ti consigliamo di proteggere l'app di destinazione con Accedi con Google e recuperare l'ID utente utilizzando il token di identità emesso durante l'accesso. La rivendicazione secondaria contiene l'ID univoco dell'utente e può essere correlata all'ID del componente aggiuntivo.

Convalida sempre l'integrità del token prima di accettare lo User-ID dichiarato.

Creare e restituire una scheda di accesso

Per la scheda di accesso al tuo servizio, puoi utilizzare la scheda di autorizzazione di base di Google oppure personalizzare una carta in modo da visualizzare ulteriori informazioni, ad esempio il logo della tua organizzazione. Se intendi pubblicare il componente aggiuntivo pubblicamente, devi utilizzare una carta personalizzata.

Scheda di autorizzazione di base

L'immagine seguente mostra un esempio della scheda di autorizzazione di base di Google:

Per utilizzare la scheda di autorizzazione di base, restituisci la seguente risposta JSON:

{
  "basic_authorization_prompt": {
    "authorization_url": "AUTHORIZATION_REDIRECT",
    "resource": "RESOURCE_DISPLAY_NAME"
  }
}

Sostituisci quanto segue:

• AUTHORIZATION_REDIRECT: l'URL dell'app web che gestisce l'autorizzazione.
• RESOURCE_DISPLAY_NAME: il nome visualizzato della risorsa o del servizio protetto. Questo nome viene mostrato all'utente nella richiesta di autorizzazione. Ad esempio, se il tuo RESOURCE_DISPLAY_NAME è Example Account, viene visualizzato il messaggio "Questo componente aggiuntivo vorrebbe mostrare ulteriori informazioni, ma necessita dell'approvazione per accedere al tuo Account di esempio".

Dopo aver completato l'autorizzazione, all'utente viene chiesto di aggiornare il componente aggiuntivo per accedere alla risorsa protetta.

Scheda di autorizzazione personalizzata

Per modificare la richiesta di autorizzazione, puoi creare una carta personalizzata per l'esperienza di accesso al tuo servizio.

Se pubblichi il componente aggiuntivo pubblicamente, devi utilizzare una scheda di autorizzazione personalizzata. Per scoprire di più sui requisiti di pubblicazione per Google Workspace Marketplace, consulta Informazioni sulla revisione delle app.

Le seguenti immagini mostrano un esempio di scheda di autorizzazione personalizzata per la home page di un componente aggiuntivo. La scheda include un logo, una descrizione e un pulsante di accesso:

Per utilizzare questo esempio di scheda personalizzata, restituisci la seguente risposta JSON:

{
  "custom_authorization_prompt": {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "sections": [
              {
                "widgets": [
                  {
                    "image": {
                      "imageUrl": "LOGO_URL",
                      "altText": "LOGO_ALT_TEXT"
                    }
                  },
                  {
                    "divider": {}
                  },
                  {
                    "textParagraph": {
                      "text": "DESCRIPTION"
                    }
                  },
                  {
                    "buttonList": {
                      "buttons": [
                        {
                          "text": "Sign in",
                          "onClick": {
                            "openLink": {
                              "url": "AUTHORIZATION_REDIRECT",
                              "onClose": "RELOAD",
                              "openAs": "OVERLAY"
                            }
                          },
                          "color": {
                            "red": 0,
                            "green": 0,
                            "blue": 1,
                            "alpha": 1,
                          }
                        }
                      ]
                    }
                  },
                  {
                    "textParagraph": {
                      "text": "TEXT_SIGN_UP"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Sostituisci quanto segue:

• LOGO_URL: l'URL di un logo o di un'immagine. Deve essere un URL pubblico.
• LOGO_ALT_TEXT: testo alternativo per il logo o l'immagine, ad esempio Cymbal Labs Logo.
• DESCRIPTION: un invito all'azione che consente agli utenti di accedere, ad esempio Sign in to get started.
• Per aggiornare il pulsante di accesso:
  • AUTHORIZATION_REDIRECT: l'URL dell'app web che gestisce l'autorizzazione.
  • (Facoltativo) Per modificare il colore del pulsante, aggiorna i valori a virgola mobile RGBA del campo color.
• TEXT_SIGN_UP: un testo che richiede agli utenti di creare un account, se non ne hanno uno. Ad esempio, New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.