Серверная OAuth авторизация

Во время создания приложения потребуется указать redirect_uri, который будет использован во время авторизации OAuth.

1. Открытие диалога авторизации 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

После подтверждения авторизации пользователь будет перенаправлен на указанный при открытии диалога авторизации 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 суток, не возвращается, в случае использования токена с удлинённым сроком жизни (используя право LONG_ACCESS_TOKEN)
  • 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)