L'autenticazione e l'autorizzazione sono meccanismi utilizzati per verificare, rispettivamente, l'identità e l'accesso alle risorse. Questo documento descrive il funzionamento dell'autenticazione e dell'autorizzazione per le app Chat e le richieste API Chat.
Panoramica della procedura
Il seguente diagramma mostra i passaggi generali dell'autenticazione e dell'autorizzazione per Google Chat:
Configura un progetto Google Cloud, abilita l'API Chat e configura l'app Chat: durante lo sviluppo, crei un progetto Google Cloud. Nel progetto Google Cloud, devi abilitare l'API Chat, configurare l'app Chat e impostare l'autenticazione. Per maggiori informazioni, vedi Sviluppare in Google Workspace e Creare un'app di chat.
API Call Chat: quando la tua app chiama l'API Chat, invia le credenziali di autenticazione all'API Chat. Se la tua app si autentica con un account di servizio, le credenziali vengono inviate come parte del codice dell'app. Se la tua app richiede di chiamare l'API Chat utilizzando un'autenticazione utente che non è ancora stata concessa, all'utente verrà chiesto di accedere.
Richiedi risorse: la tua app richiede l'accesso con ambiti che hai specificato durante la configurazione dell'autenticazione.
Chiedi il consenso: se la tua app viene autenticata come utente, Google mostra una schermata per il consenso OAuth in modo che l'utente possa decidere se concedere all'app l'accesso ai dati richiesti. L'autenticazione con un account di servizio non richiede il consenso dell'utente.
Invia una richiesta approvata per le risorse: se l'utente acconsente agli ambiti di autorizzazione, la tua app raggruppa le credenziali e gli ambiti approvati dall'utente in una richiesta. La richiesta viene inviata al server di autorizzazione di Google per ottenere un token di accesso.
Google restituisce un token di accesso: il token di accesso contiene un elenco degli ambiti concessi. Se l'elenco restituito di ambiti è più restrittivo degli ambiti richiesti, l'app disattiva tutte le funzionalità limitate dal token.
Accesso alle risorse richieste:la tua app utilizza il token di accesso di Google per richiamare l'API Chat e accedere alle risorse dell'API Chat.
(Facoltativo) Richiedi un token di aggiornamento: se la tua app deve accedere all'API Google Chat oltre la durata di un singolo token di accesso, può ricevere un token di aggiornamento. Per maggiori informazioni, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.
Richiedi altre risorse: se la tua app ha bisogno di un maggiore accesso, chiede all'utente di concedere nuovi ambiti, il che genera una nuova richiesta per ottenere un token di accesso (passaggi 3-6).
Quando le app di chat richiedono l'autenticazione
Le app di chat possono inviare messaggi in risposta a un'interazione utente o in modo asincrono. Possono anche completare attività per conto di un utente, come la creazione di uno spazio di Chat o la ricezione di un elenco di persone in uno spazio di Chat.
Le app di chat non richiedono l'autenticazione per rispondere a un'interazione utente, a meno che l'app Chat non chiami l'API Chat o un'altra API Google durante l'elaborazione di una risposta.
Per inviare messaggi asincroni o eseguire attività per conto di un utente, le app di Chat inviano richieste RESTful all'API Chat, che richiedono autenticazione e autorizzazione.
Le risposte alle interazioni degli utenti non richiedono l'autenticazione
Le app Google Chat non devono eseguire l'autenticazione come utente o app Chat per ricevere e rispondere in modo sincrono agli eventi di interazione.
Le app Google Chat ricevono eventi di interazione ogni volta che un utente interagisce o richiama un'app di Chat, tra cui:
- Un utente invia un messaggio a un'app di chat.
- Un utente @menziona un'app di chat.
- Un utente richiama uno dei comandi slash dell'app di Chat.
Il seguente diagramma mostra una sequenza di richiesta-risposta tra un utente di Chat e un'app di Chat:
- L'utente invia un messaggio all'app Chat in Google Chat.
- Google Chat inoltra il messaggio all'app.
- L'app riceve il messaggio, lo elabora e restituisce una risposta a Google Chat.
- Google Chat esegue il rendering della risposta per l'utente o in uno spazio.
Questa sequenza si ripete per ogni evento di interazione nell'app di chat.
I messaggi asincroni richiedono l'autenticazione
I messaggi asincroni si verificano quando un'app Chat invia una richiesta all'API Chat, che richiede autenticazione e autorizzazione.
Chiamando l'API Chat, le app di Chat possono pubblicare messaggi su Google Chat o completare attività e accedere ai dati per conto di un utente. Ad esempio, dopo aver rilevato un'interruzione del server, un'app Chat può chiamare l'API Chat per:
- Creare uno spazio di Chat dedicato a indagare e correggere l'interruzione.
- Aggiungere persone allo spazio di Chat.
- Pubblica un messaggio nello spazio di Chat per fornire dettagli sull'interruzione.
Il seguente diagramma mostra una sequenza di messaggi asincrona tra un'app di Chat e uno spazio di Chat:
- Un'app Chat crea un messaggio chiamando l'API Chat utilizzando il metodo
spaces.messages.createe include le credenziali utente nella richiesta HTTP. - Google Chat autentica l'app Chat con un account di servizio o credenziali utente.
- Google Chat esegue il rendering del messaggio dell'app in uno spazio di Chat specificato.
Ambiti API Chat
Configura la schermata per il consenso OAuth e scegli gli ambiti per definire le informazioni da mostrare a utenti e revisori di app e registra la tua app in modo da poterla pubblicare in un secondo momento.
Per definire il livello di accesso concesso alla tua app, devi identificare e dichiarare gli ambiti di autorizzazione. Un ambito di autorizzazione è una stringa URI OAuth 2.0 che contiene il nome dell'app Google Workspace, il tipo di dati a cui accede e il livello di accesso.
Ambiti non sensibili
| Codice ambito | Descrizione |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
L'ambito Consente alle app di Chat di visualizzare le chat e inviare messaggi. Concede l'accesso a tutte le funzionalità disponibili per le app di chat. |
Ambiti sensibili
| Codice ambito | Descrizione |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
Creare conversazioni e spazi e visualizzare o aggiornare i metadati (incluse le impostazioni della cronologia) in Chat. |
https://www.googleapis.com/auth/chat.spaces.create
|
Creare nuove conversazioni in Chat. |
https://www.googleapis.com/auth/chat.spaces.readonly
|
Visualizzare la chat e gli spazi in Chat. |
https://www.googleapis.com/auth/chat.memberships
|
Visualizzare, aggiungere e rimuovere membri dalle conversazioni in Chat. |
https://www.googleapis.com/auth/chat.memberships.app
|
Aggiungersi e rimuoversi dalle conversazioni in Google Chat. |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Visualizzare i membri nelle conversazioni in Chat. |
https://www.googleapis.com/auth/chat.messages.create
|
Scrivere e inviare messaggi in Chat. |
https://www.googleapis.com/auth/chat.messages.reactions
|
Visualizzare, aggiungere ed eliminare reazioni ai messaggi in Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
Aggiungere reazioni a un messaggio in Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
Visualizzare le reazioni a un messaggio in Chat. |
https://www.googleapis.com/auth/chat.users.readstate
|
Visualizzare e modificare data e ora dell'ultima lettura delle conversazioni in Chat. |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
Visualizzare l'ora dell'ultima lettura delle conversazioni in Chat. |
Ambiti con restrizioni
| Codice ambito | Descrizione |
|---|---|
https://www.googleapis.com/auth/chat.delete
|
Eliminare conversazioni e spazi e rimuovere l'accesso ai file associati in Chat. |
https://www.googleapis.com/auth/chat.import
|
Importare spazi, messaggi e abbonamenti in Chat. Per maggiori informazioni, vedi Autorizzare le app di Chat a importare dati |
https://www.googleapis.com/auth/chat.messages
|
Visualizza, scrivi, invia, aggiorna ed elimina messaggi e aggiungi, visualizza ed elimina reazioni ai messaggi. |
https://www.googleapis.com/auth/chat.messages.readonly
|
Visualizzare i messaggi e le reazioni in Chat. |
Gli ambiti nelle tabelle precedenti indicano la loro sensibilità, in base alle seguenti definizioni:
Non sensibile: questi ambiti forniscono la sfera più piccola di accesso all'autorizzazione e richiedono solo la verifica di base dell'app. Per informazioni su questo requisito, consulta la sezione Passaggi per prepararsi alla verifica.
Sensibili: questi ambiti consentono alla tua app di accedere ai dati di Google di un utente specifico dopo aver ricevuto l'autorizzazione dell'utente. Richiede un'ulteriore verifica dell'app. Per informazioni su questo requisito, consulta Passaggi per le app che richiedono ambiti sensibili.
Limitato: questi ambiti forniscono accesso ampio ai dati utente di Google e richiedono il processo di verifica dell'ambito con restrizioni. Per informazioni su questo requisito, consulta le Norme sui dati utente: servizi API di Google e Requisiti aggiuntivi per ambiti API specifici. Vedi anche Passaggi per le app che richiedono ambiti limitati.
Se la tua app richiede l'accesso a qualsiasi altra API di Google, puoi aggiungere anche questi ambiti. Per ulteriori informazioni sugli ambiti delle API di Google, consulta la pagina relativa all'utilizzo di OAuth 2.0 per accedere alle API di Google.
Per saperne di più sugli ambiti per le API Google Workspace, consulta Configurare la schermata per il consenso OAuth e scegliere gli ambiti.
Tipi di autenticazione richiesta
Le app di Chat possono autenticarsi e autorizzare con l'API Chat in due modi: con le credenziali utente o con gli account di servizio.
Con l'autorizzazione delle credenziali utente, un'app di Chat può accedere ai dati utente e completare azioni per conto di un utente. Gli ambiti OAuth specificano i dati e le azioni autorizzati.
Con l'autorizzazione dell'app, un'app di chat accede
all'API come app utilizzando le credenziali dell'account di servizio. L'autorizzazione app utilizza sempre l'ambito di autorizzazione chat.bot.
Quando decidi quale tipo di credenziale utilizzare per una determinata richiesta API, tieni presente che alcuni metodi dell'API supportano solo un tipo particolare di credenziali. Se un metodo API supporta entrambe le credenziali, il tipo di credenziale utilizzato nella chiamata influisce sul risultato che viene restituito:
- Con l'autorizzazione delle app, i metodi restituiscono solo le risorse a cui l'app può accedere.
- Con l'autorizzazione dell'utente, i metodi restituiscono solo risorse a cui l'utente può accedere nell'interfaccia utente di Chat.
Ad esempio, la chiamata del metodo ListSpaces con l'autorizzazione dell'app restituisce
l'elenco degli spazi di cui l'app è membro. La chiamata a ListSpaces con l'autorizzazione
utente restituisce l'elenco degli spazi di cui l'utente è membro. In pratica, la tua app potrebbe utilizzare entrambi i tipi di autorizzazione quando chiami l'API Chat, a seconda della funzionalità che preferisci.
Per le chiamate all'API Chat asincrone
Nella tabella seguente sono elencati i metodi dell'API Chat e i relativi ambiti di autorizzazione supportati:
| Metodo | Autenticazione utente supportata | Autenticazione app supportata | Ambiti di autorizzazione supportati | |
|---|---|---|---|---|
| Spazi | ||||
| Creare uno spazio | — |
Con l'autenticazione utente:
|
||
| Configurare uno spazio | — |
Con l'autenticazione utente:
|
||
| Acquista spazio |
Con l'autenticazione utente:
|
|||
| Elenca spazi |
Con l'autenticazione utente:
|
|||
| Aggiornare uno spazio | — |
Con l'autenticazione utente:
|
||
| Eliminare uno spazio | — |
Con l'autenticazione utente:
|
||
| Completare la procedura di importazione per uno spazio | — |
Con l'autenticazione utente:
|
||
| Trovare un messaggio diretto |
Con l'autenticazione utente:
|
|||
| Membri | ||||
| Creare un membro | — |
Con l'autenticazione utente:
|
||
| Abbonati |
Con l'autenticazione utente:
|
|||
| Membri dell'elenco |
Con l'autenticazione utente:
|
|||
| Eliminare un membro | — |
Con l'autenticazione utente:
|
||
| Messaggi | ||||
| Creare un messaggio |
Con l'autenticazione utente:
|
|||
| Ricevere un messaggio |
Con l'autenticazione utente:
|
|||
| Elenca messaggi | — |
Con l'autenticazione utente:
|
||
| Aggiornare un messaggio |
Con l'autenticazione utente:
|
|||
| Eliminare un messaggio |
Con l'autenticazione utente:
|
|||
| Reazioni | ||||
| Creare una reazione | — |
Con l'autenticazione utente:
|
||
| Elencare le reazioni | — |
Con l'autenticazione utente:
|
||
| Eliminare una reazione | — |
Con l'autenticazione utente:
|
||
| Contenuti multimediali e allegati | ||||
| Caricare contenuti multimediali come file allegato | — |
Con l'autenticazione utente:
|
||
| Scaricare contenuti multimediali |
Con l'autenticazione utente:
|
|||
| Ricevere un allegato a un messaggio | — |
Con l'autenticazione delle app:
|
||
| Stati di lettura dell'utente | ||||
| Conoscere lo stato di lettura dello spazio di un utente | — |
Con l'autenticazione utente:
|
||
| Aggiornare lo stato di lettura dello spazio di un utente | — |
Con l'autenticazione utente:
|
||
| Conoscere lo stato di lettura dei thread di un utente | — |
Con l'autenticazione utente:
|
||
| Eventi dello spazio | ||||
| Visualizza eventi spaziali | — |
Con l'autenticazione utente:
|
||
| Elenca gli eventi dello spazio | — |
Con l'autenticazione utente:
|
||
Per eventi di interazione con l'app Chat
La tabella seguente elenca i modi comuni in cui gli utenti interagiscono con le app di chat e se l'autenticazione è richiesta o supportata:
| Scenario | Nessuna autenticazione richiesta | Autenticazione utente supportata | Autenticazione app supportata | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Ricevi messaggi da: |
|
|||||||||||||||
| Rispondere ai messaggi: |
|
|||||||||||||||
| Invia nuovi messaggi: |
|
|||||||||||||||
Argomenti correlati
- Per una panoramica dell'autenticazione e dell'autorizzazione in Google Workspace, consulta Scopri di più su autenticazione e autorizzazione.
- Per una panoramica dell'autenticazione e dell'autorizzazione in Google Cloud, consulta la Panoramica dell'autenticazione.
- Per scoprire di più sugli account di servizio, consulta Account di servizio.
- Per scoprire di più su come le API di Google sfruttano OAuth 2.0, consulta Utilizzo di OAuth 2.0 per accedere alle API di Google.
- Configura l'autenticazione e l'autorizzazione con credenziali utente o un account di servizio.