configure aws credentials

Настройка учетных данных AWS для действий GitHub

Настройте свои учетные данные AWS и переменные среды региона для использования в других действиях GitHub.

Это действие реализует цепочку разрешения учетных данных AWS JavaScript SDK и экспортирует переменные среды сеанса для других ваших действий для использования. Экспорт переменной среды обнаруживается как AWS SDK, так и AWS CLI для вызовов AWS API.

Обзор

API вызовы в AWS должны быть подписаны с информацией о учете учетных данных, поэтому, когда вы используете один из AWS SDK или инструмент AWS, вы должны предоставить ему учетные данные AWS и регион AWS. Одним из способов сделать это в действиях GitHub является использование секрета репозитория с учетными данными IAM, но это не соответствует руководящим принципам безопасности AWS при использовании долгосрочных учетных данных. Вместо этого мы рекомендуем вам использовать долгосрочные учетные данные или JWT, чтобы принести временные учетные данные, а вместо этого использовать их со своими инструментами. Это действие GitHub облегчает это.

AWS SDK и инструменты ищут ваши учетные данные в стандартизированных переменных среды. По сути, это действие проходит через стандартный поток разрешения учетных данных, и в конце экспортирует переменные среды, чтобы вы могли использовать позже.

Мы поддерживаем пять методов получения учетных данных из AWS, но мы рекомендуем использовать поставщик OIDC от GitHub в сочетании с конечной точкой поставщика идентификации AWS IAM.

Для получения дополнительной информации о том, как это сделать, читайте дальше.

Примечание о GHES

Некоторая из этой документации может быть неточной, если вы используете GHES (GitHub Enterprise Server), пожалуйста, обратите внимание, чтобы просмотреть документацию GitHub, когда это было актуально.

Например, URL, из которого выпускается OIDC JWT, отличается от обычного token.actions.githubusercontent.com . В результате вам нужно будет настроить это по -разному при создании поставщика идентификаций.

В настоящее время у нас нет среды тестирования GHES для проверки этого действия. Если вы работаете в GHE и сталкиваетесь с проблемами, пожалуйста, сообщите нам об этом.

Рекомендации по безопасности

Мы рекомендуем следить за лучшими практиками Amazon IAM для учетных данных AWS, используемых в рабочих процессах GitHub Actions, включая:

• Не храните учетные данные в коде вашего репозитория.
• Предоставьте наименьшую привилегию для учетных данных, используемых в рабочих процессах действий GitHub. Предоставьте только разрешения, необходимые для выполнения действий в ваших рабочих процессах GitHub. Не принимайте чрезмерно допустимые роли, даже для тестирования.
• Следите за активностью учетных данных, используемых в рабочих процессах действий GitHub.
• Используйте временные учетные данные, когда это возможно.
• Периодически вращайте любые долгосрочные учетные данные, которые вы используете.

Используя это действие

Есть пять различных поддерживаемых способов получить полномочия:

• Использование поставщика OIDC от GitHub ( AssumeRoleWithWebIdentity )
• Работа в качестве пользователя IAM (вызов STS не сделан)
• Использование клавиш доступа в качестве ввода действия ( AssumeRole )
• Использование файла токена WebIdenity ( AssumeRoleWithWebIdentity )
• Использование существующих учетных данных в вашем бегуне ( AssumeRole )

Поскольку мы используем AWS JavaScript SDK, мы всегда будем использовать поток разрешения учетных данных для node.js. В зависимости от ваших входов, действие может переопределить части этого потока.

Мы рекомендуем использовать первый вариант выше: поставщик GitHub OIDC. Этот метод использует OIDC для получения недолговечных учетных данных, необходимых для ваших действий. См. OIDC для получения дополнительной информации о том, как настроить свою учетную запись AWS, чтобы взять на себя роль в OIDC.

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

Идентичность используется	aws-access-key-id	role-to-assume	web-identity-token-file	role-chaining	id-token разрешение
[✅ рекомендуется] Принять роль непосредственно с использованием поставщика GitHub OIDC		✔			✔
IAM пользователь	✔
Примите роль, используя учетные данные IAM пользователя	✔	✔
Примите роль, используя учетные данные для файлов токена WebIdenity		✔	✔
Примите роль, используя существующие учетные данные		✔		✔

Примечание: role-chaining не всегда необходима для использования существующих учетных данных. Если вы получаете ошибку «учетные данные, загруженные SDK, не совпадают», попробуйте включить эту опцию.

Параметры

См. Action.yml для более подробной информации.

Вариант	Описание	Необходимый
AWS-Region	Какой регион AWS использовать	Да
роль-osmume	Роль для получения учетных данных. Требуется только для некоторых типов аутентификации.	Нет
AWS-ACCESS-KEY-ID	AWS Access Key для использования. Требуется только для некоторых типов аутентификации.	Нет
AWS-Secret-Access-ключ	AWS Secret Key для использования. Требуется только для некоторых типов аутентификации.	Нет
AWS-Session-Token	Токен сеанса AWS для использования. Используется в необычных сценариях аутентификации.	Нет
ролевая цепочка	Используйте существующие учетные данные из среды, чтобы взять на себя новую роль.	Нет
аудитория	Аудитория JWT при использовании OIDC. Используется в неколевых перегородках AWS, таких как Китайские регионы.	Нет
http-proxy	HTTP -прокси для использования для вызовов API.	Нет
Маска-яс-поступок-ид	Идентификаторы аккаунта AWS не считаются секретными. Установка этого в любом случае скрывает идентификаторы учетной записи от вывода.	Нет
ролевые секунды	Предполагаемая продолжительность роли за считанные секунды, если принять роль. По умолчанию до 1 часа.	Нет
Ролевой иид	Внешний идентификатор роли, чтобы взять на себя. Требуется только в том случае, если ваша роль требует этого.	Нет
ролевая сессия	По умолчанию «Githubactions», но могут быть изменены, если это необходимо.	Нет
ролевая сессия-сессия	Пропустить теги сеанса, если установлено.	Нет
встроенная политика	Вы можете также ограничить предполагаемую политику роли, определяя встроенную политику здесь.	Нет
Управляемые сессии	Вы можете также ограничить предполагаемую политику роли, указав здесь управляемую политику.	Нет
выходные дни	При установке выходы извлекали учетные данные в качестве выхода шага действия. По умолчанию ложно.	Нет
UNSET-Current-Credentials	При установке попытки не отключить любые существующие учетные данные в вашем бегуне.	Нет
Отключить-резок	Отключено повторная перенапряжение/логика отступления для принятия ролевых вызовов. По умолчанию повторные данные включены.	Нет
Retry-Max-Attempts	Ограничивает количество попыток повторения, прежде чем сдаться. По умолчанию до 12.	Нет
Специальные характеристики	Необычно, некоторые среды не могут переносить специальных персонажей в секретном ключе. Эта опция повторно извлечет учетные данные до тех пор, пока ключ секретного доступа не содержит специальных символов. Этот вариант переопределяет отключение отключения и повторного макса-аттэмпта.	Нет

Спективные сроки жизни

Продолжительность сеанса по умолчанию составляет 1 час .

Если вы хотите скорректировать это, вы можете передать продолжительность к role-duration-seconds , но продолжительность не может превышать максимум, который был определен, когда была создана роль IAM.

Внешний идентификатор

Если для вашей роли требуется внешний идентификатор, вы можете предоставить внешний идентификатор с помощью ввода role-external-id

Тегинга и имя сеанса

Имя сеанса по умолчанию-«Githubactions», и вы можете изменить его, указав желаемое имя в role-session-name . Сеанс будет отмечен следующими тегами: (см. Документацию Github для определений переменных среды GITHUB_ )

Ключ	Ценить
GitHub	"Действия"
Репозиторий	Github_repository
Рабочий процесс	Github_workflow
Действие	Github_action
Актер	Github_actor
Ветвь	Github_ref
Совершить	Github_sha

Примечание. Все значения тегов должны соответствовать требованиям тега. В частности, GITHUB_WORKFLOW будет усечен, если он будет слишком долго. Если GITHUB_ACTOR или GITHUB_WORKFLOW содержит недопустимые символы, символы будут заменены на '*'.

Действие будет использовать сессию по умолчанию во время предположения о роле, если вы не следовали нашей рекомендации и не принимаете роль с веб -идентичности. Для предположения о роле веб -идентификации теги сеанса должны быть включены в кодируемый токен веб -идентификации. Это означает, что теги могут быть поставлены только поставщиком OIDC, и они не могут установить во время вызова API ApeMeroleWithWeThebIdentity в действии. Смотрите #419 для получения дополнительной информации.

Вы можете пропустить эту сеанс, предоставив role-skip-session-tagging как верно в входе действий:

      uses : aws-actions/configure-aws-credentials@v4
      with :
        role-skip-session-tagging : true

Сессионные политики

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

Встроенные сессионные политики

Политика IAM в струнном формате JSON, который вы хотите использовать в качестве встроенной политики сессии. В зависимости от предпочтений, JSON может быть написан на одной строке, подобной этим:

      uses : aws-actions/configure-aws-credentials@v4
      with :
         inline-session-policy : ' {"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:List*","Resource":"*"}]} '

Или у нас также может быть хорошо отформатированный JSON:

      uses : aws-actions/configure-aws-credentials@v4
      with :
         inline-session-policy : >-
          {
           "Version": "2012-10-17",
           "Statement": [
            {
             "Sid":"Stmt1",
             "Effect":"Allow",
             "Action":"s3:List*",
             "Resource":"*"
            }
           ]
          } 

Управляемые сессионные политики

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

      uses : aws-actions/configure-aws-credentials@v4
      with :
         managed-session-policies : arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

И мы можем передать несколько управляемых политик, нравится это:

      uses : aws-actions/configure-aws-credentials@v4
      with :
         managed-session-policies : |
          arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess
          arn:aws:iam::aws:policy/AmazonS3OutpostsReadOnlyAccess

Разное

Отрегулируйте механизм повторения

Теперь вы можете настроить настройки повторной попытки, когда вызов STS не удается. По умолчанию мы повторяем с экспоненциальным отбором 12 раз. Вы можете полностью отключить это поведение, установив вход disable-retry в true , или вы можете настроить количество раз, когда он возвращает с помощью ввода retry-max-attempts .

Идентификатор учетной записи маски

Идентификатор вашей учетной записи не замаскирован по умолчанию в журналах рабочих процессов, поскольку она не считается конфиденциальной информацией. Тем не менее, вы можете установить true mask-aws-account-id чтобы замаскировать идентификатор своей учетной записи в журналах рабочих процессов, если это необходимо.

Неоткрытые текущие полномочия

Иногда существующие учетные данные в вашем бегуне могут мешать предполагаемому результату. Вы можете установить входные данные unset-current-credentials для true этой проблемы.

Специальные символы в AWS_SECRET_ACCESS_KEY

Некоторые кромки не могут должным образом проанализировать AWS_SECRET_ACCESS_KEY , если он содержит специальные символы. Для получения дополнительной информации см. Документацию AWS CLI. Если вы установите вариант special-characters-workaround , это действие будет постоянно повторно извлекать учетные данные, пока мы не получим тот, у которого нет особых персонажей. Этот вариант переопределяет варианты disable-retry и retry-max-attempts . Мы рекомендуем вам не включать этот вариант, если не требуется, потому что повторение API бесконечно до тех пор, пока они не достигнут успеха, не является наилучшей практикой.

Oidc

Мы рекомендуем использовать поставщика OIDC от GitHub, чтобы получить недолговечные учетные данные AWS, необходимые для ваших действий. При использовании OIDC вы настраиваете IAM, чтобы принять JWT из конечной точки GitHub OIDC. Затем это действие создаст JWT, уникальный для рабочего процесса с использованием конечной точки OIDC, и он будет использовать JWT, чтобы взять на себя указанную роль с краткосрочными учетными данными.

Чтобы заставить это работать

1. Настройте свой рабочий процесс, чтобы использовать id-token: write разрешение.

2. Настройте свою аудиторию, если требуется.

3. В вашей учетной записи AWS настройте IAM, чтобы доверять поставщику идентификации OIDC GitHub.

4. Настройте роль IAM с соответствующими ограничениями претензий и разрешением.

   Примечание . Сообщалось, что называет вашу роль «Githubactions» не работает. Смотрите #953.

5. Укажите ARN этой роли при настройке этого действия.

Во-первых, для того, чтобы это действие создало JWT, ваш файл рабочего процесса должен иметь id-token: write разрешение:

    permissions :
      id-token : write
      contents : read

OIDC аудитория

Когда JWT создается, необходимо указать аудиторию. Обычно вы используете sts.amazonaws.com , и это действие использует это по умолчанию, если вы не указаете его. Это будет работать для большинства случаев. Изменение аудитории по умолчанию может потребоваться при использовании раздела AWS без декорации, такие как регионы Китая. Вы можете указать аудиторию через вклад audience :

    - name : Configure AWS Credentials for China region audience
      uses : aws-actions/configure-aws-credentials@v4
      with :
        audience : sts.amazonaws.com.cn
        aws-region : us-east-3
        role-to-assume : arn:aws-cn:iam::123456789100:role/my-github-actions-role

Настройка IAM для доверия GitHub

Чтобы использовать поставщика GitHub OIDC, вы должны сначала настроить федерацию с поставщиком в качестве IAM IDP. Поставщик GitHub OIDC должен быть создан только один раз на каждой учетной записи (то есть несколько ролей IAM, которые могут быть приняты OIDC GitHub, может поделиться одним поставщиком OIDC). Вот пример шаблона облачной информации, который будет настроить это доверие для вас.

Обратите внимание, что отпечаток большого пальца ниже был установлен на все F, потому что отпечаток большого пальца не используется при аутентификации token.actions.githubusercontent.com . Это особый случай, используемый только тогда, когда OIDC GitHub аутентифицирует IAM . IAM использует свою библиотеку доверенных CAS для аутентификации. Значение по -прежнему остается API, поэтому он должен быть указан.

Вы можете скопировать шаблон ниже или загрузить его отсюда: https://d38mtn6aq9zhn6.cloudfront.net/configure-aws-credentials-latest.yml

 Parameters :
  GitHubOrg :
    Description : Name of GitHub organization/user (case sensitive)
    Type : String
  RepositoryName :
    Description : Name of GitHub repository (case sensitive)
    Type : String
  OIDCProviderArn :
    Description : Arn for the GitHub OIDC Provider.
    Default : " "
    Type : String
  OIDCAudience :
    Description : Audience supplied to configure-aws-credentials.
    Default : " sts.amazonaws.com "
    Type : String

Conditions :
  CreateOIDCProvider : !Equals 
    - !Ref OIDCProviderArn
    - " "

Resources :
  Role :
    Type : AWS::IAM::Role
    Properties :
      AssumeRolePolicyDocument :
        Statement :
          - Effect : Allow
            Action : sts:AssumeRoleWithWebIdentity
            Principal :
              Federated : !If 
                - CreateOIDCProvider
                - !Ref GithubOidc
                - !Ref OIDCProviderArn
            Condition :
              StringEquals :
                token.actions.githubusercontent.com:aud : !Ref OIDCAudience
              StringLike :
                token.actions.githubusercontent.com:sub : !Sub repo:${GitHubOrg}/${RepositoryName}:*

  GithubOidc :
    Type : AWS::IAM::OIDCProvider
    Condition : CreateOIDCProvider
    Properties :
      Url : https://token.actions.githubusercontent.com
      ClientIdList : 
        - sts.amazonaws.com
      ThumbprintList :
        - ffffffffffffffffffffffffffffffffffffffff

Outputs :
  Role :
    Value : !GetAtt Role.Arn 

Претензии и разрешения на оценку

Чтобы соответствовать наилучшей практике Amazon IAM по предоставлению наименьшей привилегии, документ о политике роля предполагает, что должно содержать Condition , которое указывает субъект ( sub ), который разрешил взять на себя роль. GitHub также рекомендует фильтрацию для правильной аудитории ( aud ). См. Документацию AWS IAM, по которой вы можете фильтровать в своей доверительной политике.

Без субъекта ( sub ) условия любой пользователь или репозиторий GitHub может потенциально принять роль. Субъект может быть охвачен организацией GitHub и репозиторием, как показано в шаблоне CloudFormation. Тем не менее, охват его до вашей организации и репо может привести к тому, что в некоторых случаях предположение о роле не удалось. См. Пример претензий субъекта для конкретных подробностей о том, что будет зависеть от вашего рабочего процесса. Вы также можете настроить свой предмет утверждений, если вы хотите полного контроля над информацией, которую вы можете фильтровать в своей доверительной политике. Если вы не уверены, что такое ваш объект ( sub ), вы можете добавить действие actions-oidc-debugger в свой рабочий процесс, чтобы увидеть значение ключа субъекта ( sub ), а также другие претензии.

Дополнительные условия претензий могут быть добавлены для более высокой специфичности, как объяснено в документации GitHub. Из -за деталей реализации не все претензии OIDC в ​​настоящее время поддерживаются IAM.

Дополнительная информация о OIDC

Для получения дополнительной информации о действиях OIDC и GitHub, см.

• AWS DOCS: Создание поставщиков идентификаций OpenID Connect (OIDC)
• AWS DOCS: IAM JSON Политические элементы: условие
• GitHub Docs: о упрочнении безопасности с OpenID Connect
• Документы GitHub: настройка OpenID Connect в веб -сервисах Amazon
• GitHub Changelog: GitHub Действия: безопасное развертывание облаков с OpenID Connect

Самостоятельные бегуны

Если вы запускаете свои действия GitHub в самостоятельном бегуне, который уже имеет доступ к учетным данным AWS, таким как экземпляр EC2, вам не нужно предоставлять ключевые данные IAM доступа к этому действию. Мы будем использовать стандартные методы разрешения учетных данных AWS Javascript SDK, чтобы найти ваши учетные данные, поэтому, если AWS JS SDK может аутентифицировать подлинности вашего бегуна, это действие также будет.

Если никакие учетные данные ключа доступа не указаны в входе действий, это действие будет использовать учетные данные из среды бегуна, используя методы по умолчанию для AWS SDK для JavaScript.

Вы можете использовать это действие для простого настройки региона и идентификатора учетной записи в среде, а затем использовать учетные данные Runner для всех вызовов API API, сделанных вашим рабочим процессом:

 uses : aws-actions/configure-aws-credentials@v4
with :
  aws-region : us-east-2

В этом случае учетные данные вашего бегуна должны иметь разрешения на вызов любых API APS, вызванных вашим рабочим процессом.

Или вы можете использовать это действие, чтобы взять на себя роль, а затем использовать учетные данные для всех вызовов API API, сделанные вашим рабочим процессом:

 uses : aws-actions/configure-aws-credentials@v4
with :
  aws-region : us-east-2
  role-to-assume : my-github-actions-role

В этом случае учетные данные вашего бегуна должны иметь разрешения на участие в роли.

Вы также можете взять на себя роль, используя файл токенов веб -идентификации, например, при использовании Amazon EKS IRSA. Стручки, работающие в узлах рабочих EKS, которые не работают как root, могут использовать этот файл, чтобы взять на себя роль с веб -идентичностью.

Конфигурация прокси

Если необходимо использовать HTTP -прокси, вы можете установить его в действие вручную.

Кроме того, это действие всегда будет учитывать переменную среды HTTP_PROXY .

Настроенный вручную прокси:

 uses : aws-actions/configure-aws-credentials@v4
with :
  aws-region : us-east-2
  role-to-assume : my-github-actions-role
  http-proxy : " http://companydomain.com:3128 "

Прокси, настроенный в переменной среды:

 # Your environment configuration
HTTP_PROXY= " http://companydomain.com:3128 "

Использовать с AWS CLI

Этот рабочий процесс не устанавливает AWS CLI в вашу среду. Самостоятельные бегуны, которые намерены запустить это действие до выполнения команд aws , должны установить AWS CLI, если его еще нет. Большинство сред, размещенных GitHub, должны включать AWS CLI по умолчанию.

Примеры

AssumeroleWithWebidentity (рекомендуется)

    - name : Configure AWS Credentials
      uses : aws-actions/configure-aws-credentials@v4
      with :
        aws-region : us-east-2
        role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
        role-session-name : MySessionName

В этом примере действие будет загружать токен OIDC из переменной среды, предоставленной GitHub и использовать его, чтобы взять на себя роль arn:aws:iam::123456789100:role/my-github-actions-role с именем сессии MySessionName .

Предполагаемая роль, ранее предполагаемая действием в том же рабочем процессе

    - name : Configure AWS Credentials
      uses : aws-actions/configure-aws-credentials@v4
      with :
        aws-region : us-east-2
        role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
        role-session-name : MySessionName
    - name : Configure other AWS Credentials
      uses : aws-actions/configure-aws-credentials@v4
      with :
        aws-region : us-east-2
        role-to-assume : arn:aws:iam::987654321000:role/my-second-role
        role-session-name : MySessionName
        role-chaining : true

В этом двухэтапном примере первый шаг будет использовать OIDC, чтобы взять на себя роль arn:aws:iam::123456789100:role/my-github-actions-role как и в предыдущем примере. После этого второй шаг будет использовать эту роль, чтобы взять на себя другую роль, arn:aws:iam::987654321000:role/my-second-role .

Предполагаемая среда со статическими полномочиями IAM в секретах репозитория

    - name : Configure AWS Credentials
      uses : aws-actions/configure-aws-credentials@v4
      with :
        aws-access-key-id : ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key : ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region : us-east-2
        role-to-assume : ${{ secrets.AWS_ROLE_TO_ASSUME }}
        role-external-id : ${{ secrets.AWS_ROLE_EXTERNAL_ID }}
        role-duration-seconds : 1200
        role-session-name : MySessionName

В этом примере секретный AWS_ROLE_TO_ASSUME содержит такую ​​строку, как arn:aws:iam::123456789100:role/my-github-actions-role . Чтобы взять на себя роль в той же учетной записи, что и статические учетные данные, вы можете просто указать название «Роль», например role-to-assume: my-github-actions-role .

Получение учетных данных из вывода шага, предполагаемая с временными учетными данными

    - name : Configure AWS Credentials 1
      id : creds
      uses : aws-actions/configure-aws-credentials@v4
      with :
        aws-region : us-east-2
        role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
        output-credentials : true
    - name : get caller identity 1
      run : |
        aws sts get-caller-identity
    - name : Configure AWS Credentials 2
      uses : aws-actions/configure-aws-credentials@v4
      with :
        aws-region : us-east-2
        aws-access-key-id : ${{ steps.creds.outputs.aws-access-key-id }}
        aws-secret-access-key : ${{ steps.creds.outputs.aws-secret-access-key }}
        aws-session-token : ${{ steps.creds.outputs.aws-session-token }}
        role-to-assume : arn:aws:iam::123456789100:role/my-other-github-actions-role
    - name : get caller identity2
      run : |
        aws sts get-caller-identity

В этом примере показано, что вы можете ссылаться на полученные учетные данные как выходы, если output-credentials установлены на true. Этот пример также показывает, что вы можете использовать входные данные aws-session-token в ситуации, когда токены сеанса извлекаются и переданы в это действие.

Резюме лицензии

Этот код доступен по лицензии MIT.

Раскрытие информации о безопасности

Если вы хотите сообщить о потенциальной проблеме безопасности в этом проекте, не создавайте проблему GitHub. Вместо этого, пожалуйста, следуйте инструкциям здесь или по электронной почте AWS Security напрямую.