Плюсофон OAuth¶
OAuth — открытый протокол авторизации, который позволяет предоставить третьей стороне ограниченный доступ к защищённым ресурсам пользователя без необходимости передавать ей (третьей стороне) логин и пароль.
Разработчики должны зарегистрировать свое приложение, чтобы использовать oauth. Зарегистрированному приложению присваивается идентификатор клиента и секретный ключ. Секретный ключ клиента должен храниться в тайне и использоваться только между приложением и сервером авторизации Плюсофон.
Авторизация для приложений, имеющих серверную часть¶
Это самый сложный вариант авторизации, но только он позволяет сервису однозначно установить приложение, обращающееся за авторизацией. Во всех остальных вариантах авторизация происходит полностью на клиенте и по понятным причинам возможна маскировка одного приложения под другое. Это стоит учитывать при внедрении OAuth-аутентификации в API сервисов.
Шаг 1. Авторизация пользователя.
Дать пользователю ссылку на авторизацию, которая перенаправляет пользователя на Плюсофон с дополнительными URL параметрами:
https://login.plusofon.ru/authorize
Параметры, которые необходимо передать в URL:
| Параметр | Описание |
|---|---|
| client_id | ID приложения |
| redirect_uri | URL-адрес, на который пользователи будут отправлены после авторизации |
| response_type | Должен иметь значение «code» |
Пример:
https://login.plusofon.ru/authorize?response_type=code&client_id=1001&redirect_uri=https://example.com/callback
Шаг 2. Получение токена доступа.
После того, как пользователь авторизовался, происходит редирект на указанный redirect_uri с дополнительным параметром «code»: https://example.com/callback?code=authCode.
Полученный код используется для получения токена доступа путем отправки POST запроса на URL: https://login.plusofon.ru/token.
Параметры:
| Параметр | Описание |
|---|---|
| client_id | ID приложения |
| grant_type | Должен иметь значение «authorization_code» |
| code | Код, полученный на шаге 1 |
| client_secret | Секретный ключ приложения |
Ответ в формате JSON будет содержать следующие данные:
| Параметр | Описание |
|---|---|
| access_token | Токен доступа |
| token_type | Тип ключа |
| expires_in | Время «протухания» токена |
| refresh_token | Токен восстановление предыдущей авторизации |
Авторизация полностью клиентских приложений¶
Этот вариант требует поднятия в приложении окна браузера, но не требует серверной части и дополнительного вызова сервер-сервер для обмена authorization code на access token. Это полезно для полностью клиентских приложений, например, для мобильных приложений.
Шаг 1. Авторизация пользователя.
Дать пользователю ссылку на авторизацию, которая перенаправляет пользователя на Плюсофон с дополнительными URL параметрами:
https://login.plusofon.ru/authorize
Параметры, которые необходимо передать в URL:
| Параметр | Описание |
|---|---|
| client_id | ID приложения |
| redirect_uri | URL-адрес, на который пользователи будут отправлены после авторизации |
| response_type | Должен иметь значение «token» |
Шаг 2. Получение токена доступа.
После того, как пользователь авторизовался, происходит редирект на указанный redirect_uri с дополнительными параметрами:
| Параметр | Описание |
|---|---|
| access_token | Токен доступа |
| token_type | Тип ключа |
| expires_in | Время «протухания» токена |
| refresh_token | Токен восстановление предыдущей авторизации |
Пример:
https://example.ru/callback?access_token=accessToken&token_type=bearer&expires_in=86400&refresh_token=refreshToken
Восстановление предыдущей авторизации¶
Обычно, access token имеет ограниченный срок годности. Это может быть полезно, например, если он передается по открытым каналам. Чтобы не заставлять пользователя проходить авторизацию после истечения срока действия access token’а, во всех перечисленных выше вариантах, в дополнение к access token’у может возвращаться еще refresh token. По нему можно получить access token с помощью HTTP-запроса.
Шаг 1. Получение токена доступа.
Refresh token используется для получения токена доступа путем отправки POST запроса на URL: https://login.plusofon.ru/token.
Параметры:
| Параметр | Описание |
|---|---|
| grant_type | Должен иметь значение «refresh_token» |
| refresh_token | Refresh token, полученный одним из методов авторизации |
Ответ в формате JSON будет содержать следующие данные:
| Параметр | Описание |
|---|---|
| access_token | Новый токен доступа |
| token_type | Тип ключа |
| expires_in | Время «протухания» токена |
| refresh_token | Новый токен восстановление предыдущей авторизации |
Использование токена доступа¶
Для аутентификации пользователя, в HTTP запросе необходимо передавать заголовок «Authorization»:
curl -H "Authorization: Bearer $TOKEN" https://api.plusofon.ru ...