Настройка OpenID Connect в Amazon Web Services

Использование OpenID Connect в рабочих процессах для проверки подлинности в Amazon Web Services.

В этой статье

Обзор

OpenID Connect (OIDC) позволяет рабочим процессам GitHub Actions получать доступ к ресурсам в Amazon Web Services (AWS) без необходимости хранить учетные данные AWS в виде долгоживущих секретов GitHub.

В этом руководстве рассказывается, как в AWS настроить доверие к OIDC GitHub в качестве федеративного удостоверения, а также есть пример рабочего процесса для действия aws-actions/configure-aws-credentials, в котором для проверки подлинности в AWS и доступа к ресурсам используются маркеры.

Примечание.

Поддержка пользовательских утверждений для OIDC недоступна в AWS.

Необходимые компоненты

  • Основные понятия о том, как GitHub использует OpenID Connect (OIDC) и его архитектуру и преимущества, см. в разделе OpenID Connect.

  • Прежде чем продолжить, необходимо спланировать стратегию безопасности, чтобы обеспечить выдачу маркеров доступа только предсказуемым способом. Чтобы управлять тем, как поставщик облачных служб выдает маркеры доступа, необходимо определить по крайней мере одно условие, запретив недоверенным репозиториям запрашивать маркеры доступа к облачным ресурсам. Дополнительные сведения см. в разделе OpenID Connect.

Добавление поставщика удостоверений в AWS

Сведения о добавлении поставщика OIDC GitHub в IAM см. в документации по AWS.

  • Для URL-адреса поставщика: укажите https://token.actions.githubusercontent.com
  • Для аудитории: укажите sts.amazonaws.com, если используете официальное действие.

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

Для настройки роли и доверия в IAM см. документацию AWS Configure AWS Credentials for GitHub Actions и Configuring a role for GitHub OIDC identity provider.

Примечание.

Aws Identity and Access Management (IAM) рекомендует пользователям оценивать ключ условия IAM в token.actions.githubusercontent.com:subполитике доверия любой роли, которая доверяет GitHubпоставщика удостоверений OIDC (IdP). Оценка этого ключа условия в политике доверия ролей ограничивает, какие действия GitHub могут принимать роль.

Измените политику доверия, добавив sub поле в условия проверки. Например:

JSON
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

Если вы используете рабочий процесс с средой, sub поле должно ссылаться на имя среды: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME Дополнительные сведения см. в разделе Справочник по OpenID Connect.

Примечание.

Если среды используются в рабочих процессах или политиках OIDC, рекомендуется добавить правила защиты в среду для дополнительной безопасности. Например, можно настроить правила развертывания в среде, чтобы ограничить, какие ветви и теги могут развертываться в среде или получить доступ к секретам среды. Дополнительные сведения см. в разделе Управление средами для развертывания.

JSON
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:environment:prod"
  }
}

В следующем примере StringLike используется с оператором подстановочных знаков (*) для разрешения любой ветви, ветви слияния по запросу на вытягивание или среды из octo-org/octo-repo организации и репозитория, чтобы взять на себя роль в AWS.

JSON
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456123456:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:*"
                },
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

Обновление рабочего процесса GitHub Actions

Чтобы обновить рабочие процессы для OIDC, необходимо внести два изменения в YAML:

  1. Добавьте параметры разрешений для маркера.
  2. Используйте действие aws-actions/configure-aws-credentials для обмена токена OIDC (JWT) на облачный токен доступа.

Добавление параметров разрешений

Для выполнения задания или рабочего процесса требуется permissions параметр, позволяющий id-token: write поставщику OIDC GitHubсоздать веб-токен JSON для каждого запуска.

Примечание.

Параметр id-token: write в разрешениях рабочего процесса не дает рабочему процессу разрешение на изменение или запись в ресурсы. Вместо этого он позволяет рабочему процессу запрашивать (получить) и использовать (задать) маркер OIDC для действия или шага. Затем этот маркер используется для проверки подлинности с помощью внешних служб с помощью кратковременного маркера доступа.

Подробные сведения о необходимых разрешениях, примерах конфигурации и расширенных сценариях см. в разделе Справочник по OpenID Connect.

Запрос маркера доступа

Действие aws-actions/configure-aws-credentials получает JWT от поставщика OIDC GitHub, а затем запрашивает маркер доступа из AWS. Дополнительные сведения см. в документации по AWS.

  •         `BUCKET-NAME`: замените это именем контейнера S3.

  •         `AWS-REGION`: замените его именем региона AWS.

  •         `ROLE-TO-ASSUME`: замените это ролью AWS. Например: `arn:aws:iam::1234567890:role/example-role`
YAML
# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow creates a static website using Amazon S3
# Этот рабочий процесс использует действия, которые не сертифицированы GitHub.
# Они предоставляются сторонним поставщиком, и на них распространяются
# отдельные условия обслуживания, политика конфиденциальности и поддержка
# документации.
name: AWS example workflow
on:
  push
env:
  BUCKET_NAME : "BUCKET-NAME"
  AWS_REGION : "AWS-REGION"
# permission can be added at job level or workflow level
permissions:
  id-token: write   # This is required for requesting the JWT
  contents: read    # This is required for actions/checkout
jobs:
  S3PackageUpload:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v5
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
        with:
          role-to-assume: ROLE-TO-ASSUME
          role-session-name: samplerolesession
          aws-region: ${{ env.AWS_REGION }}
      # Upload a file to AWS s3
      - name: Copy index.html to s3
        run: |
          aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/

Дополнительные материалы