Общее описание процесса аутентификации

Аутентификация в api выполнена согласно спецификации OAuth2.

Процесс аутентификации выглядит следующим образом:

1. Пользователь отправляет свои логин и пароль в api POST запросом на адрес /login
2. В случае успеха API возвращает JWT (Json web token) токен доступа.
3. Пользователь отправляет токен доступа вместе с каждым запросом к api
4. По истечении времени действия токена (1 час) пользователь получает новый токен и продолжает работу с ним.

Теперь подробнее по каждому шагу.

Получение токена доступа

Необходимо отправить POST запрос в api на адрес /login. В теле запроса нужно передать следующие параметры:

• grant_type = password
• username = логин пользователя
• password = пароль

:warning: Данные нужно передавать как html-форму (Content-Type: application/x-www-form-urlencoded), а не в виде JSON объекта. Этого требует спецификация OAuth2.

В случае успешно авторизации API вернёт http код 200 и JSON вида

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWFkZXIiLCJleHAiOjE2MTY3ODEyNTV9.-Jh1DkU5VwgR-LUePH-_4cU0YL6FMdAxpUTis8859hY",
"token_type":"bearer"}

строка в поле "access_token" является JWT токеном доступа.

Использование токена доступа в запросах

Токен доступа нужно передавать с каждым запросом к api в http-заголовке Authorization, предварив его строкой "Bearer ":

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWFkZXIiLCJleHAiOjE2MTY3ODEyNTV9.-Jh1DkU5VwgR-LUePH-_4cU0YL6FMdAxpUTis8859hY

:warning: Время действия токена доступа - 60 минут. По истечении этого времени api не будет его принимать - нужно будет получить новый токен и использовать его.

Проверка своих прав доступа

Для проверки прав доступа следует отправить запрос на /whoami (не забыв передать токен доступа как написано выше). В ответ api вернёт информацию о пользователе:

• имя пользователя
• полное имя
• список ролей

:warning: для неавторизованных пользователей (не передающих http-заголовок Authorization) будут возвращены данные пользователя "public".

Авторизация

Возможность выполнять те или иные действия в api зависит от ролей пользователя.

На данный момент создавать и редактировать ресурсы могут только пользователи с ролью 'writer'. Роль 'reader' позволяет читать любые данные.

Неавторизованные пользователи ("public") имеют роль public, которая на данный момент не позволяет ничего.

Документация доступна всем без авторизации.

:stop_sign: Но всё может измениться и к сожалению а автоматической документации это никак не отображается, а эта страница может устареть...