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 | Да | Тип ответа от сервера, укажите code |
| redirect_uri | Да | URI, на который будет передан access_token. URI должен посимвольно совпадать с одним из URI, зарегистрированных в настройках приложения. Часть URI после символа ‘?’ (query) не учитывается при проверке, тем не менее, для передачи динамически изменяющихся данных рекомендуется использовать параметр state. |
| layout | Нет | Внешний вид окна авторизации: * w – (по умолчанию) стандартное окно для полной версии сайта; * m – окно для мобильной авторизации; * a – упрощённое окно для мобильной авторизации без шапки. |
| state | Нет | Параметр состояния. В неизменном виде пробрасывается в redirect_uri. Позволяет передавать произвольные данные между разными фазами OAuth и защищаться от xsrf. |
2. Разрешение прав доступа
Если пользователь ранее выдал приложению все права, указанные в параметре scope, то окно автоматически закрывается и дополнительное подтверждение от пользователя не требуется.
После перехода по сформированному URL пользователь будет должен ввести свой логин и пароль, если ранее он этого не сделал. После входа на сайт ему будет предложено авторизовать приложение и подтвердить запрошенные права:
3. Получение code
При использовании OAuth в игровых приложениях, размещенных вне соц. сети Одноклассники:
- требуется подключать OAuth с использованием того же приложения, которое используется и в версии, размещенной на платформе ОК.
С 15 июля 2020 года:
- пользователи, ранее играющие в это приложение на платформе ОК, при прохождении авторизации через OAuth будут автоматически перенаправлены на соответствующую версию приложения на платформе ОК;
- пользователи, ранее на игравшие в это приложения на платформе ОК, при прохождении авторизации через OAuth перенаправляться не будут, OAuth будет работать согласно документации
Такое использование Oauth не противоречит п. 5.6 правил платформы и не будет расценено как нарушение правил размещения приложений на платформе.
После подтверждения авторизации пользователь будет перенаправлен на указанный при открытии диалога авторизации redirect_uri, в GET-параметрах которого будет передан ключ доступа code, а также state в случае, если он был указан на этапе 1:
{redirect_uri}?code={code}&state={state}
Полученный параметр code действителен в течение 2 минут.
В случае ошибки или отказа от авторизации будет передан параметр error, идентифицирующий причину проблемы:
{redirect_uri}#error={error}&state={state}
4. Получение access_token
Для получения access_token необходимо совершить POST-запрос с сервера вашего сайта к API на URL:
https://api.ok.ru/oauth/token.do?code={code}&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&grant_type={grant_type}
| Название | Описание |
|---|---|
| code | Код авторизации, полученный в пункте 3 |
| client_id | Идентификатор приложения {application id} |
| client_secret | Секретный ключ приложения {application_secret_key} |
| redirect_uri | Тот же URI переадресации, что был указан в пункте 1 |
| grant_type | Тип выдаваемых прав, укажите authorization_code |
В ответе от сервера приходит json, содержащий запрошенный access_token или информацию об ошибке.
Вид ответа в случае успеха:
{
"access_token": "{access_token}",
"token_type": "session",
"refresh_token": "{refresh_token}",
"expires_in":"{expires_in}"
}- access_token – токен доступа, используемый для формирования запроса к API;
- token_type – на данный момент возвращается только session;
- refresh_token – токен обновления, который можно использовать в дальнейшем для упрощённой процедуры авторизации. Действителен в течение 30 суток;
- expires_in – время действия токена доступа в секундах.
Вид ответа в случае ошибки
{
"error": "{error}",
"error_description": "{error_description}"
}- error – код ошибки;
- error_description – описание ошибки.
5. Использование refresh_token
Имея токен обновления refresh_token, можно получить access_token по упрощённой процедуре, сделав один POST-запрос на URL:
https://api.ok.ru/oauth/token.do?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type={grant_type}
| Название | Описание |
|---|---|
| refresh_token | Маркер обновления, полученный ранее в пункте 4 |
| client_id | Идентификатор приложения {application id} |
| client_secret | Секретный ключ приложения {application_secret_key} |
| grant_type | Тип выдаваемых прав, укажите refresh_token |
Формат ответа аналогичен получению access_token, но без refresh_token.
Возможные ошибки
| Ошибка | Варианты возникновения |
|---|---|
| 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) |