Аутентификация и вход в OneDrive
Использование Microsoft Graph
В этой статье рассказывается о том, как выполнить авторизацию приложения с использованием учетных записей Майкрософт для OneDrive персональный. Этот подход больше не является рекомендуемым. Новые приложения следует разрабатывать с использованием Microsoft Graph и процесса авторизации, описанного в статье Авторизация и вход в систему для OneDrive в Microsoft Graph.
Начало работы
Чтобы использовать API OneDrive, вам потребуется маркер доступа, выполняющий аутентификацию приложения и предоставляющий определенный набор разрешений для пользователя. Из этого раздела вы узнаете, как:
- зарегистрировать приложение, чтобы получить идентификатор и секрет клиента;
- обеспечить вход пользователя в OneDrive с указанными областями, используя поток маркеров или поток кода;
- обеспечить выход пользователя (необязательно).
Для аутентификации пользователей и создания маркеров доступа в API OneDrive используется стандартная схема аутентификации OAuth 2.0. Вам потребуется отправлять маркер доступа для каждого вызова API в одном из указанных ниже элементов.
- Заголовок HTTP:
Authorization: bearer {token}
Регистрация приложения
Чтобы приложение могло пройти аутентификацию, вам потребуется зарегистрировать его в корпорации Майкрософт и указать некоторые сведения о нем.
Регистрация приложения
Сведения о регистрации приложения для API OneDrive см. в этой статье.
Вход пользователей
Приложение должно запустить процесс входа, связавшись с веб-службой авторизации учетных записей Майкрософт с указанной областью, и получить маркер доступа. Поток соответствует стандартным потокам аутентификации OAuth 2.0, и для него необходимы вызовы из веб-браузера или элемента управления в веб-браузере.
Области аутентификации
Области определяют тип доступа, который будет предоставлен приложению после входа пользователя. Все области поддерживают технологию единого входа в Интернете. Это означает, что если пользователь уже вошел в OneDrive, то он может пропустить поток аутентификации и перейти непосредственно к потоку авторизации.
| Имя области | Описание | Обязательная |
|---|---|---|
| offline_access | Позволяет приложению работать в автономном режиме, даже если пользователь неактивен. Предоставляет приложению маркер обновления, с помощью которого можно создавать дополнительные маркеры доступа по мере необходимости. Эта область недоступна для потока маркеров. | Нет |
| onedrive.readonly | Предоставляет разрешение только на чтение всех файлов пользователя в OneDrive, в том числе файлов, к которым пользователю предоставлен доступ. | Да |
| onedrive.readwrite | Предоставляет разрешение на чтение и изменение всех файлов пользователя в OneDrive, в том числе файлов, к которым пользователю предоставлен доступ. Эта область необходима для создания ссылок для общего доступа. | Да |
| onedrive.appfolder | Предоставляет приложению разрешения на чтение и запись в определенной папке. | Да |
Например, типичное приложение может запрашивать следующие области:
onedrive.readwrite offline_access
Поддерживаемые потоки аутентификации
Вы можете выбрать один из двух поддерживаемых потоков аутентификации:
Поток маркеров
Самый простой поток аутентификации — это поток маркеров. С помощью этого потока можно быстро и удобно получить маркер доступа, что позволяет использовать API OneDrive в интерактивном режиме. Этот поток не предоставляет маркер обновления, поэтому его невозможно использовать для долгосрочного доступа к API OneDrive.
Чтобы запустить процесс входа с использованием потока маркеров, загрузите URL-запрос с помощью веб-браузера или элемента управления веб-браузера.
GET https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope}
&response_type=token&redirect_uri={redirect_uri}
Обязательные параметры строки запроса
| Имя параметра | Значение | Описание |
|---|---|---|
| client_id | строка | Идентификатор клиента, созданный для приложения. |
| redirect_uri | string | URL-адрес, на который перенаправляется браузер после аутентификации. |
| response_type | string | Тип ответа, ожидаемого от потока авторизации. Для этого потока значение должно представлять собой маркер. |
| scope | строка | Разделенный пробелами список областей, необходимых приложению. |
Для мобильных и классических приложений используйте следующий URL-адрес перенаправления: https://login.live.com/oauth20_desktop.srf.
Ответ
После успешной аутентификации и авторизации приложения веб-браузер будет перенаправлен на ваш URL-адрес перенаправления, причем этот адрес будет включать дополнительные параметры.
https://login.live.com/oauth20_authorize.srf#access_token=EwC...EB
&authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600
&scope=onedrive.readwrite&user_id=3626...1d
В предыдущем примере значения свойств access_token, authentication_token и user_id усечены. Значения свойств access_token и authentication_token довольно длинные.
Вы можете использовать значение параметра access_token для отправки запросов к API OneDrive.
Поток кода
Поток кода для аутентификации представляет собой трехэтапный процесс с отдельными вызовами для аутентификации и авторизации приложения и для создания маркера доступа, необходимого для использования API OneDrive. Это позволяет вашему приложению получать маркер обновления. Благодаря этому маркеру в ряде сценариев можно использовать API на долгосрочной основе, когда пользователь не очень активно использует приложение.
Шаг 1. Получение кода авторизации
Чтобы запустить процесс входа в систему с использованием потока кода, загрузите этот URL-запрос с помощью веб-браузера или элемента управления веб-браузера.
GET https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope}
&response_type=code&redirect_uri={redirect_uri}
Обязательные параметры строки запроса
| Имя параметра | Значение | Описание |
|---|---|---|
| client_id | string | Идентификатор клиента, созданный для приложения. |
| scope | строка | Разделенный пробелами список областей, необходимых приложению. |
| redirect_uri | string | URL-адрес, на который перенаправляется браузер после аутентификации. |
| response_type | string | Тип ответа, ожидаемого от потока авторизации. Для этого потока значение должно представлять собой код. |
Ответ
После успешной аутентификации и авторизации приложения веб-браузер будет перенаправлен на ваш URL-адрес перенаправления, причем этот адрес будет включать дополнительные параметры.
https://login.live.com/oauth20_authorize.srf?code=df6aa589-1080-b241-b410-c4dff65dbf7c
Этап 2. Активация кода для получения маркеров доступа
Получив значение code, вы сможете активировать этот код и получить набор маркеров, с помощью которых можно выполнить аутентификацию в API OneDrive. Чтобы активировать код, создайте приведенный ниже запрос.
POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&code={code}&grant_type=authorization_code
Обязательные параметры в тексте запроса
Текст запроса представляет собой правильно закодированную строку URL-адреса с несколькими обязательными параметрами.
| Имя параметра | Значение | Описание |
|---|---|---|
| client_id | строка | Идентификатор клиента, созданный для приложения. |
| redirect_uri | string | URL-адрес, на который перенаправляется браузер после аутентификации. Это значение должно совпадать со значением redirect_uri в первом запросе. |
| client_secret | строка | Секрет клиента, созданный для вашего приложения. |
| code | строка | Код авторизации, который вы получили в первом запросе на аутентификацию. |
Примечание Для веб-приложений доменная часть URI перенаправления должна соответствовать доменной части URI перенаправления, указанной в Центре разработчиков учетной записи Майкрософт.
Ответ
При успешном выполнении вызова ответ на запрос POST содержит строку JSON, включающую несколько свойств, в том числе access_token, token_type и refresh_token (если вы запросили область wl.offline_access).
{
"token_type":"bearer",
"expires_in": 3600,
"scope":"wl.basic onedrive.readwrite",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Теперь вы можете сохранить и использовать access_token, предназначенный для отправки запросов с проверкой подлинности к API OneDrive.
Важно! Храните значения access_token и refresh_token, полученные в этом ответе, так же надежно, как пароль пользователя.
Маркер доступа действует в течение времени, указанного в свойстве expires_in (в секундах). Вы можете запросить новый маркер доступа, используя маркер обновления (если он доступен) либо заново запросив аутентификацию.
Этап 3. Получение нового маркера доступа или маркера обновления
Если ваше приложение запросило доступ к wl.offline_access, то в этом действии будет возвращен маркер refresh_token, который можно использовать для создания дополнительных маркеров доступа по истечении срока действия исходного маркера.
Чтобы активировать маркер обновления и получить новый маркер доступа, отправьте приведенный ниже запрос.
POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&refresh_token={refresh_token}&grant_type=refresh_token
Обязательные параметры в тексте запроса
Текст запроса представляет собой правильно закодированную строку URL-адреса с несколькими обязательными параметрами.
| Имя параметра | Значение | Описание |
|---|---|---|
| client_id | string | Идентификатор клиента, созданный для приложения. |
| redirect_uri | string | URL-адрес, на который перенаправляется браузер после проверки подлинности. Это значение должно соответствовать значению redirect_uri, использованному в первом запросе. |
| client_secret | строка | Секрет клиента, созданный для вашего приложения. |
| refresh_token | string | Маркер обновления, который вы получили ранее. |
Примечание Для веб-приложений доменная часть URI перенаправления должна соответствовать доменной части URI перенаправления, указанной на сайте управления приложениями Live SDK.
Ответ
При успешном выполнении вызова ответ на запрос POST содержит строку JSON, включающую несколько свойств, в том числе access_token, authentication_token и refresh_token (если вы запросили область wl.offline_access).
{
"token_type":"bearer",
"expires_in": 3600,
"scope": "wl.basic onedrive.readwrite wl.offline_access",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Теперь вы можете сохранить и использовать access_token для отправки запросов с проверкой подлинности к API OneDrive.
Важно! Храните значения access_token и refresh_token, полученные в этом ответе, так же надежно, как пароль пользователя.
Маркер доступа действует в течение времени, указанного в свойстве expires_in (в секундах). Вы можете запросить новый маркер доступа, используя маркер обновления (если он доступен) либо заново запросив аутентификацию.
Выход пользователя
Чтобы выполнить выход для пользователя, выполните указанные ниже действия.
- Удалите все кэшированные значения
access_tokenилиrefresh_token, которые вы получили ранее из потока OAuth. - Выполните необходимые действия по выходу из системы в своем приложении (например, очистку локального состояния, удаление всех элементов из кэша и т. д.).
- Вызовите веб-службу авторизации, используя следующий URL-адрес:
GET https://login.live.com/oauth20_logout.srf?client_id={client_id}&redirect_uri={redirect_uri}
При этом будут удалены все файлы cookie, позволяющие выполнить единый вход. Это гарантирует, что когда ваше приложение в следующий раз запустит процесс входа, пользователю придется снова ввести имя и пароль.
Обязательные параметры строки запроса
| Имя параметра | Значение | Описание |
|---|---|---|
| client_id | строка | Идентификатор клиента, созданный для приложения. |
| redirect_uri | string | URL-адрес, на который перенаправляется браузер после аутентификации. Он должен точно совпадать со значением redirect_uri, используемым в запросе маркера. |
После удаления файла cookie браузер будет перенаправлен на указанный вами URL-адрес перенаправления. Когда браузер загрузит страницу перенаправления, параметры запроса аутентификации не будут заданы, из чего можно сделать вывод, что пользователь вышел из системы.
Отмена доступа
Пользователь может отменить доступ приложения к своей учетной записи на странице предоставления согласия на управление учетной записью Майкрософт.
При отмене согласия для приложения все маркеры обновления, ранее предоставленные ему, становятся недействительными. Вам потребуется повторить поток аутентификации, чтобы заново запросить новые маркер доступа и маркер обновления.
Ошибки
Если возникнет ошибка аутентификации, веб-браузер будет перенаправлен на страницу ошибки. На странице ошибки всегда отображается сообщение, понятное для пользователя. Кроме того, URL-адрес страницы ошибки содержит дополнительные сведения, которые могут помочь вам при отладке кода, выполнение которого привело к ошибке. Эти сведения не всегда отображаются на странице ошибки в браузере.
https://login.live.com/err.srf?lc=1033#error={error_code}&error_description={message}
URL-адрес включает параметры запроса, которые помогут вам проанализировать ошибку и принять соответствующие меры. Эти параметры всегда включаются как закладки (после символа #). На странице всегда отображается сообщение с общими сведениями об ошибке для пользователя.
Если пользователь не предоставит свое согласие вашему приложению, поток выполнит перенаправление на ваш URI перенаправления и включит те же параметры ошибки.
Параметры ошибок
| Имя параметра | Значение | Описание |
|---|---|---|
| error | строка | Код возникшей ошибки. |
| error_description | строка | Описание ошибки. |
Похожие темы
В указанных ниже статьях содержатся общие сведения о других понятиях, применимых к API OneDrive.