Mecanismo de OAuth 2.0

En este documento, se define el mecanismo SASL XOAUTH2 para usar con los comandos IMAP AUTHENTICATE, POP AUTH y SMTP AUTH. Este mecanismo permite usar 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. En ese documento, se explica cómo funciona OAuth 2.0 y los pasos necesarios para escribir un cliente.

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

Permisos de OAuth 2.0

El alcance del 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 de 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 planeas usar la delegación de todo el dominio de Google Workspace con cuentas de servicio para acceder a los buzones de correo de los usuarios de Google Workspace a través de IMAP, puedes autorizar tu cliente con el alcance https://www.googleapis.com/auth/gmail.imap_admin.

Cuando se autoriza 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 SASL XOAUTH2

El mecanismo XOAUTH2 permite que los clientes envíen 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 Control + A (U+0001).

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, se convierte en lo siguiente (se insertan saltos de línea para mayor claridad):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Respuesta de error

Una respuesta inicial del cliente que provoca un error hace que el servidor envíe un desafío que contiene un mensaje de error con el siguiente formato:

base64({JSON-Body})

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

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Después de la decodificación en base64, se convierte en lo siguiente (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...]

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

  • El comando AUTHENTICATE de IMAP se documenta 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 requiere un recorrido de ida y vuelta para la autenticación. SASL-IR se documenta en RFC 4959.
  • La capacidad AUTH=XOAUTH2 declara que el servidor admite el mecanismo SASL definido en 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 de comandos reales. Todo el argumento en 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 protocolos IMAP:

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

Intercambio de protocolos de 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 protocolos POP:

  • El comando AUTH de POP se documenta en RFC 1734.
  • Los saltos de línea en el comando AUTH se incluyen para mayor claridad y no estarían presentes en los datos del comando real. Todo el argumento en 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 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ó 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...]

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

  • El comando AUTH de SMTP se documenta en RFC 4954.
  • Los saltos de línea en el comando AUTH se incluyen para mayor claridad y no estarían presentes en los datos del comando real. Todo el argumento en 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