Авторизация в WEB API ПОЛИНОМ:MDM

Авторизация — предоставление определённому лицу или группе лиц прав на выполнение определённых действий, а также процесс проверки (подтверждения) данных прав при попытке выполнения этих действий^[1].

Общая информация

Web-сервер ПОЛИНОМ:MDM использует механизм авторизации, основанный на технологии JWT токена^[2]^[3].

Принцип JWT заключается в том, что при успешной авторизации сервер присылает в ответ специальный токен в формате JSON.

Для доступа к защищенной информации сервера пользователь должен добавить токен в заголовки последующих запросов:

Authorization: Bearer <token>

Алгоритм авторизации:

Получение списка зарегистрированных хранилищ.
Вход.
Обновление токена входа;
Выход.

Во всех случаях web-сервер возвращает стандартный ответ с кодом 200^[4] в случае успеха или с кодом ошибки в случае неудачи.

Примечание: здесь и далее адрес web-сервера будет обозначаться как <web-server>.

Получение списка зарегистрированных хранилищ

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

Для получения списка хранилищ следует выполнить GET-запрос по адресу:

<web-server>/api/v1/login/storage-definitions

Ответ на запрос - список объектов, содержащих названия и идентификаторы хранилищ web-сервера.

Пример списка хранилищ

[
  {
    "storageId": "f552d8ff-50b1-468e-9577-2069cbaed16e",
    "displayName": "WebTest-23"
  },
  {
    "storageId": "e52e4911-ab43-4add-a694-1c0c352e6efe",
    "displayName": "Demo5.0.0"
  }
]

Для дальнейшего подключения к хранилищу нужен его идентификатор.

Вход

Для входа на web-сервер нужно выполнить POST-запрос по адресу:

<web-server>/api/v1/login/sign-in

Тело запроса - объект, содержащий логин, пароль, идентификатор хранилища и тип клиента.

Параметры запроса:

storageId - идентификатор хранилища;
login - имя входа пользователя;
password - пароль пользователя;
moduleName - имя клиента (нужно для отображения имени в журнале событий);
clientType - тип клиента (влияет на получение лицензии).

Возможные значения clientType:

0 - тип не определен (будет назначен Клиент);
8 - Клиент;
16 - Конвертер;
32 - Редактор;
64 - Администратор.

Пример тела запроса:

{
  "storageId": "f552d8ff-50b1-468e-9577-2069cbaed16e",
  "login": "admin",
  "password": "111",
  "moduleName": "Клиент справочника",
  "clientType": 8
}

Тело ответа от web-сервера - объект, содержащий JWT токен, и иную информацию, а именно:

access_token - токен доступа;
token_type - тип токена авторизации (Bearer);
expires_in - срок жизни токена доступа. (сек.);
refresh_token - токен обновления токена доступа.

Пример ответа:

{
  "access_token": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IlBvbHlub20ifQ.eyJuYW1lIjoiYWRtaW4iLCJuYW1laWRlbnRpZmllciI6IjUyOTkxMTFjNWMyYzRhZTlhOGQzYmE4YzNlMjMxODEwIiwic2Vzc2lvbiI6ImNhMzRiNjFkZWM0YjRlZWNiMzQ4Y2Y5MzI4NjRlNzNiIiwicm9sZXMiOiIiLCJwb3N0cyI6IiIsIm5iZiI6MTczMTY2MjExMCwiZXhwIjoxNzMxNjYyNDEwLCJpc3MiOiJBc2NvbiIsImF1ZCI6IkFzY29uIn0.VdiBbL7d5-n280MEKUs8N0w3fxUkhAlF8Acly7NH5aLoF6RQPl6E_79BatIUTcvFj4GHm-8ZHxwLC2opLcBrQYhBXbgrpx-DgA8AY-e0EvOBJjd37lw4A_NcywNcqw9fineUT7gIHuEFx7e2anyTYxgJeSEpOUp6ZJP_4avF9bc",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "f9de8e4fdf874247be4d14c160a0525f"
}

Обновление токена входа

ВНИМАНИЕ: применяемость токена входа истекает через 10 минут после его создания. Для продолжения работы нужно использовать токен обновления.

Для выполнения обновления токена входа нужно выполнить PATCH-запрос по адресу:

<web-server>/api/v1/login/update-token

Параметры запроса:

access_token - В заголовке указать токен доступа.
refresh_token - Указать токен обновления в теле запроса как простой текст (text/plain).

В заголовке:
Authorization: Bearer <значение access_token>
Content-Type: text/plain

В теле:
<значение refresh_token>

Ответ от web-сервера аналогичен ответу на запрос авторизации за исключением обновленных токенов входа и обновления.

Выход

При завершении работы или смене пользователя нужно выполнить выход из текущей сессии. Для этого нужно отправить DELETE-запрос по адресу:

<web-server>/api/v1/login/sign-out

Параметры запроса:

access_token - В звголовке указать токен доступа.

В заголовке:
Authorization: Bearer <значение access_token>

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

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

Каждый этап авторизации выполняется с помощью утилиты curl^[5] в командной строке.

В качестве примера рассмотрено обращение к локальному серверу, расположенному по адресу http://localhost:5000.

Получение списка зарегистрированных хранилищ

Запрос:

curl -X 'GET' \
  'http://localhost:5000/api/v1/login/storage-definitions' \
  -H 'accept: application/json'

Ответ:

[
  {
    "storageId": "6ec6991a-9f09-4d40-b124-e7457148655f",
    "displayName": "Demo-23.2"
  }
]

Вход

Выбранное хранилище - "Demo-23.2" с идентификатором "6ec6991a-9f09-4d40-b124-e7457148655f".

Запрос:

curl -X 'POST' \
  'http://localhost:5000/api/v1/login/sign-in' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "storageId": "6ec6991a-9f09-4d40-b124-e7457148655f",
  "login": "admin",
  "password": "111",
  "moduleName": "Клиент справочника",
  "clientType": 8
}'

Ответ:

{
  "access_token": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IlBvbHlub20ifQ.eyJuYW1lIjoiYWRtaW4iLCJuYW1laWRlbnRpZmllciI6Ijg4MGFmYzg2YTBjMzRhNmM4ODEzNjdmNDY0NDI5MDA1Iiwic2Vzc2lvbiI6ImIzNDE3NzZhYjVjMTRlOTc4NDg4NjFhMDY3YTZiNjRiIiwicm9sZXMiOiIiLCJwb3N0cyI6IiIsIm5iZiI6MTczMTY2MjYwNSwiZXhwIjoxNzMxNjYzMjA1LCJpc3MiOiJBc2NvbiIsImF1ZCI6IkFzY29uIn0.TcHZfgkKBQA3yzE6alAAoslIgwdDsntyGGdfuhXljvE2lDKdrwb3SvUIRY-UfJfky4DkXPbiZQhp1LkYaj57M9uYrAn2NkFDAI3WKgbM1TUJLf_KT_s7m4SQgmC3zRJhZQoE4oZ6ah2LMU_0sxJGC-h99bZi_9aTj_lYrW61ESU",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "51be76a0996041a98e0c919cf1f2cb3e"
}

Обновление токена входа

Запрос:

curl -X 'PATCH' \
  'http://localhost:5000/api/v1/login/update-token' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IlBvbHlub20ifQ.eyJuYW1lIjoiYWRtaW4iLCJuYW1laWRlbnRpZmllciI6Ijg4MGFmYzg2YTBjMzRhNmM4ODEzNjdmNDY0NDI5MDA1Iiwic2Vzc2lvbiI6ImIzNDE3NzZhYjVjMTRlOTc4NDg4NjFhMDY3YTZiNjRiIiwicm9sZXMiOiIiLCJwb3N0cyI6IiIsIm5iZiI6MTczMTY2MjYwNSwiZXhwIjoxNzMxNjYzMjA1LCJpc3MiOiJBc2NvbiIsImF1ZCI6IkFzY29uIn0.TcHZfgkKBQA3yzE6alAAoslIgwdDsntyGGdfuhXljvE2lDKdrwb3SvUIRY-UfJfky4DkXPbiZQhp1LkYaj57M9uYrAn2NkFDAI3WKgbM1TUJLf_KT_s7m4SQgmC3zRJhZQoE4oZ6ah2LMU_0sxJGC-h99bZi_9aTj_lYrW61ESU' \
  -H 'Content-Type: text/plain' \
  -d '51be76a0996041a98e0c919cf1f2cb3e'

Ответ:

{
  "access_token": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IlBvbHlub20ifQ.eyJuYW1lIjoiYWRtaW4iLCJuYW1laWRlbnRpZmllciI6Ijg4MGFmYzg2YTBjMzRhNmM4ODEzNjdmNDY0NDI5MDA1Iiwic2Vzc2lvbiI6ImIzNDE3NzZhYjVjMTRlOTc4NDg4NjFhMDY3YTZiNjRiIiwicm9sZXMiOiIiLCJwb3N0cyI6IiIsIm5iZiI6MTczMTY2MjY3OSwiZXhwIjoxNzMxNjYzMjc5LCJpc3MiOiJBc2NvbiIsImF1ZCI6IkFzY29uIn0.U_lfSUqxFrK-LtyR91NN69T10yxOZBgcUx_ASGG_vUC7RCa01vNNENXId7gKEw7FwNu5Zk-4ImaLdQyGLH4e7u6jHKakOQIum8iW3nSSLcHIeZ1sMShXEFgou0WA7u2Rf2oQFy-hPxyEkNCBHz0nQbo2LbKkuYdjWJJUdMHBPn4",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "3bf467ded1664584939c0db9eadff389"
}

Выход

Запрос:

curl -X 'DELETE' \
  'http://localhost:5000/api/v1/login/sign-out' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6IlBvbHlub20ifQ.eyJuYW1lIjoiYWRtaW4iLCJuYW1laWRlbnRpZmllciI6Ijg4MGFmYzg2YTBjMzRhNmM4ODEzNjdmNDY0NDI5MDA1Iiwic2Vzc2lvbiI6ImIzNDE3NzZhYjVjMTRlOTc4NDg4NjFhMDY3YTZiNjRiIiwicm9sZXMiOiIiLCJwb3N0cyI6IiIsIm5iZiI6MTczMTY2MjY3OSwiZXhwIjoxNzMxNjYzMjc5LCJpc3MiOiJBc2NvbiIsImF1ZCI6IkFzY29uIn0.U_lfSUqxFrK-LtyR91NN69T10yxOZBgcUx_ASGG_vUC7RCa01vNNENXId7gKEw7FwNu5Zk-4ImaLdQyGLH4e7u6jHKakOQIum8iW3nSSLcHIeZ1sMShXEFgou0WA7u2Rf2oQFy-hPxyEkNCBHz0nQbo2LbKkuYdjWJJUdMHBPn4'

Авторизация в Swagger

{: #Авторизации-на-C#-.NET }

Swagger^[6] - впомогательный инструмент для работы, документирования и изучения API.

На основе существующего исходного кода Swagger генерирует страницу, содержащую формы обращения к ресурсам API.

Страница Swagger запущенного web-сервера ПОЛИНОМ:MDM доступна по адресу:

<web-server>/api/index.html

Текстовое описание API в формате json, сгенерированное Swagger, доступно по адресу:

<web-server>/swagger/v1/swagger.json

Стартовая страница Swagger

Рис. 1. Стартовая страница Swagger

Формы вызова методов авторизации находятся в выпадающем элементе Login.

Элемент Login

Рис. 2. Элемент Login

Получение списка зарегистрированных хранилищ

При нажатии на элемент /api/v{version}/login/storage-definitions будет отображена форма получения списка хранилищ.

Неактивная форма получения списка хранилищ

Рис. 3. Неактивная форма получения списка хранилищ

При нажатии на кнопку Try it out поля формы станут активными.

Активная форма получения списка хранилищ

Рис. 4. Активная форма получения списка хранилищ

Заполнив поля и нажав кнопку Execute, можно получить результат. В случае списка хранилищ нужно указать только версию API.

Результат выполнения метода

Рис. 5. Результат выполнения метода

Вход

Для раскрытия формы метода авторизации нужно нажать на элемент **/api/v{version}/login/sign-in **

alt text

Рис. 6. Неактивная форма авторизации

При нажатии на кнопку Try it out форма станет активной. Так как авторизация выполняется через POST-запрос, то помимо версии API нужно указать тело запроса.

Активная форма авторизации

Рис. 7. Активная форма авторизации

Заполнив параметры тела запроса и нажав кнопку Execute, можно получить результат.

Результат выполнения метода

Рис. 8. Результат выполнения метода

Добавление токена входа в формы запросов Swagger

После выполнения авторизации и получения токена входа можно добавить его в заголовки последующих запросов. Для этого нужно нажать кнопку Authorize, находящуюся в начале страницы Swagger. При ее нажатии откроется окно с формой ввода токена.

Незаполненная форма ввода токена