Questo documento definisce il meccanismo SASL XOAUTH2 per l'utilizzo con i comandi IMAP AUTHENTICATE
, POP AUTH
e SMTP AUTH
. Questo meccanismo consente di utilizzare token di accesso OAuth 2.0 per eseguire l'autenticazione nell'account Gmail di un utente.
Utilizzare OAuth 2.0
Per iniziare, acquisisci familiarità con l'utilizzo di OAuth 2.0 per accedere alle API di Google. Questo documento spiega come funziona OAuth 2.0 e i passaggi necessari per scrivere un client.
Puoi anche sfogliare il codice XOAUTH2 di esempio per trovare esempi pratici.
Ambiti OAuth 2.0
L'ambito per l'accesso IMAP, POP e SMTP è https://mail.google.com/
. Se richiedi l'accesso all'ambito completo della posta per la tua app IMAP, POP o SMTP, deve essere conforme alle nostre Norme sui dati utente: servizi API di Google.
- Per essere approvata, la tua app deve mostrare l'utilizzo completo di
https://mail.google.com/
. - Se la tua app non richiede
https://mail.google.com/
, esegui la migrazione all'API Gmail e utilizza ambiti con restrizioni più granulari.
Delega a livello di dominio per Google Workspace
Se intendi utilizzare la
Google Workspace delega a livello di dominio
utilizzando gli
account di servizio
per accedere Google Workspace alle caselle di posta degli utenti tramite IMAP,
puoi autorizzare il client utilizzando invece l'ambito
https://www.googleapis.com/auth/gmail.imap_admin
.
Se autorizzate con questo ambito, le connessioni IMAP si comportano in modo diverso:
- Tutte le etichette vengono mostrate tramite IMAP, anche se gli utenti hanno disattivato l'opzione "Mostra in IMAP" per l'etichetta nelle impostazioni di Gmail.
- Tutti i messaggi vengono mostrati tramite IMAP, indipendentemente da quanto l'utente ha impostato in "Limiti della dimensione delle cartelle" nelle impostazioni di Gmail.
Meccanismo SASL XOAUTH2
Il meccanismo XOAUTH2 consente ai client di inviare token di accesso OAuth 2.0 al server. Il protocollo utilizza valori codificati mostrati nelle sezioni seguenti.
Risposta iniziale del cliente
La risposta iniziale del client SASL XOAUTH2 ha il formato seguente:
base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")
Utilizza il meccanismo di codifica Base64 definito in RFC 4648. ^A
rappresenta un tasto Ctrl + A (\001).
Ad esempio, prima della codifica base64, la risposta iniziale del client potrebbe essere la seguente:
user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A
Dopo la codifica Base64, questo diventa (interruzioni di riga inserite per maggiore chiarezza):
dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
Risposta di errore
Una risposta iniziale del client che causa un errore comporta l'invio da parte del server di un test contenente un messaggio di errore nel seguente formato:
base64({JSON-Body})
JSON-Body contiene tre valori: status
, schemes
e scope
. Ad esempio:
eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K
Dopo la decodifica base64, questo diventa (formattato per chiarezza):
{
"status":"401",
"schemes":"bearer",
"scope":"https://mail.google.com/"
}
Il protocollo SASL richiede che i client inviino una risposta vuota a questa verifica.
Scambio del protocollo IMAP
Questa sezione spiega come utilizzare SASL XOAUTH2 con il server IMAP di Gmail.
Risposta iniziale del cliente
Per accedere con il meccanismo SASL XOAUTH2, il client richiama il comando AUTHENTICATE
con il parametro del meccanismo XOAUTH2
e la risposta iniziale del client come descritto in precedenza. Ad esempio:
[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2 AUTH=XOAUTH
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvb
QFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG
1semRHRXVZMjl0Q2cBAQ==
S: A01 OK Success
[connection continues...]
Aspetti importanti dello scambio del protocollo IMAP:
- Il comando IMAP
AUTHENTICATE
è documentato in RFC 3501. - La funzionalità SASL-IR consente di inviare la risposta iniziale del client nella prima riga del comando
AUTHENTICATE
, in modo che sia richiesto un solo round trip per l'autenticazione. SASL-IR è documentato in RFC 4959. - La funzionalità AUTH=XOAUTH2 dichiara che il server supporta il meccanismo SASL definito in questo documento e questo meccanismo viene attivato specificando XOAUTH2 come primo argomento del comando
AUTHENTICATE
. - Le interruzioni di riga nei comandi
AUTHENTICATE
eCAPABILITY
servono per maggiore chiarezza e non sarebbero presenti nei dati effettivi del comando. L'intero argomento base64 deve essere una stringa continua, senza spazi vuoti incorporati, in modo che l'intero comandoAUTHENTICATE
sia costituito da una singola riga di testo.
Risposta di errore
Gli errori di autenticazione vengono restituiti anche tramite il comando AUTHENTICATE
IMAP:
[connection begins]
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQ
FhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1s
emRHRXVZMjl0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: A01 NO SASL authentication failed
Aspetti importanti dello scambio del protocollo IMAP:
- Il client invia una risposta vuota ("\r\n") alla verifica contenente il messaggio di errore.
Scambio di protocolli POP
Questa sezione spiega come utilizzare SASL XOAUTH2 con il server POP di Gmail.
Risposta iniziale del cliente
Per accedere con il meccanismo SASL XOAUTH2, il client richiama il comando AUTH
con il parametro del meccanismo XOAUTH2
e la risposta iniziale del client come descritto in precedenza. Ad esempio:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]
Aspetti importanti dello scambio del protocollo POP:
- Il comando POP
AUTH
è documentato in RFC 1734. - Le interruzioni di riga nel comando
AUTH
servono per maggiore chiarezza e non sarebbero presenti nei dati effettivi del comando. L'intero argomento base64 deve essere una stringa continua, senza spazi vuoti incorporati, in modo che l'intero comandoAUTH
sia costituito da una singola riga di testo.
Risposta di errore
Gli errori di autenticazione vengono restituiti anche tramite il comando POP AUTH
:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==
Scambio di protocolli SMTP
Questa sezione spiega come utilizzare SASL XOAUTH2 con il server SMTP di Gmail.
Risposta iniziale del cliente
Per accedere con il meccanismo XOAUTH2, il client richiama il comando AUTH
con il parametro del meccanismo XOAUTH2
e la risposta iniziale del client come descritto in precedenza. Ad esempio:
[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Accepted
[connection continues...]
Aspetti importanti sullo scambio del protocollo SMTP:
- Il comando SMTP
AUTH
è documentato in RFC 4954. - Le interruzioni di riga nel comando
AUTH
servono per maggiore chiarezza e non sarebbero presenti nei dati effettivi del comando. L'intero argomento base64 deve essere una stringa continua, senza spazi vuoti incorporati, in modo che l'intero comandoAUTH
sia costituito da una singola riga di testo.
Risposta di errore
Gli errori di autenticazione vengono restituiti anche tramite il comando SMTP AUTH
:
[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJl
ciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cB
AQ==
S: 334 eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: 535-5.7.1 Username and Password not accepted. Learn more at
S: 535 5.7.1 https://support.google.com/mail/?p=BadCredentials hx9sm5317360pbc.68
[connection continues...]
Aspetti importanti sullo scambio del protocollo SMTP:
- Il client invia una risposta vuota ("\r\n") alla verifica contenente il messaggio di errore.
Riferimenti
- OAUTH2: Utilizzare OAuth 2.0 per accedere alle API di Google
- SMTP: RFC 2821: Simple Mail Transfer Protocol
- IMAP: RFC 3501: PROTOCOLLO DI ACCESSO AI MESSAGGI INTERNET - VERSIONE 4rev1
- POP: RFC 1081: Protocollo post-ufficio - Versione 3
- SASL: RFC 4422: Simple Authentication and Security Layer (SASL)
- JSON: RFC 4627: il tipo di elemento multimediale application/json per la notazione dell'oggetto JavaScript
- BASE64: RFC 4648: le codifiche dei dati Base16, Base32 e Base64
- SASL-IR: RFC 4959: risposta iniziale del client per l'estensione IMAP per la semplice autenticazione e sicurezza del livello (SASL)
- SMTP-AUTH: RFC 4954: estensione del servizio SMTP per l'autenticazione