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 autenticação na conta do Gmail de um usuário.

Como usar o OAuth 2.0

Comece por se familiarizar com 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 consultar o exemplo de código XOAUTH2 (em inglês) para conferir exemplos funcionais.

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 do 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, o app precisa mostrar a 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 para Google Workspace

Se você pretende usar a Google Workspace delegação em todo o domínio usando contas de serviço para acessar Google Workspace as caixas de e-mails dos usuários via IMAP, autorize o 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 pelo IMAP, mesmo que os usuários desativem a opção "Mostrar no IMAP" para o marcador nas configurações do Gmail.
  • Todas as mensagens são mostradas pelo IMAP, independentemente do que o usuário definiu em "Limites de tamanho da pasta" nas configurações do Gmail.

Mecanismo SASL XOAUTH2

O mecanismo XOAUTH2 permite que os clientes enviem tokens de acesso do OAuth 2.0 para o 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 Control + A (\001).

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

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

Depois da codificação 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 neste 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 maior clareza):

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

O protocolo SASL exige que os clientes enviem uma resposta vazia para essa solicitação.

Troca de protocolo IMAP

Esta seção explica 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 de XOAUTH2 e a resposta inicial do cliente, conforme construído 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 AUTHENTICATE do IMAP está documentado no RFC 3501.
  • O recurso SASL-IR permite enviar a resposta inicial do cliente na primeira linha do comando AUTHENTICATE, de modo que apenas uma ida e volta é necessária para a autenticação. O SASL-IR está documentado na RFC 4959 (em inglês).
  • O capability AUTH=XOAUTH2 declara que o servidor oferece suporte ao mecanismo SASL definido neste documento. Esse mecanismo é ativado especificando XOAUTH2 como o primeiro argumento do comando AUTHENTICATE.
  • As quebras de linha nos comandos AUTHENTICATE e CAPABILITY são para fins de esclarecimento e não estão presentes nos dados de comando reais. O argumento base64 inteiro 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 AUTHENTICATE do 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

Observações sobre a troca de protocolo IMAP:

  • O cliente envia uma resposta vazia ("\r\n") para o 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 AUTH do POP está documentado na RFC 1734.
  • As quebras de linha no comando AUTH são para maior clareza e não estarão presentes nos dados reais do comando. O argumento base64 inteiro precisa ser uma string contínua, sem espaço em branco incorporado, 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 AUTH do POP:

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

Coisas a serem observadas sobre a troca de protocolos SMTP:

  • O comando AUTH SMTP está documentado na RFC 4954.
  • As quebras de linha no comando AUTH são para maior clareza e não estarão presentes nos dados reais do comando. O argumento base64 inteiro precisa ser uma string contínua, sem espaço em branco incorporado, 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 AUTH do 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...]

Coisas a serem observadas sobre a troca de protocolos SMTP:

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

Referências