Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.
Übersicht
OpenID Connect (OIDC) ermöglicht deinen GitHub Actions-Workflows den Zugriff auf Ressourcen in Amazon Web Services (AWS), ohne dass die AWS-Anmeldeinformationen als langlebige GitHub-Geheimnisse gespeichert werden müssen.
Dieser Leitfaden beschreibt die Konfiguration von AWS, um von GitHub als Verbundidentität zu vertrauen, und enthält ein Workflowbeispiel für die aws-actions/configure-aws-credentials
, die Token zur Authentifizierung bei AWS und zum Zugriff auf Ressourcen verwendet.
Voraussetzungen
-
Informationen zu den grundlegenden Konzepten, nach denen GitHub OpenID Connect (OIDC) sowie die Architektur und Vorteile des Protokolls verwendet, findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.
-
Bevor du fortfährst, musst du deine Sicherheitsstrategie planen, um sicherzustellen, dass Zugriffs-Token nur auf vorhersehbare Weise zugewiesen werden. Zur Steuerung, wie dein Cloud-Anbieter Zugriffs-Token ausgibt, musst du mindestens eine Bedingung definieren, damit nicht vertrauenswürdige Repositorys keine Zugriffs-Token für deine Cloud-Ressourcen anfordern können. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.
Hinzufügen des Identitätsanbieters zu AWS
Weitere Informationen zum Hinzufügen des GitHub-OIDC-Anbieters zu IAM findest du in der AWS-Dokumentation.
- Für die Anbieter-URL: Verwende
https://HOSTNAME/_services/token
- Für die „Zielgruppe“: Verwende
sts.amazonaws.com
, wenn du die offizielle Aktion verwendest.
Konfigurieren der Rolle und der Vertrauensstellungsrichtlinie
Um die Rolle und die Vertrauensstellung in IAM zu konfigurieren, lies die AWS-Dokumentation zu Annehmen einer Rolle und Erstellen einer Rolle für Webidentität oder OpenID Connect-Verbund.
Bearbeite die Vertrauensstellungsrichtlinie, um das sub
-Feld den Überprüfungsbedingungen hinzuzufügen. Beispiel:
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
}
}
Im folgenden Beispiel wird StringLike
mit einem Platzhalteroperator (*
) verwendet, um jedem Branch, jedem Branch für das Mergen des Pull Requests oder jeder Umgebung aus der Organisation und dem Repository octo-org/octo-repo
die Übernahme einer Rolle in AWS zu ermöglichen.
{
"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"
}
}
}
]
}
Aktualisieren deines GitHub Actions-Workflows
Um deine Workflows für OIDC zu aktualisieren, musst du zwei Änderungen an deinen YAML-Daten vornehmen:
- Füge Berechtigungseinstellungen für das Token hinzu.
- Tausche mit der
aws-actions/configure-aws-credentials
-Aktion das OIDC-Token (JWT) gegen ein Cloudzugriffstoken aus.
Hinzufügen von Berechtigungseinstellungen
Der Auftrag oder die Workflowausführung erfordert eine Einstellung permissions
mit id-token: write
. Du kannst das OIDC JWT-ID-Token nicht anfordern, wenn die Einstellung permissions
für id-token
auf read
oder none
festgelegt ist.
Mit der Einstellung id-token: write
kann der JWT von GitHub-OIDC-Anbieter mit einer der folgenden Ansätze angefordert werden:
- Verwenden von Umgebungsvariablen auf dem Runner (
ACTIONS_ID_TOKEN_REQUEST_URL
undACTIONS_ID_TOKEN_REQUEST_TOKEN
). - Verwenden von
getIDToken()
aus dem Actions-Toolkit.
Wenn du ein OIDC-Token für einen Workflow abrufen musst, können die Berechtigungen auf Workflowebene festgelegt werden. Beispiel:
permissions:
id-token: write # This is required for requesting the JWT
contents: read # This is required for actions/checkout
Wenn Du nur ein OIDC-Token für einen einzelnen Auftrag abrufen musst, kann diese Berechtigung innerhalb dieses Auftrags festgelegt werden. Beispiel:
permissions:
id-token: write # This is required for requesting the JWT
Möglicherweise musst Du hier zusätzliche Berechtigungen angeben, abhängig von den Anforderungen Deines Workflows.
Für wiederverwendbare Workflows sollte die permissions
-Einstellung für id-token
auf Aufruferworkflowebene oder in dem bestimmten Auftrag auf write
festgelegt werden, der den wiederverwendbaren Workflow aufruft. Weitere Informationen findest du unter Wiederverwenden von Workflows.
Anfordern des Zugriffstokens
Die aws-actions/configure-aws-credentials
-Aktion empfängt ein JWT vom GitHub-OIDC-Anbieter und fordert dann ein Zugriffstoken von AWS an. Weitere Informationen findest du in der AWS-Dokumentation.
<example-bucket-name>
: Füge den Namen deines S3-Buckets hier hinzu.<role-to-assume>
: Ersetze das Beispiel durch deine AWS-Rolle.<example-aws-region>
: Füge den Namen deiner AWS-Region hier hinzu.
# 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 : "<example-bucket-name>"
AWS_REGION : "<example-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@v3
- name: configure aws credentials
uses: aws-actions/configure-aws-credentials@v2
with:
role-to-assume: arn:aws:iam::1234567890:role/example-role
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 }}/