Проверка подлинности подключения IMAP, POP или SMTP с помощью OAuth

  • Статья

Узнайте, как использовать проверку подлинности OAuth для подключения по протоколам IMAP, POP или SMTP и доступа к данным электронной почты для Office 365 пользователей.

Поддержка протоколов IMAP, POP и SMTP oAuth2, как описано ниже, доступна как для пользователей Microsoft 365 (которая включает Office в Интернете), так и для пользователей Outlook.com.

Важно!

В этой документации используется устаревшая область REST API Outlook. Новые приложения должны использовать конечную точку REST API Graph .

Если вы не знакомы с протоколом OAuth 2.0, см. статью Протокол OAuth 2.0 на платформа удостоверений Майкрософт обзор. Дополнительные сведения о библиотеках проверки подлинности Майкрософт (MSAL), которые реализуют протокол OAuth 2.0 для проверки подлинности пользователей и доступа к защищенным API, см. в статье Обзор MSAL.

Вы можете использовать службу проверки подлинности OAuth, предоставляемую Microsoft Entra (Microsoft Entra), чтобы разрешить приложению подключаться по протоколам IMAP, POP или SMTP для доступа к Exchange Online в Office 365. Чтобы использовать OAuth с приложением, необходимо:

  1. Зарегистрируйте приложение с помощью Microsoft Entra.
  2. Получение маркера доступа с сервера маркеров.
  3. Проверка подлинности запросов на подключение с помощью маркера доступа.

Регистрация приложения

Чтобы использовать OAuth, приложение должно быть зарегистрировано в Microsoft Entra.

Следуйте инструкциям, приведенным в разделе Регистрация приложения с помощью платформа удостоверений Майкрософт, чтобы создать новое приложение.

Получение токена доступа

Для получения маркера доступа из клиентского приложения можно использовать одну из клиентских библиотек MSAL .

Кроме того, можно выбрать соответствующий поток из следующего списка и выполнить соответствующие действия, чтобы вызвать rest API базовой платформы удостоверений и получить маркер доступа.

  1. Поток кода авторизации OAuth2
  2. Поток предоставления авторизации устройства OAuth2
  3. Поток предоставления учетных данных клиента OAuth2

Обязательно укажите полные области, включая URL-адреса ресурсов Outlook, при авторизации приложения и запросе маркера доступа.

Протокол Строка область разрешений
IMAP https://outlook.office.com/IMAP.AccessAsUser.All
POP https://outlook.office.com/POP.AccessAsUser.All
ПРОВЕРКА ПОДЛИННОСТИ SMTP https://outlook.office.com/SMTP.SendAsApp

Кроме того, можно запросить offline_access область. Когда пользователь утверждает offline_access область, приложение может получать маркеры обновления из конечной точки маркера платформа удостоверений Майкрософт. Маркеры обновления являются долгосрочными. Приложение может получать новые маркеры доступа по мере истечения срока действия старых.

Проверка подлинности запросов на подключение

Подключение к почтовым серверам Office 365 можно инициировать с помощью параметров электронной почты IMAP и POP для Office 365.

SASL XOAUTH2

Интеграция OAuth требует, чтобы ваше приложение использовало SASL XOAUTH2 формат для кодирования и передачи маркера доступа. SASL XOAUTH2 кодирует имя пользователя и маркер доступа в следующем формате:

base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")

^A представляет элемент управления + A (%x01).

Например, sasl XOAUTH2 формат для доступа test@contoso.onmicrosoft.com с помощью маркера EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA доступа:

base64("user=test@contoso.onmicrosoft.com^Aauth=Bearer EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA^A^A")

После кодирования base64 этот формат преобразуется в следующую строку. Разрывы строк вставляются для удобства чтения.

dXNlcj10ZXN0QGNvbnRvc28ub25taWNyb3NvZnQuY29tAWF1dGg9QmVhcmVy
IEV3QkFBbDNCQUFVRkZwVUFvN0ozVmUwYmpMQldaV0NjbFJDM0VvQUEBAQ==

Проверка подлинности SASL XOAUTH2 для общих почтовых ящиков в Office 365

В случае доступа к общему почтовому ящику с помощью OAuth приложение должно получить маркер доступа от имени пользователя, но заменить поле userName в SASL XOAUTH2 закодированную строку адресом электронной почты общего почтового ящика.

Обмен протоколами IMAP

Для проверки подлинности подключения IMAP-сервера клиент должен ответить командой AUTHENTICATE в следующем формате:

AUTHENTICATE XOAUTH2 <base64 string in XOAUTH2 format>

Пример обмена сообщениями между клиентом и сервером, который приводит к успешной проверке подлинности:

[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 OK AUTHENTICATE completed.

Пример обмена сообщениями между клиентом и сервером, который приводит к сбою проверки подлинности:

[connection begins]
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 NO AUTHENTICATE failed.

Обмен протоколами POP

Для проверки подлинности подключения POP-сервера клиенту потребуется ответить командой, разделенной AUTH на две строки в следующем формате:

AUTH XOAUTH2 
<base64 string in XOAUTH2 format>

Пример обмена сообщениями между клиентом и сервером, который приводит к успешной проверке подлинности:

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

Пример обмена сообщениями между клиентом и сервером, который приводит к сбою проверки подлинности:

[connection begins] 
C: AUTH XOAUTH2  
S: + 
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY 
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj 
l0Q2cBAQ= 
S: -ERR Authentication failure: unknown user name or bad password.

Обмен протоколами SMTP

Чтобы проверить подлинность подключения SMTP-сервера, клиент должен ответить командой AUTH в следующем формате:

AUTH XOAUTH2 <base64 string in XOAUTH2 format>

Пример обмена сообщениями между клиентом и сервером, который приводит к успешной проверке подлинности:

[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Authentication successful
[connection continues...]

Пример обмена сообщениями между клиентом и сервером, который приводит к сбою проверки подлинности:

[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 535 5.7.3 Authentication unsuccessful [SN2PR00CA0018.namprd00.prod.outlook.com]

Использование потока предоставления учетных данных клиента для проверки подлинности подключений SMTP, IMAP и POP

Субъекты-службы в Exchange используются для предоставления приложениям доступа к почтовым ящикам Exchange через поток учетных данных клиента с протоколами SMTP, POP и IMAP.

Добавление разрешений POP, IMAP или SMTP в приложение Entra AD

  1. В портал Azure выберите колонку Разрешения API в представлении управления приложения Microsoft Entra.

  2. Выберите Добавить разрешение.

  3. Выберите вкладку API, которые использует моя организация, и найдите "Office 365 Exchange Online".

  4. Щелкните Разрешения приложения.

  5. Для доступа по протоколу POP выберите pop. Разрешение AccessAsApp . Для доступа по протоколу IMAP выберите IMAP. Разрешение AccessAsApp . Для доступа ПО SMTP выберите SMTP. Разрешение SendAsApp .

    pop-imap-permission

  6. Выбрав тип разрешения, выберите Добавить разрешения.

Теперь к разрешениям приложения Entra AD должны быть добавлены разрешения smtp, POP или IMAP.

Чтобы получить доступ к почтовым ящикам Exchange по протоколу POP или IMAP, приложение Entra AD должно получить согласие администратора клиента для каждого клиента. Дополнительные сведения см. в разделе Процесс предоставления согласия администратора клиента.

Если ваш поставщик программного обеспечения или партнер зарегистрировали приложение Microsoft Entra с параметром "Учетные записи в любом каталоге организации", необходимо добавить это приложение и согласиться на него, выполнив следующие действия, используя URL-адрес запроса на авторизацию.

Руководство по POP и IMAP

В запросе scope на авторизацию клиента OAuth 2.0 параметр запроса должен быть https://ps.outlook.com/.default для областей приложений POP и IMAP. URL-адрес запроса авторизации OAuth 2.0 показан в следующем примере:

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://ps.outlook.com/.default
Руководство по SMTP

В запросе scope на авторизацию клиента OAuth 2.0 параметр запроса должен быть https://outlook.office365.com/.default только для SMTP. URL-адрес запроса авторизации OAuth 2.0 показан в следующем примере:

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://outlook.office365.com/.default

Если вы зарегистрировали приложение в собственном клиенте с помощью "Учетные записи только в этом каталоге организации", вы можете перейти вперед и использовать страницу конфигурации приложения в Центр администрирования Microsoft Entra, чтобы предоставить согласие администратора, и вам не нужно использовать URL-адрес запроса на авторизацию.

granting-consent-for-tenant

Регистрация субъектов-служб в Exchange

После того как администратор клиента согласится на Microsoft Entra приложение, он должен зарегистрировать субъект-службу приложения Entra AD в Exchange с помощью Exchange Online PowerShell. Эта регистрация включается командлетомNew-ServicePrincipal .

Чтобы использовать командлет New-ServicePrincipal , установите ExchangeOnlineManagement и подключитесь к клиенту, как показано в следующем фрагменте кода:

Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement 
Connect-ExchangeOnline -Organization <tenantId>

Если после выполнения этих действий по-прежнему возникает ошибка при выполнении командлета New-ServicePrincipal , скорее всего, это связано с тем, что у пользователя недостаточно разрешений в Exchange Online для выполнения операции.

Регистрация субъекта-службы приложения Microsoft Entra в Exchange показана в следующем примере:

New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> [-Organization <ORGANIZATION_ID>]

Администратор клиента может найти указанные выше идентификаторы субъекта-службы в экземпляре корпоративного приложения Entra AD в клиенте. Список экземпляров корпоративных приложений в клиенте можно найти в колонке Корпоративные приложения в представлении Microsoft Entra на портале Azure.

Идентификатор зарегистрированного субъекта-службы можно получить с помощью командлетаGet-ServicePrincipal .

Get-ServicePrincipal | fl

OBJECT_ID — это идентификатор объекта на странице Обзор узла Корпоративное приложение (портал Azure) для регистрации приложения. Это не идентификатор объекта со страницы Обзор узла Регистрация приложений. Использование неправильного идентификатора объекта приведет к сбою проверки подлинности.

Теперь администратор клиента может добавить в клиент определенные почтовые ящики, доступ к которым будет разрешен вашему приложению. Эта настройка выполняется с помощью командлетаAdd-MailboxPermission .

В следующем примере показано, как предоставить субъекту-службе приложения доступ к одному почтовому ящику:

Add-MailboxPermission -Identity "john.smith@contoso.com" -User 
<SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

Различные идентификаторы используются при создании субъекта-службы Exchange, а также позже при предоставлении разрешений для почтового ящика. Следующий пример может помочь вам использовать правильный идентификатор для различных этапов. В этом примере используются командлеты Microsoft Entra. Поэтому вам потребуется установить Microsoft Entra модуль PowerShell, если вы еще этого не сделали. Дополнительные сведения см. в статье Установка Microsoft Entra PowerShell для 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

Теперь приложение Microsoft Entra может получить доступ к разрешенным почтовым ящикам по протоколам SMTP, POP или IMAP, используя поток предоставления учетных данных клиента OAuth 2.0. Дополнительные сведения см. в разделе Разрешения и согласие в платформа удостоверений Майкрософт.

Необходимо использовать https://outlook.office365.com/.default в свойстве scope в полезных данных основного текста для запроса маркера доступа.

Созданные маркеры доступа можно использовать в качестве маркеров для проверки подлинности подключений SMTP, POP и IMAP через SASL XOAUTH2 формате, как описано ранее.

См. также