L'autenticazione e l'autorizzazione sono meccanismi utilizzati per verificare l'identità e l'accesso alle risorse, rispettivamente. Questo documento descrive come funzionano l'autenticazione e l'autorizzazione per le app di Chat e le richieste API di Chat.
Panoramica sulla procedura
Il seguente diagramma mostra i passaggi di autenticazione e autorizzazione di alto livello per Google Chat:
Configura un progetto Google Cloud, abilita l'API Chat e configura la tua app Chat: durante lo sviluppo, crea un progetto Google Cloud. Nel progetto Google Cloud, abilita l'API Chat, configura la tua app Chat e imposta l'autenticazione. Per saperne di più, vedi Sviluppare su Google Workspace e Creare un'app Chat.
Chiamata dell'API Chat:quando la tua app chiama l'API Chat, invia le credenziali di autenticazione all'API Chat. Se la tua app esegue l'autenticazione con un service account, le credenziali vengono inviate come parte del codice dell'app. Se la tua app richiede di chiamare l'API Chat utilizzando l'autenticazione di un utente a cui non è ancora stato concesso l'accesso, viene chiesto all'utente di accedere.
Richiedi risorse: la tua app chiede l'accesso con ambiti che specifichi durante la configurazione dell'autenticazione.
Richiedi il consenso:se l'app esegue l'autenticazione come utente, Google mostra una schermata di consenso OAuth in modo che l'utente possa decidere se concedere all'app l'accesso ai dati richiesti. L'autenticazione con un service account non richiede il consenso dell'utente.
Invia la 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 di ambiti concessi. Se l'elenco degli ambiti restituito è più restrittivo di quelli richiesti, l'app disattiva tutte le funzionalità limitate dal token.
Accedere 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) Ottieni un token di aggiornamento: se la tua app deve accedere all'API Google Chat oltre la durata di un singolo token di accesso, può ottenere un token di aggiornamento. Per ulteriori informazioni, vedi Utilizzare OAuth 2.0 per accedere alle API di Google.
Richiedi più risorse: se la tua app ha bisogno di più accesso, chiede all'utente di concedere nuovi ambiti, il che comporta 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 dell'utente o in modo asincrono. Possono anche completare attività per conto di un utente, ad esempio creare uno spazio di Chat o ottenere 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 non chiamino l'API Chat o un'altra API di Google durante l'elaborazione di una risposta.
Per inviare messaggi asincroni o eseguire attività per conto di un utente, le app di Chat effettuano 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 autenticarsi come utente o app Chat per ricevere e rispondere in modo sincrono agli eventi di interazione.
Le app di 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 dell'app Chat.
Il seguente diagramma mostra una sequenza di richiesta-risposta tra un utente di Chat e l'app 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 dell'app di chat.
I messaggi asincroni richiedono l'autenticazione
I messaggi asincroni si verificano quando un'app di Chat effettua 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 di Chat può chiamare l'API Chat per:
- Crea uno spazio di Chat dedicato all'analisi e alla risoluzione dell'interruzione.
- Aggiungi 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 asincroni tra un'app Chat e uno spazio 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 credenziali dell'account di servizio o dell'utente.
- Google Chat esegue il rendering del messaggio dell'app in uno spazio di Chat specificato.
Ambiti dell'API Chat
Configura la schermata per il consenso OAuth e scegli gli ambiti per definire quali informazioni vengono visualizzate dagli utenti e dai revisori delle 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
|
Consente alle app di chat di visualizzare le chat e inviare messaggi. Questo ambito supporta solo l'autenticazione dell'app con i service account. Non puoi autenticarti con le credenziali utente o con la delega a livello di dominio utilizzando questo ambito. |
Ambiti sensibili
| Codice ambito | Descrizione |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
Creare conversazioni e spazi e visualizzare o modificare metadati (incluse le impostazioni della cronologia e di accesso) 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, aggiornare 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 di 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 l'ora dell'ultima lettura per le conversazioni di Chat. |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
Visualizzare l'ora dell'ultima lettura delle conversazioni di Chat. |
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
Visualizzare la chat e gli spazi di proprietà del dominio dell'amministratore in Chat. |
https://www.googleapis.com/auth/chat.admin.spaces
|
Visualizzare o modificare chat e spazi di proprietà del dominio dell'amministratore in Chat. |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
Visualizzare membri e gestori nelle conversazioni di proprietà del dominio dell'amministratore in Chat. |
https://www.googleapis.com/auth/chat.admin.memberships
|
Visualizzare, aggiungere, aggiornare e rimuovere membri e gestori nelle conversazioni di proprietà del dominio dell'amministratore in Chat. |
https://www.googleapis.com/auth/chat.app.spaces
|
Creare conversazioni e spazi e visualizzare o aggiornare i metadati (incluse le impostazioni della cronologia e di accesso) in Chat. Richiede l'approvazione dell'amministratore. Questo ambito supporta solo l'autenticazione dell'app con i service account. Non puoi autenticarti con le credenziali utente o con la delega a livello di dominio utilizzando questo ambito. |
https://www.googleapis.com/auth/chat.app.spaces.create
|
Creare nuove conversazioni e nuovi spazi in Chat. Richiede l'approvazione dell'amministratore. Questo ambito supporta solo l'autenticazione dell'app con i service account. Non puoi autenticarti con le credenziali utente o con la delega a livello di dominio utilizzando questo ambito. |
https://www.googleapis.com/auth/chat.app.memberships
|
Visualizzare, aggiungere, aggiornare e rimuovere membri dalle conversazioni e dagli spazi in Chat. Richiede l'approvazione dell'amministratore. Questo ambito supporta solo l'autenticazione dell'app con i service account. Non puoi autenticarti con le credenziali utente o con la delega a livello di dominio utilizzando questo ambito. |
https://www.googleapis.com/auth/chat.customemojis
|
Visualizzare, creare ed eliminare emoji personalizzate in Chat. |
https://www.googleapis.com/auth/chat.customemojis.readonly
|
Visualizzare le emoji personalizzate in Chat. |
https://www.googleapis.com/auth/chat.users.spacesettings
|
Visualizzare e aggiornare le impostazioni dello spazio utente di 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
|
Visualizzare, scrivere, inviare, aggiornare ed eliminare messaggi, nonché aggiungere, visualizzare ed eliminare reazioni ai messaggi. |
https://www.googleapis.com/auth/chat.messages.readonly
|
Visualizzare messaggi e reazioni in Chat. |
https://www.googleapis.com/auth/chat.admin.delete
|
Eliminare le conversazioni e gli spazi di proprietà del dominio dell'amministratore e rimuovere l'accesso ai file associati in Chat. |
https://www.googleapis.com/auth/chat.app.delete
|
Eliminare conversazioni e spazi e rimuovere l'accesso ai file associati in Chat. Richiede l'approvazione dell'amministratore. Questo ambito supporta solo l'autenticazione dell'app con i service account. Non puoi autenticarti con le credenziali utente o con la delega a livello di dominio utilizzando questo ambito. |
Gli ambiti nelle tabelle precedenti indicano la loro sensibilità, in base alle seguenti definizioni:
Non sensibili: 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, vedi Passaggi per prepararsi alla verifica.
Sensibili: questi ambiti forniscono alla tua app l'accesso a dati Google di un utente specifico dopo aver ricevuto l'autorizzazione da parte dell'utente. Richiede di eseguire una verifica aggiuntiva dell'app. Per informazioni su questo requisito, vedi Passaggi per le app che richiedono ambiti sensibili.
Con restrizioni: questi ambiti forniscono un ampio accesso ai dati utente di Google e richiedono di superare la procedura di verifica degli ambiti con restrizioni. Per informazioni su questo requisito, consulta Servizi API di Google: norme relative ai dati utente e Requisiti aggiuntivi per gli ambiti API specifici. Vedi anche Passaggi per le app che richiedono ambiti con restrizioni.
Se la tua app richiede l'accesso ad altre API di Google, puoi aggiungere anche questi ambiti. Per ulteriori informazioni sugli ambiti delle API di Google, vedi Utilizzare OAuth 2.0 per accedere alle API di Google.
Per scoprire di più sugli ambiti per le API Google Workspace, vedi Configurare la schermata per il consenso OAuth e scegliere gli ambiti.
Tipi di autenticazione obbligatoria
Esistono due modi in cui le app di Chat possono autenticarsi e autorizzarsi con l'API Chat:
- Autenticazione utente
- L'autenticazione utente consente a un'app di chat di accedere ai dati utente e completare azioni per conto di un utente. Gli ambiti OAuth specificano i dati e le azioni autorizzati. A meno che l'app Chat non sia stata installata dall'amministratore o non sia stata concessa la delega a livello di dominio, la prima volta che l'app Chat esegue un'azione per conto di un utente, quest'ultimo deve autorizzare l'app Chat utilizzando la schermata del consenso OAuth.
- Autenticazione app
L'autenticazione dell'app consente a un'app Chat di utilizzare le credenziali del service account e accedere ai dati e completare le azioni come se fosse l'app stessa. Poiché l'app Chat utilizza le proprie credenziali per accedere alle risorse e utilizzarle, gli utenti finali non devono approvare le chiamate API dell'app Chat e non puoi aggiungere ambiti di autorizzazione OAuth che supportano l'autorizzazione dell'app alla schermata di consenso OAuth.
Due tipi di ambiti di autorizzazione OAuth supportano l'autenticazione delle app:
https://www.googleapis.com/auth/chat.bot: La tua app di chat può chiamare i metodi dell'API Google Chat che supportano questo ambito di autorizzazione per creare, aggiornare, ottenere, elencare o eliminare le risorse a cui ha accesso, come i messaggi negli spazi a cui gli utenti finali aggiungono la tua app di chat. La tua app Chat può concedere autonomamente questo ambito di autorizzazione, senza richiedere l'autorizzazione dell'amministratore o dell'utente finale.https://www.googleapis.com/auth/chat.app.*(Anteprima per gli sviluppatori): l'utilizzo di questi ambiti richiede l'approvazione una tantum dell'amministratore. Per ricevere l'approvazione dell'amministratore, devi preparare il service account dell'app Chat a ricevere l'approvazione dell'amministratore creando un client OAuth compatibile con Google Workspace Marketplace e configurando l'app nell'SDK Google Workspace Marketplace. Questi ambiti consentono all'app Chat di chiamare metodi specifici dell'API Google Chat. Ad esempio,chat.app.spaces.createconsente alle app di creare spazi di Chat.
Se un metodo supporta l'autenticazione utente o app, l'API Chat restituisce risultati diversi in base al tipo di autenticazione utilizzato:
- Con l'autenticazione delle app, i metodi restituiscono solo le risorse a cui può accedere l'app Chat.
- Con l'autenticazione utente, i metodi restituiscono solo le risorse a cui l'utente può accedere.
Ad esempio, la chiamata al metodo spaces.list() con l'autorizzazione app restituisce
l'elenco degli spazi di cui l'app Chat è membro.
La chiamata a spaces.list() con
l'autorizzazione utente restituisce l'elenco degli spazi di cui l'utente è membro. In
pratica, potresti utilizzare entrambi i tipi di
autenticazione quando chiami l'API Chat, a seconda della progettazione
e delle funzionalità della tua app di chat.
Per le chiamate asincrone all'API Chat
La tabella seguente elenca i metodi dell'API Chat e gli ambiti di autorizzazione supportati:
| Metodo | Autenticazione utente supportata | Autenticazione dell'app supportata | Ambiti di autorizzazione supportati | |
|---|---|---|---|---|
| Spazi | ||||
| Creare uno spazio |
Con l'autenticazione utente:
|
|||
| Configurare uno spazio | — |
Con l'autenticazione utente:
|
||
| Ottenere uno spazio |
Con l'autenticazione utente:
|
|||
| Elenco degli spazi |
Con l'autenticazione utente:
|
|||
| Spazi di ricerca | — |
Con l'autenticazione utente che utilizza i privilegi amministrativi:
|
||
| 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:
|
|||
| Aderisci al programma |
Con l'autenticazione utente:
|
|||
| Membri dell'elenco |
Con l'autenticazione utente:
|
|||
| Eliminare un membro |
Con l'autenticazione utente:
|
|||
| Aggiornare 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:
|
||
| Elenco delle reazioni | — |
Con l'autenticazione utente:
|
||
| Eliminare una reazione | — |
Con l'autenticazione utente:
|
||
| Emoji personalizzate | ||||
| Creare un'emoji personalizzata | — |
Con l'autenticazione utente:
|
||
| Eliminare un'emoji personalizzata | — |
Con l'autenticazione utente:
|
||
| Ottenere un'emoji personalizzata | — |
Con l'autenticazione utente:
|
||
| Elencare le emoji personalizzate | — |
Con l'autenticazione utente:
|
||
| Contenuti multimediali e allegati | ||||
| Caricare contenuti multimediali come allegato di un file | — |
Con l'autenticazione utente:
|
||
| Scaricare contenuti multimediali |
Con l'autenticazione utente:
|
|||
| Ottenere un allegato del messaggio | — |
Con l'autenticazione app:
|
||
| Stati di lettura dell'utente | ||||
| Ottenere lo stato di lettura dello spazio di un utente | — |
Con l'autenticazione utente:
|
||
| Aggiornare lo stato di lettura di uno spazio di un utente | — |
Con l'autenticazione utente:
|
||
| Ottenere lo stato di lettura di un thread di un utente | — |
Con l'autenticazione utente:
|
||
| Impostazioni dello spazio utente | ||||
| Recuperare l'impostazione di notifica dello spazio di un utente | — |
Con l'autenticazione utente:
|
||
| Aggiornare l'impostazione di notifica di uno spazio di un utente | — |
Con l'autenticazione utente:
|
||
| Eventi dello spazio | ||||
| Recuperare gli eventi dello spazio | — |
Con l'autenticazione utente,
devi utilizzare un ambito basato sul
tipo di evento:
|
||
| Elenca gli eventi dello spazio | — |
Con l'autenticazione utente,
devi utilizzare un ambito per ogni
tipo di evento incluso nella richiesta:
|
||
Per gli eventi di interazione dell'app Chat
La seguente tabella 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 dell'app supportata | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Ricevi messaggi da: |
|
|||||||||||||||
| Rispondere ai messaggi: |
|
|||||||||||||||
| Inviare nuovi messaggi: |
|
|||||||||||||||
Argomenti correlati
- Per una panoramica dell'autenticazione e dell'autorizzazione in Google Workspace, vedi Informazioni su autenticazione e autorizzazione.
- Per una panoramica dell'autenticazione e dell'autorizzazione in Google Cloud, consulta Panoramica dell'autenticazione.
- Per scoprire di più sui service account, consulta la sezione Service account.
- Per saperne di più su come le API di Google utilizzano OAuth 2.0, vedi Utilizzare OAuth 2.0 per accedere alle API di Google.
- Configura l'autenticazione e l'autorizzazione con credenziali utente o un service account.