Mecanismo do OAuth 2.0

Este documento define o mecanismo SASL XOAUTH2 para uso com os comandos IMAP AUTHENTICATE, POP AUTH e SMTP AUTH. Esse mecanismo permite o uso de tokens de acesso do OAuth 2.0 para autenticar a conta do Gmail de um usuário.

Como usar o OAuth 2.0

Comece lendo Como usar o OAuth 2.0 para acessar as APIs do Google. Esse documento explica como o OAuth 2.0 funciona e as etapas necessárias para escrever um cliente.

Você também pode navegar pelo exemplo de código XOAUTH2 para ver exemplos de funcionamento.

Escopos do OAuth 2.0

O escopo para acesso IMAP, POP e SMTP é https://mail.google.com/. Se você solicitar acesso ao escopo de e-mail completo para seu app IMAP, POP ou SMTP, ele precisará estar em conformidade com nossa Política de dados do usuário dos serviços de API do Google.

  • Para ser aprovado, seu app precisa mostrar utilização total de https://mail.google.com/.
  • Se o app não exigir https://mail.google.com/, migre para a API Gmail e use escopos restritos mais granulares.

Delegação em todo o domínio do Google Workspace

Se você pretende usar a delegação em todo o domínio do Google Workspace com contas de serviço para acessar as caixas de correio dos usuários do Google Workspace via IMAP, autorize seu cliente usando o escopo https://www.googleapis.com/auth/gmail.imap_admin.

Quando autorizadas com esse escopo, as conexões IMAP se comportam de maneira diferente:

  • Todos os marcadores são mostrados via IMAP, mesmo que os usuários tenham desativado a opção "Mostrar no IMAP" nas configurações do Gmail.
  • Todas as mensagens são mostradas via IMAP, independente do que o usuário definiu em "Limites de tamanho da pasta" nas configurações do Gmail.

O mecanismo SASL XOAUTH2

O mecanismo XOAUTH2 permite que os clientes enviem tokens de acesso do OAuth 2.0 ao servidor. O protocolo usa valores codificados mostrados nas seções a seguir.

Resposta inicial do cliente

A resposta inicial do cliente SASL XOAUTH2 tem o seguinte formato:

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

Use o mecanismo de codificação base64 definido na RFC 4648. ^A representa um Control+A (\001).

Por exemplo, antes da codificação em base64, a resposta inicial do cliente pode ser assim:

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

Depois da codificação em base64, isso se torna (quebras de linha inseridas para maior clareza):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Resposta de erro

Uma resposta inicial do cliente que causa um erro faz com que o servidor envie um desafio contendo uma mensagem de erro no seguinte formato:

base64({JSON-Body})

O JSON-Body contém três valores: status, schemes e scope. Exemplo:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

Depois da decodificação em base64, isso se torna (formatado para clareza):

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

O protocolo SASL exige que os clientes enviem uma resposta vazia a esse desafio.

Troca de protocolo IMAP

Nesta seção, explicamos como usar o SASL XOAUTH2 com o servidor IMAP do Gmail.

Resposta inicial do cliente

Para fazer login com o mecanismo SASL XOAUTH2, o cliente invoca o comando AUTHENTICATE com o parâmetro de mecanismo XOAUTH2 e a resposta inicial do cliente, conforme construída acima. Exemplo:

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

Observações sobre a troca de protocolo IMAP:

  • O comando IMAP AUTHENTICATE está documentado na RFC 3501.
  • O recurso SASL-IR permite enviar a resposta inicial do cliente na primeira linha do comando AUTHENTICATE, para que apenas uma ida e volta seja necessária para a autenticação. O SASL-IR está documentado na RFC 4959 (em inglês).
  • A capacidade AUTH=XOAUTH2 declara que o servidor é compatível com o mecanismo SASL definido neste documento, e esse mecanismo é ativado especificando XOAUTH2 como o primeiro argumento do comando AUTHENTICATE.
  • As quebras de linha nos comandos AUTHENTICATE e CAPABILITY são para facilitar a leitura e não estão presentes nos dados reais do comando. Todo o argumento base64 precisa ser uma string contínua, sem espaços em branco incorporados, para que o comando AUTHENTICATE inteiro consista em uma única linha de texto.

Resposta de erro

As falhas de autenticação também são retornadas pelo comando IMAP AUTHENTICATE:

[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

Observações sobre a troca de protocolo IMAP:

  • O cliente envia uma resposta vazia ("\r\n") ao desafio que contém a mensagem de erro.

Troca de protocolo POP

Esta seção explica como usar o SASL XOAUTH2 com o servidor POP do Gmail.

Resposta inicial do cliente

Para fazer login com o mecanismo SASL XOAUTH2, o cliente invoca o comando AUTH com o parâmetro de mecanismo XOAUTH2 e a resposta inicial do cliente, conforme construída acima. Exemplo:

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

Observações sobre a troca de protocolo POP:

  • O comando POP AUTH está documentado na RFC 1734.
  • As quebras de linha no comando AUTH são para maior clareza e não estariam presentes nos dados reais do comando. Todo o argumento base64 precisa ser uma string contínua, sem espaços em branco incorporados, para que o comando AUTH inteiro consista em uma única linha de texto.

Resposta de erro

As falhas de autenticação também são retornadas pelo comando POP AUTH:

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

Troca de protocolo SMTP

Esta seção explica como usar o SASL XOAUTH2 com o servidor SMTP do Gmail.

Resposta inicial do cliente

Para fazer login com o mecanismo XOAUTH2, o cliente invoca o comando AUTH com o parâmetro de mecanismo XOAUTH2 e a resposta inicial do cliente, conforme construída acima. Exemplo:

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

Observações sobre a troca de protocolo SMTP:

  • O comando SMTP AUTH está documentado na RFC 4954.
  • As quebras de linha no comando AUTH são para maior clareza e não estariam presentes nos dados reais do comando. Todo o argumento base64 precisa ser uma string contínua, sem espaços em branco incorporados, para que o comando AUTH inteiro consista em uma única linha de texto.

Resposta de erro

As falhas de autenticação também são retornadas pelo 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...]

Observações sobre a troca de protocolo SMTP:

  • O cliente envia uma resposta vazia ("\r\n") ao desafio que contém a mensagem de erro.

Referências