Autenticar uma conexão IMAP, POP ou SMTP usando o OAuth
Saiba como usar a autenticação OAuth para se conectar com protocolos IMAP, POP ou SMTP e acessar dados de email para usuários Office 365.
O suporte do OAuth2 para protocolos IMAP, POP e SMTP, conforme descrito abaixo, está disponível para usuários do Microsoft 365 (que inclui Office na Web) e Outlook.com usuários.
Importante
Essa documentação usa o escopo preterido da API REST do Outlook. Em vez disso, novos aplicativos devem usar o Ponto de Extremidade da API REST do Graph .
Se você não estiver familiarizado com o protocolo OAuth 2.0, consulte Protocolo OAuth 2.0 em plataforma de identidade da Microsoft visão geral. Para obter mais informações sobre as MSAL (Bibliotecas de Autenticação da Microsoft), que implementam o protocolo OAuth 2.0 para autenticar usuários e acessar APIs seguras, consulte Visão geral do MSAL.
Você pode usar o serviço de autenticação OAuth fornecido por Microsoft Entra (Microsoft Entra) para habilitar a conexão do aplicativo com protocolos IMAP, POP ou SMTP para acessar Exchange Online em Office 365. Para usar o OAuth com seu aplicativo, você precisa:
- Registre seu aplicativo com Microsoft Entra.
- Obtenha um token de acesso de um servidor de token.
- Autenticar solicitações de conexão com um token de acesso.
Registre seu aplicativo
Para usar o OAuth, um aplicativo deve ser registrado com Microsoft Entra.
Siga as instruções listadas em Registrar um aplicativo com o plataforma de identidade da Microsoft para criar um novo aplicativo.
Obter um token de acesso
Você pode usar uma de nossas bibliotecas de clientes MSAL para buscar um token de acesso do aplicativo cliente.
Como alternativa, você pode selecionar um fluxo apropriado na lista a seguir e seguir as etapas correspondentes para chamar as APIs REST da plataforma de identidade subjacente e recuperar um token de acesso.
- Fluxo de código de autorização OAuth2
- Fluxo de concessão de autorização de dispositivo OAuth2
- Fluxo de concessão de credenciais do cliente OAuth2
Certifique-se de especificar os escopos completos, incluindo URLs de recurso do Outlook, ao autorizar seu aplicativo e solicitar um token de acesso.
| Protocolo | Cadeia de caracteres de escopo de permissão |
|---|---|
| IMAP | https://outlook.office.com/IMAP.AccessAsUser.All |
| POP | https://outlook.office.com/POP.AccessAsUser.All |
| SMTP AUTH | https://outlook.office.com/SMTP.SendAsApp |
Além disso, você pode solicitar offline_access escopo. Quando um usuário aprova o escopo offline_access, seu aplicativo pode receber tokens de atualização do ponto de extremidade do token plataforma de identidade da Microsoft. Os tokens de atualização são de longa duração. Seu aplicativo pode obter novos tokens de acesso à medida que os mais antigos expirarem.
Autenticar solicitações de conexão
Você pode iniciar uma conexão com Office 365 servidores de email usando as configurações de email IMAP e POP para Office 365.
SASL XOAUTH2
A integração do OAuth exige que seu aplicativo use o formato SASL XOAUTH2 para codificar e transmitir o token de acesso. O SASL XOAUTH2 codifica o nome de usuário e o token de acesso juntos no seguinte formato:
base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")
^A representa um Controle + A (%x01).
Por exemplo, o formato de XOAUTH2 SASL a ser acessado test@contoso.onmicrosoft.com com o token EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA de acesso é:
base64("user=test@contoso.onmicrosoft.com^Aauth=Bearer EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA^A^A")
Após a codificação base64, esse formato se traduz na cadeia de caracteres a seguir. As quebras de linha são inseridas para legibilidade.
dXNlcj10ZXN0QGNvbnRvc28ub25taWNyb3NvZnQuY29tAWF1dGg9QmVhcmVy
IEV3QkFBbDNCQUFVRkZwVUFvN0ozVmUwYmpMQldaV0NjbFJDM0VvQUEBAQ==
Autenticação de XOAUTH2 SASL para caixas de correio compartilhadas em Office 365
No caso de acesso de caixa de correio compartilhada usando o OAuth, um aplicativo precisa obter o token de acesso em nome de um usuário, mas substituir o campo userName na cadeia de caracteres codificada SASL XOAUTH2 com o endereço de email da caixa de correio compartilhada.
Troca de ProtocoloS IMAP
Para autenticar uma conexão de servidor IMAP, o cliente deve responder com um AUTHENTICATE comando no seguinte formato:
AUTHENTICATE XOAUTH2 <base64 string in XOAUTH2 format>
Exemplo de troca de mensagens cliente-servidor que resulta em um sucesso de autenticação:
[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 OK AUTHENTICATE completed.
Exemplo de troca de mensagens cliente-servidor que resulta em uma falha de autenticação:
[connection begins]
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 NO AUTHENTICATE failed.
Troca de Protocolo POP
Para autenticar uma conexão de servidor POP, o cliente terá que responder com um AUTH comando dividido em duas linhas no seguinte formato:
AUTH XOAUTH2
<base64 string in XOAUTH2 format>
Exemplo de troca de mensagens cliente-servidor que resulta em um sucesso de autenticação:
[connection begins]
C: AUTH XOAUTH2
S: +
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK User successfully authenticated.
[connection continues...]
Exemplo de troca de mensagens cliente-servidor que resulta em uma falha de autenticação:
[connection begins]
C: AUTH XOAUTH2
S: +
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ=
S: -ERR Authentication failure: unknown user name or bad password.
Troca de Protocolos SMTP
Para autenticar uma conexão de servidor SMTP, o cliente deve responder com um AUTH comando no seguinte formato:
AUTH XOAUTH2 <base64 string in XOAUTH2 format>
Exemplo de troca de mensagens cliente-servidor que resulta em um sucesso de autenticação:
[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Authentication successful
[connection continues...]
Exemplo de troca de mensagens cliente-servidor que resulta em uma falha de autenticação:
[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 535 5.7.3 Authentication unsuccessful [SN2PR00CA0018.namprd00.prod.outlook.com]
Usar o fluxo de concessão de credenciais do cliente para autenticar conexões SMTP, IMAP e POP
As entidades de serviço no Exchange são usadas para permitir que aplicativos acessem caixas de correio do Exchange por meio do fluxo de credenciais do cliente com os protocolos SMTP, POP e IMAP.
Adicione as permissões POP, IMAP ou SMTP ao aplicativo Entra AD
No portal do Azure, escolha a folha Permissões de API na exibição de gerenciamento do aplicativo Microsoft Entra.
Selecione Adicionar permissão.
Selecione as APIs que minha organização usa a guia e pesquise "Office 365 Exchange Online".
Clique em Permissões de aplicativo.
Para acesso POP, escolha o POP. Permissão AccessAsApp . Para acesso IMAP, escolha o IMAP. Permissão AccessAsApp . Para acesso SMTP, escolha o SMTP. Permissão SendAsApp .
Depois de escolher o tipo de permissão, selecione Adicionar permissões.
Agora você deve ter as permissões de aplicativo SMTP, POP ou IMAP adicionadas às permissões do aplicativo Entra AD.
Obter o consentimento do administrador do locatário
Para acessar caixas de correio do Exchange por meio de POP ou IMAP, seu aplicativo Entra AD deve obter o consentimento do administrador do locatário para cada locatário. Para obter mais informações, consulte processo de consentimento do administrador de locatário.
Como conceder consentimento se o aplicativo estiver registrado/configurado para uso de vários locatários, por exemplo, para o aplicativo registrado centralmente desenvolvido pelo Partner/ISV
Se o ISV/parceiro registrou o aplicativo Microsoft Entra com a opção "Contas em qualquer diretório organizacional", você precisará adicionar esse aplicativo e consenti-lo usando as etapas a seguir aproveitando a URL da solicitação de autorização.
Diretrizes POP e IMAP
Na solicitação de autorização de locatário do OAuth 2.0, o scope parâmetro de consulta deve ser https://ps.outlook.com/.default para os escopos de aplicativo POP e IMAP.
A URL da solicitação de autorização do OAuth 2.0 é mostrada no exemplo a seguir:
https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://ps.outlook.com/.default
Diretrizes do SMTP
Na solicitação de autorização de locatário do OAuth 2.0, o scope parâmetro de consulta deve ser https://outlook.office365.com/.default apenas para SMTP. A URL da solicitação de autorização do OAuth 2.0 é mostrada no exemplo a seguir:
https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://outlook.office365.com/.default
Como conceder consentimento se você registrou o aplicativo para seu próprio locatário
Se você registrou seu aplicativo em seu próprio locatário usando "Contas neste diretório organizacional", poderá avançar e usar a página de configuração do aplicativo no centro de administração do Microsoft Entra para conceder o consentimento do administrador e não precisar usar a abordagem de URL da solicitação de autorização.
Registrar entidades de serviço no Exchange
Depois que um administrador de locatário consentir seu aplicativo Microsoft Entra, ele deverá registrar a entidade de serviço do aplicativo Entra AD no Exchange por meio Exchange Online PowerShell. Esse registro está habilitado pelo New-ServicePrincipal cmdlet.
Para usar o cmdlet New-ServicePrincipal , instale o ExchangeOnlineManagement e conecte-se ao locatário, conforme mostrado no seguinte snippet:
Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <tenantId>
Se você ainda receber um erro executando o cmdlet New-ServicePrincipal depois de executar essas etapas, é provável que o usuário não tenha permissões suficientes no Exchange online para executar a operação.
O registro da entidade de serviço de um aplicativo Microsoft Entra no Exchange é mostrado no exemplo a seguir:
New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> [-Organization <ORGANIZATION_ID>]
O administrador do locatário pode encontrar os identificadores da entidade de serviço referenciados acima na instância de aplicativo empresarial do aplicativo Entra AD no locatário. Você pode encontrar a lista das instâncias do aplicativo empresarial no locatário na folha aplicativos Enterprise na exibição Microsoft Entra no Portal do Azure.
Você pode obter o identificador da entidade de serviço registrada usando o Get-ServicePrincipal cmdlet.
Get-ServicePrincipal | fl
O OBJECT_ID é a ID do Objeto da página Visão geral do nó aplicativo empresarial (Portal do Azure) para o registro do aplicativo. Não é a ID do Objeto da página Visão geral do nó Registros de Aplicativo. O uso da ID de Objeto incorreta causará uma falha de autenticação.
O administrador do locatário agora pode adicionar as caixas de correio específicas no locatário que poderão ser acessadas pelo aplicativo. Essa configuração é feita com o Add-MailboxPermission cmdlet.
O exemplo a seguir mostra como dar à entidade de serviço do aplicativo acesso a uma caixa de correio:
Add-MailboxPermission -Identity "john.smith@contoso.com" -User
<SERVICE_PRINCIPAL_ID> -AccessRights FullAccess
Diferentes IDs são usadas durante a criação da entidade de serviço do Exchange e também posteriores ao conceder permissões de caixa de correio. O exemplo a seguir pode ajudá-lo a usar a ID correta para os diferentes estágios. Este exemplo usa Microsoft Entra cmdlets; portanto, você precisará instalar o módulo Microsoft Entra PowerShell, se ainda não tiver. Para obter mais informações, consulte Instalar Microsoft Entra PowerShell para Graph.
$AADServicePrincipalDetails = Get-AzureADServicePrincipal -SearchString YourAppName
New-ServicePrincipal -AppId $AADServicePrincipalDetails.AppId -ObjectId $AADServicePrincipalDetails.ObjectId -DisplayName "EXO Serviceprincipal for EntraAD App $($AADServicePrincipalDetails.Displayname)"
$EXOServicePrincipal = Get-ServicePrincipal -Identity "EXO Serviceprincipal for EntraAD App YourAppName"
Add-MailboxPermission -Identity "john.smith@contoso.com" -User $EXOServicePrincipal.Identity -AccessRights FullAccess
Seu aplicativo Microsoft Entra agora pode acessar as caixas de correio permitidas por meio dos protocolos SMTP, POP ou IMAP usando o fluxo de concessão de credenciais de cliente do OAuth 2.0. Para obter mais informações, consulte as instruções em Permissões e consentimento no plataforma de identidade da Microsoft.
Você deve usar https://outlook.office365.com/.default na scope propriedade na carga do corpo para a solicitação de token de acesso.
Os tokens de acesso gerados podem ser usados como tokens para autenticar conexões SMTP, POP e IMAP por meio do formato de XOAUTH2 SASL, conforme descrito anteriormente.
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de