Authentication in the SDK
- Methods for creating token generation objects
- Procedure for determining the authentication mode and parameters from the environment
- Python SDK specifics
As described in the article on connecting to the YDB server, with each request, the client should send an authentication token. The server verifies the authentication token and, if the authentication is successful, the request is authorized and executed, otherwise the Unauthenticated
error is returned.
The YDB SDK uses an object that is responsible for generating these tokens. The SDK provides built-in methods for obtaining this object:
- Methods with parameters passed explicitly, each of the methods implements a certain authentication mode.
- A method that determines the authentication mode and the necessary parameters from environment 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 a token generation object is not defined, the driver won’t add any authentication information to requests. This may let you successfully connect to locally deployed YDB clusters with no mandatory authentication configured. If it is configured, DB requests without an authentication token will be rejected with an authentication error returned.
Methods for creating token generation objects
You can click on any of the methods described below to go to the source code of the relevant example in the repository. You can also learn about the authentication code recipes.
Python
Go
Java
Node.js
Mode | Method |
---|---|
Anonymous | ydb.AnonymousCredentials() |
Access Token | ydb.AccessTokenCredentials( token ) |
Metadata | ydb.iam.MetadataUrlCredentials() |
Service Account Key | ydb.iam.ServiceAccountCredentials.from_file( key_file, iam_endpoint=None, iam_channel_credentials=None ) |
Determined by environment variables | ydb.construct_credentials_from_environ() |
Mode | Package | Method |
---|---|---|
Anonymous | ydb-go-sdk/v3 | ydb.WithAnonymousCredentials() |
Access Token | ydb-go-sdk/v3 | ydb.WithAccessTokenCredentials( token ) |
Metadata | ydb-go-yc | yc.WithMetadataCredentials( ctx ) |
Service Account Key | ydb-go-yc | yc.WithServiceAccountKeyFileCredentials( key_file ) |
Determined by environment variables | ydb-go-sdk-auth-environ | environ.WithEnvironCredentials(ctx) |
Mode | Method |
---|---|
Anonymous | new ‘ydb-sdk’.AnonymousAuthService() |
Access Token | new ‘ydb-sdk’.TokenAuthService( accessToken, database ) |
Metadata | new ‘ydb-sdk’.MetadataAuthService( database ) |
Service Account Key | new ‘ydb-sdk’.getSACredentialsFromJson( saKeyFile ) |
Determined by environment variables | new ‘ydb-sdk’.getCredentialsFromEnv( entryPoint, database, logger ) |
Procedure for determining the authentication mode and parameters from the environment
The following algorithm that is the same for all SDKs applies:
- 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. - Otherwise, if the value of the
YDB_ANONYMOUS_CREDENTIALS
environment variable is set to 1, the anonymous authentication mode is used. - Otherwise, if the value of the
YDB_METADATA_CREDENTIALS
environment variable is set to 1, the Metadata authentication mode is used. - 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. - 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 Cloud Functions in Yandex.Cloud without setting any environment variables.
Python SDK specifics
Warning
The behavior of the Python SDK differs from the one described above.
- The algorithm for determining the authentication mode and the necessary parameters from the environment variables in the
construct_credentials_from_environ()
method differs from the one used in other SDKs:- 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 the value of the
- If no object responsible for generating tokens is passed when initializing the driver, the general procedure for reading environment variable values applies.