Mecanismo do OAuth 2.0

Este documento define o mecanismo SASL XOAUTH2 para uso com o IMAP AUTHENTICATE, POP AUTH e SMTP AUTH. Com esse mecanismo, a utilização 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 aprendendo mais sobre 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 criar um cliente.

Você também pode procurar o exemplo de código XOAUTH2 para ver exemplos práticos.

Escopos do OAuth 2.0

O escopo para acesso IMAP, POP e SMTP é https://mail.google.com/. Se você solicitar acesso a todo o escopo de e-mails do seu aplicativo IMAP, POP ou SMTP Ele precisa estar em conformidade com nossa Política de dados do usuário do serviço da API do Google.

  • Para ser aprovado, o app precisa mostrar o uso total do https://mail.google.com/.
  • Caso o app não exija o https://mail.google.com/, migre para o Gmail e usar escopos restritos mais granulares.

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

Se você pretende usar Google Workspace Delegação em todo o domínio usando Contas de serviço para acessar os Google Workspace usuários caixas de e-mail via IMAP, você pode autorizar 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 por IMAP, mesmo que os usuários tenham desativado a opção "Mostrar no IMAP" para o marcador nas configurações do Gmail.
  • Todas as mensagens são mostradas via IMAP, independentemente do que o usuário tenha definido em "Limites de tamanho de 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 no 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, passa a ser (quebras de linha inseridas para maior clareza):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Resposta de erro

A resposta inicial do cliente que causa um erro faz com que o servidor envie um que contém 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

Após a 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 esse desafio.

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 IMAP AUTHENTICATE está documentado na 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 seja necessária para a autenticação. O SASL-IR está documentado na RFC 4959.
  • O recurso AUTH=XOAUTH2 declara que o servidor oferece suporte ao mecanismo SASL definido por este documento, e esse mecanismo é ativado especificando XOAUTH2 como o primeiro argumento para o 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ço em branco incorporado, 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") 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 de XOAUTH2 e a resposta inicial do cliente, conforme construído acima. Exemplo:

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

Pontos a serem observados 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 fins de esclarecimento e não estariam 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...]

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 fins de esclarecimento e não estariam 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 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