Mecanismo de OAuth 2.0

En este documento, se define el mecanismo SASL de XOAUTH2 para usar con los comandos IMAP 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

Comienza por familiarizarte 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 un cliente.

Es posible que también desees explorar el código de muestra de XOAUTH2 para ver ejemplos prácticos.

Alcances de OAuth 2.0

El alcance del acceso IMAP, POP y SMTP es https://mail.google.com/. Si solicitas acceso al alcance completo del correo electrónico 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 API 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 Google Workspace delegación de todo el dominio con cuentas de servicio para acceder a los Google Workspace buzones de usuarios a través de IMAP, puedes autorizar al cliente mediante el alcance https://www.googleapis.com/auth/gmail.imap_admin.

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 por medio 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 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")

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

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

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

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

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Respuesta de error

Una respuesta inicial del cliente que provoca un error da como resultado que el servidor envíe un desafío con 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 pasa a ser (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ó 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 del 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 recorrido de ida y vuelta para la autenticación. SASL-IR está documentado en RFC 4959.
  • La función AUTH=XOAUTH2 declara que el servidor admite el mecanismo SASL definido en este documento. Este mecanismo se activa especificando XOAUTH2 como primer argumento del comando AUTHENTICATE.
  • Los saltos de línea en los comandos AUTHENTICATE y CAPABILITY se usan para brindar mayor claridad y no se incluyen en los datos del comando reales. El argumento base64 completo debe ser una string 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 del 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 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ó 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 protocolos POP:

  • El comando AUTH de POP está documentado en RFC 1734.
  • Los saltos de línea en el comando AUTH se usan para mayor claridad y no estarían presentes en los datos del comando reales. El argumento base64 completo debe ser una string 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 devuelven a través del comando AUTH de POP:

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

Intercambio de protocolo SMTP

En esta sección, se explica cómo usar 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 de 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...]

Aspectos que debes tener en cuenta sobre el intercambio del protocolo SMTP:

  • El comando AUTH de SMTP está documentado en RFC 4954.
  • Los saltos de línea en el comando AUTH se usan para mayor claridad y no estarían presentes en los datos del comando reales. El argumento base64 completo debe ser una string 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 del protocolo SMTP:

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

Referencias