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@visionlabs.ai/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”.

Authorization to access resources

To make requests to Luna-API resources, authorization should be specified.

There are three types of authorization:

  • BasicAuth. Authorization by login and password (set during account creation).

  • BearerAuth. Authorization by JWT token (issued after the token is created).

  • LunaAccountIdAuth. Authorization by “Luna-Account-Id” header, which specifies the “account_id” generated after creating the account (this type of authorization was used as the only one until LP version v.5.29.0).

There is no need to use all three types of authorization when making requests. It is necessary to choose the preferred method depending on the required tasks.

Note

Authorization type LunaAccountIdAuth has the lowest priority compared to other types and marked as Deprecated in the OpenAPI specification. You can disable authorization of the LunaAccountIdAuth type using the ALLOW_LUNA_ACCOUNT_AUTH_HEADER setting. The setting is enabled by default.

When using the LunaAccountIdAuth, the visibility area is controlled using the Luna-Account-Id header, i.e. only the data of the account associated with this ID is visible.

If the authorization type is not specified in the request, an error with the status code 403 will be issued.

Token permissions

The following table describes token permissions for Luna-API resources

route

method

token permissions

/6/accounts

get

accounts - view

/6/account

get

account - view

/6/tokens

post

token - creation

get

token - view

/6/tokens/{token_id}

put

token - modification

get

token - view

delete

token - deletion

/6/sdk

post

resource - sdk

/6/iso

post

resource - iso

/6/samples/faces

post

faceSample - creation

/6/samples/faces/{sample_id}

get

faceSample - view

head

faceSample - view

delete

faceSample - deletion

/6/samples/bodies

post

bodySample - creation

/6/samples/bodies/{sample_id}

get

bodySample - view

head

bodySample - view

delete

bodySample - deletion

/5/samples/{sample_id}

get

faceSample - view

head

faceSample - view

delete

faceSample - deletion

/6/samples/{sample_id}

get

faceSample - view

head

faceSample - view

delete

faceSample - deletion

/6/extractor

post

attrbiute - creation

/6/attributes

post

attribute - creation

get

attribute - view

/6/attributes/{attribute_id}

get

attribute - view

head

attribute - view

delete

attribute - deletion

/6/attributes/{attribute_id}/samples

get

attribute - view

/6/faces

post

face - creation & list - modification *1

get

face - view

delete

face - deletion

/6/faces/count

get

face - view

/6/faces/attributes/count

get

attribute - view

/6/faces/{face_id}

get

face - view

patch

face - modification

delete

face - deletion

head

face - view

/6/faces/{face_id}/attributes

put

face - creation

get

face - view

delete

face - deletion

/6/faces/{face_id}/attributes/samples

get

faceSample - view

/6/lists

post

list - creation *2

get

list - view

delete

list - deletion *2

/6/lists/count

get

list - view

/6/lists/{list_id}

get

list - view

head

list - view

patch

list - modification

delete

list - deletion

/6/lists/{list_id}/faces

patch

list - modification

/6/matcher/faces

post

face/event/attribute - matching *3

/6/matcher/bodies

post

event - matching *4

/6/handlers

post

handler - creation

get

handler - view

/6/handlers/count

get

handler - view

/6/handlers/{handler_id}

get

handler - view

put

handler - modification

head

handler - view

delete

handler - deletion

/6/handlers/{handler_id}/events

post

event - emit_events *5

/6/handlers/{handler_id}/stream_events

post

event - emit_events *5

/6/handlers/{handler_id}/events/raw

post

event - creation

/6/events/statistic

post

event - view

/6/events

get

event - view

/6/events/{event_id}

get

event - view

head

event - view

/6/tasks/clustering

post

task - creation

/6/tasks/reporter

post

task - creation

/6/tasks/exporter

post

task - creation

/6/tasks/linker

post

task - creation

/6/tasks/gc

post

task - creation

/6/tasks/cross_match

post

task - creation

/6/tasks/roc

post

task - creation

/6/tasks/estimator

post

task - creation

/6/tasks

get

task - view

/6/tasks/count

get

task - view

/6/tasks/{task_id}

get

task - view

patch

task - modification

delete

task - deletion

/6/tasks/{task_id}/result

get

task - view

/6/tasks/{task_id}/subtasks

get

task - view

/6/tasks/{task_id}/notification_policy

get

task - view

put

task - modification

/6/tasks/{task_id}/errors

get

task - view

/6/tasks/errors

get

task - view

/6/tasks/errors/count

get

task - view

/6/tasks/errors/{error_id}

get

task - view

/6/verifiers

post

verifier - creation

get

verifier - view

/6/verifiers/count

get

verifier - view

/6/verifiers/{verifier_id}

get

verifier - view

put

verifier - modification

head

verifier - view

delete

verifier - deletion

/6/liveness

post

resource - liveness

/6/images

post

image - creation

/6/images/{image_id}

get

image - view

head

image - view

delete

image - deletion

/6/objects

post

object - creation

/6/objects/{object_id}

get

object - view

head

object - view

delete

object - deletion

*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.

Authorization modules

Module .. attribute:: LunaAccountIdWhiteLists

storage with white lists for authorization with Luna-Account-Id header

luna_api.app.auth.white_resources_list.WhiteLists[source]

storage with white lists for authorization with basic/bearer authorization header

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 – request

luna_api.app.auth.auth_middleware.checkCredentialsRights(verificationRequestKwargs, requestCredentials, request)[source]

Verify request credentials rights :param verificationRequestKwargs: verification request kwargs (authorization data from headers) :param requestCredentials: credentials for request :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 :param request: api request :param verificationRequestKwargs: verification kwargs

Raises:
  • VLException(Error.BadHeaderAuth, 401, False) if no verification kwargs specified, service allows to useLuna-Account-Id header and request required credentials

  • VLException(Error.BadHeaderAuth, 401, False) if no verification kwargs specified, service not allows useLuna-Account-Id header and request required credentialst

  • 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)[source]

Get authentication header for 401 response :param sendBasicAuthInfo: whether to send basic auth info, otherwise bearer

Returns:

dict with WWW-Authenticate

Return type:

dict[str, str]

async luna_api.app.auth.auth_middleware.getRequestCredentials(verificationKwargs, request)[source]

Verify and get request credentials :param verificationKwargs: keyword arguments for credentials verification request :param request: api request

Returns:

verified request credentials

Raises:

VLException(Error.CorruptedToken, 400, False) if failed to decode jwt token

Return type:

RequestCredentials

luna_api.app.auth.auth_middleware.getVerificationRequestKwargs(request)[source]

Get kwargs for credentials verification from request :param request: api request

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

Return type:

VerificationRequestKwargs

luna_api.app.auth.auth_middleware.logWhoIsRequestBelong(logger, verificationKwargs)[source]

Log auth info who is request belong :param logger: logger :param verificationKwargs: verification kwargs

Return type:

None

luna_api.app.auth.auth_middleware.morphRequest(request, requestCredentials)[source]

Morph request query/json/headers according to request method and request credentials :param request: api request :param requestCredentials: verified request credentials

Return type:

None

async luna_api.app.auth.auth_middleware.verifyCredentials(accountsClient, verificationKwargs)[source]

Verify credentials :param accountsClient: account client :param verificationKwargs: authorization credentials

Returns:

dictionary with account-type and permissions (for token validation only)

Return type:

dict