Mecanismo de OAuth 2.0

En este documento, se define el mecanismo SASL XOAUTH2 para usar con IMAP Comandos AUTHENTICATE, POP AUTH y SMTP AUTH. Este mecanismo permite el uso de tokens de acceso de OAuth 2.0 para autenticarse en la cuenta de Gmail de un usuario.

A través de OAuth 2.0

Familiarízate con el uso de OAuth 2.0 para acceder a las APIs de Google. Ese documento explica cómo funciona OAuth 2.0 y los pasos necesarios para escribir a un cliente.

También puedes explorar el código XOAUTH2 de muestra para ver ejemplos prácticos.

Alcances de OAuth 2.0

El alcance del acceso IMAP, POP y SMTP es https://mail.google.com/. Si solicitar acceso al permiso completo del correo electrónico para tu aplicación IMAP, POP o SMTP, debe cumplir con nuestra Política sobre los datos del usuario de los servicios de las APIs de Google.

  • Para que se apruebe, tu app debe mostrar el uso completo de https://mail.google.com/.
  • Si tu app no requiere https://mail.google.com/, migra a Gmail y usar permisos restringidos más detallados.

Delegación de todo el dominio para Google Workspace

Si piensas usar Google Workspace delegación de todo el dominio mediante Cuentas de servicio para acceder a Google Workspace los usuarios buzones de correo a través de IMAP, puedes autorizar a tu cliente con el permiso https://www.googleapis.com/auth/gmail.imap_admin en su lugar.

Cuando se autorizan con este alcance, las conexiones IMAP se comportan de manera diferente:

  • Todas las etiquetas se muestran a través de IMAP, incluso si los usuarios inhabilitaron la opción "Mostrar en IMAP". para la etiqueta en la configuración de Gmail.
  • Todos los mensajes se muestran a través de IMAP, independientemente de lo que el usuario haya configurado en "Límites de tamaño de las carpetas". en la configuración de Gmail.

El mecanismo de SASL XOAUTH2

El mecanismo XOAUTH2 permite a los clientes enviar tokens de acceso de OAuth 2.0 al servidor. El protocolo usa valores codificados que se muestran en las siguientes secciones.

Respuesta inicial del cliente

La respuesta inicial del cliente de SASL XOAUTH2 tiene el siguiente formato:

base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")

Usa el mecanismo de codificación base64 definido en RFC 4648. ^A representa un Control + A (\001).

Por ejemplo, antes de la codificación en base64, la respuesta inicial del cliente podría verse de la siguiente manera:

user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A

Después de la codificación en Base64, esto se convierte en (se insertan saltos de línea para mayor claridad):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Respuesta de error

Una respuesta inicial del cliente que causa un error hace que el servidor envíe un desafío que contenga un mensaje de error en el siguiente formato:

base64({JSON-Body})

JSON-Body contiene tres valores: status, schemes y scope. Por ejemplo:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Después de la decodificación en Base64, esto tiene el siguiente formato:

{
  "status":"401",
  "schemes":"bearer",
  "scope":"https://mail.google.com/"
}

El protocolo SASL requiere que los clientes envíen una respuesta vacía a este desafío.

Intercambio de protocolo IMAP

En esta sección, se explica cómo usar SASL XOAUTH2 con el servidor IMAP de Gmail.

Respuesta inicial del cliente

Para acceder con el mecanismo SASL XOAUTH2, el cliente invoca el comando AUTHENTICATE con el parámetro de mecanismo XOAUTH2 y la respuesta inicial del cliente como se construyó antes. Por ejemplo:

[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...]

Aspectos que debes tener en cuenta sobre el intercambio de protocolo IMAP:

  • El comando AUTHENTICATE de IMAP está documentado en RFC 3501.
  • La capacidad SASL-IR permite enviar la respuesta inicial del cliente en la primera línea del comando AUTHENTICATE, de modo que solo se requiera un proceso de ida y vuelta para la autenticación. SASL-IR está documentado en RFC 4959.
  • La capacidad AUTH=XOAUTH2 se declara que el servidor admite el mecanismo SASL definido en este documento, y este mecanismo se activa cuando se especifica XOAUTH2 como primer argumento en el comando AUTHENTICATE.
  • Los saltos de línea en los comandos AUTHENTICATE y CAPABILITY son para mayor claridad y no estarían presentes en los datos reales del comando. Todo el argumento base64 debe ser una cadena continua, sin espacios en blanco incorporados, de modo que todo el comando AUTHENTICATE conste de una sola línea de texto.

Respuesta de error

Las fallas de autenticación también se muestran a través del comando AUTHENTICATE de 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

Aspectos que debes tener en cuenta sobre el intercambio de protocolo IMAP:

  • El cliente envía una respuesta vacía ("\r\n") al desafío que contiene el mensaje de error.

Intercambio de protocolo POP

En esta sección, se explica cómo utilizar SASL XOAUTH2 con el servidor POP de Gmail.

Respuesta inicial del cliente

Para acceder con el mecanismo SASL XOAUTH2, el cliente invoca el comando AUTH con el parámetro de mecanismo XOAUTH2 y la respuesta inicial del cliente como se construyó antes. Por ejemplo:

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]

Aspectos que debes tener en cuenta sobre el intercambio de protocolo POP:

  • El comando AUTH de POP está documentado en RFC 1734.
  • Los saltos de línea en el comando AUTH son para mayor claridad y no estarían presentes en los datos reales del comando. Todo el argumento base64 debe ser una cadena continua, sin espacios en blanco incorporados, de modo que todo el comando AUTH conste de una sola línea de texto.

Respuesta de error

Los errores de autenticación también se muestran a través del comando POP AUTH:

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==

Intercambio de protocolos SMTP

En esta sección, se explica cómo utilizar SASL XOAUTH2 con el servidor SMTP de Gmail.

Respuesta inicial del cliente

Para acceder con el mecanismo XOAUTH2, el cliente invoca el comando AUTH con el parámetro de mecanismo XOAUTH2 y la respuesta inicial del cliente como se construyó antes. Por ejemplo:

[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...]

Ten en cuenta lo siguiente sobre el intercambio de protocolo SMTP:

  • El comando AUTH de SMTP está documentado en RFC 4954.
  • Los saltos de línea en el comando AUTH son para mayor claridad y no estarían presentes en los datos reales del comando. Todo el argumento base64 debe ser una cadena continua, sin espacios en blanco incorporados, de modo que todo el comando AUTH conste de una sola línea de texto.

Respuesta de error

Los errores de autenticación también se muestran a través del comando de 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...]

Ten en cuenta lo siguiente sobre el intercambio de protocolo SMTP:

  • El cliente envía una respuesta vacía ("\r\n") al desafío que contiene el mensaje de error.

Referencias