Accounts, tokens and authorization types#
Account#
An account is required to delimit the visibility areas of objects for a particular user. The account is necessary to perform most of the requests. Each created account has its own unique "account_id". All account data is stored in the Accounts service database under this ID.
The account can be created using a POST request "create account" to the API service, or using the Admin service . When creating the account, you must specify the following data: login (email), password and account type.
Account type#
The account type determines what data is available to the user.
There are three types of accounts:
- user - the type of account with which you can create objects and use only your account data.
- advanced_user - the type of account for which rights similar to "user" are available, and there is access to the data of all accounts. Access to data from other accounts means the ability to receive data (GET requests), check their availability (HEAD requests) and perform comparison requests based on data from other accounts.
- admin - the type of account for which rights similar to "advanced_user" are available, and there is also access to the Admin service.
In the API service, you can work with all types of accounts, but only "advanced_user" and "user" types of accounts can be created, while in the Admin service you can create all three types.
By default, there is the "admin" type account in the system with the default login and password root@visionlabs.ai/root.
Using the header "Luna-Account-Id" in the "create account" request you can set the desired account ID. It should also be used if it is necessary to preserve the ability to work with data created in LP versions prior to 5.30.0 by specifying the "account_id" in the "Luna-Account-Id" header. Thus, using this parameter will link the old "account_id" to the account being created (See "Account migration" section in the LUNA PLATFORM upgrade manual for details on migration).
In response to a request to create the account, "account_id" is issued. After creating the account, you can use this ID for LunaAccountIdAuth authorization type or use BasicAuth authorization type (login/password authorization).
Token#
Token is linked to an existing account with any type ("user", "advanced_user", "admin") and enables you to impose extended restrictions on the requests being made. For example, when creating the token, you can give the user permission only to create and modify all lists and faces, or you can prevent the use of certain handlers by specifying their ID.
The token is created using the "create token" request to the API service.
An unlimited number of tokens can be created for each account. The token and all its restrictions are stored in the database and linked to the account by the "account_id" parameter. You cannot link one token to different accounts. To create tokens with the same permissions across different accounts, it is recommended to save the request body template for creating the account and use it.
There is no need to use both the token and the account. When working with tokens, you can restrict access to the "/accounts" resource using external means.
You can give additional restrictions on the token at any time using the "replace token" request or you can revoke the token using the "delete token" request. In this case, the token will be deleted from the database and can no longer be used for authorization.
When creating the token, you need to set the following parameters:
- expiration_time – expiration time of the token in the RFC 3339 format. You can specify an infinite token expiration time using the value "null"
- permissions – actions that the user can perform (see "Permissions set in token")
You can also specify whether the token is visible to other accounts data using the "visibility_area" parameter (see the "Viewing other account data" section).
The response to the request is "token_id" and a Base64 encoded JWT token. After creating the token, you can use the received JWT token for BearerAuth authorization type.
Permissions set in token#
The following permissions are available for the generated token:
| Permission name | Permission description | Rights |
|---|---|---|
| face | rights to use the face | creation, view, modification, deletion, matching |
| list | rights to use the list | creation, view, modification, deletion |
| event | rights to use the event | creation (only "save event" request), view, matching |
| attribute | rights to use the attribute | creation, view, modification, deletion, matching |
| handler | rights to use the handler | creation, view, modification, deletion |
| verifier | rights to use the verifier | creation, view, modification, deletion |
| task | rights to use the task | creation, view, modification, deletion |
| face_sample | rights to use the face sample | creation, view, deletion |
| body_sample | rights to use the body sample | creation, view, deletion |
| object | rights to use the object | creation, view, deletion |
| image | rights to use the image | creation, view, deletion |
| token | rights to use the token | view, modification, deletion |
| resource | rights to use resources | "/iso", "/sdk", "/liveness" |
| emit_events | permissions to perform "generate events" requests | (see below) |
Resources "/iso", "/sdk" and "/liveness" do not require any authorization by default.
The value [] means no permissions.
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. The maximum number of IDs in the lists is 100. When using the "emit_events" permission, the user must not have the "creation" and "modification" rights to use the handler.
If the "emit_events" permission is granted, then all necessary objects will be created during the generation of the event, regardless of the permissions specified in the token. For example, the "faces" type permission regulates work with faces only in requests to "faces/*" resources, but does not affect the creation of the face during event generation. Thus, when using the handler with the "store_face" parameter and not having the "creation" permission for "faces", the face will still be created.
- the "modification" permission means performing of PATCH and PUT requests
- linking/unlinking face to list is the "modification" permission
- deleting list with "with_faces" setting enabled ("delete lists" request) requires "face" > "deletion" permission
- linking face to list in the "create face" request requires "list" > "modification" permission
- when performing matching, you should have the "matching" permission for the corresponding objects (event, face, attribute)
- requests to "get statistics on events" resource require "event" > "view" permission
- permission "event" > "create" only grants the right to create an event using the "save event" request. To generate an event, you should use the "emit_events" permission (see above)
- permission "event" > "create" does not apply to verifiers
See the token coverage table for specific resources in the developer manual of the API service.
Viewing other account data#
Other account details can be viewed if:
- account type is set to "advanced_user" or "admin"
- when creating the token, the "visibility_area" = "all" parameter was specified.
Account type "user" cannot be set to "visibility_area" = "all".
If the account type is set to "advanced_user"/"admin" and the token is created with the "visibility_area" = "account" parameter set, then when logging in using the token (BearerAuth) you will no longer be able to view data from other accounts, but when logging in using login/password (BasicAuth), this option will remain.
If the account type is set to "advanced_user"/"admin" and the token is created with "visibility_area" set to "all" and then the account type is changed to "user" (using the "patch account" request), then an attempt to perform a request to view the data of other accounts using the token will result in an error.
When using the LunaAccountIdAuth authorization, the visibility area is controlled using the "Luna-Account-Id" header.
For verifiers, the ability to use the visibility area of all accounts is not available. If the "visibility_area" = "all", only the data of your account will be visible.
Authorization types for accessing resources#
There are three types of authorization available in LUNA PLATFORM:
- 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 method was adopted as the main one before version 5.30.0).
LunaAccountIdAuth authorization has the lowest priority compared to other methods and can be disabled using the "ALLOW_LUNA_ACCOUNT_AUTH_HEADER" setting in the "OTHER" section of the API service settings in the Configurator (enabled by default).
In OpenAPI specification the "Luna-Account-Id" header is marked with the word Deprecated.
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.
If the authorization type is not specified in the request, an error with the status code 403 will be issued.
Credentials verifier#
Using the "verify credentials" resource, you can verify existing credentials by one of the types:
- login/password verification. If verification is successful, the "account_id" and account type will be returned.
- token verification. If verification is successful, the account type and all permissions for the token will be returned.
- account ID verification. If verification is successful, the account type will be returned.
Logging account information#
When executing any request, information about the corresponding account is displayed in the logs of the API service. This functionality enables you to determine who exactly executed a particular request. This may be required for information security and system administrators.
If the request was executed with BasicAuth or LunaAccountIdAuth type authorization, the following message will be displayed in the logs:
Request invoked by user (account_id: '270531af-e52e-4538-9181-628d9900a0db')
If the request was executed with BearerAuth type authorization, the following message will be displayed in the logs:
Request invoked by user (account_id: '270531af-e52e-4538-9181-628d9900a0db' token_id: 'd57e16f5-e243-47d2-aa85-8b200c12d86f')
If the request was executed without authorization, the following message will be displayed in the logs:
Request invoked by user (account_id: null)
The logs of the Accounts service additionally display information about the creation of tokens by specific users:
User with account_id: '270531af-e52e-4538-9181-628d9900a0db' create token: 'd57e16f5-e243-47d2-aa85-8b200c12d86f'
Logging information about the creation of tokens enables you to track where the token came from and which user it belonged to, even after it was deleted.