[Документация Yandex Cloud](../../index.md) > [Yandex Object Storage](../index.md) > Справочник API > Аутентификация в API

# Аутентификация в API Object Storage

Вы можете работать с Object Storage с помощью следующих типов API:

* [AWS S3 API](#aws-s3-api);
* [Yandex Cloud gRPC и REST API](#yandex-api).

## AWS S3 API {#aws-s3-api}

Для аутентификации в [AWS S3 API](../s3/api-ref/index.md) вы можете использовать:
* [IAM-токен](../../iam/concepts/authorization/iam-token.md);
* [статический ключ доступа](../../iam/concepts/authorization/access-key.md);
* [временные ключи Security Token Service](../../iam/concepts/authorization/sts.md);
* [эфемерные ключи доступа](../../iam/concepts/authorization/ephemeral-keys.md).

{% note warning %}

Рекомендованным способом аутентификации в AWS S3 API является аутентификация с помощью IAM-токена: этот способ более безопасен и, в отличие от аутентификации с помощью статического ключа, не требует создания [подписи запроса](../s3/signing-requests.md).

{% endnote %}

{% list tabs group=auth_keys %}


- Аутентификация с помощью IAM-токена {#iam-token}

  IAM-токен может выпускаться как для пользовательского, так и для сервисного аккаунта, а действия с использованием IAM-токена выполняются от имени того аккаунта, для которого этот IAM-токен был выпущен. При этом выполнять действия с бакетами и объектами безопаснее от имени сервисного аккаунта.

  Если для аутентификации в [API](../../glossary/rest-api.md) вы используете IAM-токен, то дополнительно [подписывать](../s3/signing-requests.md) HTTP-запросы не требуется.


- Аутентификация с помощью статического ключа {#static-key}

  Для аутентификации в [AWS S3 API](../s3/api-ref/index.md) и работы с Terraform и другими [поддерживаемыми инструментами](../tools/index.md) вы можете использовать [статический ключ доступа](../../iam/concepts/authorization/access-key.md). Статический ключ доступа выпускается на [сервисный аккаунт](../../iam/concepts/users/service-accounts.md), и все действия с использованием этого ключа выполняются от имени этого сервисного аккаунта. Подробнее на странице [Как пользоваться S3 API](../s3/index.md).

  {% note info %}
  
  Вы можете [запретить доступ в бакет с помощью статических ключей](../operations/buckets/disable-statickey-auth.md). После запрета доступ будет прекращен для всех инструментов, которые их используют: AWS CLI, SDK и сторонние приложения. Это также отключит доступ с помощью [эфемерных ключей](../security/ephemeral-keys.md), [временных ключей доступа Security Token Service](../security/sts.md) и [подписанных (pre-signed) URL](../security/overview.md#pre-signed). Останется доступ только через [IAM-токен](../../iam/concepts/authorization/iam-token.md) или [анонимный доступ](../security/public-access.md) (если он включен).
  
  {% endnote %}

  
  Статический ключ для доступа к Object Storage можно безопасно хранить в сервисе Yandex Lockbox. Подробнее смотрите [Использование секрета Yandex Lockbox для хранения статического ключа доступа](../tutorials/static-key-in-lockbox/index.md).


  Чтобы использовать AWS S3 API с аутентификацией с помощью статического ключа доступа напрямую, без SDK и приложений, необходимо самостоятельно [подписывать запросы](../s3/signing-requests.md). Процесс формирования запроса и подписи вы можете отработать с помощью AWS CLI в [режиме отладки](../s3/signing-requests.md#debugging).

{% endlist %}

Полный перечень методов S3 API приведен в [Справочнике S3 API](../s3/api-ref/index.md).

{% note info %}

Сервисный аккаунт может просматривать список бакетов только в том каталоге, в котором он был создан.

Сервисный аккаунт может выполнять действия с объектами в бакетах, которые созданы в каталогах, отличных от каталога сервисного аккаунта. Для этого [назначьте](../../iam/operations/sa/assign-role-for-sa.md) сервисному аккаунту [роли](../security/index.md#service-roles) на нужный каталог или бакет в нем.

{% endnote %}

### Пример использования AWS S3 API {#s3-api-example}

{% note warning %}

Убедитесь, что аккаунт, от имени которого вы выполняете запрос, имеет необходимые права для выполнения запрашиваемого действия. Например, для загрузки объекта в бакет [назначьте](../../iam/operations/sa/assign-role-for-sa.md) аккаунту [роль](../security/index.md#storage-uploader) `storage.uploader` на бакет. Подробнее на странице [Обзор способов управления доступом в Object Storage](../security/overview.md).

{% endnote %}

Ниже приведены примеры запросов для загрузки объекта в бакет:

{% list tabs group=auth_keys %}


- Аутентификация с помощью IAM-токена {#iam-token}

  ```bash
  IAM_TOKEN="<содержимое_IAM-токена>"
  BUCKET_NAME="<имя_бакета>"
  LOCAL_FILE="<путь_к_локальному_файлу>"
  OBJECT_PATH="<ключ_объекта>"

  curl \
    --request PUT \
    --header "Authorization: Bearer ${IAM_TOKEN}" \
    --upload-file "${LOCAL_FILE}" \
    --verbose \
    "https://storage.yandexcloud.kz/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Где:

  * `IAM_TOKEN` — тело IAM-токена.
  * `BUCKET_NAME` — [имя бакета](../concepts/bucket.md#naming), в который загружается файл.
  * `LOCAL_FILE` — путь к локальному файлу, который вы хотите загрузить в бакет. Например: `./sample.txt`.
  * `OBJECT_PATH` — [ключ](../concepts/object.md#key), который будет присвоен объекту в бакете. Например: `new-prefix/sample-object.txt`.

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

  ```bash
  IAM_TOKEN="<содержимое_IAM-токена>"
  BUCKET_NAME="<имя_бакета>"
  OBJECT_PATH="<ключ_объекта>"
  DIRECTORY_PATH="<путь_к_директории>"

  tar -cvzf - "${DIRECTORY_PATH}" | curl \
    --request PUT \
    --header "Authorization: Bearer ${IAM_TOKEN}" \
    --upload-file - \
    --verbose \
    "https://storage.yandexcloud.kz/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Где `DIRECTORY_PATH` — путь к директории, которую вы хотите заархивировать.


- Аутентификация с помощью статического ключа {#static-key}

  Начиная с версии [8.3.0](https://curl.se/changes.html) утилита `curl` поддерживает автоматическое формирование [строки для подписи](../s3/signing-requests.md#string-to-sign-gen), [подпись запроса](../s3/signing-requests.md#signing) и подстановку необходимых заголовков при работе с AWS S3 API.

  Также вы можете вручную сформировать указанные заголовки и подписать запрос. Смотрите пример для **Версии curl 8.2.1 и ниже**.

  {% cut "Версия curl 8.3.0 и выше" %}

  ```bash
  AWS_KEY_ID="<идентификатор_статического_ключа>"
  AWS_SECRET_KEY="<секретный_ключ>"
  LOCAL_FILE="<путь_к_локальному_файлу>"
  BUCKET_NAME="<имя_бакета>"
  OBJECT_PATH="<ключ_объекта>"

  curl \
    --request PUT \
    --user "${AWS_KEY_ID}:${AWS_SECRET_KEY}" \
    --aws-sigv4 "aws:amz:kz1:s3" \
    --upload-file "${LOCAL_FILE}" \
    --verbose \
    "https://storage.yandexcloud.kz/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Где:
  * `AWS_KEY_ID` — [идентификатор](../../iam/concepts/authorization/access-key.md#key-id) статического ключа доступа.
  * `AWS_SECRET_KEY` — [секретный ключ](../../iam/concepts/authorization/access-key.md#private-key).
  * `LOCAL_FILE` — путь к локальному файлу, который вы хотите загрузить, например `./sample.txt`.
  * `BUCKET_NAME` — [имя бакета](../concepts/bucket.md#naming), в который загружается файл.
  * `OBJECT_PATH` — [ключ](../concepts/object.md#key), который будет присвоен объекту в бакете, например `new-prefix/sample-object.txt`.

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

  ```bash
  AWS_KEY_ID="<идентификатор_статического_ключа>"
  AWS_SECRET_KEY="<секретный_ключ>"
  BUCKET_NAME="<имя_бакета>"
  OBJECT_PATH="<ключ_объекта>"
  DIRECTORY_PATH="<путь_к_директории>"

  tar -cvzf - "${DIRECTORY_PATH}" | curl \
    --request PUT \
    --user "${AWS_KEY_ID}:${AWS_SECRET_KEY}" \
    --aws-sigv4 "aws:amz:kz1:s3" \
    --upload-file - \
    --verbose \
    "https://storage.yandexcloud.kz/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Где `DIRECTORY_PATH` — путь к директории, которую вы хотите заархивировать.

  {% endcut %}

  {% cut "Версия curl 8.2.1 и ниже" %}

  ```bash
  AWS_KEY_ID="<идентификатор_статического_ключа>"
  AWS_SECRET_KEY="<секретный_ключ>"
  LOCAL_FILE="<путь_к_локальному_файлу>"
  BUCKET_NAME="<имя_бакета>"
  OBJECT_PATH="<ключ_объекта>"
  CONTENT_TYPE="<MIME-тип_объекта>"
  DATE_VALUE=`date -R`
  STRING_TO_SIGN="PUT\n\n${CONTENT_TYPE}\n${DATE_VALUE}\n/${BUCKET_NAME}/${OBJECT_PATH}"
  SIGNATURE=`echo -en ${STRING_TO_SIGN} | openssl sha1 -hmac ${AWS_SECRET_KEY} -binary | base64`

  curl \
    --request PUT \
    --upload-file "${LOCAL_FILE}" \
    --verbose \
    --header "Host: storage.yandexcloud.kz" \
    --header "Date: ${DATE_VALUE}" \
    --header "Content-Type: ${CONTENT_TYPE}" \
    --header "Authorization: AWS ${AWS_KEY_ID}:${SIGNATURE}" \
    "https://storage.yandexcloud.kz/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Где:
  * `AWS_KEY_ID` — [идентификатор](../../iam/concepts/authorization/access-key.md#key-id) статического ключа доступа.
  * `AWS_SECRET_KEY` — [секретный ключ](../../iam/concepts/authorization/access-key.md#private-key).
  * `LOCAL_FILE` — путь к локальному файлу, который вы хотите загрузить, например `./sample.txt`.
  * `BUCKET_NAME` — [имя бакета](../concepts/bucket.md#naming), в который загружается файл.
  * `OBJECT_PATH` — [ключ](../concepts/object.md#key), который будет присвоен объекту в бакете, например `new-prefix/sample-object.txt`.
  * `CONTENT_TYPE` — [MIME-тип](https://ru.wikipedia.org/wiki/Список_MIME-типов) загружаемого объекта, например `text/plain`.

  {% endcut %}

{% endlist %}

## Yandex Cloud gRPC и REST API {#yandex-api}


Для аутентификации в Yandex Cloud gRPC и REST API получите [IAM-токен](../../iam/concepts/authorization/iam-token.md). Подробнее о получении IAM-токена для разных типов аккаунтов:

* [Аккаунт на Яндексе](../../iam/operations/iam-token/create.md).
* [Федеративный аккаунт](../../iam/operations/iam-token/create-for-federation.md).
* [Сервисный аккаунт](../../iam/operations/iam-token/create-for-sa.md).

Полученный IAM-токен указывайте при обращении к ресурсам Yandex Cloud через API. Передайте IAM-токен в заголовке `Authorization` в следующем формате:

```yaml
Authorization: Bearer <IAM-токен>
```

Если вы записали IAM-токен в переменную, используйте ее:

```yaml
Authorization: Bearer ${IAM_TOKEN}
```


Полный перечень вызовов и методов Yandex Cloud API смотрите в справочниках [gRPC API](grpc/index.md) и [REST API](index.md).

### Пример использования Yandex Cloud API {#example}

В примере создается бакет со стандартным классом хранилища и размером 50 ГБ.

{% list tabs group=instructions %}

- gRPC API {#grpc-api}

  ```bash
  export IAM_TOKEN="<IAM-токен>"
  grpcurl \
    -H "Authorization: Bearer $IAM_TOKEN" \
    -d '{
      "name": "<имя_бакета>",
      "folder_id": "<идентификатор_каталога>",
      "default_storage_class": "STANDARD",
      "max_size": "53687091200",
      "anonymous_access_flags": [{
        "read": false,
        "list": false,
        "configRead": false
      }]
    }' \
    storage.api.yandexcloud.kz:443 \
    yandex.cloud.storage.v1.BucketService/Create
  ```

  Где:

  * `IAM_TOKEN` — IAM-токен. Подробнее в разделе [Получение IAM-токена](../../iam/operations/index.md#authentication).
  * `name` — имя бакета.
  * `folder_id` — [идентификатор](../../resource-manager/operations/folder/get-id.md) каталога.
  * `default_storage_class` — [класс](../concepts/storage-class.md) хранилища.
  * `max_size` — размер бакета.
  * `anonymous_access_flags` — настройки [доступа](../concepts/bucket.md#bucket-access) к бакету:
    * `read` — публичный доступ на чтение объектов.
    * `list` — публичный доступ к списку объектов.
    * `configRead` — публичный доступ на чтение настроек.

  Результат:

  ```text
  {
    "id": "e3ehmmasama1********",
    "description": "create bucket",
    "createdAt": "2023-08-10T06:32:19.836842Z",
    "createdBy": "ajego134p5h1********",
    "modifiedAt": "2023-08-10T06:32:19.836842Z",
    "done": true,
    "metadata": {"@type":"type.googleapis.com/yandex.cloud.storage.v1.CreateBucketMetadata","name":"<имя_бакета>"},
    "response": {"@type":"type.googleapis.com/yandex.cloud.storage.v1.Bucket","acl":{},"anonymousAccessFlags":{"read":false,"list":false},"createdAt":"2023-08-10T06:32:17.557756Z","defaultStorageClass":"STANDARD","folderId":"b1gmit33ngp3********","maxSize":"53687091200","name":"<имя_бакета>","versioning":"VERSIONING_DISABLED"}
  }
  ```


- REST API {#api}

  ```bash
  export IAM_TOKEN="<IAM-токен>"
  curl \
    --request POST \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --data '{
      "name": "<имя_бакета>",
      "folderId": "<идентификатор_каталога>",
      "defaultStorageClass": "STANDARD",
      "maxSize": "53687091200",
      "anonymousAccessFlags": {
        "read": false,
        "list": false,
        "configRead": false
      }
    }' \
    https://storage.api.yandexcloud.kz/storage/v1/buckets
  ```

  Где:

  * `IAM_TOKEN` — IAM-токен. Подробнее в разделе [Получение IAM-токена](../../iam/operations/index.md#authentication).
  * `name` — имя бакета.
  * `folderId` — [идентификатор](../../resource-manager/operations/folder/get-id.md) каталога.
  * `default_storage_class` — [класс](../concepts/storage-class.md) хранилища.
  * `maxSize` — размер бакета.
  * `anonymousAccessFlags` — настройки [доступа](../concepts/bucket.md#bucket-access) к бакету:
    * `read` — публичный доступ на чтение объектов.
    * `list` — публичный доступ к списку объектов.
    * `configRead` — публичный доступ на чтение настроек.

  Результат:

  ```text
  {
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.storage.v1.CreateBucketMetadata",
    "name": "<имя_бакета>"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.storage.v1.Bucket",
    "anonymousAccessFlags": {
    "read": false,
    "list": false
    },
    "acl": {},
    "name": "<имя_бакета>",
    "folderId": "b1gmit33ngp3********",
    "defaultStorageClass": "STANDARD",
    "versioning": "VERSIONING_DISABLED",
    "maxSize": "53687091200",
    "createdAt": "2023-08-08T12:54:29.321021Z"
  },
  "id": "e3enrkcct2pt********",
  "description": "create bucket",
  "createdAt": "2023-08-08T12:54:32.111022Z",
  "createdBy": "ajego134p5h1********",
  "modifiedAt": "2023-08-08T12:54:32.111022Z"
  }
  ```


{% endlist %}

#### Полезные ссылки {#see-also}

* [Начало работы с AWS S3 API в Yandex Object Storage](../s3/s3-api-quickstart.md)