Skip to content

Latest commit

 

History

History
235 lines (168 loc) · 11.1 KB

authorization.md

File metadata and controls

235 lines (168 loc) · 11.1 KB

Авторизация

Авторизация осуществляется по протоколу OAuth 2.0. Подробная документация по протоколу: [RFC 6749](http://tools.ietf.org/html/rfc6749).

Зарегистрированное приложение может запрашивать у пользователей hh.ru разрешение доступа к их персональным данным, без получения и хранения их логина и пароля.

До 1 апреля 2015 года основной домен API был m.hh.ru. Авторизация через m.hh.ru будет доступна, однако теперь рекоммендуется использовать домен hh.ru. Документация была обновлена в соответствии с новым адресом.

 ## Получение авторизации В начале приложению необходимо направить пользователя (открыть страницу) по адресу: 
https://hh.ru/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}

Обязательные параметры:

  • response_type=code — указание на способ получение авторизации, используя authorization code;
  • client_id={client_id} — идентификатор, полученный при создании приложения;

Необязательные параметры:

  • state={state} — в случае указания, будет включен в ответный редирект. Это позволяет исключить возможность взлома путём подделки межсайтовых запросов. Подробнее об этом: RFC 6749. Section 10.12
  • redirect_uri={redirect_uri} — uri для перенаправления пользователя после авторизации. Если не указать, используется из настроек приложения. При наличии происходит валидация значения.
### Правила формирования специального redirect_uri

К примеру, если в настройках сохранен http://example.com/oauth, то разрешено указывать:

  • http://www.example.com/oauth — поддомен;
  • http://www.example.com/oauth/sub/path — уточнение пути;
  • http://example.com/oauth?lang=RU — дополнительный параметр;
  • http://www.example.com/oauth/sub/path?lang=RU — всё вместе.

Запрещено:

  • https://example.com/oauth — различные протоколы;
  • http://wwwexample.com/oauth — различные домены;
  • http://wwwexample.com/ — другой путь;
  • http://example.com/oauths — другой путь;
  • http://example.com:80/oauths — указание изначально отсутствующего порта;
 ### Процесс авторизации

Если пользователь не авторизован на сайте, ему будет показана форма авторизации на сайте. После прохождения авторизации на сайте, пользователю будет выведена форма с запросом разрешения доступа вашего приложения к его персональным данным.

Если пользователь не разрешает доступ приложению, пользователь будет перенаправлен на указанный redirect_uri с ?error=access_denied и state={state}, если таковой был указан при первом запросе.

 ### Успешное получение временного `authorization_code`

В случае разрешения прав, в редиректе будет указан временный authorization_code:

HTTP/1.1 302 FOUND
Location: {redirect_uri}?code={authorization_code}

Если пользователь авторизован на сайте и доступ данному приложению однажды ранее выдан, ответом будет сразу вышеописаннный редирект с authorization_code (без показа формы логина и выдачи прав).

 ### Получение access и refresh токенов

После получения authorization_code приложению необходимо сделать сервер-сервер POST-запрос на https://hh.ru/oauth/token для обмена полученного authorization_code на access_token.

В запросе необходимо передать:

grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&code={authorization_code}&redirect_uri={redirect_uri}

Если при получении authorization_code был указан redirect_uri, то в запросе необходимо обязательно передать это значение (происходит сравнение строк), иначе этот параметр необязателен. Если же не указать redirect_uri при запросе на /oauth/authorize, то при указании его во втором запросе (/oauth/token) сервер вернёт ошибку.

Тело запроса необходимо передавать в стандартном application/x-www-form-urlencoded с указанием соответствующего заголовка Content-Type.

В ответе вернётся JSON:

{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "expires_in": 1209600,
  "refresh_token": "{refresh_token}",
}

authorization_code имеет довольно короткий срок жизни, при его истечении необходимо запросить новый.

Если обмен authorization_code произвести не удалось, то вернётся ответ 400 Bad Request с телом:

{
    "error": "...",
    "error_description": "..."
}

где:

  • error будет иметь одно из значений, описанных в стандарте RFC 6749. Например, invalid_request, если какой либо из обязательных параметров не был передан.
  • error_description будет содержать дополнительное описание ошибки.
## Обновление пары access и refresh токенов `access_token` также имеет срок жизни (ключ `expires_in`, в секундах), при его истечении приложение должно сделать запрос с `refresh_token` для получения нового.

Запрос необходимо делать в application/x-www-form-urlencoded.

POST https://hh.ru/oauth/token
grant_type=refresh_token&refresh_token={refresh_token}

Ответ будет идентичен ответу на получения токенов в первый раз:

{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "expires_in": 1209600,
  "refresh_token": "{refresh_token}",
}

refresh_token можно использовать только один раз и только по истечению срока действия access_token.

После получения новой пары access и refresh токенов, их необходимо использовать в дальнейших запросах в api и запросах на продление токена.

 ### Использование и проверка access_token

Приложение должно использовать полученный access_token для авторизации, передавая его в заголовке в формате:

Authorization: Bearer ACCESS_TOKEN

Для тестирования токена, удобно использовать метод /me (это необязательный шаг).

GET /me HTTP/1.1
User-Agent: MyApp/1.0 ([email protected])
Host: api.hh.ru
Accept: */*
Authorization: Bearer access_token

Документация по ответу от /me в соответствующем разделе.

Описание ошибок авторизации.

Запрос авторизации под другим пользователем

Возможен следующий сценарий:

  1. Приложение перенаправляет пользователя на сайт с запросом авторизации.
  2. Пользователь на сайте уже авторизован и данному приложение доступ уже был разрешен.
  3. В ответ сразу приходит перенаправление (redirect) со временным токеном и приложение получает по нему access_token.

В этом случае, автоматически выдаётся доступ пользователю авторизованному на сайте. Если необходимо запросить доступ другого пользователя, приложение может добавить к запросу /oauth/authorize... параметр force_login=true. В этом случае, пользователю будет показана форма авторизации с логином и паролем даже в случае, если пользователь уже авторизован.

Это может быть полезно приложениям, которые предоставляют сервис только для соискателей. Если пришел пользователь-работодатель, приложение может предложить пользователю повторно разрешить доступ на сайте, уже указав другую учетную запись.

Также, после авторизации приложение может показать пользователю сообщение:

Вы вошли как %Имя_Фамилия%. Это не вы?

и предоставить ссылку с force_login=true для возможности захода под другим логином.

Полезные ссылки

  • Подробная документация по протоколу: RFC 6749