Note
GitHubразмещенные в данный момент средства выполнения не поддерживаются в GitHub Enterprise Server. Дополнительные сведения о планируемой поддержке в будущем см. в GitHub public roadmap.
Обзор
OpenID Connect (OIDC) позволяет рабочим процессам GitHub Actions получать доступ к ресурсам в Amazon Web Services (AWS) без необходимости хранить учетные данные AWS в виде долгоживущих секретов GitHub.
В этом руководстве рассказывается, как в AWS настроить доверие к OIDC GitHub в качестве федеративного удостоверения, а также есть пример рабочего процесса для действия aws-actions/configure-aws-credentials
, в котором для проверки подлинности в AWS и доступа к ресурсам используются маркеры.
Note
Поддержка пользовательских утверждений для OIDC недоступна в AWS.
Необходимые компоненты
-
Основные понятия о том, как GitHub использует OpenID Connect (OIDC) и его архитектуру и преимущества, см. в разделе "Сведения об усилении защиты с помощью OpenID Connect".
-
Прежде чем продолжить, необходимо спланировать стратегию безопасности, чтобы обеспечить выдачу маркеров доступа только предсказуемым способом. Чтобы управлять тем, как поставщик облачных служб выдает маркеры доступа, необходимо определить по крайней мере одно условие, запретив недоверенным репозиториям запрашивать маркеры доступа к облачным ресурсам. Дополнительные сведения см. в разделе Сведения об усилении защиты с помощью OpenID Connect.
-
Необходимо убедиться, что следующие конечные точки OIDC доступны поставщиком облачных служб:
https://HOSTNAME/_services/token/.well-known/openid-configuration
https://HOSTNAME/_services/token/.well-known/jwks
Note
Доступ к конечным точкам OIDC можно ограничить, разрешая только диапазоны IP-адресов AWS.
Note
GitHub изначально не поддерживает теги сеансов AWS.
Добавление поставщика удостоверений в AWS
Сведения о добавлении поставщика OIDC GitHub в IAM см. в документации по AWS.
- Для URL-адреса поставщика: укажите
https://HOSTNAME/_services/token
- Для аудитории: укажите
sts.amazonaws.com
, если используете официальное действие.
Настройка роли и политики доверия
Сведения о настройке роли и доверия в IAM см. в документации по AWS "Настройка учетных данных AWS для действий GitHub" и "Настройка роли для поставщика удостоверений OIDC GitHub".
Note
Aws Identity and Access Management (IAM) рекомендует пользователям оценивать ключ условия IAM в token.actions.githubusercontent.com:sub
политике доверия любой роли, которая доверяет GitHubпоставщика удостоверений OIDC (IdP). Оценка этого ключа условия в политике доверия ролей ограничивает, какие действия GitHub могут принимать роль.
Измените политику доверия, добавив sub
поле в условия проверки. Например:
"Condition": { "StringEquals": { "HOSTNAME/_services/token:aud": "sts.amazonaws.com", "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch" } }
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
}
}
Если вы используете рабочий процесс с средой, sub
поле должно ссылаться на имя среды: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
Дополнительные сведения см. в разделе Сведения об усилении защиты с помощью OpenID Connect.
Note
Если среды используются в рабочих процессах или политиках OIDC, рекомендуется добавить правила защиты в среду для дополнительной безопасности. Например, можно настроить правила развертывания в среде, чтобы ограничить, какие ветви и теги могут развертываться в среде или получить доступ к секретам среды. Дополнительные сведения см. в разделе «Управление средами для развертывания».
"Condition": { "StringEquals": { "HOSTNAME/_services/token:aud": "sts.amazonaws.com", "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod" } }
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod"
}
}
В следующем примере StringLike
используется с оператором подстановочных знаков (*
) для разрешения любой ветви, ветви слияния по запросу на вытягивание или среды из octo-org/octo-repo
организации и репозитория, чтобы взять на себя роль в AWS.
{ "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" } } } ] }
{
"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:
- Добавьте параметры разрешений для маркера.
- Используйте действие
aws-actions/configure-aws-credentials
для обмена маркера OIDC (JWT) на маркер доступа к облаку.
Добавление параметров разрешений
Для выполнения задания или рабочего процесса требуется permissions
параметр, позволяющий id-token: write
GitHubпоставщика OIDC для создания веб-маркера JSON для каждого запуска. Вы не сможете запросить маркер идентификатора JWT OIDC, если permissions
оно id-token
не задано write
, однако это значение не подразумевает предоставление доступа на запись к любым ресурсам, только возможность получить и задать маркер OIDC для действия или шага, чтобы включить проверку подлинности с помощью маркера доступа с коротким сроком действия. Любой фактический параметр доверия определяется с помощью утверждений OIDC, дополнительные сведения см. в разделе "Сведения об усилении защиты с помощью OpenID Connect".
Этот параметр id-token: write
позволяет запрашивать JWT у поставщика OIDC GitHub, применяя один из следующих способов:
- использование переменных среды в средстве выполнения (
ACTIONS_ID_TOKEN_REQUEST_URL
иACTIONS_ID_TOKEN_REQUEST_TOKEN
); - использование
getIDToken()
из набора средств Actions.
Если необходимо получить токен OIDC для рабочего процесса, разрешение можно установить на уровне рабочего процесса. Например:
permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkout
permissions:
id-token: write # This is required for requesting the JWT
contents: read # This is required for actions/checkout
Если необходимо получить токен OIDC только для одного задания, такое разрешение можно установить в этом задании. Например:
permissions: id-token: write # This is required for requesting the JWT
permissions:
id-token: write # This is required for requesting the JWT
Вам может потребоваться указать дополнительные разрешения в зависимости от требований рабочего процесса.
Для повторно используемых рабочих процессов, принадлежащих одному и тому же пользователю, организации или предприятиям, что и рабочий процесс вызывающего объекта, маркер OIDC, созданный в повторно используемый рабочий процесс, можно получить из контекста вызывающего объекта.
Для повторно используемых рабочих процессов за пределами организации или предприятия параметр id-token
должен быть явно задан write
на уровне рабочего процесса вызывающего объекта или permissions
в конкретном задании, которое вызывает повторно используемый рабочий процесс.
Это гарантирует, что маркер OIDC, созданный в повторно используемом рабочем процессе, может использоваться только в рабочих процессах вызывающего объекта.
Дополнительные сведения см. в разделе «Повторное использование рабочих процессов».
Запрос маркера доступа
Действие 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
# Sample workflow to access AWS resources when workflow is tied to branch # The workflow Creates static website using aws s3 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@v4 - 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 }}/
# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow Creates static website using aws s3
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@v4
- 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 }}/