Autenticazione e autorizzazione sono meccanismi utilizzati per verificare l'identità e l'accesso alle risorse. Questo documento illustra come l'autenticazione per le app Chat e le richieste dell'API Chat.
Panoramica della procedura
Il seguente diagramma mostra i passaggi generali di autenticazione e autorizzazione per Google Chat:
Configura un progetto Google Cloud, abilita l'API Chat e configura App di chat: durante lo sviluppo, crei un'app progetto Google Cloud. Nel progetto Google Cloud, abiliti l'API Chat, configurare l'app Chat e impostare l'autenticazione. Per ulteriori informazioni, vedi Sviluppa su Google Workspace e Creare un'app di chat.
Chiama l'API Chat: quando l'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 l'autenticazione di un utente che non è ancora stata concessa, chiede all'utente di accedere.
Richiedi risorse: l'app richiede l'accesso con gli ambiti da te specificati 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 alla tua 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 al ambiti di autorizzazione, l'app raggruppa le credenziali e i dati 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 gli ambiti concessi. Se l'elenco degli ambiti restituito è più restrittivo rispetto 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 allo API Google Chat oltre la durata di un singolo token di accesso, può ricevere token di aggiornamento. Per ulteriori informazioni, vedi Utilizzare OAuth 2.0 per accedere alle API di Google.
Richiedere altre risorse: se l'app richiede un accesso maggiore, chiede all'utente di accedere. per concedere nuovi ambiti, generando 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 oppure in modo asincrono. Possono anche completare attività per conto di un utente, ad esempio: creare uno spazio di Chat o recuperare un elenco di persone in Spazio di Chat.
Le app di chat non richiedono l'autenticazione per rispondere a un interazione dell'utente, a meno che l'app Chat non chiami 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 API Chat, che richiedono autenticazione e autorizzazione.
Le risposte alle interazioni degli utenti non richiedono l'autenticazione
Non è necessario eseguire l'autenticazione per le app di Google Chat come utente o App Chat per ricevere e rispondere in modo sincrono eventi di interazione.
Le app Google Chat ricevono eventi di interazione ogni volta che un utente interagisce o richiama un'app di Chat, include quanto segue:
- Un utente invia un messaggio a un'app di Chat.
- Un utente @menziona un'app di Chat.
- Un utente richiama una delle comandi slash.
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 interazione con l'app di chat .
I messaggi asincroni richiedono l'autenticazione
I messaggi asincroni si verificano quando un'app di Chat invia una richiesta alla API Chat, che richiede autenticazione e autorizzazione.
Chiamando l'API Chat, le app di Chat possono pubblicare messaggi in Google Chat o completare attività e accedere ai dati per conto di un utente. Per Ad esempio, dopo aver rilevato un'interruzione del server, un'app di Chat può chiamare il API Chat per:
- Crea uno spazio di Chat dedicato a esaminare e risolvere l'interruzione del servizio.
- Aggiungi persone allo spazio di Chat.
- Pubblica un messaggio nello spazio di Chat per fornire dettagli su o un'interruzione del servizio.
Il seguente diagramma mostra una sequenza di messaggi asincrona tra un'app Chat e uno spazio Chat:
- Un'app di Chat crea un messaggio chiamando il
l'API Chat con
spaces.messages.createmetodo predefinito, e include le credenziali utente nella richiesta HTTP. - Google Chat autentica l'app Chat con le credenziali dell'account di servizio o dell'utente.
- Google Chat esegue il rendering del messaggio dell'app in un messaggio di Chat specificato spazio.
Ambiti API Chat
Configura la schermata per il consenso OAuth e scegli gli ambiti per definire quali informazioni mostrare a utenti e revisori di app e registrare la tua app per 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 è un URI OAuth 2.0 stringa che contiene il nome dell'app Google Workspace, il tipo di dati accessi 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 delle app con gli account di servizio. Tu che non possono eseguire l'autenticazione con le credenziali utente o con 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 i 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
|
Visualizza 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 delle 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 le 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 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 la chat e gli spazi di proprietà del dominio dell'amministratore in Chat. |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
Visualizzare i membri e i 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 (tra cui impostazioni della cronologia e di accesso) in Chat. Richiede approvazione degli amministratori. Questo ambito supporta solo l'autenticazione delle app con gli account di servizio. Con questo ambito non puoi autenticarti con le credenziali utente o con la delega a livello di dominio. |
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 delle app con gli account di servizio. Tu che non possono eseguire l'autenticazione con le credenziali utente o con 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. È necessaria l'approvazione dell'amministratore. Questo ambito supporta solo l'autenticazione delle app con gli account di servizio. Con questo ambito non puoi autenticarti con le credenziali utente o con la delega a livello di dominio. |
https://www.googleapis.com/auth/chat.customemojis
|
Visualizza, crea ed elimina emoji personalizzate 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 ulteriori 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 e Eliminare le reazioni ai messaggi. |
https://www.googleapis.com/auth/chat.messages.readonly
|
Visualizza 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. È necessaria l'approvazione dell'amministratore. Questo ambito supporta solo l'autenticazione delle app con gli account di servizio. Tu che non possono eseguire l'autenticazione con le credenziali utente o con delega a livello di dominio utilizzando questo ambito. |
Gli ambiti nelle tabelle precedenti ne indicano la sensibilità, in base alle seguenti definizioni:
Non sensibili: questi ambiti forniscono la sfera di accesso all'autorizzazione più ridotta e richiedono solo la verifica di base dell'app. Per informazioni su questo requisito, consulta la sezione Passaggi per prepararsi verifica.
Sensibile: questi ambiti forniscono alla tua app l'accesso a un ambiente i dati Google dell'utente dopo aver ricevuto l'autorizzazione da parte sua. Richiede di effettuare un'ulteriore verifica dell'app. Per informazioni su questo requisito, consulta la sezione Passaggi per le app che richiedono ambiti sensibili.
Con restrizioni: questi ambiti forniscono un accesso ampio ai dati utente di Google e richiedono di completare la procedura di verifica degli ambiti con restrizioni. Per per informazioni su questo requisito, consulta Servizi API di Google: dati utente Norme e Requisiti aggiuntivi per API specifiche Ambiti. Vedi anche la Procedura per le app che richiedono limitazioni ambiti.
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, consulta Utilizzo di OAuth 2.0 per Accedi alle API di Google.
Per saperne di più sugli ambiti per le API Google Workspace, consulta Configura la schermata per il consenso OAuth e scegli gli ambiti.
Tipi di autenticazione richiesti
Esistono due modi in cui le app di Chat possono autenticarsi e autorizzarsi con l'API Chat:
- Autenticazione utente
- Autenticazione degli utenti 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 assegnata la delega a livello di dominio, la prima volta che l'app Chat esegue un'azione per conto di un utente, l'utente deve autorizzarla utilizzando la schermata del consenso OAuth.
- Autenticazione delle app
L'autenticazione delle app consente a L'app di chat utilizza le credenziali e l'accesso dell'account di servizio e completare le azioni come se stesse. 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 del consenso OAuth.
Due tipi di ambiti di autorizzazione OAuth supportano l'autenticazione delle app:
https://www.googleapis.com/auth/chat.bot: La tua app Chat può chiamare l'API Google Chat che supportano questo ambito di autorizzazione 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. Il tuo L'app di chat può concedere autonomamente questo ambito di autorizzazione, non è richiesta 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. A ricevere l'approvazione dell'amministratore, preparare l'account di servizio dell'app Chat per ricevere l'approvazione dell'amministratore creando un client OAuth compatibile con Google Workspace Marketplace configurando l'app nell'SDK di 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 sia degli utenti che delle 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 che l'utente a cui possono accedere.
Ad esempio, una chiamata al metodo spaces.list() con autorizzazione app restituisce
l'elenco degli spazi di cui l'app Chat è membro.
Chiamata a spaces.list() con
autorizzazione utente restituisce l'elenco degli spazi di cui l'utente è membro. Nella
potresti utilizzare entrambi i tipi di
durante la chiamata all'API Chat, in base alla progettazione
e le funzionalità dell'app Chat.
Per le chiamate asincrone all'API Chat
La tabella seguente elenca i metodi dell'API Chat e i relativi metodi supportati ambiti di autorizzazione:
| Metodo | Autenticazione utente supportata | Autenticazione delle app supportata | Ambiti di autorizzazione supportati | |
|---|---|---|---|---|
| Spazi | ||||
| Creare uno spazio |
Con l'autenticazione utente:
|
|||
| Configurare uno spazio | — |
Con l'autenticazione utente:
|
||
| Ottieni uno spazio |
Con l'autenticazione utente:
|
|||
| Elenco spazi |
Con l'autenticazione utente:
|
|||
| Cerca spazi | — |
Con l'autenticazione utente mediante i privilegi di amministratore:
|
||
| Aggiornare uno spazio |
Con l'autenticazione utente:
|
|||
| Eliminare uno spazio |
Con l'autenticazione utente:
|
|||
| Completare il processo di importazione di uno spazio | — |
Con l'autenticazione utente:
|
||
| Trovare un messaggio diretto |
Con l'autenticazione utente:
|
|||
| Membri | ||||
| Creare un membro |
Con l'autenticazione utente:
|
|||
| Abbonarsi |
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:
|
|||
| Ricevi 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:
|
||
| Emoji personalizzate | ||||
| Creare un'emoji personalizzata | — |
Con l'autenticazione utente:
|
||
| Eliminare un'emoji personalizzata | — |
Con l'autenticazione utente:
|
||
| Ricevere un'emoji personalizzata | — |
Con l'autenticazione utente:
|
||
| Elenca emoji personalizzate | — |
Con l'autenticazione utente:
|
||
| Contenuti multimediali e allegati | ||||
| Caricare contenuti multimediali come allegato file | — |
Con l'autenticazione utente:
|
||
| Scaricare contenuti multimediali |
Con l'autenticazione utente:
|
|||
| Ricevere un allegato del messaggio | — |
Con l'autenticazione delle 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 dello spazio di un utente | — |
Con l'autenticazione utente:
|
||
| Ottenere lo stato di lettura del thread di un utente | — |
Con l'autenticazione utente:
|
||
| Eventi di Space | ||||
| Ricevere gli eventi dello spazio | — |
Con l'autenticazione utente,
devi utilizzare un ambito in base al
tipo di evento:
|
||
| Elenca eventi dello spazio | — |
Con l'autenticazione utente,
devi utilizzare un ambito per ogni
tipo di evento incluso nella richiesta:
|
||
Per gli eventi di interazione con l'app di Chat
La tabella seguente elenca i modi comuni in cui gli utenti interagiscono con le app di chat e indica se l'autenticazione è richiesta o supportata:
| Scenario | Nessuna autenticazione richiesta | Autenticazione utente supportata | Autenticazione app supportata | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Ricevere messaggi da: |
|
|||||||||||||||
| Rispondere ai messaggi: |
|
|||||||||||||||
| Inviare nuovi messaggi: |
|
|||||||||||||||
Argomenti correlati
- Per una panoramica dell'autenticazione e dell'autorizzazione in Google Workspace, consulta Informazioni su autenticazione e autorizzazione.
- Per una panoramica dell'autenticazione e dell'autorizzazione in Google Cloud, consulta Panoramica dell'autenticazione.
- Per scoprire di più sugli account di servizio, consulta Account di servizio.
- Per saperne di più su come le API di Google utilizzano 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.