Користувачі REST API та автентифікація

Fledge підтримує декілька різних схем автентифікації для використання REST API

Без автентифікації або необов'язкова автентифікація. Для використання API в системі Fledge не потрібно проходити ніякої аутентифікації. Користувач може пройти автентифікацію за бажанням, але це не є обов'язковим.
Автентифікація за допомогою імені користувача/пароля. Автентифікація є обов'язковою, і користувач обирає автентифікацію за допомогою імені користувача та пароля.
Автентифікація на основі сертифіката. Автентифікація є обов'язковою, і для автентифікації користувач надає токен, виданий за допомогою сертифіката.

API автентифікації

Вхід

POST /fledge/login - Створює токен сесії входу, який можна використовувати для майбутніх звернень до API

Request Payload

Якщо користувач підключається за допомогою імені користувача та пароля, то структуру JSON слід передати як корисне навантаження, що забезпечує такі пари ключ/значення.

Назва ключа	Тип	Опис	Приклад
username	string	Ім'я користувача, який намагається увійти	admin
password	string	Звичайний текстовий пароль користувача, який намагається увійти	fledge

Response Payload

Корисним навантаженням відповіді є токен автентифікації, який слід включати в усі наступні виклики API. Цей токен буде включено в заголовок наступних запитів як значення властивості авторизації.

Example

Припустимо, що постачальником автентифікації є ім’я користувача та пароль.

curl -X POST http://localhost:8081/fledge/login -d'
{
  "username" : "admin",
  "password" : "fledge"
}'

Поверне токен автентифікації

{
  "message": "Logged in successfully",
  "uid": 1,
  "token": "********************",
  "admin": true
}

Наступні виклики мають містити HTTP-заголовок із токеном авторизації, наданим у цій відповіді.

curl -H "authorization: <token>" http://localhost:8081/fledge/ping

Альтернативно можна використовувати автентифікацію на основі сертифікатів, коли користувач надає сертифікат замість JSON-даних, показаних вище, кінцевій точці /fledge/login.

curl -T user.cert -X POST http://localhost:8081/fledge/login --insecure

Корисне навантаження, що повертається, таке ж, як і для автентифікації на основі імені користувача та пароля.

Примітка Наведені вище приклади були показані з використанням HTTP в якості транспорту, однак, якщо використовується автентифікація, то, як правило, очікується, що для шифрування зв'язку буде використовуватися HTTPS.

Вихід

PUT /fledge/logout - Припиняє поточний сеанс входу та анулює токен автентифікації

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

PUT /fledge/{user_id}/logout - Завершує сеанс входу для всіх активних сеансів користувача.

Адміністратор може припинити сеанс входу іншого користувача.

curl -H "authorization: <token>" -X PUT http://localhost:8081/fledge/{user_id}/logout

Користувачі

Fledge підтримує два рівні користувачів: користувачів адміністратора та звичайних користувачів. Існує набір викликів API, які дозволяють створювати, запитувати, змінювати та знищувати користувачів.

Додати користувача

POST /fledge/admin/user - додає нового користувача до бази даних користувачів Fledge

Примітка

Лише адміністратори можуть створювати інших користувачів.

Request Payload

Документ JSON, який описує користувача, якого потрібно додати.

Ім'я ключа	Тип	Опис	Приклад
username	string	The username of the new user to add. It is a required field.	david
password	string	Пароль для призначення новому користувачеві. Це обов’язкове поле.	Inv1nc!ble
access_method	string	Доступ користувача. Це необов’язкове поле.	Можливі значення: cert, any.
real_name	string	Справжнє ім'я користувача. Це використовується лише для показу. Це необов’язкове поле.	David Brent
role_id	integer	Ідентифікатор ролі нового користувача. Це необов’язкове поле.	1 для адміністратора і 2 для звичайного користувача. Якщо не надано, він буде розглядатися як звичайний користувач.
description	string	Опис користувача. Це необов’язкове поле.	1 для адміністратора та 2 для звичайного користувача. Якщо не надано, він буде розглядатися як звичайний користувач.

Response Payload

Корисне навантаження відповіді – це документ JSON, що містить повну інформацію про новоствореного користувача.

Errors

Можуть бути повернуті такі відповіді про помилки

HTTP Code	Причина
400	Неповне або погано сформоване корисне навантаження запиту
403	Користувач без прав адміністратора намагався додати нового користувача
409	Ім'я користувача вже використовується

Example

curl -H "authorization: <token>" -X POST -d '{"username": "david", "password": "Inv1nc!ble", "role_id": 1, "real_name": "David Brent"}' http://localhost:8081/fledge/admin/user

Get All Users

GET /fledge/user - Отримати дані про всіх користувачів

Response Payload

Документ JSON, який містить усіх користувачів в масиві JSON.

JSON Key	Тип	Опис	Приклад
.users[].userName	string	Ім'я користувача	david
.users[].roleId	integer	Рівень дозволів користувача	1
.users[].realName	string	Справжнє ім'я користувача. Це використовується лише для показу.	David Brent
.users[].description	string	Опис користувача.	Це адміністратор.

Примітка

Це корисне навантаження не включає пароль користувача.

Example

curl -H "authorization: <token>" -X GET http://localhost:8081/fledge/user

Повертає корисне навантаження відповіді

{
    "users" : [
                {
                   "userId"       : 1,
                   "userName"     : "admin",
                   "roleId"       : 1,
                   "accessMethod" : "any",
                   "realName"     : "Admin user",
                   "description"  : "admin user"
                },
                {
                   "userId"       : 2,
                   "userName"     : "david",
                   "realName"     : "David Brent",
                   "accessMethod" : "any",
                   "roleId"       : 1,
                   "description"  : "OT Department Head"
                },
                {
                   "userId"       : 3,
                   "userName"     : "paul",
                   "realName"     : "Paul Smith"
                   "roleId"       : 2,
                   "accessMethod" : "any",
                   "description"  : "OT Supervisor"
                }
              ]
}

Оновити користувача

PUT /fledge/user - Дозволяє користувачеві оновлювати власну інформацію користувача

Request Payload

Документ JSON, який описує оновлення запису користувача.

Назва ключа	Тип	Опис	Приклад
real_name	string	Справжнє ім'я користувача. Це використовується лише для показу.	David Brent

Примітка

Користувач може оновити лише своє справжнє ім’я, іншу інформацію має оновити користувач-адміністратор.

Response Payload

Корисне навантаження відповіді – це документ JSON, що містить повідомлення про успішність операції.

Errors

Можуть бути повернуті такі відповіді про помилки

HTTP Code	Причина
400	Неповне або погано сформоване корисне навантаження запиту

Example

curl -H "authorization: <token>" -X PUT /fledge/user -d '{"real_name": "Dave Brent"}'

Зміна паролю

PUT /fledge/user/{userid}/password - змінити пароль для поточного користувача

Request Payload

Документ JSON, який містить старий і новий паролі.

Назва ключа	Тип	Опис	Приклад
current_password	string	Поточний пароль користувача	Inv1nc!ble
new_password	string	Новий пароль користувача	F0gl!mp1

Response Payload

Повідомлення про успіх операції

Example

curl -X PUT -d '{"current_password": "Inv1nc!ble", "new_password": "F0gl!mp1"}' http://localhost:8081/fledge/user/{user_id}/password

Оновлення користувача адміністратором

PUT /fledge/admin/user - Адміністратор може оновити інформацію будь-якого користувача

Request Payload

Документ JSON, який описує оновлення запису користувача.

Імя	Тип	Опис	Приклад
description	string	Опис користувача	david
access_method	string	Дозволи, які слід надати новому користувачеві	Можливі значення cert, any.
real_name	string	Справжнє ім'я користувача. Це використовується лише для показу.	David Brent

Response Payload

Корисне навантаження відповіді – це документ JSON, що містить інформацію про користувача.

Errors

Можуть бути повернуті такі відповіді про помилки

HTTP Code	Причина
400	Неповне або погано сформоване корисне навантаження запиту
403	Користувач без прав адміністратора намагався додати нового користувача
409	Ім'я користувача вже використовується

Example

curl -H "authorization: <token>" -X PUT -d '{"description": "OT Department Head", "real_name": "David Brent", "access_method": "pwd"}' http://localhost:8081/fledge/admin/{user_id}

Видалення користувача

DELETE /fledge/admin/user/{userID}/delete - видаляє користувача

Примітка

Неможливо видалити користувача, який на даний момент увійшов до системи.

Тільки Адміністратор може видалити користувача.

Супер адміністратор не може бути видалений.

Example

curl -H "authorization: <token>" -X DELETE  http://localhost:8081/fledge/admin/{user_id}/delete

API автентифікації​

Вхід​

Вихід​

Користувачі​

Додати користувача​

Get All Users​

Оновити користувача​

Зміна паролю​

Оновлення користувача адміністратором​

Видалення користувача​

API автентифікації

Вхід

Вихід

Користувачі

Додати користувача

Get All Users

Оновити користувача

Зміна паролю

Оновлення користувача адміністратором

Видалення користувача