Skip to content

Latest commit

 

History

History
212 lines (153 loc) · 11.3 KB

authorization_for_user.md

File metadata and controls

212 lines (153 loc) · 11.3 KB

Авторизация пользователя

Для выполнения запросов от имени пользователя необходимо пользоваться токеном пользователя.

Получение авторизации пользователя

В начале приложению необходимо направить пользователя (открыть страницу) по адресу:

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 — идентификатор, полученный при создании приложения

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

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

Правила формирования специального 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.

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

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

Ответ

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

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

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

Ошибки

  • 400 Bad Request – ошибка в параметрах запроса.

Дополнительно к HTTP коду сервер может вернуть описание причины ошибки.

Обновление пары access и refresh токенов

access_token также имеет срок жизни (ключ expires_in, в секундах), при его истечении приложение должно сделать запрос с refresh_token для получения нового.

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

POST https://hh.ru/oauth/token

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

Ответ

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

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

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

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

Ошибки

  • 400 Bad Request – ошибка в параметрах запроса.

Дополнительно к HTTP коду сервер может вернуть описание причины ошибки.

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

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

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

Если есть необходимость, чтобы на шаге 3 сразу происходило перенаправление (redirect) с временным токеном, необходимо добавить к запросу /oauth/authorize... параметр skip_choose_account=true. В этом случае автоматически выдаётся доступ пользователю авторизованному на сайте.

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

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

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

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

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

Авторизация под разными рабочими аккаунтами

Для получения списка рабочих аккаунтов менеджера и для работы под разными рабочими аккаунтами менеджера необходимо прочитать документацию по рабочим аккаунтам менеджера