Authentication in the SDK

As described in the article about connecting to the YDB server, the client must send an authentication token with each request. The authentication token is verified by the server, and if authentication succeeds, the request is authorized and executed; otherwise, an Unauthenticated error is returned.

The YDB SDK uses an object responsible for generating such tokens. The SDK provides built-in ways to obtain such an object:

1. Methods with explicit parameter passing, each of which implements one of the authentication modes.
2. A method for determining the authentication mode and required parameters from environment variables.

Typically, the token generation object is created before initializing the YDB driver and passed as a parameter to its constructor. The C++ and Go SDKs additionally allow working with multiple databases and token generation objects through a single driver.

If the token generation object is not defined, the driver will not add any authentication information to requests. This approach allows successfully connecting to locally deployed YDB clusters without mandatory authentication configured. If mandatory authentication is configured, requests to the database without an authentication token will be rejected with an authentication error.

Methods for creating a token generation object

You can click the methods below to go to the source code of the relevant example in the repository. You can also check out the Authentication code recipes.

Order of determining the authentication mode and parameters from the environment

The following algorithm is executed, which is the same for all SDKs:

1. If the environment variable YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS is set, the System Account Key authentication mode is used, and the key is loaded from the file specified in this variable.
2. Otherwise, if the environment variable YDB_ANONYMOUS_CREDENTIALS is set to 1, the anonymous authentication mode is used.
3. Otherwise, if the environment variable YDB_METADATA_CREDENTIALS is set to 1, the Metadata authentication mode is used.
4. Otherwise, if the environment variable YDB_ACCESS_TOKEN_CREDENTIALS is set, the Access token authentication mode is used, and the value of this variable is passed to it.
5. Otherwise, if the environment variable YDB_OAUTH2_KEY_FILE is set, the OAuth 2.0 token exchange authentication mode is used, and the settings are loaded from the JSON file specified in this variable.
6. Otherwise, the Metadata authentication mode is used.

The presence of Metadata as the last item in the mode selection algorithm allows you to deploy a working application on virtual machines and in Cloud Functions Yandex.Cloud without setting any environment variables.

Format of the settings file for the OAuth 2.0 token exchange authentication mode

Description of the fields of the JSON settings file for the OAuth 2.0 token exchange authentication method. The set of fields depends on the type of the source token, JWT or FIXED.

In the table below, creds_json denotes JSON with parameters for the source token exchanged for an access token.

Fields not described in this table are ignored.

Example

Example of JWT token exchange

{
   "subject-credentials": {
      "type": "JWT",
      "alg": "RS256",
      "private-key": "-----BEGIN RSA PRIVATE KEY-----\n...-----END RSA PRIVATE KEY-----\n",
      "kid": "my_key_id",
      "sub": "account_id"
   }
}

Features of YDB Python SDK v2 (legacy version)

• How the construct_credentials_from_environ() function of YDB Python SDK v2 works:

  • If the environment variable USE_METADATA_CREDENTIALS is set to 1, the Metadata authentication mode is used.
  • Otherwise, if the environment variable YDB_TOKEN is set, the Access Token authentication mode is used, and the value of this variable is passed to it.
  • Otherwise, if the environment variable SA_KEY_FILE is set, the System Account Key authentication mode is used, and the key is loaded from the file whose name is specified in this variable.
  • Otherwise, no authentication information will be added to requests.

• If no object responsible for token generation is passed during driver initialization, the general procedure for reading environment variable values is applied.