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:

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.

LDAP directory integration

YDB supports authentication and authorization via an LDAP directory. To use this feature, an LDAP directory service must be deployed and accessible from the YDB servers.

Examples of supported LDAP implementations include OpenLDAP and Active Directory.

Authentication

Authentication using the LDAP protocol is similar to the static credentials authentication process (using a login and password). The difference is that the LDAP directory acts as the authentication component. The LDAP directory is used solely to verify the login/password pair.

Note

Since the LDAP directory is an external, independent service, YDB cannot manage user accounts within it. For successful authentication, the user must already exist in the LDAP directory. The commands CREATE USER, CREATE GROUP, ALTER USER, ALTER GROUP, DROP USER, and DROP GROUP do not affect the list of users and groups in the LDAP directory. Information on managing accounts should be found in the documentation for the specific LDAP directory implementation in use.

Currently, YDB supports only one method of LDAP authentication, known as the search+bind method, which involves several steps. Upon receiving the username and password of the user being authenticated, a bind operation is performed using the credentials of a special service account specified in the ldap_authentication section. These credentials are defined by the bind_dn and bind_password configuration parameters. After the service account is successfully authenticated, a search is conducted in the LDAP directory for the user attempting to authenticate in the system. The search operation is performed across the entire subtree rooted at the location specified by the base_dn configuration parameter and uses the filter defined in the search_filter configuration parameter.

Once the user entry is found, YDB performs another bind operation using the found user's entry and the password provided earlier. The success of this second bind operation determines whether the user authentication is successful.

After successful authentication, a token is generated. This token is then used in place of the username and password, speeding up the authentication process and enhancing security.

Note

When using LDAP authentication, no user passwords are stored in YDB.

Token verification

After a user is authenticated in the system, a token is generated and verified before executing the requested operation. During the token verification process, the system determines on whose behalf the action is being requested and identifies the groups the user belongs to. For users from the LDAP directory, the token does not include information about group memberships. Therefore, after the token is verified, an additional query is made to the LDAP server to retrieve the list of groups the user is a member of.

Groups, like users, are entities that can have assigned access rights to perform operations on database schema objects and other resources. These assigned rights determine which operations a user is authorized to perform.

The process of retrieving a user's group list from an LDAP directory is similar to the steps taken during authentication. First, a bind operation is performed using the service user credentials specified by the bind_dn and bind_password parameters in the ldap_authentication section of the configuration file. After successful authentication, a search is conducted for the user entry associated with the previously generated token. This search uses the search_filter parameter. If the user still exists, the result of the search operation will be a list of attribute values specified by the requested_group_attribute parameter. If this parameter is not set, the memberOf attribute is used as the default for reverse group membership. The memberOf attribute contains the distinguished names (DNs) of the groups to which the user belongs.

By default, YDB only searches for groups in which the user is a direct member. However, by enabling the extended_settings.enable_nested_groups_search flag in the ldap_authentication section, YDB will attempt to retrieve groups at all levels of nesting, not just those the user directly belongs to. If YDB is configured to work with Active Directory, the Active Directory-specific matching rule LDAP_MATCHING_RULE_IN_CHAIN will be used to find all nested groups. This rule allows for the retrieval of all nested groups with a single query. For LDAP servers based on OpenLDAP, group searches will be conducted using recursive graph traversal, which generally requires multiple queries. In both Active Directory and OpenLDAP configurations, the group search is performed only within the subtree specified by the base_dn parameter.

Note

In the current implementation, the group names that YDB uses match the values stored in the memberOf attribute. These names can be long and difficult to read.

Example:

cn=Developers,ou=Groups,dc=mycompany,dc=net@ldap

Note

In the configuration file section that specifies authentication information, the refresh rate for user and group information can be set using the refresh_time parameter. For more detailed information about configuration files, refer to the cluster configuration section.

Warning

It should be noted that currently, YDB does not have the capability to track group renaming on the LDAP server side. Consequently, a group with a new name will not retain the rights assigned to the group under its previous name.

LDAP users and groups in YDB

Since YDB supports various methods of user authentication (login and password authentication, IAM provider usage, LDAP directory), it is often helpful to identify the specific source of authentication when handling user and group names. For all authentication types except login and password, a suffix in the format <username>@<domain> is appended to user and group names.

For LDAP users, the <domain> is determined by the ldap_authentication_domain configuration parameter in the configuration section. By default, this parameter is set to ldap, so all usernames authenticated through the LDAP directory, as well as their corresponding group names in YDB, will follow this format:

  • user1@ldap
  • group1@ldap
  • group2@ldap

Warning

To indicate that the entered login should be recognized as a username from the LDAP directory, rather than for login and password authentication, you need to append the LDAP authentication domain suffix. This suffix is specified through the ldap_authentication_domain configuration parameter.

Below are examples of authenticating the user user1 using the YDB CLI:

  • Authentication of a user from the LDAP directory: ydb --user user1@ldap -p ydb_profile scheme ls
  • Authentication of a user using the internal YDB mechanism: ydb --user user1 -p ydb_profile scheme ls

TLS connection

Depending on the specified configuration parameters, YDB can establish either an encrypted or unencrypted connection. An encrypted connection with the LDAP server is established using the TLS protocol, which is recommended for production clusters. There are two ways to enable a TLS connection:

  • Automatically via the ldaps connection scheme.
  • Using the StartTls LDAP protocol extension*.

When using an unencrypted connection, all data transmitted in requests to the LDAP server, including passwords, will be sent in plain text. This method is easier to set up and is more suited for experimentation or testing purposes.

LDAPS

To have YDB automatically establish an encrypted connection with the LDAP server, the scheme value in the configuration parameter should be set to ldaps. The TLS handshake will be initiated on the port specified in the configuration. If no port is specified, the default port 636 will be used for the ldaps scheme. The LDAP server must be configured to accept TLS connections on the specified ports.

LDAP protocol extension StartTls

StartTls is an LDAP protocol extension that enables message encryption using the TLS protocol. It allows a combination of encrypted and plain-text message transmission within a single connection to the LDAP server. YDB sends a StartTls request to the LDAP server to initiate a TLS connection. In YDB, enabling or disabling TLS within an active session is not supported. Therefore, once an encrypted connection is established using StartTls, all subsequent messages sent to the LDAP server will be encrypted. One advantage of using this extension, provided the LDAP server is appropriately configured, is the capability to initiate a TLS connection over an unencrypted port. The extension can be enabled in the use_tls section of the configuration file.

Previous
Connecting to a database
Next
Data model and schema