API: Аутентификация

Общая схема

Аутентификации реализуется по протоколу OAuth 2.0:

  • Client — интегрируемое приложение.
  • Resource Server — сервер WorkPoint API.
  • Authorization Server — WorkPoint Passport.
  • Access Token — можно рассматривать как «ключ», который надо предъявить API для получения доступа.
  • Refresh Token — второй «ключ», который нужен для одной цели — запроса обновления Access Token.
Данная статья затрагивает только общие моменты в работе с OAuth 2.0. Для получения дополнительной информации о протоколе можно обратиться к официальному стандарту или многочисленным статьям в интернете.

Получение и обновление Access Token

Для интеграционных решений используется один Authorization Grant Type — Resource Owner Password. Т.е. чтобы пройти аутентификацию необходимо использовать адрес эл. почты и пароль одного из пользователей системы.

Для получения Access Token и Refresh Token необходимо вызвать конечную точку:

[POST] https://passport.workpoint.app/connect/token
Content-Type: application/x-www-form-urlencoded

client_id=external&scope=all offline_access&grant_type=password&username=***&password=****

В ответ передаются два токена. Время жизни Access Token — 1 час, а Refresh Token — 15 дней.

Хранение логина и пароля не рекомендуется (особенно если «место хранения» не защищено). Вместо этого можно хранить Refresh Token и использовать его для обновления Access Token по мере необходимости.

Для обновления Access Token необходимо вызвать конечную точку:

[POST] https://passport.workpoint.app/connect/token
Content-Type: application/x-www-form-urlencoded

client_id=external&scope=all offline_access&grant_type=refresh_token&refresh_token=***

В ответ также передаются два токена. Т.е. при каждом обновлении Access Token обновляется и Refresh Token, что обеспечивает более высокий уровень безопасности.

Обращение к API

В каждый запрос к API должен быть добавлен заголовок (HEADER) Authorization в виде строки:

Bearer ACCESS_TOKEN