Аутентификация и авторизация¶

Выполнение запросов к API Продукта требует аутентификации и авторизации пользователя.

Механизм аутентификации основан на JSON Web Tokens (JWT). Он заключается в получении и последующей передаче токена в HTTP-заголовке Authorization каждого запроса.

Механизм авторизации основан на системе разрешений пользователей.

Получение токена¶

Получение токена выполняется по логину и паролю.
Запрос: POST /token
HTTP-заголовки:

Content-Type: application/json
Accept: application/json

Тело запроса:

{
    "Username": "логин",
    "Password": "пароль"
}

В случае успешного выполнения запроса возвращается JSON, который содержит токен:

{
    "access_token": "eyJh ... vnuE",                    // токен
    "expires_in": 86400,                                // срок действия токена в секундах
    "userId": "13",                                     // идентификатор пользователя
    "userName": "krabov@domain.com",                    // логин пользователя
    "displayName": "Эдуард Крабов",                     // отображаемое имя пользователя
    "roles": "[\"acceptor\",\"rejector\",...,\"user\"]" // набор разрешений, назначенных пользователю
}

Передача токена¶

Для выполнения прочих запросов к API нужно передавать токен в HTTP-заголовке Authorization:

Authorization: Bearer access_token

где access_token – полученный на предыдущем шаге токен.

Кэширование и обновление токена¶

Полученный токен нужно закэшировать и использовать повторно для последующих запросов к API.

Токен может стать невалидным. Это может произойти, если:

закончился срок действия токена: в этом случае сервис в ответ на очередной запрос вернет статус 401 (Unauthorized);
учетная запись была удалена либо был изменен пароль: в этом случае сервис в ответ на очередной запрос также вернет статус 401 (Unauthorized);
был изменен набор разрешений пользователя: в этом случае сервис в ответ на очередной запрос вернет статус 403 (Forbidden).

При получении одного из статусов 401 (Unauthorized) или 403 (Forbidden) токен нужно запросить повторно.

Если повторный запрос токена завершен со статусом 401 (Unauthorized), то учетные данные невалидны. В этом случае следует использовать другие учетные данные.

Если повторный запрос токена успешно завершен, то нужно закэшировать новый токен и повторить очередной запрос уже с новым токеном.

Предупреждение

Не кэшируйте токен в долговременном хранилище. Это не имеет смысла, так как токен имеет срок действия. Не кэшируйте токен во внешнем хранилище в открытом виде. Это может привести к несанкционированному доступу к данным, в том числе к содержимому документов и паролям. Используйте шифрование, если по какой-то причине токен нужно закэшировать во внешнем хранилище.

Шифрование токена¶

Токен - это зашифрованная строка, содержащая учетные данные пользователя. После получения токена в заголовке запроса, API Продукта пытается расшифровать его.

Ключ для расшифровки токена задается в файле конфигурации хоста appSettings.json для каждого HTTP-сервиса, в поле Jwt.Key. В поставке Продукта все API используют один и тот же ключ по умолчанию.

Предупреждение

Не используйте ключ по умолчанию для шифрования токенов и не передавайте ключ третьим лицам. Это может привести к несанкционированному доступу к данным, в том числе к содержимому документов и паролям. Меняйте ключ сразу после развертывания HTTP-сервисов.

Использование единого токена для всех API¶

Все API Продукта могут использовать один и тот же ключ для шифрования токенов.

В этом случае токен, полученный в одном сервисе, подойдет для использования в другом сервисе, если в другом сервисе есть учетная запись пользователя с таким же именем.

Разрешения пользователей¶

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

Если разрешение не назначено пользователю или набор разрешений пользователя был изменен, то сервис в ответ на очередной запрос вернет статус 403 (Forbidden). Если разрешение было удалено из набора разрешений пользователя, то в этом случае для доступа к выбранному ресурсу следует использовать другую учетную запись.

Учетные записи по умолчанию¶

При развертывании компонентов Продукта создаются две учетные записи по умолчанию:

администратор:
- логин: admin@domain.com
- пароль: 1234aA
пользователь:
- логин: user@domain.com
- пароль: 1234aA

Учетная запись администратора имеет доступ к настройкам, но не имеет доступа к основному функционалу API. Учетная запись пользователя, наоборот, не имеет доступа к настройкам, но имеет доступ к основному функционалу API.

Предупреждение

Не используйте учетные записи и пароли по умолчанию в продуктивной среде. Это может привести к несанкционированному доступу к данным, в том числе к содержимому документов и паролям. Используйте свои учетные записи и пароли.

Примечание

Учетная запись пользователя может осутствовать в некоторых HTTP-сервисах. В этом случае для доступа к API от имени учетной записи по умолчанию следует использовать учетную запись администратора.