Аккаунты, токены и способы авторизации#
Аккаунт#
Аккаунт необходим для разграничения областей видимости объектов для конкретного пользователя. Наличие аккаунта требуется для выполнения большинства запросов. Каждый созданный аккаунт имеет свой собственный уникальный идентификатор "account_id". Все данные аккаунтов сохраняются в БД сервиса Accounts под этим идентификатором.
Аккаунт можно создать с помощью POST запроса "create account" к сервису API, либо с помощью сервиса Admin. При создании аккаунта необходимо указать следующие данные: электронная почта (login), пароль (password) и тип аккаунта (account_type).
Тип аккаунта#
Тип аккаунта определяет, какие данные доступны пользователю.
Существует три типа аккаунтов:
- user — тип аккаунта, с помощью которого можно создавать объекты и использовать только данные своего аккаунта.
- advanced_user — тип аккаунта, для которого доступны права, аналогичные "user", а также есть доступ к данным всех аккаунтов. Доступ к данным других аккаунтов означает возможность получать данные (запросы GET), проверять их наличие (запросы HEAD) и выполнять запросы на сравнение по данным других аккаунтов.
- admin — тип аккаунта, для которого доступны права, аналогичные "advanced_user", а также есть доступ к сервису Admin.
В сервисе API можно работать со всеми типами аккаунтов, но создать можно только аккаунты типа "advanced_user" и "user", в то время как в сервисе Admin можно создать все три типа.
По умолчанию в системе существует аккаунт типа "admin" и логином и паролем по умолчанию root@visionlabs.ai/root.
С помощью заголовка "Luna-Account-Id" в запросе "create account" можно задать желаемый идентификатор аккаунта. Также его необходимо использовать в случае, если необходимо сохранить возможность работы с данными, созданными в версиях LP до 5.30.0 с помощью указания идентификатора "account_id" в заголовке "Luna-Account-Id". Таким образом, использование данного параметра привяжет старый "account_id" к создаваемому аккаунту (см. подробную информацию о миграции в разделе "Миграция аккаунтов" в руководстве по обновлению LUNA PLATFORM).
В ответе на запрос на создание аккаунта выдается "account_id". После создания аккаунта можно использовать этот идентификатор для авторизации LunaAccountIdAuth или использовать авторизацию авторизацию BasicAuth (авторизация по по логину/паролю).
Токен#
Токен привязывается к существующему аккаунту с любым типом ("user", "advanced_user", "admin") и позволяет наложить расширенные ограничения на выполняемые запросы. Например, при создании токена можно дать пользователю разрешение только на создание и изменение всех списков и лиц, или можно запретить использование определенных обработчиков, указав их идентификатор.
Токен создается с помощью запроса "create token" к сервису API.
Для каждого аккаунта можно создать неограниченное количество токенов. Токен и все его ограничения сохраняются в БД и привязываются к аккаунту по параметру "account_id". Нельзя привязать один токен к разным аккаунтам. Для создания токенов с одинаковыми разрешениями в рамках разных аккаунтов рекомендуется сохранить шаблон тела запроса для создания аккаунта и использовать его.
Нет необходимости в использовании и токена и аккаунта. При работе с токенами можно ограничить доступ к ресурсу "/accounts" с помощью внешних средств.
Для токена в любой момент можно выдать дополнительные ограничения с помощью запроса "replace token" или можно отозвать токен с помощью запроса "delete token". В этом случае токен будет удален из БД и больше не может быть использован для авторизации.
При создании токена требуется задать следующие параметры:
— expiration_time – время окончания действия токена в формате RFC 3339. Можно указать бесконечное время действия токена с помощью значения "null" — permissions – действия, которые может выполнять пользователь (см. "Разрешения, задаваемые в токене")
Для токена также возможно указать видимость токеном данных других аккаунтов с помощью параметра "visibility_area" (см. раздел "Просмотр данных других аккаунтов").
В ответе на запрос на создание токена выдается "token_id" и закодированный в Base64 JWT токен. После создания токена можно использовать полученный JWT токен для авторизации BearerAuth.
Разрешения, задаваемые в токене#
Для создаваемого токена доступны следующие разрешения:
| Название разрешения | Описание разрешения | Права |
|---|---|---|
| account | права на использование аккаунта | view |
| face | права на использование лица | creation, view, modification, deletion, matching |
| list | права на использование списка | creation, view, modification, deletion |
| event | права на использование события | creation (только запрос "save event"), view, matching |
| attribute | права на использование атрибута | creation, view, modification, deletion, matching |
| handler | права на использование обработчика | creation, view, modification, deletion |
| verifier | права на использование верификатора | creation, view, modification, deletion |
| task | права на использование задачи и расписания задачи | creation, view, modification, deletion |
| face_sample | права на использование БО лица | creation, view, deletion |
| body_sample | права на использование БО тела | creation, view, deletion |
| object | права на использование объекта | creation, view, deletion |
| image | права на использование изображения | creation, view, deletion |
| token | права на использование токена | view, modification, deletion |
| resources | права на использование ресурсов | "/iso", "/sdk", "/liveness" |
| emit_events | права на выполнение запросов "generate events" | (см. ниже) |
| lambdas | права на использование lambda | creation, view, modification, deletion |
| verify | права на выполнение запросов "perform verification" | (см. ниже) |
| video_stream | права на использование потоков | creation, view, modification, deletion |
| video_group | права на использование групп | creation, view, modification, deletion |
| video_analytic | права на просмотр аналитик | view |
| пользовательское | пользовательские права | creation, view, modification, deletion |
Пользовательские права предназначены для проксирования запросов LUNA Streams через LUNA API. В остальных случаях использование пользовательских прав не будет иметь эффекта. См. раздел "Проксирование запросов в LUNA Streams через LUNA API" в руководстве администратора FaceStream.
Ресурсы "/iso", "/sdk" и "/liveness" по умолчанию не требуют никакой авторизации.
Значение [] означает отсутствие всех разрешений.
Разрешения "emit_events" и "verify" позволяют указать можно ли выполнять запросы к ресурсу "generate events" или "perform verification", а также поместить идентификаторы обработчиков или верификаторов в черный или белый списки. Если идентификаторы "handler_id" или "verifier_id" присутствуют в черном списке, то только их использование будет запрещено. Если же идентификаторы присутствуют в белом списке, то только их использование будет разрешено. Максимальное количество идентификаторов в списках — 100. При использовании разрешения "emit_events" у пользователя не должно быть прав "creation" и "modification" на использование обработчика.
Если выдано разрешение "emit_events", то во время генерации события будут созданы все необходимые объекты независимо от разрешений, задаваемых в токене. Например, разрешение типа "faces" регулирует работу с лицами только в запросах к ресурсам "faces/*", но не влияет на создание лица во время генерации события. Таким образом, при использовании обработчика с параметром "store_face" и отсутствии права "creation" для "faces", все равно будет создано лицо.
Если выдано разрешение "verify", то во время выполнения верификации будут созданы все необходимые объекты независимо от разрешений, задаваемых в токене. Например, разрешение типа "sample" не влияет на создание биометрического образца во время выполнения верификации. Таким образом, при использовании верификатора с параметром "store_sample" и отсутствии права "creation" для "samples", все равно будет создан биометрический образец.
При задании разрешений следует учитывать следующие особенности:
- тип "modification" означает выполнение PATCH и PUT запросов
- прикрепление/открепление к списку является разрешением типа "modification"
- удаление списка с включенной настройкой "with_faces" (запрос "delete lists") требует разрешения "face" > "deletion"
- прикрепление лица к списку в запросе на создания лица (запрос "create face") требует разрешения "list" > "modification"
- при выполнении сравнения необходимо иметь разрешение "matching" для соответствующих объектов (event, face, attribute)
- запросы на получение статистики по событиям (запрос "get statistics on events") требуют разрешения "event" > "view"
- разрешение "event" > "create" дает право только на создание события с помощью запроса "save event". Для генерации события необходимо воспользоваться разрешением "emit_events" (см. выше)
- разрешение "event" > "create" не распространяется на верификаторы
См. таблицу зависимости разрешений токенов от ресурсов сервиса API в руководстве разработчика.
Просмотр данных других аккаунтов#
Данные другого аккаунта могут быть просмотрены если:
- тип аккаунта установлен как "advanced_user" или "admin"
- при создании токена был указан параметр "visibility_area" = "all".
Для типа аккаунта "user" нельзя задать "visibility_area" = "all".
Если установлен тип аккаунта "advanced_user"/"admin" и создается токен с установленным параметром "visibility_area" = "account", то при авторизации по токену (BearerAuth) пропадет возможность смотреть данные других аккаунтов, однако при авторизации по логину/паролю (BasicAuth), такая возможность останется.
Если установлен тип аккаунта "advanced_user"/"admin" и создан токен с установленным параметром "visibility_area" = "all", а затем тип аккаунта изменяется на "user" (с помощью запроса "patch account"), то при попытке выполнить запрос на просмотр данных других аккаунтов с помощью токена будет выдана ошибка.
При использовании авторизации LunaAccountIdAuth область видимости регулируется с помощью заголовка "Luna-Account-Id", что означает, что видны только данные аккаунта, связанного с этим идентификатором.
Для верификаторов недоступна возможность использования области видимости данных всех аккаунтов. При значении параметра "visibility_area" = "all", будет видны данные только своего аккаунта.
Типы авторизации для доступа к ресурсам#
В LUNA PLATFORM доступно три типа авторизации:
- BasicAuth. Авторизация по логину и паролю (задаются во время создания аккаунта).
- BearerAuth. Авторизация по JWT токену (выдается после создания токена).
- LunaAccountIdAuth. Авторизация по заголовку "Luna-Account-Id", в котором указывается сгенерированный после создания аккаунта "account_id". Данный способ считается устаревшим и не рекомендуется к использованию.
Авторизация LunaAccountIdAuth может быть включена с помощью настройки "ALLOW_LUNA_ACCOUNT_AUTH_HEADER" в секции "OTHER" настроек сервиса API в Configurator (по умолчанию отключена).
В спецификации OpenAPI заголовок "Luna-Account-Id" помечен словом Deprecated.
Нет необходимости в использовании всех трех типов авторизации при выполнении запросов. Необходимо выбрать предпочтительный способ в зависимости от требуемых задач.
Если в запросе не указан тип авторизации, будет выдаваться ошибка с кодом состояния 403.
Проверка актуальности учетной записи#
С помощью ресурса "verify credentials" можно проверять существующие учетные записи по одному из типов:
- верификация логина/пароля. Если верификация успешна – вернется идентификатор аккаунта и его тип.
- верификация токена. Если верификация успешна, вернется тип аккаунта и все разрешения для токена.
- верификация идентификатора аккаунта. Если верификация успешна – вернется тип аккаунта.
Логирование информации об аккаунтах#
При выполнении любого запроса, в логах сервиса API выводится информация о соответствующем аккаунте. Данный функционал позволяет определить кто именно выполнил тот или иной запрос. Это может потребоваться для информационной безопасности и администраторов систем.
Если запрос был выполнен с авторизацией типа BasicAuth или LunaAccountIdAuth, то в логах будет выдано следующее сообщение:
Request invoked by user (account_id: '270531af-e52e-4538-9181-628d9900a0db')
Если запрос был выполнен с авторизацией типа BearerAuth, то в логах будет выдано следующее сообщение:
Request invoked by user (account_id: '270531af-e52e-4538-9181-628d9900a0db' token_id: 'd57e16f5-e243-47d2-aa85-8b200c12d86f')
Если запрос был выполнен без авторизации, то в логах будет выдано следующее сообщение:
Request invoked by user (account_id: null)
В логах сервиса Accounts дополнительно выводится информация о создании токенов конкретными пользователями:
User with account_id: '270531af-e52e-4538-9181-628d9900a0db' create token: 'd57e16f5-e243-47d2-aa85-8b200c12d86f'
Логирование информации о создании токенов позволяет отследить откуда появился токен и какому пользователю он принадлежал, даже после его удаления.