![Una scheda di autorizzazione personalizzata da un'anteprima del link che include il logo dell'azienda, una descrizione e un pulsante di accesso.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/add-ons/images/card-auth-link-preview.png?authuser=5&hl=it)
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:
- Rileva quando è richiesta l'autorizzazione.
- Restituire un'interfaccia a scheda che richiede agli utenti di accedere al servizio.
- 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.
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:
![Richiesta di autorizzazione di base per Account di esempio. La
richiesta indica che il componente aggiuntivo vorrebbe mostrare
ulteriori informazioni, ma necessita dell'approvazione dell'utente per
accedere all'account.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/add-ons/images/third-party-auth-prompt.png?authuser=5&hl=it)
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 tuoRESOURCE_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:
![Una scheda di autorizzazione personalizzata per Cymbal Labs che include il logo
dell'azienda, una descrizione e un pulsante di accesso.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/add-ons/images/card-auth-homepage.png?authuser=5&hl=it)
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 esempioCymbal Labs Logo
.DESCRIPTION
: un invito all'azione che consente agli utenti di accedere, ad esempioSign 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
.