Настройка приложения
Для использования клиентской OAuth-авторизации необходимо включить в настройках приложения клиентскую авторизацию.
Во время создания приложения требуется указать redirect_uri, который будет использован во время авторизации OAuth:
| Тип | Описание | Пример |
|---|---|---|
| Android SDK | okauth://ok{app_id} вместо [app_id] необходимо подставить id приложения | okauth://ok123456 |
| iOS SDK | ok{app_id}://authorize вместо [app_id] необходимо подставить id приложения | ok123456://authorize |
| External | URI, который будет обрабатывать авторизацию. Можно использовать https://oauth.mycdn.me/blank.html | http://localhost/auth |
1. Открытие диалога авторизации OAuth
Во время создания приложения потребуется указать redirect_uri, который будет использован во время авторизации OAuth
Для начала процесса авторизации нужно открыть новое окно браузера (или webView) и осуществить переход на специально сформированный URL:
https://connect.ok.ru/oauth/authorize?client_id={clientId}&scope={scope}&response_type={{response_type}}&redirect_uri={redirectUri}&layout={layout}&state={state}
| Название | Обязательный | Описание |
|---|---|---|
| client_id | Да | Идентификатор приложения {application id} |
| scope | Да | Запрашиваемые права приложения, разделённые символом ‘;’. См. права приложения |
| response_type | Да | Тип ответа от сервера, укажите token |
| redirect_uri | Да | URI, на который будет передан access_token. URI должен посимвольно совпадать с одним из URI, зарегистрированных в настройках приложения. Часть URI после символа ‘?’ (query) не учитывается при проверке, тем не менее, для передачи динамически изменяющихся данных рекомендуется использовать параметр state. |
| layout | Нет | Внешний вид окна авторизации: * w – (по умолчанию) стандартное окно для полной версии сайта; * m – окно для мобильной авторизации; * a – упрощённое окно для мобильной авторизации без шапки. |
| state | Нет | Параметр состояния. В неизменном виде пробрасывается в redirect_uri. Позволяет передавать произвольные данные между разными фазами OAuth и защищаться от xsrf. |
2. Разрешение прав доступа
Если пользователь ранее выдал приложению все права, указанные в параметре scope, то окно автоматически закрывается и дополнительное подтверждение от пользователя не требуется.
После перехода по сформированному URL пользователь будет должен ввести свой логин и пароль, если ранее он этого не сделал. После входа на сайт ему будет предложено авторизовать приложение и подтвердить запрошенные права:
3. Получение access_token
После подтверждения авторизации пользователь будет перенаправлен на указанный при открытии диалога авторизации redirect_uri, в котором после символа решётки будут переданы параметры access_token и session_secret_key, а также state в случае, если он был указан на этапе 1:
{redirect_uri}#access_token={access_token}&session_secret_key={session_secret_key}&state={state}&permissions_granted={permissions_granted}&expires_in={expires_in}
| Название | Описание |
|---|---|
| access_token | Токен доступа, используемый для формирования запроса к API |
| session_secret_key | Секретный сессионный ключ, используемый для подписи запроса к API |
| state | Значение, которое было передано в параметре state при открытии диалога авторизации |
| permissions_granted | Права, выданные пользователем приложению |
| expires_in | Время действия токена доступа в секундах |
В случае ошибки или отказа от авторизации будет передан параметр error, идентифицирующий причину проблемы:
{redirect_uri}#error={error}&state={state}
Возможные ошибки
| Ошибка | Варианты возникновения |
|---|---|
| invalid_request | * был передан неверный code (описание ошибки - Invalid code) * время действия code истекло (описание ошибки - Expired code) * redirect_uri отличается от переданного на этапе OAuth (описание ошибки - Wrong redirect_uri) |
| invalid_client | * не удалось найти указанное приложение (описание ошибки - Unknown client) |
| unauthorized_client | * секретный ключ приложения неверен (описание ошибки - Invalid request parameters) |
| access_denied | * пользователь не авторизовал приложение (например, удалил его в настройках, описание ошибки - Access denied) * время действия refesh_token истекло (описание ошибки - Refresh token expired) * пользователь принудительно вышел со всех устройств (см. настройки, описание ошибки - Logout all) |
| invalid_grant | * не удалось распознать параметр grant_type (описание ошибки - Invalid grant type или Invalid parameters for grant type) |
| invalid_token | * не удалось определить пользователя (описание ошибки - Session expired) * refresh_token был передан неверно (описание ошибки - Invalid refresh token / Invalid refresh token structure / Invalid refresh token, user not found) |