Autenticar uma ligação IMAP, POP ou SMTP com o OAuth
Saiba como utilizar a autenticação OAuth para se ligar a protocolos IMAP, POP ou SMTP e aceder a dados de e-mail para Office 365 utilizadores.
O suporte OAuth2 para protocolos IMAP, POP e SMTP, conforme descrito abaixo, está disponível para o Microsoft 365 (que inclui Office na Web) e Outlook.com utilizadores.
Se não estiver familiarizado com o protocolo OAuth 2.0, veja OAuth 2.0 protocol on plataforma de identidade da Microsoft overview (Descrição geral do protocolo OAuth 2.0). Para obter mais informações sobre as Bibliotecas de Autenticação da Microsoft (MSAL), que implementam o protocolo OAuth 2.0 para autenticar utilizadores e aceder a APIs seguras, veja MsAL overview (Descrição geral da MSAL).
Pode utilizar o serviço de autenticação OAuth fornecido pelo Microsoft Entra (Microsoft Entra) para permitir que a sua aplicação se ligue a protocolos IMAP, POP ou SMTP para aceder a Exchange Online no Office 365. Para utilizar o OAuth com a sua aplicação, tem de:
- Registe a sua aplicação com Microsoft Entra.
- Obter um token de acesso a partir de um servidor de tokens.
- Autenticar pedidos de ligação com um token de acesso.
Registre seu aplicativo
Para utilizar o OAuth, tem de ser registada uma aplicação com Microsoft Entra.
Siga as instruções listadas em Registar uma aplicação com o plataforma de identidade da Microsoft para criar uma nova aplicação.
Obter um token de acesso
Pode utilizar uma das nossas bibliotecas de cliente MSAL para obter um token de acesso da sua aplicação cliente.
Em alternativa, pode selecionar um fluxo adequado na lista seguinte e seguir os passos correspondentes para chamar as APIs REST da plataforma de identidade subjacente e obter um token de acesso.
Certifique-se de que especifica os âmbitos completos, incluindo os URLs de recursos do Outlook, ao autorizar a sua aplicação e ao pedir um token de acesso.
| Protocolo | Cadeia de âmbito de permissão |
|---|---|
| IMAP | https://outlook.office.com/IMAP.AccessAsUser.All |
| POP | https://outlook.office.com/POP.AccessAsUser.All |
| AUTENTICAÇÃO SMTP | https://outlook.office.com/SMTP.Send |
Além disso, pode pedir offline_access âmbito. Quando um utilizador aprova o âmbito de offline_access, a sua aplicação pode receber tokens de atualização do plataforma de identidade da Microsoft ponto final do token. Os tokens de atualização são de longa duração. A sua aplicação pode obter novos tokens de acesso à medida que os mais antigos expiram.
Em alternativa, pode utilizar o fluxo de concessão de credenciais de cliente OAuth2 para obter um token de acesso, em vez do fluxo de código de autorização OAuth2 ou do fluxo de concessão de autorização do dispositivo OAuth2.
Autenticar pedidos de ligação
Pode iniciar uma ligação para Office 365 servidores de correio com as definições de e-mail IMAP e POP para Office 365.
SASL XOAUTH2
A integração do OAuth requer que a sua aplicação utilize o formato saSL XOAUTH2 para codificar e transmitir o token de acesso. O SASL XOAUTH2 codifica o nome de utilizador e o token de acesso em conjunto no seguinte formato:
base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")
^A representa um Controlo + A (%x01).
Por exemplo, o formato de XOAUTH2 SASL para aceder 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, este formato traduz-se para a seguinte cadeia. As quebras de linha são inseridas para legibilidade.
dXNlcj10ZXN0QGNvbnRvc28ub25taWNyb3NvZnQuY29tAWF1dGg9QmVhcmVy
IEV3QkFBbDNCQUFVRkZwVUFvN0ozVmUwYmpMQldaV0NjbFJDM0VvQUEBAQ==
SaSL XOAUTH2 autenticação para caixas de correio partilhadas no Office 365
No caso de acesso de caixa de correio partilhada através do OAuth, uma aplicação tem de obter o token de acesso em nome de um utilizador, mas substituir o campo userName na cadeia codificada sasl XOAUTH2 pelo endereço de e-mail da caixa de correio partilhada.
Exchange de Protocolo IMAP
Para autenticar uma ligação de servidor IMAP, o cliente tem de responder com um AUTHENTICATE comando no seguinte formato:
AUTHENTICATE XOAUTH2 <base64 string in XOAUTH2 format>
Troca de mensagens cliente/servidor de exemplo que resulta num êxito 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.
Troca de mensagens cliente/servidor de exemplo que resulta numa falha de autenticação:
[connection begins]
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 NO AUTHENTICATE failed.
POP Protocol Exchange
Para autenticar uma ligação de servidor POP, o cliente terá de responder com um AUTH comando dividido em duas linhas no seguinte formato:
AUTH XOAUTH2
<base64 string in XOAUTH2 format>
Troca de mensagens cliente/servidor de exemplo que resulta num êxito de autenticação:
[connection begins]
C: AUTH XOAUTH2
S: +
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK User successfully authenticated.
[connection continues...]
Troca de mensagens cliente/servidor de exemplo que resulta numa falha de autenticação:
[connection begins]
C: AUTH XOAUTH2
S: +
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ=
S: -ERR Authentication failure: unknown user name or bad password.
Exchange de Protocolo SMTP
Para autenticar uma ligação de servidor SMTP, o cliente tem de responder com um AUTH comando no seguinte formato:
AUTH XOAUTH2 <base64 string in XOAUTH2 format>
Troca de mensagens cliente/servidor de exemplo que resulta num êxito de autenticação:
[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Authentication successful
[connection continues...]
Troca de mensagens cliente/servidor de exemplo que resulta numa 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]
Utilizar o fluxo de concessão de credenciais de cliente para autenticar ligações SMTP, IMAP e POP
Os principais de serviço no Exchange são utilizados para permitir que as aplicações acedam a caixas de correio do Exchange através do fluxo de credenciais de cliente com os protocolos SMTP, POP e IMAP.
Adicionar as permissões POP, IMAP ou SMTP à sua aplicação Entra AD
Na portal do Azure, selecione o painel Permissões da API na vista de gestão da aplicação Microsoft Entra.
Selecione Adicionar permissão.
Selecione as APIs que a minha organização utiliza no separador e procure "Office 365 Exchange Online".
Clique em Permissões da aplicação.
Para acesso POP, selecione POP . Permissão do AccessAsApp . Para acesso IMAP, selecione o IMAP. Permissão do AccessAsApp . Para acesso SMTP, selecione o SMTP. Permissão do SendAsApp .
Depois de escolher o tipo de permissão, selecione Adicionar permissões.
Agora, deverá ter as permissões da aplicação SMTP, POP ou IMAP adicionadas às permissões da sua aplicação Entra AD.
Obter consentimento do administrador do inquilino
Para aceder às caixas de correio do Exchange através de POP ou IMAP, a sua aplicação Entra AD tem de obter o consentimento do administrador do inquilino para cada inquilino. Para obter mais informações, veja Processo de consentimento do administrador do inquilino.
Como conceder consentimento se a aplicação estiver registada/configurada para utilização de vários inquilinos, por exemplo, para a aplicação parceira/ISV desenvolvida centralmente registada
Se o seu ISV/parceiro registou a aplicação Microsoft Entra com a opção "Contas em qualquer diretório organizacional", terá de adicionar esta aplicação e consenti-la através dos seguintes passos ao tirar partido do URL do pedido de autorização.
Orientações POP e IMAP
No seu pedido de autorização de inquilino OAuth 2.0, o scope parâmetro de consulta deve ser https://ps.outlook.com/.default para os âmbitos da aplicação POP e IMAP.
O URL do pedido de autorização do OAuth 2.0 é apresentado no exemplo seguinte:
https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://ps.outlook.com/.default
Documentação de Orientação do SMTP
No seu pedido de autorização de inquilino OAuth 2.0, o scope parâmetro de consulta deve ser https://outlook.office365.com/.default apenas para SMTP. O URL do pedido de autorização do OAuth 2.0 é apresentado no exemplo seguinte:
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 registou a aplicação para o seu próprio inquilino
Se registou a aplicação no seu próprio inquilino através de "Contas apenas neste diretório organizacional", pode avançar e utilizar a página de configuração da aplicação no centro de administração do Microsoft Entra para conceder o consentimento do administrador e não tem de utilizar a abordagem do URL do pedido de autorização.
Registar principais de serviço no Exchange
Assim que um administrador de inquilinos consentir a sua aplicação Microsoft Entra, este tem de registar o principal de serviço da sua aplicação Entra AD no Exchange através do Exchange Online PowerShell. Este registo é ativado pelo New-ServicePrincipal cmdlet .
Para utilizar o cmdlet New-ServicePrincipal , instale o ExchangeOnlineManagement e ligue-se ao seu inquilino, conforme mostrado no fragmento seguinte:
Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <tenantId>
Se continuar a receber um erro ao executar o cmdlet New-ServicePrincipal depois de executar estes passos, é provável que o utilizador não tenha permissões suficientes no Exchange Online para executar a operação.
O registo do principal de serviço de uma aplicação Microsoft Entra no Exchange é apresentado no exemplo seguinte:
New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> [-Organization <ORGANIZATION_ID>]
O administrador de inquilinos pode encontrar os identificadores do principal de serviço referenciados acima na instância da aplicação empresarial da sua aplicação Entra AD no inquilino. Pode encontrar a lista das instâncias da aplicação empresarial no inquilino no painel Aplicações empresariais na vista Microsoft Entra no Portal do Azure.
Pode obter o identificador do principal de serviço registado com o Get-ServicePrincipal cmdlet .
Get-ServicePrincipal | fl
O OBJECT_ID é o ID do Objeto na página Descrição geral do nó Aplicação Empresarial (Portal do Azure) para o registo da aplicação. Não é o ID do Objeto da página Descrição geral do nó Registos de Aplicações. A utilização do ID de Objeto incorreto causará uma falha de autenticação.
O administrador de inquilinos pode agora adicionar as caixas de correio específicas no inquilino às quais será permitido aceder pela sua aplicação. Esta configuração é feita com o Add-MailboxPermission cmdlet .
O exemplo seguinte mostra como conceder acesso ao principal de serviço da sua aplicação a uma caixa de correio:
Add-MailboxPermission -Identity "john.smith@contoso.com" -User
<SERVICE_PRINCIPAL_ID> -AccessRights FullAccess
São utilizados IDs diferentes durante a criação do principal de serviço do Exchange e, mais tarde, ao conceder permissões de caixa de correio. O exemplo seguinte pode ajudá-lo a utilizar o ID correto para as diferentes fases. Este exemplo utiliza Microsoft Entra cmdlets; por isso, terá de instalar o Microsoft Entra módulo do PowerShell, caso ainda não o tenha feito. Para obter mais informações, veja Install Microsoft Entra PowerShell for Graph (Instalar o 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
A sua aplicação Microsoft Entra pode agora aceder às caixas de correio permitidas através dos protocolos SMTP, POP ou IMAP com o fluxo de concessão de credenciais de cliente OAuth 2.0. Para obter mais informações, veja as instruções em Permissões e consentimento no plataforma de identidade da Microsoft.
Tem de utilizar https://outlook.office365.com/.default na scope propriedade no payload do corpo para o pedido de token de acesso.
Os tokens de acesso gerados podem ser utilizados como tokens para autenticar ligações SMTP, POP e IMAP através de SASL XOAUTH2 formato, conforme descrito anteriormente.
Observação
Se estiver a tentar utilizar o Fluxo de Concessão de Credenciais de Cliente com SendAs, terá de conceder permissões SendAs ao remetente: Add-RecipientPermission (ExchangePowerShell).