Проверка подлинности OneNote и разрешения для приложений Azure AD
Область применения: корпоративные записные книжки в Office 365
Проверка подлинности с использованием Azure AD (корпоративные приложения)
- Регистрация приложения и получение идентификатора клиента и секрета
- Выбор области разрешений приложения OneNote
- Получение согласия администратора
- Получение маркера доступа
- Получение нового маркера доступа после истечения срока действия предыдущего
Зарегистрируйте ваше приложение и получите идентификатор клиента и секрет (корпоративные приложения)
См. раздел Регистрация приложения и получение идентификатора клиента и секрета.
Выбор области разрешений приложения OneNote (корпоративные приложения)
Области разрешений представляют уровни доступа к содержимому OneNote. Разрешение приложения предоставляется приложению администратором организации и может использоваться только для доступа к данным, принадлежащим этой организации и ее сотрудникам. Например, OneNote API предоставляет несколько разрешений приложениям для выполнения следующих действий:
- Просмотр заметок для всех пользователей
- Просмотр и изменение заметок для всех пользователей
Выполните следующие действия, чтобы назначить разрешения OneNote для вашего приложения:
На Портале управления Azure в разделе Разрешения для других приложений страницы настройки приложения выберите Добавить приложение.
Выберите приложение OneNote, а затем установите флажок в правом нижнем углу. Если OneNote отсутствует в списке, убедитесь, что вы указали в качестве клиента OneDrive для бизнеса.
Выберите самый низкий уровень разрешений, которые необходимы вашему приложению для функционирования, и сохраните изменения. Вы можете сделать запрос для нескольких областей.
Области для разрешений приложений
Если вы обращаетесь к записным книжкам с разрешениями приложений, выберите одну из следующих областей.
| Область (корпоративная) | Разрешение на портале Azure | Описание |
|---|---|---|
| Notes.Read.All | Просмотр заметок для всех пользователей | Позволяет приложению просматривать заметки OneNote всех пользователей вашей организации без выполнения входа пользователя. Приложение не может создавать новые заметки, изменять существующие или просматривать заметки в разделах, защищенных паролем. |
| Notes.ReadWrite.All | Просмотр и изменение заметок для всех пользователей | Позволяет приложению просматривать и редактировать заметки OneNote всех пользователей вашей организации без выполнения входа пользователя. Приложение не получает доступ к заметкам в разделах, защищенных паролем. |
Получение согласия администратора
Рекомендуем обеспечить выполнение входа пользователя в ваше приложение
Как правило, при создании приложения, использующего разрешения приложения, требуется страница или представление, где администратор сможет утвердить разрешения приложения. Эта страница может быть частью потока входа в приложение, настроек приложения или может быть выделенным потоком "подключения". Во многих случаях может быть целесообразно показать это представление ("подключение") только после того, как пользователь выполнит вход в систему с рабочей или учебной учетной записью Майкрософт.
Если пользователь выполнит вход в приложение, вы сможете определить организацию, к которой принадлежит пользователь, прежде чем вы попросите пользователя утвердить разрешения приложения. Хоть в этом и нет строгой необходимости, это может сделать приложение более интуитивным для ваших пользователей. Чтобы обеспечить пользователю вход, следуйте нашим руководствам по протоколам версии 2.0.
Запрос разрешений у администратора каталога
Когда вы будете готовы запросить разрешения у администратора организации, вы можете перенаправить пользователя к конечной точке согласия администратора. Можно сделать вызов API, включая следующие:
// Line breaks are for legibility only.
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={app_id}
&state=12345
&redirect_uri=https://localhost/myapp/permissions
Вы также можете испытать действие вышеуказанного запроса в веб-обозревателе, введя следующий URL-адрес в адресную строку вашего веб-обозревателя (введите действующий URL-адрес в соответствии с инструкциями ниже).
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app_id}&state=12345&redirect_uri=https://localhost/myapp/permissions
В этой таблице описаны параметры, используемые в предыдущем запросе:
| Параметр | Условие | Описание |
|---|---|---|
| клиент | Обязательный | Клиент каталога, у которого вы хотите запросить разрешение. Имя может быть в понятном или GUID-формате. Если вы не знаете, какому клиенту принадлежит пользователь, и вы хотите разрешить ему вход с любым клиентом, используйте common (общий). |
| client_id | Обязательный | Идентификатор приложения, назначенный порталом регистрации приложений. |
| redirect_uri | Обязательный | URI перенаправления, на который должен отправляться ответ для обработки приложением. Он должен в точности совпадать с одним из URI перенаправления, зарегистрированных на портале, и быть закодирован как URL-адрес. Может содержать дополнительные сегменты пути. |
| состояние | Рекомендуемый | Значение, которое включается в запрос и возвращается в ответе с маркером. Это может быть строка с любым содержимым. Параметр state используется для кодирования сведений о состоянии пользователя в приложении до запрашивания проверки подлинности, например о просматриваемых странице и представлении. |
Вам будет представлен диалог согласия администратора, который вы можете утвердить.
Успешный ответ
Если администратор утверждает разрешения для приложения, успешный ответ выглядит так:
GET https://login.microsoftonline.com/{tenant}/Consent/Grant
В этой таблице описываются значения, возвращаемые в предыдущем ответе:
| Параметр | Описание |
|---|---|
| клиент | Клиент каталога, который предоставил приложению запрашиваемые разрешения, в формате GUID. |
Сообщение об ошибке
Если администратор не утверждает разрешения для вашего приложения, отрицательный ответ выглядит следующим образом:
GET https://login.microsoftonline.com/{tenant}/login
Additional technical information:
Correlation ID: f3817dd1-8476-46c2-a81b-fdefd209f988
Timestamp: 2017-01-18 05:36:57Z
AADSTS90093: This operation can only be performed by an administrator. Sign out and sign in as an administrator or contact one of your organization's administrators.
В этой таблице описываются значения, возвращаемые в предыдущем ответе:
| Параметр | Описание |
|---|---|
| клиент | Клиент каталога, который предоставил приложению запрашиваемые разрешения, в формате GUID. |
После того, как вы получили успешный ответ от конечной точки подготовки приложения, ваше приложение получает прямые разрешения, которые оно запрашивало. Теперь вы можете запросить маркер для нужного вам ресурса.
Примечание
- Согласие администратора — разовый шаг для конкретного клиента.
- Если необходимо, чтобы приложение запустило клиентов .her, необходимо настроить его в качестве приложения нескольких развертываний в Azure AD.
- Независимо от того, работает ли приложение на собственном или другом клиенте, согласие администратора является необходимым шагом
- Приложению позволено делегировать разрешения в дополнение к разрешениям приложений (однако согласие администратора по-прежнему необходимо).
Получение маркера доступа (корпоративные приложения)
После прохождения необходимой авторизации для приложения вы можете приступить к получению маркеров доступа для API.
Для получения маркера с использованием учетных данных клиента отправьте запрос POST в соответствии с примером ниже:
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
// Replace {app_secret} with an Azure AD generated key for your application
POST https://login.microsoftonline.com/{tenant}/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&resource=https%3A%2F%2Fonenote.com%2F
В этой таблице описаны параметры, используемые в предыдущем запросе:
| Параметр | Условие | Описание |
|---|---|---|
| grant_type | Обязательный | Должно быть задано значение client_credentials. |
| client_id | Обязательный | Идентификатор приложения, назначенный порталом регистрации приложений. |
| client_secret | Обязательный | Секрет приложения, созданный на портале регистрации приложений. Очень важно, чтобы этот URL-адрес был зашифрован |
| resource | Обязательный | Значение, передаваемое параметру resource этого запроса, должно представлять собой идентификатор (URI ИД приложения) нужного ресурса. Для API OneNote используется значение https://onenote.com/. Это значение сообщает конечной точке маркера, что из всех прямых разрешений приложения следует выдать маркер для тех, которые связаны с нужным ресурсом. |
Успешный ответ
Успешный ответ выглядит так:
{
"token_type": "Bearer",
"expires_in": "3600",
"resource": "https:\/\/onenote.com\/",
"access_token": "eyJ0eXAiOiJKV1Qi..."
}
В этой таблице описаны параметры, используемые в предыдущем запросе:
| Параметр | Описание |
|---|---|
| token_type | Указывает значение типа маркера. Azure AD поддерживает только тип bearer. |
| expires_in | Срок действия маркера доступа (в секундах). |
| resource | Идентификатор ресурса (URI ИД приложения), с которым может использоваться этот маркер. |
| access_token | Запрошенный маркер доступа. Приложение может использовать этот маркер для проверки подлинности защищенного ресурса, например, веб-API. |
Сообщение об ошибке
Ответ с ошибкой выглядит так (в этом примере в запросе указано недопустимое значение для client_secret):
{
"error": "invalid_client",
"error_description": "AADSTS70002: Error validating credentials. AADSTS50012: Invalid client secret is provided.\r\nTrace ID: b6e89947-f005-469e-92ad-18aed399b140\r\nCorrelation ID: c2d1c230-bee9-41f1-9d4d-a5687e01b7bc\r\nTimestamp: 2017-01-19 20:34:11Z",
"error_codes": [
70002,
50012
],
"timestamp": "2017-01-19 20:34:11Z",
"trace_id": "b6e89947-f005-469e-92ad-18aed399b140",
"correlation_id": "c2d1c230-bee9-41f1-9d4d-a5687e01b7bc"
}
В этой таблице описаны параметры, используемые в предыдущем запросе:
| Параметр | Описание |
|---|---|
| error | Строка кода ошибки, которую вы можете использовать для классификации типов ошибок и реагирования на ошибки. |
| error_description | Конкретное сообщение об ошибке, которое может помочь вам определить основную причину ошибки проверки подлинности. |
| error_codes | Список кодов ошибок, специфичных для STS, которые могут помочь при диагностике. |
| timestamp | Время возникновения ошибки. |
| trace_id | Уникальный идентификатор запроса, который может помочь при диагностике. |
| correlation_id | Уникальный идентификатор запроса, который может помочь при диагностике компонентов. |
Включите маркер доступа в свой запрос к API OneNote
Все ваши запросы к API OneNote должны отправлять маркер доступа в качестве маркера носителя в заголовке Authorization. Например, следующий запрос получает пять ваших записных книжек, отсортированных в алфавитном порядке по имени:
GET https://www.onenote.com/api/v1.0/users/foo@example.com/notes/notebooks?top=5
Authorization: Bearer {access-token}
Маркеры доступа действительны в течение только одного часа, поэтому вам нужно будет получить новые маркеры, когда срок предыдущих истечет. Вам нужно проверить срок действия маркера перед его использованием и получить новый при необходимости. Администраторы не должны повторно выдавать разрешения, если они не отзывали выданные ранее.
Получение нового маркера доступа после истечения его срока действия (корпоративные приложения)
Если срок действия маркера доступа истек, запросы к API будут возвращать ответ 401 Unauthorized. Ваше приложение должно обработать этот ответ и проверить срок действия маркера перед отправкой запросов.
Вы можете запросить новый маркер доступа, повторив процесс, описанный в разделе Получение маркера доступа этой статьи.
Обновите сохраненные маркеры, чтобы убедиться, что у вашего приложения есть маркеры с максимальным сроком действия.
Ошибки
Если возникнут ошибки, связанные с проверкой подлинности, веб-браузер будет перенаправлен на страницу ошибки. На странице ошибки отображается сообщение, понятное для пользователя, однако URL-адрес страницы ошибки содержит дополнительные сведения, которые могут помочь вам в отладке кода, выполнение которого привело к ошибке. Параметры URL-адреса включены в качестве закладки, например: #error={error_code}&error_description={message}
Если администратор не предоставит согласие на ваше приложение, поток будет перенаправлен на ваш URL-адрес переадресации и будет включать параметры ошибки.
Для ознакомления с более подробными сведениями об обработке ошибок см. статью Обработка ошибок в OAuth 2.0.