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

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

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

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

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

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

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

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

Режим Метод
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 )
Определяется по переменным окружения ydb.construct_credentials_from_environ()
import { AnonymousAuthService, TokenAuthService,
  MetadataAuthService, getSACredentialsFromJson,
  getCredentialsFromEnv } from 'ydb-sdk';
Режим Метод
Anonymous AnonymousAuthService()
Access Token TokenAuthService( accessToken, database )
Metadata MetadataAuthService( database )
Service Account Key getSACredentialsFromJson( saKeyFile )
Определяется по переменным окружения getCredentialsFromEnv( entryPoint, database, logger )
Режим Метод
Anonymous ydb::StaticToken("")
Access Token ydb::StaticToken(token)
Metadata ydb::GCEMetadata, ydb::YandexMetadata
Service Account Key не поддерживается
Определяется по переменным окружения не поддерживается
Выполнение внешней команды 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. Иначе используется режим аутентификации Metadata

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

Особенности Python SDK

Важно

Поведение Python SDK отличается от описанного выше.

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