Authentication

After a network connection is successfully established, the server accepts requests from the client for processing. Authentication information is transmitted as an authentication token or a client certificate. Based on it, the server determines the client's SID and checks its permissions to execute the request.

The following authentication types are supported:

• Anonymous authentication.
• Authentication by login and password.
• Authentication using an LDAP directory.
• Authentication using an external identity provider via the OpenID Connect protocol.
• Authentication by client certificate.
• Authentication using a third-party IAM provider, for example Yandex Identity and Access Management.

Anonymous authentication

By default, YDB allows executing requests without specifying authentication data, such as a username or token. Access rights verification (authorization) is also not performed in this case.

The enforce_user_token_requirement flag in the authentication mode settings of YDB is responsible for disabling anonymous authentication.

Depending on the authentication mode settings, the actual authentication may not be anonymous:

• A token missing from requests may be replaced with a default token.
• A token explicitly specified in requests may be checked according to the appropriate rules.

Then requests will be executed non-anonymously, and permission checks will also be performed.

Depending on the access level settings, anonymous requests may also perform actions in the system that require administrative access level.

Authentication by login and password

Authentication by login and password via the YDB server is available only for local users. External user authentication involves servers of external systems.

This type of access implies that each database user has a login and password. A user's login may contain only lowercase Latin letters, digits, and the @ character. Various criteria for password complexity may be established.

User login and password hash are stored in a table inside the authentication component. The password is hashed using the Argon2 method. Only the system administrator has access to this table.

In response to the login and password, an authentication token is returned. The default token lifetime is 12 hours. For token rotation, the client, for example, SDK, independently contacts the authentication service. Using a token speeds up the authentication process and improves security.

The login and password authentication process includes the following steps:

1. The client contacts the database and passes the user's login and password to the authentication service YDB.
2. The service verifies the authentication data, and upon successful matching, creates a token and returns it to the client.
3. The client contacts the database, passing the token as authentication information.

To enable login and password authentication, make sure that the parameters use_login_provider and enable_login_authentication are set to the default value true in the configuration. Additionally, to disable anonymous authentication, set the value of the parameter enforce_user_token_requirement to true.

For information about managing roles and users, see Authorization.

Password complexity

YDB allows you to configure password complexity requirements. If the password provided via the CREATE USER or ALTER USER commands does not meet the complexity criteria, the command execution will fail.
By default, no restrictions are imposed on passwords: a password of any length is accepted, including an empty string; the password may contain any number of digits and letters in any case, as well as special characters from the list !@#$%^&*()_+{}|<>?=. To set password complexity restrictions, you need to fill in the password_complexity section in the configuration.

Forced user lock/unlock

There is another way to prevent a user from authenticating: forced blocking by a cluster or database administrator. Administrators can unblock both users who were forcibly blocked and users who were blocked due to exceeding the limit on the number of incorrect password attempts. Detailed information about forced blocking and unblocking of users can be found in the description of the ALTER USER LOGIN/NOLOGIN command.

Password brute-force protection

YDB provides protection against password brute force by the user. A user will be considered blocked if they exceed the number of incorrect password attempts. After the specified time expires, they will be able to authenticate again.

By default, the user is given 4 attempts to enter the correct password. Otherwise, authentication will be blocked for them for one hour. You can configure user blocking criteria in the configuration.

If necessary, the cluster or database administrator can unblock the user ahead of schedule.

Information about the user's lock status and the number of incorrect password entry attempts can be found in the user's system view.

Authentication using an LDAP directory

YDB integrates interaction with the LDAP directory. The LDAP directory is external to the YDB service and is used for authenticating and authorizing database users. Before using this method of authentication and authorization, you must have a deployed LDAP service and configured network access between it and the YDB servers.

Examples of supported LDAP directory implementations: OpenLdap, Active Directory.

Authentication

Authentication using the LDAP protocol is similar to the login and password authentication process. The only difference is that the LDAP directory plays the role of the authentication component. The LDAP directory is used to verify the login/password pair and to determine the groups to which the user belongs.

Currently, YDB supports only one method of LDAP user authentication — search+bind: after receiving the login and password, a service bind is performed on behalf of the service account (login and password in bind_dn / bind_password, or a certificate and SASL EXTERNAL — see configuration), then a search for the user record and a second bind on behalf of the user.

The service account credentials for connecting to LDAP are specified in the configuration settings: use the bind_dn and bind_password parameters, or configure mTLS (for details, see the section Service account authentication).

The authentication process then proceeds as follows:

1. YDB connects to LDAP on behalf of the service account.
2. After a successful connection, a search is performed for the user attempting to authenticate. The search runs across the entire subtree specified in the configuration parameter base_dn and by the filter specified in the parameter search_filter.
3. If the user is found, YDB performs a repeated bind operation — now on behalf of the found user, using their password.
4. The final result — successful or unsuccessful authentication — is determined by the result of the second bind (on behalf of the user).

Thus, YDB does not store user passwords and fully relies on the LDAP authentication mechanism.

Upon successful verification of the user's login and password in the LDAP directory, YDB returns an authentication token. This token is then used instead of the login and password. Using the token speeds up the authentication process and improves security.

Service account authentication

A service account can be authenticated in two main ways:

• Using a login and password.
  In this case, you need to specify the login (bind_dn) and password (bind_password) in the configuration. These parameters will be used to connect to the LDAP server on behalf of the service account.
• Using mTLS (mutual TLS) via the SASL EXTERNAL mechanism.
  In this option, certificates are used for authentication instead of a login and password. This allows you not to store the service account password in the configuration — you only need to specify the certificate file (use_tls.cert_file) and private key file (use_tls.key_file), as well as enable a special flag (extended_settings.enable_sasl_external_bind). For detailed configuration information, see the section ldap_authentication.

Token verification

After user authentication, an authentication token is generated, which is passed with requests to YDB. When verifying the token, the node determines the user on whose behalf the request is made and the groups they belong to. Depending on the authentication method, cryptographic verification of the token may be performed on the YDB side or an external authentication system may be contacted. For example, for a user from an LDAP directory, the token does not contain group information, so the node makes an additional request to the LDAP server to obtain the user's group list. Network calls increase the time of authentication token verification and request processing, as well as the load on the external system. Therefore, YDB nodes cache verification results.

Groups, like the user themselves, are subjects of operations on database schema objects. To differentiate access to various database resources, subjects can be assigned access rights. And according to the list of assigned rights, subjects will be authorized to perform certain operations.

The process of obtaining a user's group list from an LDAP directory is similar to the actions performed during authentication. First, a bind operation is performed for a service user whose credentials are recorded in the bind_dn and bind_password parameters of the ldap_authentication section of the configuration file. After successful authentication, a search is performed for the user record for which the token was previously generated. The search is also performed in accordance with the search_filter parameter. If the user still exists, the returned result of the search operation will be a list of attribute values recorded in the requested_group_attribute parameter. If this parameter is empty, the attribute of reverse group membership will be memberOf. The memberOf attribute stores the unique names (Distinguished Name, DN) of the groups the user belongs to.

Getting groups

By default, YDB searches only for groups in which the user is directly a member. By enabling the extended_settings.enable_nested_groups_search flag of the ldap_authentication section, YDB will attempt to obtain groups at all nesting levels, not only those the user belongs to directly. If YDB is configured to work with Active Directory, the Active Directory-specific matching rule LDAP_MATCHING_RULE_IN_CHAIN will be used to search for all nested groups. This rule allows obtaining all nested groups with a single query. For LDAP servers based on OpenLDAP, group search will be performed by recursively traversing the graph, which generally requires multiple queries. For both Active Directory and OpenLDAP, group search will be performed only for the subtree whose root is taken from the configuration parameter base_dn.

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

LDAP users and LDAP groups in YDB

Since YDB allows using different user authentication methods, when working with user and group names it is often useful to distinguish where exactly the user was authenticated. For all authentication types except login and password authentication, group and user names are appended with a suffix of the form @<auth-domain>.

For LDAP users, auth-domain is set in the configuration parameter ldap_authentication_domain. By default it has the value ldap, so all user names authenticated via the LDAP directory and the names of groups they belong to will have the following form in YDB:

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

TLS connection

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

• Automatically. The connection scheme ldaps is used.
• Using the LDAP protocol extension StartTls

When using an unencrypted connection, all data transmitted in requests to the LDAP server will be sent in plaintext, including passwords. This connection method is easier to start using and is more suitable for experiments or testing.

LDAPS

For YDB to automatically establish an encrypted connection to the LDAP server, you need to set the value ldaps in the configuration parameter scheme. 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 used to encrypt messages over TLS. It allows sending some messages in encrypted form and others in plaintext within a single connection to the LDAP server. A message with this extension is sent from YDB to the LDAP server to initiate a TLS connection. In the case of YDB, enabling and disabling a TLS connection within a single connection is not supported. Therefore, when using the StartTls extension, after establishing an encrypted connection, YDB will send all further messages to the LDAP server in encrypted form. One of the advantages of using this extension instead of the ldaps schema (with appropriate LDAP server configuration) is the ability to establish a TLS connection on an unencrypted port. The extension is enabled in the use_tls section of the configuration file.

Authentication using an external IdP via the OpenID Connect protocol

YDB can authenticate users by JWT tokens issued by an external identity provider (Identity Provider, IdP) that supports the OpenID Connect (OIDC) protocol. The provider is responsible for authenticating the user and issuing the token, while YDB verifies the signature and claims about the subject and token validity conditions and forms the user's SID and their groups.

Obtaining and refreshing the JWT token is performed on the client and IdP side. The YDB server does not redirect the user to the IdP login page and does not exchange authorization code for tokens. The client passes the already obtained JWT token as a Bearer token with each request.

How it works

1. The client authenticates with the external IdP and receives a signed JWT token.
2. The client passes the token in a request to YDB with type Bearer.
3. The YDB node requests the OIDC Discovery document at <issuer>/.well-known/openid-configuration, where <issuer> is the configured provider URL and token issuer identifier. For example, for issuer: https://idp.example.com the request is sent to https://idp.example.com/.well-known/openid-configuration. The value of the issuer field in the document must exactly match the configured provider address.
4. From the jwks_uri field of the Discovery document, a URL is extracted from which YDB periodically obtains a set of public keys JWKS.
5. Based on the alg (algorithm, signature algorithm) and kid (key ID, key identifier) fields of the JWT header, a public key is selected. YDB verifies the token signature, issuer, audience, and expiration times.
6. The user identifier and group list are extracted from the token fields. The configured authentication domain suffix is added to them, after which the resulting SIDs are used for authorization.

The Discovery URL, issuer, and jwks_uri must use the https:// scheme. If the Discovery document or JWKS is temporarily unavailable, YDB retries requests with an increasing interval. The obtained keys are cached and periodically refreshed to support key rotation on the IdP side. After the cache lifetime expires, stale keys are removed; until JWKS is successfully refreshed, new token verifications fail with a temporary error.

Token and key requirements

The JWT token must have a valid compact serialization format and contain the alg and kid fields in its header. Only asymmetric signature algorithms are supported:

• RSA PKCS#1: RS256, RS384, RS512;
• RSA-PSS: PS256, PS384, PS512;
• ECDSA: ES256, ES384, ES512.

Symmetric algorithms of the HS* family are not supported. The public key in JWKS must have matching kty (key type) and kid and contain x5c (X.509 certificate chain). The public key is extracted from the first certificate x5c; JWKs containing only RSA or EC parameters without x5c are skipped.

The following fields are required for successful authentication:

• alg and kid in the JWT header;
• The iss claim (issuer) matching the value of issuer in the configuration;
• A non-empty string user identifier. To obtain it, the claim specified by the subject_claim_name parameter is used. If this claim is missing or has a different type, the standard sub claim (subject) is used.

The remaining checked fields are optional:

• The aud claim (audience) is checked if the audience parameter is set in the configuration; it is recommended to always set the expected audience so that tokens issued for other services are not accepted;
• When checking time-related claims such as exp (expiration time), nbf (not before), and iat (issued at), the allowed clock skew specified by the allowed_clock_skew parameter is taken into account. If exp is missing, YDB sets the authentication result expiration to 10 minutes;
• The claim specified by the groups_claim_name parameter contains the list of user groups. It must be an array; only string elements are extracted from the array. If the claim is missing or has a different type, the group list is considered empty.

Forming the SID

The suffix @<auth-domain> is added to the user identifier and each group from the JWT. The value of <auth-domain> is set by the external_idp_authentication_domain parameter; by default, the value sso is used.

For example, with sub: user1, groups: [admins, developers], and the default domain, the following SIDs are formed:

• user user1@sso;
• groups admins@sso and developers@sso.

YDB uses the group list from the token without additional calls to the IdP and without expanding nested groups. You cannot manage users and groups of an external IdP using the CREATE USER, ALTER USER, CREATE GROUP, and ALTER GROUP commands. Rights are assigned to the formed SIDs using the methods described in the section Authorization.

Server configuration

Authentication via an external IdP is enabled in the authentication configuration when the external_idp_config section is present.

Client certificate authentication

YDB can authenticate a client using the client certificate data obtained when establishing a TLS connection. The verification is performed at the application protocol level (gRPC, etc.), when the server already accepts requests over an open connection.

This approach is suitable, for example, in corporate scenarios with centralized certificate issuance.

How it works

1. The client establishes a TLS connection with the YDB server, passing the client certificate (and the trust chain).
2. When processing a request, the server extracts the certificate from the TLS context.
3. The server uses the certificate for authentication and checks it against the rules of the client_certificate_authorization section.
4. As a result of successful certificate verification, the client is assigned a security identifier SID, which has all the rights assigned to the corresponding identifier.

Certificate authentication is applied only to requests without an authentication token. If the client passes an authentication token — for example, in the Authorization header for HTTP or via SDK/CLI mechanisms for IAM, login, and password — the token takes precedence. In this case, the certificate is passed at the TLS level but is not used for authentication.

SID generation

Successful certificate authentication creates a user SID with the suffix @<domain>, where <domain> is the parameter value certificate_authentication_domain in the auth_config section (default: cert). The name is formed from all attributes of the certificate's Subject field in Name=Value,...@<domain> notation. The attribute order matches the order of fields in the certificate. Example:

C=RU,ST=MSK,O=MyOrg,CN=account1.apps.example.net@cert

Getting groups

If the client_certificate_authorization section specifies client_certificate_definitions blocks, the certificate is accepted if it matches at least one of them. For each matching block, the client is included in the groups from member_groups. If member_groups is not specified, the default group is used — default_group (default value: DefaultClientAuth@cert).

Server configuration

Certificate verification and group assignment rules are set in the client_certificate_authorization section of the cluster's static configuration. To enable client certificate requests during the TLS handshake over gRPCs, set the request_client_certificate: true parameter.

Client configuration

For more information about configuring YDB CLI, see the TLS connection parameters section.

Device authentication by certificate

Device authentication is the verification of the client certificate when establishing a TLS connection; no SID is generated in this case. If a certificate is presented, the chain of trust to the CA is verified; an untrusted certificate causes the connection to be rejected before application requests are processed. Whether a certificate must be presented depends on the interface (see the section Usage in YDB).

Why device authentication is needed

Device authentication solves the following tasks in YDB:

1. Cluster isolation — restrict the set of hosts and applications that can establish a TLS connection with YDB nodes.
2. Protection against configuration errors — prevent connections to foreign YDB clusters. For example, if the node-broker parameter is incorrect, a dynamic node will not connect to a foreign cluster, whereas with regular TLS such a connection could be established.
3. Complicating application-level attacks — a process on a foreign host without a suitable certificate does not get access to the cluster API, even if a network route to the port exists.

After device authentication, authentication of a user or application may be required to access data. It can be performed not only using a verified client certificate, but also using other authentication methods in YDB, for example, by login and password.

How it works

1. The client establishes a TLS connection with the YDB server and, if the connection interface requires it, presents a client certificate.
2. If a certificate is presented, the server verifies it at the TLS level: the chain of trust to the configured certificate authority (CA), expiration date, and so on. Additional rules for matching certificate fields (for example, require_same_issuer, Subject, and SAN) are applied during client certificate authentication.
3. If verification succeeds, the connection is opened; if it fails, it is rejected.

Usage in YDB

Device authentication is optional and configured independently: the mechanism can be enabled on some ports and disabled on others.

• Interconnect — when TLS is enabled in the interconnect_config section, Interconnect requires a client certificate.
• Kafka API — when mTLS is enabled, it requires a client certificate; only the chain of trust to the CA is verified, and a connection without a certificate or with an untrusted certificate is not established. Server configuration is described in the kafka_proxy_config section, and client connection in the Device authentication by mTLS section.
• gRPC and YDB Monitoring — you can enable a client certificate request for device authentication, and also separately enable its mandatory verification (an untrusted certificate is always rejected). gRPC configuration is described in the grpc_config and client_certificate_authorization sections, and client connection — in the TLS connection parameters section; YDB Monitoring configuration is described in the monitoring_config section.

Authentication using a third-party IAM provider

• Access Token — a fixed token is set as a parameter for the client (SDK or CLI) and is passed in requests.
• Refresh Token — an OAuth token of a personal account is set as a parameter for the client (SDK or CLI), based on which the client periodically accesses the IAM API in the background to rotate (obtain the next) token passed in requests.
• Service Account Key — the attributes of a service account and a signing key are set as parameters for the client (SDK or CLI), based on which the client periodically accesses the IAM API in the background to rotate (obtain the next) token passed in requests.
• Metadata — the client (SDK or CLI) periodically accesses a local service to rotate (obtain the next) token passed 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, which is then passed in requests to the YDB API.

Any holder of a valid token can gain access to perform operations, so the main task of the security system is to ensure token secrecy and prevent its compromise.

Authentication modes with token rotation, Refresh Token and Service Account Key, provide a higher level of security compared to the mode with a fixed token, Access Token, because only short-lived secrets are transmitted over the network to the YDB server.

Maximum security and performance are ensured when using the Metadata mode, as it eliminates the need to work with secrets when deploying an application and also allows you to access IAM and cache the token in advance, before the application starts.

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

• Anonymous is usually used on self-deployed local clusters YDB that are not accessible over the network.
• Access Token is used when other modes are not supported on the server side or for configuration and debugging purposes. It does not require client interactions with IAM. However, if the IAM supports an API for token rotation, the fixed tokens issued by such IAM typically have a short lifetime, which forces you to manually refresh them in IAM on a regular basis.
• Refresh Token can be used for one-off manual operations under a personal account, for example, those related to data maintenance in the database, running ad-hoc operations in the CLI, or launching applications from a workstation. Such a token can be obtained manually in IAM once for a long period and stored in an environment variable on your personal workstation so that it is applied automatically when you run the CLI without additional authentication parameters.
• Service Account Key is primarily used for applications designed to run in environments that support the Metadata mode, when testing them outside such environments (for example, on a workstation). It can also be used for applications outside such environments, acting as an analog of Refresh Token for service accounts. Unlike a personal account, the access objects and roles of a service account can be limited.
• 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 be specified in the parameters can be obtained from the IAM system associated with a particular YDB installation. In particular, Yandex.Passport OAuth and service accounts Yandex.Cloud are used for the YDB service in Yandex.Cloud. When using YDB in corporate contexts, standard centralized authentication systems for the organization may be used.

When using modes that involve the YDB client accessing IAM, you can additionally specify the IAM URL that provides the token issuance API. By default, existing SDKs and CLIs attempt to access the IAM API Yandex.Cloud hosted on iam.api.cloud.yandex.net:443.