Authentication

Once a network connection is established, the server starts to accept client requests with authentication information for processing. The server uses it to identify the client's account and to verify access to execute the query.

The following authentication modes are supported:

• Anonymous access is enabled by default and available immediately when you install the cluster.
• Authentication through a third-party IAM provider, for example, Yandex Identity and Access Management.
• Authentication by username and password.

Authentication through a third-party IAM provider

• Anonymous: Empty token passed in a request.
• Access Token: Fixed token set as a parameter for the client (SDK or CLI) and passed in requests.
• Refresh Token: OAuth token of a user's personal account set as a parameter for the client (SDK or CLI), which the client periodically sends to the IAM API in the background to rotate a token (obtain a new one) to pass in requests.
• Service Account Key: Service account attributes and a signature key set as parameters for the client (SDK or CLI), which the client periodically sends to the IAM API in the background to rotate a token (obtain a new one) to pass in requests.
• Metadata: Client (SDK or CLI) periodically accesses a local service to rotate a token (obtain a new one) to pass in requests.
• OAuth 2.0 token exchange - The client (SDK or CLI) exchanges a token of another type for an access token using the OAuth 2.0 token exchange protocol, then it uses the access token in YDB API requests.

Any owner of a valid token can get access to perform operations; therefore, the principal objective of the security system is to ensure that a token remains private and to protect it from being compromised.

Authentication modes with token rotation, such as Refresh Token and Service Account Key, provide a higher level of security compared to the Access Token mode that uses a fixed token, since only secrets with a short validity period are transmitted to the YDB server over the network.

The highest level of security and performance is provided when using the Metadata mode, since it eliminates the need to work with secrets when deploying an application and allows accessing the IAM system and caching a token in advance, before running the application.

When choosing the authentication mode among those supported by the server and environment, follow the recommendations below:

• You would normally use Anonymous on self-deployed local YDB clusters that are inaccessible over the network.
• You would use Access Token when other modes are not supported on server side or for setup/debugging purposes. It does not require that the client access IAM. However, if the IAM system supports an API for token rotation, fixed tokens issued by this IAM usually have a short validity period, which makes it necessary to update them manually in the IAM system on a regular basis.
• Refresh Token can be used when performing one-time manual operations under a personal account, for example, related to DB data maintenance, performing ad-hoc operations in the CLI, or running applications from a workstation. You can manually obtain this token from IAM once to have it last a long time and save it in an environment variable on a personal workstation to use automatically and with no additional authentication parameters on CLI launch.
• Service Account Key is mainly used for applications designed to run in environments where the Metadata mode is supported, when testing them outside these environments (for example, on a workstation). It can also be used for applications outside these environments, working as an analog of Refresh Token for service accounts. Unlike a personal account, service account access objects and roles can be restricted.
• Metadata is used when deploying applications in clouds. Currently, this mode is supported on virtual machines and in Cloud Functions Yandex.Cloud.

The token to specify in request parameters can be obtained in the IAM system that the specific YDB deployment is associated with. In particular, YDB in Yandex.Cloud uses Yandex.Passport OAuth and Yandex.Cloud service accounts. When using YDB in a corporate context, a company's standard centralized authentication system may be used.

When using modes in which the YDB client accesses the IAM system, the IAM URL that provides an API for issuing tokens can be set additionally. By default, existing SDKs and CLIs attempt to access the Yandex.Cloud IAM API hosted at iam.api.cloud.yandex.net:443.

Authenticating by username and password

Authentication by username and password includes the following steps:

1. The client accesses the database and presents their username and password to the YDB authentication service.

   You can only use lower case Latin letters and digits in usernames. No restrictions apply to passwords (empty passwords can be used).

2. The authentication service passes authentication data to the YDB authentication component.

3. The component validates authentication data. If the data matches, it generates a token and returns it to the authentication service.

   Tokens accelerate authentication and strengthen security. Tokens have a default lifetime of 12 hours. YDB SDK rotates tokens by accessing the authentication service.

   The username and hashed password are stored in the table inside the authentication component. The password is hashed by the Argon2 method. In authentication mode, only the system administrator can use a username/password pair to access the table.

4. The authentication system returns the token to the client.

5. The client accesses the database, presenting their token as authentication data.

To enable username/password authentication, use true in the enforce_user_token_requirement key of the cluster's configuration file.

To learn how to manage roles and users, see Access management.