Authentication in the SDK

As we discussed in the YDB server connection article, the client must add an authentication token to each request. The authentication token is checked by the server. If the authentication is successful, the request is authorized and executed. Otherwise, the Unauthenticated error returns.

The YDB SDK uses an object that is responsible for generating these tokens. SDK provides built-in methods for getting such an object:

  1. The methods that pass parameters explicitly, with each method implementing a certain authentication mode.
  2. The method that determines the authentication mode and relevant parameters based on environmental variables.

Usually, you create a token generation object before you initialize the YDB driver, and you pass the object to the driver constructor as a parameter. The C++ and Go SDKs additionally let you work with multiple databases and token generation objects through a single driver.

If the token generation object is not defined, the driver won't add any authentication data to the requests. This approach enables you to successfully connect to locally deployed YDB clusters without enabling mandatory authentication. If you enable mandatory authentication, database requests without an authentication token will be rejected with an authentication error.

Methods for creating token generation objects

You can click any of the methods below to go to the source code of an example in the repository. You can also learn about the authentication code recipes.

Mode Method
Anonymous ydb::StaticToken("")
Access Token ydb::StaticToken(token)
Metadata ydb::GCEMetadata, ydb::YandexMetadata
Static Credentials ydb::StaticCredentialsAuth
Service Account Key not supported
Determined by environment variables not supported
Execution of an external command ydb.CommandLineYcToken (for example, for authentication using a Yandex.Cloud IAM token from the developer's computer ydb::CommandLineYcToken.from_cmd("yc iam create-token"))

Procedure for determining the authentication mode and parameters from the environment

The following algorithm that is the same for all SDKs applies:

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

If the last step of the algorithm is selecting the Metadata mode, you can deploy a working application on VMs and in Yandex.Cloud Cloud Functions without setting any environment variables.

File format for OAuth 2.0 token exchange authentication mode parameters

Description of fields of JSON file with OAuth 2.0 token exchange authentication mode parameters. The set of fields depends on the original token type, JWT and FIXED.

In the table below, creds_json means a JSON with parameters for exchanging the original token for an access token.

Fields not described in this table are ignored.

Field

Type

Description

Default value/optionality

grant-type

string

Grant type

urn:ietf:params:oauth:grant-type:token-exchange

res

string | list of strings

Resource

optional

aud

string | list of strings

Audience option for token exchange request

optional

scope

string | list of strings

Scope

optional

requested-token-type

string

Requested token type

urn:ietf:params:oauth:token-type:access_token

subject-credentials

creds_json

Subject credentials

optional

actor-credentials

creds_json

Actor credentials

optional

token-endpoint

string

Token endpoint. In the case of YDB CLI, it is overridden by the --iam-endpoint option.

optional

Description of fields of creds_json (JWT)

type

string

Token source type. Set JWT

alg

string

Algorithm for JWT signature. Supported algorithms: ES256, ES384, ES512, HS256, HS384, HS512, PS256, PS384, PS512, RS256, RS384, RS512

private-key

string

(Private) key in PEM format (for algorithms ES*, PS*, RS*) or Base64 format (for algorithms HS*) for JWT signature

kid

string

kid JWT standard claim (key id)

optional

iss

string

iss JWT standard claim (issuer)

optional

sub

string

sub JWT standard claim (subject)

optional

aud

string

aud JWT standard claim (audience)

optional

jti

string

jti JWT standard claim (JWT id)

optional

ttl

string

JWT token TTL

1h

Description of fields of creds_json (FIXED)

type

string

Token source type. Set FIXED

token

string

Token value

token-type

string

Token type value. It will become subject_token_type/actor_token_type parameter in token exchange request.

Example

An example for 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"
  }
}

Peculiarities of YDB Python SDK v2 (deprecated version)

Warning

The behavior of the YDB Python SDK v2 (deprecated version) differs from the above-described version.

  • The algorithm of the construct_credentials_from_environ() function from the YDB Python SDK v2:
    • If the value of the USE_METADATA_CREDENTIALS environment variable is set to 1, the Metadata authentication mode is used.
    • Otherwise, if the value of the YDB_TOKEN environment variable is set, the Access Token authentication mode is used, where this variable value is passed.
    • Otherwise, if the value of the SA_KEY_FILE environment variable is set, the System Account Key authentication mode is used and the key is taken from the file whose name is specified in this variable.
    • Or else, no authentication information is added to requests.
  • If no object responsible for generating tokens is passed when initializing the driver, the general procedure for reading environment variables applies.