Mecanismo de OAuth 2.0

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En este documento, se define el mecanismo SASL XOAUTH2 para usar con los comandos AUTHENTICATE de IMAP, POP AUTH y AUTH 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 familiarizándote con Usa OAuth 2.0 para acceder a las API de Google. Ese documento explica cómo funciona OAuth 2.0 y los pasos necesarios para escribir un cliente.

También puedes explorar el código XOAUTH2 de muestra para ver algunos ejemplos de cómo funciona.

Alcances de OAuth 2.0

El permiso para el acceso IMAP, POP y SMTP es https://mail.google.com/. Si solicitas acceso al alcance 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 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 alcances restringidos más detallados.

Delegación de Google Workspacepara todo el dominio

Si deseas usar la Google Workspace delegación de todo el dominio con Cuentas de servicio para acceder a los buzones de correo de los usuarios a través de IMAP, puedes autorizar al cliente mediante el permiso 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 por medio 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 de SASL XOAUTH2

El mecanismo de 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 del cliente inicial 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 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

Cuando una respuesta inicial del cliente causa un error, el servidor envía 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 se convierte en (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 del mecanismo de XOAUTH2 y la respuesta inicial del cliente como se indicó 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 protocolo IMAP:

  • El comando AUTHENTICATE de IMAP se documenta en RFC 3501.
  • La función SASL-IR permite enviar la respuesta inicial del cliente en la primera línea del comando AUTHENTICATE, de modo que solo se requiera una ida y vuelta para la autenticación. SASL-IR está documentado en RFC 4959.
  • La capacidad AUTH=XOAUTH2 declara que el servidor admite el mecanismo SASL que se define en este documento, y este mecanismo se activa especificando XOAUTH2 como el primer argumento para el comando AUTHENTICATE.
  • Los saltos de línea en los comandos AUTHENTICATE y CAPABILITY son para mayor claridad y no estarán presentes en los datos de comandos reales. El argumento base64 completo debe ser una string continua, sin espacios en blanco incorporados, de modo que todo el comando AUTHENTICATE esté compuesto por 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 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 del mecanismo de XOAUTH2 y la respuesta inicial del cliente como se indicó anteriormente. Por ejemplo:

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

Información 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 claros 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 esté compuesto por una sola línea de texto.

Respuesta de error

Las fallas 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 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 del mecanismo de XOAUTH2 y la respuesta inicial del cliente como se creó 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 protocolo SMTP:

  • El comando AUTH de SMTP está documentado en RFC 4954.
  • Los saltos de línea en el comando AUTH son claros 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 esté compuesto por una sola línea de texto.

Respuesta de error

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

Aspectos que debes tener en cuenta 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