assume-role-with-saml

Описание

Возвращает набор временных учетных данных безопасности для пользователей, прошедших аутентификацию с помощью ответа на аутентификацию SAML. Данная операция обеспечивает механизм привязки корпоративной системы идентификации или каталога к доступу к Amazon Web Services на основе ролей без учетных данных или настроек для конкретного пользователя. Для сравнения с другими операциями API, создающими временные учетные данные, см. Запрос временных учетных данных безопасности и Сравнение учетных данных STS в руководстве IAM User Guide .

Временные учетные данные безопасности, возвращаемые этой операцией, состоят из идентификатора ключа доступа, секретного ключа доступа и маркера безопасности. Приложения могут использовать эти временные учетные данные безопасности для подписания вызовов к сервисам Amazon Web Services.

Продолжительность сессии

По умолчанию временные учетные данные безопасности, созданные операцией AssumeRoleWithSAML, действуют в течение одного часа. Однако вы можете использовать необязательный параметр DurationSeconds для указания продолжительности сессии. Продолжительность сессии вашей роли определяется указанным вами временем или временем, указанным в элементе SessionNotOnOrAfter ответа на аутентификацию SAML, что из них короче. Вы можете задать значение параметра DurationSeconds от 900 секунд (15 минут) до максимального значения продолжительности сессии для роли. Это значение может варьироваться от 1 часа до 12 часов. Чтобы узнать, как посмотреть максимальное значение для вашей роли, см. раздел Просмотр максимальной продолжительности сессии для роли в руководстве IAM User Guide . Максимальное ограничение продолжительности сессии применяется при использовании операций API AssumeRole* или команд CLI assume-role*. Однако это ограничение не применяется при использовании этих операций для создания URL-адреса консоли. Дополнительная информация доступна в разделе Использование ролей IAM в руководстве IAM User Guide .

Примечание

Ограничение цепочки ролей ограничивает сессию CLI или API Amazon Web Services ролью до максимума в один час. Когда вы используете операцию API AssumeRole для принятия роли, вы можете указать продолжительность сессии роли с помощью параметра DurationSeconds. Вы можете задать значение параметра до 43200 секунд (12 часов), в зависимости от максимальной продолжительности сессии для вашей роли. Однако, если вы принимаете роль с использованием цепочки ролей и задаете значение параметра DurationSeconds, превышающее один час, операция завершается ошибкой.

Разрешения

Временные учетные данные безопасности, созданные операцией AssumeRoleWithSAML, могут использоваться для выполнения вызовов API к любому сервису Amazon Web Services с одним исключением: вы не можете вызывать операции API STS GetFederationToken или GetSessionToken.

(Необязательно) Вы можете передать встроенные или управляемые политики сессии в эту операцию. Вы можете передать один документ политики JSON для использования в качестве встроенной политики сессии. Вы также можете указать до 10 управляемых политических Amazon Resource Names (ARN) для использования в качестве управляемых политиках сессии. Текст без форматирования, используемый для встроенных и управляемых политических документов, не должен превышать 2048 символов. Передача политических документов в эту операцию возвращает новые временные учетные данные. Разрешения полученной сессии являются пересечением политики идентификации роли и политических документов сессии. Вы можете использовать временные учетные данные роли в последующих вызовах API Amazon Web Services для доступа к ресурсам в аккаунте, владеющем ролью. Политики сессии не могут предоставить больше прав, чем разрешено политикой идентификации роли, которая принимается. Дополнительная информация доступна в разделе Политики сессий в руководстве IAM User Guide .

Вызов операции AssumeRoleWithSAML не требует использования учетных данных безопасности Amazon Web Services. Идентификация вызывающего лица проверяется с использованием ключей в метаданных, загруженных для сущности поставщика SAML вашего поставщика идентификации.

Предупреждение

Вызов операции AssumeRoleWithSAML может привести к записи в журналы CloudTrail. Запись включает значение элемента NameID утверждения SAML. Рекомендуется использовать NameIDType, не связанный с какой-либо личной идентифицирующей информацией (PII). Например, можно использовать постоянный идентификатор (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent).

Теги

(Необязательно) Вы можете настроить свой IdP для передачи атрибутов в утверждение SAML в качестве тегов сессии. Каждый тег сессии состоит из имени ключа и соответствующего значения. Дополнительная информация о тегах сессии доступна в разделе Передача тегов сессии в STS в руководстве IAM User Guide .

Вы можете передать до 50 тегов сессии. Ключи тегов сессии в формате простого текста не должны превышать 128 символов, а значения не должны превышать 256 символов. Подробная информация о этих и других ограничениях представлена в разделе Ограничения символов IAM и STS в руководстве IAM User Guide .

Примечание

Сервис Amazon Web Services сжимает переданную встроенную политику сессии, управляемые политические ARN и теги сессии в упакованный двоичный формат, имеющий отдельное ограничение. Ваш запрос может завершиться ошибкой из-за этого ограничения, даже если ваш текст без форматирования соответствует другим требованиям. Элемент ответа PackedPolicySize указывает процентным соотношением, насколько близки политики и теги вашего запроса к максимальному размеру.

Вы можете передать тег сессии с тем же ключом, что и тег, прикрепленный к роли. В этом случае теги сессии перезаписывают теги роли с тем же ключом.

Администратор должен предоставить вам необходимые разрешения для передачи тегов сессии. Администратор также может создать точные разрешения, чтобы разрешить передачу только определенных тегов сессии. Подробная информация представлена в руководстве IAM User Guide в разделе Учебник: использование тегов для управления доступом на основе атрибутов.

Вы можете установить теги сессии как транзитивные. Транзитивные теги сохраняются во время цепочки ролей. Дополнительная информация представлена в разделе Цепочка ролей с тегами сессии в руководстве IAM User Guide .

Настройка SAML

Прежде чем ваше приложение сможет вызывать операцию AssumeRoleWithSAML, необходимо настроить поставщика идентификации SAML (IdP) для выдачи утверждений, необходимых Amazon Web Services. Кроме того, необходимо использовать Identity and Access Management (IAM) для создания сущности поставщика SAML в вашем аккаунте Amazon Web Services, представляющей вашего поставщика идентификации. Также необходимо создать роль IAM, в политике доверия которой указан этот поставщик SAML.

Дополнительная информация доступна по следующим ссылкам:

О федерации на основе SAML 2.0 в руководстве IAM User Guide.
Создание поставщиков идентификации SAML в руководстве IAM User Guide.
Настройка стороны, доверяющей и утверждения в руководстве IAM User Guide.
Создание роли для федерации SAML 2.0 в руководстве IAM User Guide.

См. также: Документация по API AWS

Синопсис

  assume-role-with-saml
--role-arn <value>
--principal-arn <value>
--saml-assertion <value>
[--policy-arns <value>]
[--policy <value>]
[--duration-seconds <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]

Параметры

--role-arn (строка)

Идентификатор ресурса Amazon (ARN) роли, которую вызывающий элемент предполагает.

--principal-arn (строка)

Идентификатор ресурса Amazon (ARN) поставщика SAML в IAM, который описывает IdP.

--saml-assertion (строка)

Ответ аутентификации SAML в кодировке base64, предоставленный IdP.

Дополнительную информацию см. в разделе «Настройка стороны, полагающейся на SAML, и добавление утверждений» в руководстве пользователя IAM.

--policy-arns (список)

Идентификаторы ресурсов Amazon (ARN) управляемых политик IAM, которые вы хотите использовать в качестве управляемых политик сеанса. Политики должны существовать в той же учетной записи, что и роль.

Этот параметр необязателен. Вы можете указать до 10 ARN управляемых политик. Однако текст, который вы используете для встроенных и управляемых политик сеанса, не должен превышать 2048 символов. Дополнительную информацию об ARN см. в разделе «Идентификаторы ресурсов Amazon (ARN) и пространства имен служб Amazon Web Services» в общем справочнике Amazon Web Services.

Примечание

Преобразование Amazon Web Services сжимает переданную встроенную политику сеанса, управляемые ARN политик и теги сеанса в упакованный двоичный формат, имеющий отдельный лимит. Ваш запрос может завершиться ошибкой из-за этого лимита, даже если ваш текстовый формат соответствует другим требованиям. Элемент ответа PackedPolicySize указывает в процентах, насколько близки политики и теги вашего запроса к верхнему пределу размера.

Передача политик в эту операцию возвращает новые временные учетные данные. Разрешения полученного сеанса являются пересечением политики роли на основе идентификатора и политик сеанса. Вы можете использовать временные учетные данные роли в последующих вызовах API Amazon Web Services для доступа к ресурсам в учетной записи, владеющей ролью. Вы не можете использовать политики сеанса для предоставления большего числа разрешений, чем разрешено политикой на основе идентификатора роли, которая предполагается. Дополнительную информацию см. в разделе «Политики сеанса» в руководстве пользователя IAM.

(структура)

Ссылка на управляемую политику IAM, которая передается как политика сеанса для сеанса роли или сеанса федеративного пользователя.

arn -> (строка)

Идентификатор ресурса Amazon (ARN) управляемой политики IAM, которую нужно использовать в качестве политики сеанса для роли. Дополнительную информацию об ARN см. в разделе «Идентификаторы ресурсов Amazon (ARN) и пространства имен служб Amazon Web Services» в общем справочнике Amazon Web Services.

Сокращенная синтаксическая запись:

arn=string ...

Синтаксис JSON:

[
  {
    "arn": "string"
  }
  ...
]

--policy (строка)

Политика IAM в формате JSON, которую вы хотите использовать в качестве встроенной политики сеанса.

Этот параметр необязателен. Передача политик в эту операцию возвращает новые временные учетные данные. Разрешения полученного сеанса являются пересечением политики роли на основе идентификатора и политик сеанса. Вы можете использовать временные учетные данные роли в последующих вызовах API Amazon Web Services для доступа к ресурсам в учетной записи, владеющей ролью. Вы не можете использовать политики сеанса для предоставления большего числа разрешений, чем разрешено политикой на основе идентификатора роли, которая предполагается. Дополнительную информацию см. в разделе «Политики сеанса» в руководстве пользователя IAM.

Текстовый формат встроенных и управляемых политик сеанса не должен превышать 2048 символов. Символы JSON-политики могут быть любым символом ASCII от пробела до конца списка допустимых символов (u0020 до u00FF). Он также может включать символы табуляции (u0009), новой строки (u000A) и возврата каретки (u000D).

Дополнительную информацию о разрешениях сеанса роли см. в разделе «Политики сеанса».

Примечание

--duration-seconds (целое число)

Продолжительность сеанса роли в секундах. Сеанс вашей роли длится в течение времени, которое вы указываете для параметра DurationSeconds, или до момента, указанного в значении SessionNotOnOrAfter ответа аутентификации SAML, в зависимости от того, что меньше. Вы можете указать значение DurationSeconds от 900 секунд (15 минут) до максимальной продолжительности сеанса для роли. Это значение может быть от 1 часа до 12 часов. Если вы укажете значение больше этого, операция завершится ошибкой. Например, если вы укажете продолжительность сеанса 12 часов, но ваш администратор установил максимальную продолжительность сеанса 6 часов, ваша операция завершится ошибкой. Чтобы узнать, как просмотреть максимальное значение для вашей роли, см. раздел «Просмотр максимальной продолжительности сеанса для роли» в руководстве пользователя IAM.

По умолчанию значение равно 3600 секундам.

Примечание

Параметр DurationSeconds отделен от продолжительности сеанса консоли, который вы можете запросить, используя возвращенные учетные данные. Запрос к точке входа федерации для токена входа в консоль принимает параметр SessionDuration, который указывает максимальную длительность сеанса консоли. Дополнительную информацию см. в разделе «Создание URL-адреса, который позволяет федеративным пользователям получить доступ к веб-консоли Amazon Web Services» в руководстве пользователя IAM.

--cli-input-json | --cli-input-yaml (строка) Читает аргументы из предоставленной JSON-строки. JSON-строка следует формату, предоставленному --generate-cli-skeleton. Если на командной строке указаны другие аргументы, эти значения переопределят значения, предоставленные JSON. Невозможно передать произвольные двоичные значения с помощью значения, предоставленного JSON, поскольку строка будет взята дословно. Это может не быть указано вместе с --cli-input-yaml.

--generate-cli-skeleton (строка) Выводит JSON-скелет в стандартный вывод без отправки запроса API. Если он предоставлен без значения или со значением input, выводит пример входного JSON, который можно использовать в качестве аргумента для --cli-input-json. Аналогично, если предоставлено yaml-input, он выведет пример входного YAML, который можно использовать с --cli-input-yaml. Если предоставлено значение output, он проверяет входные данные команды и возвращает пример выходного JSON для этой команды. Сгенерированный JSON-скелет не является стабильным между версиями AWS CLI, и нет гарантий обратной совместимости в сгенерированном JSON-скелете.

Глобальные параметры

--debug (логическое значение)

Включить отладовую запись.

--endpoint-url (строка)

Переопределить стандартный URL команды указанным URL.

--no-verify-ssl (логическое значение)

По умолчанию AWS CLI использует SSL при взаимодействии со службами AWS. Для каждого соединения SSL AWS CLI будет проверять сертификаты SSL. Этот параметр переопределяет поведение по умолчанию по проверке сертификатов SSL.

--no-paginate (логическое значение)

Отключить автоматическую постраничную навигацию. Если автоматическая постраничная навигация отключена, AWS CLI выполнит только один вызов для первой страницы результатов.

--output (строка)

Стиль форматирования для вывода команды.

json
text
table
yaml
yaml-stream

--query (строка)

Запрос JMESPath для фильтрации данных ответа.

--profile (строка)

Использовать определенный профиль из файла учетных данных.

--region (строка)

Использовать указанный регион. Переопределяет настройки конфигурации/среды.

--version (строка)

Отобразить версию этого инструмента.

--color (строка)

Включить/выключить цветной вывод.

on
off
auto

--no-sign-request (логическое значение)

Не подписывать запросы. Учетные данные не будут загружаться, если этот аргумент указан.

--ca-bundle (строка)

Файл набора сертификатов CA для проверки сертификатов SSL. Переопределяет настройки конфигурации/среды.

--cli-read-timeout (целое число)

Максимальное время чтения сокета в секундах. Если значение установлено в 0, чтение сокета будет блокирующим и не будет иметь таймаут. Значение по умолчанию составляет 60 секунд.

--cli-connect-timeout (целое число)

Максимальное время подключения сокета в секундах. Если значение установлено в 0, подключение сокета будет блокирующим и не будет иметь таймаут. Значение по умолчанию составляет 60 секунд.

--cli-binary-format (строка)

Стиль форматирования, используемый для двоичных блоков. Формат по умолчанию — base64. Формат base64 ожидает, что двоичные блоки будут предоставлены в виде закодированной в base64 строки. Формат raw-in-base64-out сохраняет совместимость с поведением AWS CLI V1, а двоичные значения должны передаваться буквально. При предоставлении содержимого из файла, которое соответствует двоичному блоку, fileb:// всегда будет обрабатываться как двоичный и использовать содержимое файла непосредственно независимо от параметра cli-binary-format. При использовании file:// содержимое файла должно быть должным образом отформатировано для настроенного параметра cli-binary-format.

base64
raw-in-base64-out

--no-cli-pager (логическое значение)

Отключить вывод страницы cli.

--cli-auto-prompt (логическое значение)

Автоматически запрашивать параметры входных данных cli.

--no-cli-auto-prompt (логическое значение)

Отключить автоматическую запрос параметров входных данных cli.

Примеры

Примечание

Для использования следующих примеров необходимо установить и настроить AWS CLI. Дополнительную информацию см. в руководстве пользователя AWS CLI в разделе «Начало работы».

Если не указано иное, во всех примерах используются правила цитирования Unix-подобных систем. Эти примеры необходимо адаптировать к правилам цитирования вашей оболочки. Дополнительную информацию см. в руководстве пользователя AWS CLI в разделе «Использование кавычек со строками».

Получение краткосрочных учетных данных для роли, аутентифицированной с помощью SAML

Следующая команда assume-role-with-saml получает набор краткосрочных учетных данных для роли IAM TestSaml. Запрос в этом примере аутентифицируется с использованием утверждения SAML, предоставляемого вашим поставщиком идентификации при аутентификации в нем.

aws sts assume-role-with-saml \
    --role-arn arn:aws:iam::123456789012:role/TestSaml \
    --principal-arn arn:aws:iam::123456789012:saml-provider/SAML-test \
    --saml-assertion "VERYLONGENCODEDASSERTIONEXAMPLExzYW1sOkF1ZGllbmNlPmJsYW5rPC9zYW1sOkF1ZGllbmNlPjwvc2FtbDpBdWRpZW5jZVJlc3RyaWN0aW9uPjwvc2FtbDpDb25kaXRpb25zPjxzYW1sOlN1YmplY3Q+PHNhbWw6TmFtZUlEIEZvcm1hdD0idXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOm5hbWVpZC1mb3JtYXQ6dHJhbnNpZW50Ij5TYW1sRXhhbXBsZTwvc2FtbDpOYW1lSUQ+PHNhbWw6U3ViamVjdENvbmZpcm1hdGlvbiBNZXRob2Q9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDpjbTpiZWFyZXIiPjxzYW1sOlN1YmplY3RDb25maXJtYXRpb25EYXRhIE5vdE9uT3JBZnRlcj0iMjAxOS0xMS0wMVQyMDoyNTowNS4xNDVaIiBSZWNpcGllbnQ9Imh0dHBzOi8vc2lnbmluLmF3cy5hbWF6b24uY29tL3NhbWwiLz48L3NhbWw6U3ViamVjdENvbmZpcm1hdGlvbj48L3NhbWw6U3ViamVjdD48c2FtbDpBdXRoblN0YXRlbWVudCBBdXRoPD94bWwgdmpSZXNwb25zZT4="

Вывод:

{
    "Issuer": "https://integ.example.com/idp/shibboleth</Issuer",
    "AssumedRoleUser": {
        "Arn": "arn:aws:sts::123456789012:assumed-role/TestSaml",
        "AssumedRoleId": "ARO456EXAMPLE789:TestSaml"
    },
    "Credentials": {
        "AccessKeyId": "ASIAV3ZUEFP6EXAMPLE",
        "SecretAccessKey": "8P+SQvWIuLnKhh8d++jpw0nNmQRBZvNEXAMPLEKEY",
        "SessionToken": "IQoJb3JpZ2luX2VjEOz////////////////////wEXAMPLEtMSJHMEUCIDoKK3JH9uGQE1z0sINr5M4jk+Na8KHDcCYRVjJCZEvOAiEA3OvJGtw1EcViOleS2vhs8VdCKFJQWPQrmGdeehM4IC1NtBmUpp2wUE8phUZampKsburEDy0KPkyQDYwT7WZ0wq5VSXDvp75YU9HFvlRd8Tx6q6fE8YQcHNVXAkiY9q6d+xo0rKwT38xVqr7ZD0u0iPPkUL64lIZbqBAz+scqKmlzm8FDrypNC9Yjc8fPOLn9FX9KSYvKTr4rvx3iSIlTJabIQwj2ICCR/oLxBA==",
        "Expiration": "2019-11-01T20:26:47Z"
    },
    "Audience": "https://signin.aws.amazon.com/saml",
    "SubjectType": "transient",
    "PackedPolicySize": "6",
    "NameQualifier": "SbdGOnUkh1i4+EXAMPLExL/jEvs=",
    "Subject": "SamlExample"
}

Дополнительную информацию см. в разделе «Запрос временных учетных данных безопасности» в руководстве пользователя AWS IAM.

Вывод

Удостоверения -> (структура)

Временные учетные данные безопасности, которые включают идентификатор ключа доступа, секретный ключ доступа и токен безопасности (или сессии).

Примечание

Размер токена безопасности, возвращаемого операциями API STS, не фиксирован. Мы настоятельно рекомендуем не делать предположений о максимальном размере.

AccessKeyId -> (строка)

Идентификатор ключа доступа, который идентифицирует временные учетные данные безопасности.

SecretAccessKey -> (строка)

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

SessionToken -> (строка)

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

Expiration -> (метка времени)

Дата истечения срока действия текущих учетных данных.

AssumedRoleUser -> (структура)

Идентификаторы временных учетных данных безопасности, которые возвращает операция.

AssumedRoleId -> (строка)

Уникальный идентификатор, содержащий идентификатор роли и имя сессии роли, которая используется. Идентификатор роли генерируется Amazon Web Services при создании роли.

Arn -> (строка)

ARN временных учетных данных безопасности, возвращаемых действием AssumeRole. Для получения дополнительной информации об ARN и о том, как их использовать в политиках, см. Идентификаторы IAM в руководстве по IAM.

PackedPolicySize -> (целое число)

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

Subject -> (строка)

Значение элемента NameID в элементе Subject утверждения SAML.

SubjectType -> (строка)

Формат имени ID, определенный атрибутом Format в элементе NameID утверждения SAML. Типичные примеры формата — transient или persistent .

Если формат включает префикс urn:oasis:names:tc:SAML:2.0:nameid-format , этот префикс удаляется. Например, urn:oasis:names:tc:SAML:2.0:nameid-format:transient возвращается как transient . Если формат включает любой другой префикс, формат возвращается без изменений.

Issuer -> (строка)

Значение элемента Issuer утверждения SAML.

Audience -> (строка)

Значение атрибута Recipient элемента SubjectConfirmationData утверждения SAML.

NameQualifier -> (строка)

Значение хеша, основанное на конкатенации следующего:

Значение ответа Issuer.
Идентификатор учетной записи Amazon Web Services.
Название поставщика SAML в IAM (последняя часть ARN).

Комбинация NameQualifier и Subject может использоваться для уникальной идентификации пользователя.

Следующий псевдокод демонстрирует, как рассчитывается значение хеша:

BASE64 ( SHA1 ( "https://example.com/saml" + "123456789012" + "/MySAMLIdP" ) )

SourceIdentity -> (строка)

Значение в атрибуте SourceIdentity утверждения SAML. Значение источника идентификации сохраняется при цепочках сессий ролей.

Вы можете потребовать от пользователей установить значение источника идентификации при принятии роли. Для этого используется ключ условия sts:SourceIdentity в политике доверия к роли. Таким образом, действия, выполняемые с ролью, связываются с этим пользователем. После установки источника идентификации его значение нельзя изменить. Оно присутствует в запросе для всех действий, выполняемых ролью, и сохраняется при цепочках сессий ролей. Вы можете настроить свой поставщик SAML-идентификаторов на использование атрибута, связанного с пользователями (например, имя пользователя или адрес электронной почты), в качестве источника идентификации при вызове AssumeRoleWithSAML . Для этого добавьте атрибут в утверждение SAML. Дополнительную информацию об использовании источника идентификации см. в руководстве по IAM в разделе «Отслеживание и контроль действий, выполняемых с принятыми ролями».

Регулярное выражение, используемое для проверки этого параметра, представляет собой строку символов, состоящую из буквенно-цифровых символов верхнего и нижнего регистра без пробелов. Также можно использовать подчеркивания или любой из следующих символов: =,.@-