Mecanismo de OAuth 2.0

En este documento, se define el mecanismo SASL XOAUTH2 para usarlo con los comandos AUTHENTICATE de IMAP, AUTH de POP y AUTH de SMTP. 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

Comienza por familiarizarte con Cómo usar 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 de XOAUTH2 de muestra para ver ejemplos funcionales.

Permisos de OAuth 2.0

El permiso de acceso a IMAP, POP y SMTP es https://mail.google.com/. Si solicitas acceso al permiso de correo completo para tu app de IMAP, POP o SMTP, esta 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 la API de Gmail y usa permisos restringidos más detallados.

Delegación de todo el dominio para Google Workspace

Si deseas usar la delegación de todo el dominioGoogle Workspace con cuentas de servicio para acceder a los buzones de correo de los usuarios Google Workspace a través de IMAP, puedes autorizar a tu cliente con el permiso https://www.googleapis.com/auth/gmail.imap_admin.

Cuando se autorizan con este permiso, 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 establecido en "Límites de tamaño de las carpetas", en la configuración de Gmail.

El mecanismo XOAUTH2 de SASL

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 la RFC 4648. ^A representa una combinación de teclas Control + A (\001).

Por ejemplo, antes de la codificación 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 base64, se convierte en lo siguiente (se insertan saltos de línea para brindar mayor claridad):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Respuesta de error

Una respuesta inicial del cliente que causa un error hace que el servidor envíe una verificación que contiene un mensaje de error con 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, se convierte en (con formato para mayor claridad):

{
  "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 de XOAUTH2 y la respuesta inicial del cliente como se construyó anteriormente. 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...]

Ten en cuenta lo siguiente sobre el intercambio de protocolos 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 se documenta en la RFC 4959.
  • La capability AUTH=XOAUTH2 declara que el servidor admite el mecanismo SASL que define este documento, y este mecanismo se activa especificando XOAUTH2 como el primer argumento del 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

Los errores 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 protocolos POP

En esta sección, se explica cómo usar 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 de XOAUTH2 y la respuesta inicial del cliente como se construyó anteriormente. 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 se documenta en la 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 AUTH de POP:

[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 del cliente inicial como se construyó anteriormente. 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 se documenta en la RFC 4954.
  • Los saltos de línea en el comando AUTH se usan para brindar 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 AUTH de SMTP:

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

Aspectos que debes tener en cuenta sobre el intercambio de protocolos SMTP:

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

Referencias