--- metadata: - name: generator content: Diplodoc Platform v5.50.4 alternate: - https://ydb.tech/docs/en/reference/ydb-sdk/auth.md - https://ydb.tech/docs/ru/reference/ydb-sdk/auth.md sourcePath: en/core/reference/ydb-sdk/auth.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/en/llms.txt # Authentication in the SDK As we discussed in the [YDB server connection](https://ydb.tech/docs/en/concepts/connect.md) article, the client must add an [authentication token](https://ydb.tech/docs/en/security/authentication.md) 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](https://ydb.tech/docs/en/security/authentication.md). 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 {#auth-provider} 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](https://ydb.tech/docs/en/recipes/ydb-sdk/auth.md). {% list tabs %} - Python | Mode | Method | | ----- | ----- | | Anonymous | [ydb.AnonymousCredentials()](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/anonymous-credentials) | | Access Token | [ydb.AccessTokenCredentials(token)](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/access-token-credentials) | | Metadata | [ydb.iam.MetadataUrlCredentials()](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/metadata-credentials) | | Service Account Key | [ydb.iam.ServiceAccountCredentials.from_file(
key_file, iam_endpoint=None, iam_channel_credentials=None)](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/service-account-credentials) | Static Credentials | [ydb.StaticCredentials.from_user_password(user, password)](https://github.com/ydb-platform/ydb-python-sdk/blob/main/examples/static-credentials/example.py) | | OAuth 2.0 token exchange | [ydb.oauth2_token_exchange.Oauth2TokenExchangeCredentials()](https://github.com/ydb-platform/ydb-python-sdk/blob/main/ydb/oauth2_token_exchange/token_exchange.py),
[ydb.oauth2_token_exchange.Oauth2TokenExchangeCredentials.from_file(cfg_file, iam_endpoint=None)](https://github.com/ydb-platform/ydb-python-sdk/blob/main/ydb/oauth2_token_exchange/token_exchange.py) | | Determined by environment variables | `ydb.credentials_from_env_variables()` | - Go | Mode | Package | Method | | ----- | ----- | ---- | | Anonymous | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/) | [ydb.WithAnonymousCredentials()](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/anonymous_credentials) | | Access Token | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/) | [ydb.WithAccessTokenCredentials(token)](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/access_token_credentials) | | Metadata | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/) | [yc.WithMetadataCredentials(ctx)](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/metadata_credentials) | | Service Account Key | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/) | [yc.WithServiceAccountKeyFileCredentials(key_file)](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/service_account_credentials) | | Static Credentials | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/) | [ydb.WithStaticCredentials(user, password)](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/static_credentials) | | OAuth 2.0 token exchange | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/) | [ydb.WithOauth2TokenExchangeCredentials(options...)](https://github.com/ydb-platform/ydb-go-sdk/blob/master/options.go),
[ydb.WithOauth2TokenExchangeCredentialsFile(configFilePath)](https://github.com/ydb-platform/ydb-go-sdk/blob/master/options.go) | | Determined by environment variables | [ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/) | [environ.WithEnvironCredentials(ctx)](https://github.com/ydb-platform/ydb-go-examples/tree/master/auth/environ) | - Java | Mode | Method | | ----- | ----- | | Anonymous | [tech.ydb.core.auth.NopAuthProvider.INSTANCE](https://github.com/ydb-platform/ydb-java-examples/tree/master/auth/anonymous_credentials) | | Access Token | [new tech.ydb.core.auth.TokenAuthProvider(accessToken);](https://github.com/ydb-platform/ydb-java-examples/tree/master/auth/access_token_credentials) | | Metadata | [tech.ydb.auth.iam.CloudAuthHelper.getMetadataAuthProvider();](https://github.com/ydb-platform/ydb-java-examples/tree/master/auth/metadata_credentials) | | Service Account Key | [tech.ydb.auth.iam.CloudAuthHelper.getServiceAccountFileAuthProvider(saKeyFile);](https://github.com/ydb-platform/ydb-java-examples/tree/master/auth/service_account_credentials) | | OAuth 2.0 token exchange | [tech.ydb.auth.OAuth2TokenExchangeProvider.fromFile(cfgFile);](https://github.com/ydb-platform/ydb-java-sdk/blob/master/auth-providers/oauth2-provider/src/main/java/tech/ydb/auth/OAuth2TokenExchangeProvider.java) | | Determined by environment variables | [tech.ydb.auth.iam.CloudAuthHelper.getAuthProviderFromEnviron();](https://github.com/ydb-platform/ydb-java-examples/tree/master/auth/environ) | - JavaScript | Mode | Method | | ----- | ----- | | Anonymous | [AnonymousCredentialsProvider()](https://github.com/ydb-platform/ydb-js-sdk/blob/main/packages/auth/src/anonymous.ts) | | Access Token | [AccessTokenCredentialsProvider({ token })](https://github.com/ydb-platform/ydb-js-sdk/blob/main/packages/auth/src/access-token.ts) | | Metadata | [MetadataCredentialsProvider()](https://github.com/ydb-platform/ydb-js-sdk/blob/main/packages/auth/src/metadata.ts) | | Service Account Key | [ServiceAccountCredentialsProvider.fromFile(saKeyFile)](https://github.com/ydb-platform/ydb-js-sdk/tree/main/examples/auth-yandex-cloud) | | Static Credentials | [StaticCredentialsProvider({ username, password }, endpoint)](https://github.com/ydb-platform/ydb-js-sdk/blob/main/packages/auth/src/static.ts) | | Determined by environment variables | [EnvironCredentialsProvider(connectionString)](https://github.com/ydb-platform/ydb-js-sdk/tree/main/examples/environ) | - Rust | Mode | Method | | ----- | ----- | | Anonymous | ydb::AnonymousCredentials or ydb::AccessTokenCredentials::from("") | | Access Token | [ydb::AccessTokenCredentials::from("token")](https://github.com/ydb-platform/ydb-rs-sdk/blob/master/ydb/examples/auth-token.rs) | | Metadata | [ydb::MetadataUrlCredentials](https://github.com/ydb-platform/ydb-rs-sdk/blob/master/ydb/examples/auth-ycloud-metadata.rs) | | Service Account Key | [ydb::ServiceAccountCredentials](https://github.com/ydb-platform/ydb-rs-sdk/blob/master/ydb/examples/auth-ycloud-serviceaccount.rs) | | Static Credentials | [ydb::StaticCredentialsAuth](https://github.com/ydb-platform/ydb-rs-sdk/blob/master/ydb/examples/auth-static-credentials.rs) | | Determined by environment variables | [ydb::FromEnvCredentials](https://github.com/ydb-platform/ydb-rs-sdk/blob/master/ydb/examples/auth-ycloud-serviceaccount.rs) | | Execution of an external command | [ydb::CommandLineCredentials](https://github.com/ydb-platform/ydb-rs-sdk/blob/master/ydb/examples/auth-yc-cmdline.rs) (for example, for authentication using a Yandex.Cloud [IAM token](https://yandex.cloud/en/docs/iam/concepts/authorization/iam-token) from the developer's computer ```ydb::CommandLineCredentials.from_cmd("yc iam create-token")```) | - PHP | Mode | Method | | ----- | ----- | | Anonymous | [AnonymousAuthentication()](https://github.com/ydb-platform/ydb-php-sdk#anonymous) | | Access Token | [AccessTokenAuthentication($accessToken)](https://github.com/ydb-platform/ydb-php-sdk#access-token) | | Oauth Token | [OAuthTokenAuthentication($oauthToken)](https://github.com/ydb-platform/ydb-php-sdk#oauth-token) | | Metadata | [MetadataAuthentication()](https://github.com/ydb-platform/ydb-php-sdk#metadata-url) | | Service Account Key | [JwtWithJsonAuthentication($jsonFilePath)](https://github.com/ydb-platform/ydb-php-sdk#jwt--json-file) or [JwtWithPrivateKeyAuthentication($key_id, $service_account_id, $privateKeyFile)](https://github.com/ydb-platform/ydb-php-sdk#jwt--private-key) | | Determined by environment variables | [EnvironCredentials()](https://github.com/ydb-platform/ydb-php-sdk#determined-by-environment-variables) | | Static Credentials | [StaticAuthentication($user, $password)](https://github.com/ydb-platform/ydb-php-sdk#static-credentials) | {% endlist %} ## Procedure for determining the authentication mode and parameters from the environment {#env} 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](#oauth2-key-file-format) 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 {#oauth2-key-file-format} 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](https://www.rfc-editor.org/rfc/rfc8693) | 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](https://www.rfc-editor.org/rfc/rfc8693). | || |# {wide-content} ### Example An example for JWT token exchange ```json { "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) {% note warning %} The behavior of the YDB Python SDK v2 (deprecated version) differs from the above-described version. {% endnote %} * 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](#env) for reading environment variables applies.