Accounting¶
Accounts¶
Luna-API supports a data separation by accounts. An account is needed to delimit the visibility areas of objects for a particular user. Each created account has its own unique “account_id”. All data created by this account is stored in the Accounts database under this identifier.
When creating the account, you need to specify the following data: login (email), password and account type. The account type determines what data is available to the user. There are three types of accounts:
user - user who can create objects and use only the data of his account.
advanced_user - user who has rights same to user and also has access to the data of all accounts. Access to other accounts data means being able to get data (GET requests), check for its existence (HEAD requests) and perform matching requests by data of other accounts.
admin - administrator who has rights same to advanced_user and also has access to the Admin service. Administrator account creation is impossible using Luna-API. To create administrator account use Luna-Admin service.
By default, there is the account in the system with the admin type and default login and password root@example.com/root.
Restrictions on performed requests for all types of accounts are hard-coded in the system and cannot be changed. If you require restrictions other than the standard ones, you should create the “user” account and then create a token and configure the restrictions as required.
Tokens¶
The token is linked to the existing account and enables you to impose extended restrictions on performed requests. For example, when creating the token, you can give the user permission to only create and modify lists and faces, or you can prohibit the use of certain handlers by specifying their ID.
Note
See token coverage table for specific resources in the Token permissions section.
The token is created for a certain period of time (the token expiration time can be infinite).
Using the token, you can also control the visibility area of other accounts data using the “visibility_area” parameter (all - data of all accounts, account - data of this account only). For the user account type, you cannot set “visibility_area” = “all”.
Token permissions¶
The following table describes token permissions for Luna-API resources
*1 - face creation request requires list modification permission if one or more lists specified in request body
*2 - list/lists deletion requests requires face deletion permissions if with_faces parameter specified
*3 - face matching request requires face/event/attribute matching permissions if face/event/attribute candidates/references specified in request body
*4 - body matching request requires event matching permissions if event candidates/references specified in request body
- *5 - The “emit_events” permission enables you to specify whether requests can be made to
the generate events resource, as well as blacklisting or whitelisting handler IDs. If handler IDs are blacklisted, then only their use will be prohibited. If handler IDs are present in the white list, then only their use will be allowed. When using the “emit_events” permission, the user must not have the “creation” and “modification” rights to use the handler.
- *6 - The “verify” permission enables you to specify whether requests can be made to
raw verification and perform verification resources, as well as blacklisting or whitelisting verifier IDs. If verifier IDs are blacklisted, then only their use will be prohibited. If verifier IDs are present in the white list, then only their use will be allowed.
- *7 - The “service_usage” permission enables you to specify whether request can be made to
service proxy. proxy post, proxy get, proxy put, proxy head, proxy options, proxy patch, proxy delete,. If service names are blacklisted, then only their use will be prohibited. If service names are present in the white list, then only their use will be allowed.
Optional accounts¶
The luna-accounts service is optional. To disable it, see ADDITIONAL_SERVES_USAGE.luna_accounts setting . With luna-accounts disabled authorization will be performed via service configuration. To perform that the CONFIG_AUTHORIZATION_USERS setting must contain list of accounts and it`s tokens that can be used in requests authorization. Account and it’s tokens for this setting can be created by /generator resource of luna-accounts service. Note that this approach is not secure and only serves as workaround for existing product logic.
- After disabling luna-accounts next resources will be unavailable:
- A logic of several resources will be adjusted if service Luna Accounts is disabled.
Authorization modules¶
Module
- class luna_api.app.auth.white_resources_list.AuthIgnoreList[source]¶
White lists for ui authorization
- class luna_api.app.auth.white_resources_list.LunaAccountIdWhiteLists[source]¶
White lists for authorization with Luna-Account-Id header .. warning:: Authorization with Luna-Account-Id header is deprecated
- class luna_api.app.auth.white_resources_list.WhiteLists[source]¶
White lists for authorization with basic/bearer authorization header
Authorization middleware
- async luna_api.app.auth.auth_middleware.authMiddleware(request)[source]¶
Authorization middleware, check a request account id
- Parameters:
request (
ApiRequest) – request
- luna_api.app.auth.auth_middleware.checkCredentialsRights(verificationRequestKwargs, requestCredentials, request)[source]¶
Verify request credentials rights :type verificationRequestKwargs:
VerificationRequestKwargs:param verificationRequestKwargs: verification request kwargs (authorization data from headers) :type requestCredentials:RequestCredentials:param requestCredentials: credentials for request :type request:ApiRequest:param request: api request- Raises:
VLException(Error.AccountTokenPermissionError, 403, False) if specified token supposed access to any data, but – account type is user (does not imply access to other accoounts data)
VLException(Error.AccountQueryPermissionError, 403, False) if account type is user but specified query – parameter account_id (imply as data filter in other luna-* services) does not match the account id from authorization/Luna-Account-Id header
- luna_api.app.auth.auth_middleware.checkVerificationKwargs(request, verificationRequestKwargs)[source]¶
Check verification kwargs according due to request path, method and system configuration :type request:
ApiRequest:param request: api request :type verificationRequestKwargs:VerificationRequestKwargs:param verificationRequestKwargs: verification kwargs- Raises:
VLException(Error.BadHeaderAuth, 401, False) if no verification kwargs specified, service allows to use – Luna-Account-Id header and request required credentials
VLException(Error.BadHeaderAuth, 401, False) if no verification kwargs specified, service not allows use – Luna-Account-Id header and request required credentials
VLException(Error.PermissionByTokenDenied, 403, False) if token kwargs specified, but request path and/or – method not allows access using token
VLException(Error.AccountIdAuthDisabled, 403, False) if Luna-Account-Id header if specified, but service – not allows use Luna-Account-Id header
- Return type:
None
- luna_api.app.auth.auth_middleware.getAuthenticationHeader(sendBasicAuthInfo=True, setCookieHeader=False)[source]¶
Get authentication header for 401 response :type sendBasicAuthInfo:
bool:param sendBasicAuthInfo: whether to send basic auth info, otherwise bearer :type setCookieHeader:bool:param setCookieHeader: cookie header flag- Return type:
dict[str,str]- Returns:
dict with headers
- luna_api.app.auth.auth_middleware.getDecodedToken(verificationKwargs, logger)[source]¶
Get decoded token
- Parameters:
verificationKwargs (
VerificationRequestKwargs) – request credentials to verifylogger (
Logger) – logger
- Return type:
dict- Returns:
decoded token data
- Raises:
VLException(Error.CorruptedToken) if failed to decode token –
- async luna_api.app.auth.auth_middleware.getRequestCredentials(verificationKwargs, request, ignoreAuthError=False)[source]¶
Verify and get request credentials :type verificationKwargs:
VerificationRequestKwargs:param verificationKwargs: keyword arguments for credentials verification request :type request:ApiRequest:param request: api request :type ignoreAuthError:bool:param ignoreAuthError: whether to ignore authorization credentials verification error- Return type:
RequestCredentials- Returns:
verified request credentials
- Raises:
VLException(Error.CorruptedToken, 400, False) if failed to decode jwt token –
- luna_api.app.auth.auth_middleware.getVerificationRequestKwargs(request)[source]¶
Get kwargs for credentials verification from request :type request:
ApiRequest:param request: api request- Return type:
VerificationRequestKwargs- Returns:
kwargs for credentials verification
- Raises:
VLException(Error.BadAccountId, 400, isCriticalError=False) if specified Luna-Account-Id header content – does not match expected
VLException(Error.AccountIdAuthDisabled, 403, False) if Luna-Account-Id specified, but disabled by config –
- luna_api.app.auth.auth_middleware.ignoreAuthError(request)[source]¶
Ignore auth error
- Parameters:
request (
ApiRequest) – request- Return type:
bool- Returns:
ignoreAuthError flag
- luna_api.app.auth.auth_middleware.logWhoIsRequestBelong(logger, verificationKwargs)[source]¶
Log auth info who is request belong :type logger:
Logger:param logger: logger :type verificationKwargs:VerificationRequestKwargs:param verificationKwargs: verification kwargs- Return type:
None
- luna_api.app.auth.auth_middleware.morphRequest(request, requestCredentials, verificationRequestKwargs)[source]¶
Morph request query/json/headers according to request method and request credentials :type request:
ApiRequest:param request: api request :type requestCredentials:RequestCredentials:param requestCredentials: verified request credentials :type verificationRequestKwargs:VerificationRequestKwargs:param verificationRequestKwargs: verification request kwargs- Return type:
None