Added cloud auth

updated

2 files changed, 53 insertions, 2 deletions

diff --git a/ydb/docs/en/core/concepts/auth.md b/ydb/docs/en/core/concepts/auth.md
index 8e7fdad1188..ddae8b6c4eb 100644
--- a/ydb/docs/en/core/concepts/auth.md
+++ b/ydb/docs/en/core/concepts/auth.md
@@ -5,9 +5,35 @@ Once a network connection is established, the server starts to accept client req
 The following authentication modes are supported:
 
 * Anonymous access is enabled by default and available immediately when you [install the cluster](../deploy/index.md).
-* Authentication through a third-party IAM provider, for example, [Yandex Identity and Access Management]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/iam/){% endif %}.
+* [Authentication through a third-party IAM provider](#iam), for example, [Yandex Identity and Access Management]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/iam/){% endif %}.
 * Authentication by [username and password](#static-credentions).
 
+## Authentication through a third-party IAM provider {#iam}
+
+* **Anonymous**: Empty token passed in a request.
+* **Access Token**: Fixed token set as a parameter for the client (SDK or CLI) and passed in requests.
+* **Refresh Token**: [OAuth token](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/) of a user's personal account set as a parameter for the client (SDK or CLI), which the client periodically sends to the IAM API in the background to rotate a token (obtain a new one) to pass in requests.
+* **Service Account Key**: Service account attributes and a signature key set as parameters for the client (SDK or CLI), which the client periodically sends to the IAM API in the background to rotate a token (obtain a new one) to pass in requests.
+* **Metadata**: Client (SDK or CLI) periodically accesses a local service to rotate a token (obtain a new one) to pass in requests.
+
+Any owner of a valid token can get access to perform operations; therefore, the principal objective of the security system is to ensure that a token remains private and to protect it from being compromised.
+
+Authentication modes with token rotation, such as **Refresh Token** and **Service Account Key**, provide a higher level of security compared to the **Access Token** mode that uses a fixed token, since only secrets with a short validity period are transmitted to the {{ ydb-short-name }} server over the network.
+
+The highest level of security and performance is provided when using the **Metadata** mode, since it eliminates the need to work with secrets when deploying an application and allows accessing the IAM system and caching a token in advance, before running the application.
+
+When choosing the authentication mode among those supported by the server and environment, follow the recommendations below:
+
+* **You would normally use Anonymous** on self-deployed local {{ ydb-short-name }} clusters that are inaccessible over the network.
+* **You would use Access Token** when other modes are not supported on server side or for setup/debugging purposes. It does not require that the client access IAM. However, if the IAM system supports an API for token rotation, fixed tokens issued by this IAM usually have a short validity period, which makes it necessary to update them manually in the IAM system on a regular basis.
+* **Refresh Token** can be used when performing one-time manual operations under a personal account, for example, related to DB data maintenance, performing ad-hoc operations in the CLI, or running applications from a workstation. You can manually obtain this token from IAM once to have it last a long time and save it in an environment variable on a personal workstation to use automatically and with no additional authentication parameters on CLI launch.
+* **Service Account Key** is mainly used for applications designed to run in environments where the **Metadata** mode is supported, when testing them outside these environments (for example, on a workstation). It can also be used for applications outside these environments, working as an analog of **Refresh Token** for service accounts. Unlike a personal account, service account access objects and roles can be restricted.
+* **Metadata** is used when deploying applications in clouds. Currently, this mode is supported on virtual machines and in {{ sf-name }} {{ yandex-cloud }}.
+
+The token to specify in request parameters can be obtained in the IAM system that the specific {{ ydb-short-name }} deployment is associated with. In particular, {{ ydb-short-name }} in {{ yandex-cloud }} uses Yandex.Passport OAuth and {{ yandex-cloud }} service accounts. When using {{ ydb-short-name }} in a corporate context, a company's standard centralized authentication system may be used.
+
+When using modes in which the {{ ydb-short-name }} client accesses the IAM system, the IAM URL that provides an API for issuing tokens can be set additionally. By default, existing SDKs and CLIs attempt to access the {{ yandex-cloud }} IAM API hosted at `iam.api.cloud.yandex.net:443`.
+
 {% include [overlay/auth_choose.md](_includes/connect_overlay/auth_choose.md) %}
 
 ## Authenticating by username and password {#static-credentions}
diff --git a/ydb/docs/ru/core/concepts/auth.md b/ydb/docs/ru/core/concepts/auth.md
index 80a567c2c0d..3501a10b0e9 100644
--- a/ydb/docs/ru/core/concepts/auth.md
+++ b/ydb/docs/ru/core/concepts/auth.md
@@ -5,9 +5,34 @@
 Поддерживаются следующие режимы аутентификации:
 
 * Анонимный доступ — включен по умолчанию и доступен сразу после [установки кластера](../deploy/index.md).
-* Аутентификация с использованием стороннего IAM-провайдера, например [Yandex Identity and Access Management]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/iam/){% endif %}.
+* [Аутентификация с использованием стороннего IAM-провайдера](#iam), например [Yandex Identity and Access Management]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/iam/){% endif %}.
 * Аутентификация по [логину и паролю](#static-credentions).
 
+## Аутентификация с использованием стороннего IAM-провайдера {#iam}
+
+* **Access Token** — параметром для клиента (SDK или CLI) задается фиксированный токен, который передается в запросы.
+* **Refresh Token** — параметром для клиента (SDK или CLI) задается [OAuth токен](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/) персональной учетной записи, на основании которого клиент периодически в фоновом режиме обращается к IAM API для ротации (получения следующего) токена, передаваемого в запросы.
+* **Service Account Key** — параметром для клиента (SDK или CLI) задаются атрибуты сервисной учетной записи и ключ для подписи, на основании которых клиент периодически в фоновом режиме обращается к IAM API для ротации (получения следующего) токена, передаваемого в запросы.
+* **Metadata** — клиент (SDK или CLI) периодически обращается к локальному сервису для ротации (получения следующего) токена, передаваемого в запросы.
+
+Любой обладатель валидного токена может получить доступ на выполнение операций, поэтому главная задача системы безопасности — обеспечение секретности токена и предотвращение его компрометации.
+
+Режимы аутентификации с ротацией токена **Refresh Token** и **Service Account Key** обеспечивают больший уровень безопасности по сравнению с режимом с фиксированным токеном **Access Token**, так как на сервер {{ ydb-short-name }} по сети передаются только короткоживущие секреты.
+
+Максимальная безопасность и производительность обеспечивается при использовании режима **Metadata**, так как он исключает необходимость работы с секретами при развертывании приложения, а также позволяет обратиться к IAM и закешировать токен заранее, до запуска приложения.
+
+При выборе режима аутентификации среди поддерживаемых сервером и окружением, следует руководствоваться следующими рекомендациями:
+
+* **Anonymous** обычно применяется на самостоятельно разворачиваемых локальных кластерах {{ ydb-short-name }}, недоступных по сети.
+* **Access Token** применяется при отсутствии поддержки других режимов на стороне сервера или в настроечных/отладочных целях. Он не требует взаимодействий клиента с IAM. Однако, если IAM поддерживает API для ротации токенов, то обычно выдаваемые таким IAM фиксированные токены имеют короткий срок жизни, что вынуждает регулярно обновлять их в IAM вручную заново.
+* **Refresh Token** может применяться при выполнении разовых ручных операций под персональной учетной записью, например, связанных с обслуживанием данных в БД, выполнением ad-hoc операций в CLI, или запусками приложений с рабочей станции. Такой токен можно получить вручную в IAM один раз на долгий срок и сохранить в переменной окружения на личной рабочей станции для автоматического применения при запуске CLI без дополнительных параметров аутентификации.
+* **Service Account Key** применяется в первую очередь для приложений, рассчитанных на эксплуатацию в окружениях, где поддерживается режим **Metadata**, при их тестировании вне таких окружений (например, на рабочей станции). Также он может применяться для приложений вне таких окружений, работая как аналог **Refresh Token** для сервисных учетных записей. В отличие от персональной учетной записи, объекты доступа и роли сервисной учетной записи могут быть ограничены.
+* **Metadata** применяется при разворачивании приложений в облаках. В настоящее время этот режим поддерживается на виртуальных машинах и в {{ sf-name }} {{ yandex-cloud }}.
+
+Токен для указания в параметрах может быть получен в системе IAM, с которой связана конкретная установка {{ ydb-short-name }}. В частности, для сервиса {{ ydb-short-name }} в {{ yandex-cloud }} применяется Yandex.Passport OAuth и сервисные аккаунты {{ yandex-cloud }}. При использовании {{ ydb-short-name }} в корпоративных контекстах могут применяться стандартные для данной организации системы централизованной аутентификации.
+
+При использовании режимов, предусматривающих обращение клиента {{ ydb-short-name }} к IAM, дополнительно может быть задан URL IAM, предоставляющий API выдачи токенов. По умолчанию в существующих SDK и CLI производится попытка обращения к API IAM {{ yandex-cloud }}, размещенному на `iam.api.cloud.yandex.net:443`.
+
 {% include [overlay/auth_choose.md](_includes/connect_overlay/auth_choose.md) %}
 
 ## Аутентификация по логину и паролю {#static-credentions}