Аутентификация в SDK

Как описано в статье о подключении к серверу YDB, клиент с каждым запросом должен отправить аутентификационный токен. Аутентификационный токен проверяется сервером и, в случае успешной аутентификации, запрос авторизуется и выполняется, иначе возвращается ошибка Unauthenticated.

YDB SDK использует объект, отвечающий за генерацию таких токенов. SDK предоставляет встроенные cпособы получения такого объекта:

  1. Методы с явной передачей параметров, каждый из методов реализует один из режимов аутентификации.
  2. Метод определения режима аутентификации и необходимых параметров из переменных окружения.

Обычно объект генерации токенов создается перед инициализацией драйвера YDB и передается параметром в его конструктор. C++ и Go SDK дополнительно позволяют через один драйвер работать с несколькими БД и объектами генерации токенов.

Если объект генерации токенов не определен, драйвер не будет добавлять в запросы какой-либо аутентификационной информации. Такой подход позволяет успешно соединиться с локально развернутыми кластерами YDB без настроенной обязательной аутентификации. Если обязательная аутентификация настроена, то запросы к базе данных без аутентификационного токена будут отклоняться с выдачей ошибки аутентификации.

Методы создания объекта генерации токенов

На приведенные ниже методы можно кликнуть, чтобы перейти к исходному коду релевантного примера в репозитории. Также можно ознакомиться с рецептами кода Аутентификации.

Режим Метод
Anonymous AnonymousAuthService()
Access Token TokenAuthService(accessToken, database)
Metadata MetadataAuthService(database)
Service Account Key getSACredentialsFromJson(saKeyFile)
Static Credentials StaticCredentialsAuthService(user, password, endpoint)
Определяется по переменным окружения getCredentialsFromEnv(entryPoint, database, logger)
Режим Метод
Anonymous ydb::StaticToken("")
Access Token ydb::StaticToken(token)
Metadata ydb::GCEMetadata, ydb::YandexMetadata
Service Account Key не поддерживается
Static Credentials ydb::StaticCredentialsAuth
Определяется по переменным окружения не поддерживается
Выполнение внешней команды ydb.CommandLineYcToken (например, для авторизации с помощью IAM-токена Yandex.Cloud с компьютера разработчика ydb::CommandLineYcToken.from_cmd("yc iam create-token"))

Порядок определения режима и параметров аутентификации из окружения

Выполняется следующий алгоритм, одинаковый для всех SDK:

  1. Если задано значение переменной окружения YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS, то используется режим аутентификации System Account Key, а ключ загружается из файла, указанного в данной переменной.
  2. Иначе, если задано значение переменной окружения YDB_ANONYMOUS_CREDENTIALS, равное 1, то используется анонимный режим аутентификации.
  3. Иначе, если задано значение переменной окружения YDB_METADATA_CREDENTIALS, равное 1, то используется режим аутентификации Metadata.
  4. Иначе, если задано значение переменной окружения YDB_ACCESS_TOKEN_CREDENTIALS, то используется режим аутентификации Access token, в который передается значение данной переменной.
  5. Иначе, если задано значение переменной окружения YDB_OAUTH2_KEY_FILE, то используется режим аутентификации OAuth 2.0 token exchange, а настройки загружаются из JSON файла, указанного в данной переменной.
  6. Иначе используется режим аутентификации Metadata.

Наличие последним пунктом алгоритма выбора режима Metadata позволяет развернуть рабочее приложение на виртуальных машинах и в Cloud Functions Yandex.Cloud без задания каких-либо переменных окружения.

Формат файла настроек для режима аутентификации OAuth 2.0 token exchange

Описание полей JSON файла настроек метода аутентификации OAuth 2.0 token exchange. Набор полей зависит от типа исходного токена, JWT или FIXED.

В таблице ниже creds_json обозначает JSON с параметрами для исходного токена, обмениваемого на access token.

Поля, не описанные в этой таблице, игнорируются.

Поле Тип Описание Значение по умолчанию/опциональность
grant-type string Grant type urn:ietf:params:oauth:grant-type:token-exchange
res string | list of strings Resource опциональное
aud string | list of strings Опция audience для запроса обмена токена опциональное
scope string | list of strings Scope опциональное
requested-token-type string Тип получаемого токена urn:ietf:params:oauth:token-type:access_token
subject-credentials creds_json Subject credentials опциональное
actor-credentials creds_json Actor credentials опциональное
token-endpoint string Token endpoint. В случае с YDB CLI перезаписывается опцией --iam-endpoint. опциональное
Описание полей creds_json (JWT)
type string Тип источника токена. Нужно задать константу JWT
alg string Алгоритм подписи JWT. Поддерживаются следующие алгоритмы: ES256, ES384, ES512, HS256, HS384, HS512, PS256, PS384, PS512, RS256, RS384, RS512
private-key string (Приватный) ключ в формате PEM (для алгоритмов ES*, PS*, RS*) или Base64 (для алгоритмов HS*) для подписи
kid string Стандартное поле JWT kid (key id) опциональное
iss string Стандартное поле JWT iss (issuer) опциональное
sub string Стандартное поле JWT sub (subject) опциональное
aud string Стандартное поле JWT aud (audience) опциональное
jti string Стандартное поле JWT jti (JWT id) опциональное
ttl string Время жизни JWT токена 1h
Описание полей creds_json (FIXED)
type string Тип источника токена. Нужно задать константу FIXED
token string Значение токена
token-type string Значение типа токена. Это значение попадёт в параметр subject_token_type/actor_token_type в запросе обмена токена

Пример

Пример для обмена JWT токена

{
   "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"
   }
}

Особенности YDB Python SDK v2 (устаревшая версия)

Важно

Поведение YDB Python SDK v2 (устаревшая версия) отличается от описанного выше.

  • Алгоритм работы функции construct_credentials_from_environ() YDB Python SDK v2:

    • Если задано значение переменной окружения USE_METADATA_CREDENTIALS, равное 1, то используется режим аутентификации Metadata
    • Иначе, если задано значение переменной окружения YDB_TOKEN, то используется режим аутентификации Access Token, в который передается значение данной переменной
    • Иначе, если задано значение переменной окружения SA_KEY_FILE, то используется режим аутентификации System Account Key, а ключ загружается из файла, имя которого указано в данной переменной
    • Иначе в запросах не будет добавлена информация об аутентификации.

  • В случае, если при инициализации драйвера не передан никакой объект, отвечающий за генерацию токенов, то применяется общий порядок чтения значений переменных окружения.

Предыдущая
Установка SDK
Следующая
Параметризованные запросы