Konfigurieren von OpenID Connect in Amazon Web Services

Ü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 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 finden Sie unter OpenID Connect.

• Beachte, dass du bestimmte Werte in der folgenden Dokumentation ersetzen musst, wenn du den Leitfaden auf GHE.com verwendest. Weitere Informationen findest du unter 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://token.actions.githubusercontent.com
• Für die „Zielgruppe“: Verwende sts.amazonaws.com, wenn du die offizielle Aktion verwendest.

Konfigurieren der Rolle und der Vertrauensstellungsrichtlinie

Weitere Informationen zum Konfigurieren der Rolle und Vertrauensstellung in IAM findest du in der AWS-Dokumentation unter Konfigurieren von AWS-Anmeldeinformationen für GitHub Actions und Konfigurieren einer Rolle für den GitHub OIDC-Identitätsanbieter.

Bearbeiten Sie die Vertrauensstellungsrichtlinie und fügen Sie das sub-Feld zu den Überprüfungsbedingungen hinzu. Zum Beispiel:

"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"
  }
}

"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"
  }
}

Wenn Sie einen Workflow mit einer Umgebung verwenden, muss das sub-Feld auf den Namen der Umgebung verweisen: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME. Weitere Informationen finden Sie unter OpenID Connect-Referenz.

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

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

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"
                }
            }
        }
    ]
}

{
    "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:

1. Füge Berechtigungseinstellungen für das Token hinzu.
2. Tausche mit der aws-actions/configure-aws-credentials-Aktion das OIDC-Token (JWT) gegen ein Cloudzugriffstoken aus.

Hinzufügen von Berechtigungseinstellungen

Für die Auftrags- oder Workflowausführung ist eine permissions-Einstellung mit id-token: write erforderlich, damit der OIDC-Anbieter von GitHub für jede Ausführung eine JSON Web Token-Instanz erstellen kann.

Ausführliche Informationen zu erforderlichen Berechtigungen, Konfigurationsbeispielen und erweiterten Szenarios findest du unter OpenID Connect-Referenz.

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.

• BUCKET-NAME: Ersetzen Sie dies durch den Namen Ihres S3-Buckets.
• AWS-REGION: Ersetzen Sie dies durch den Namen Ihrer AWS-Region:
• ROLE-TO-ASSUME: Ersetzen Sie dies durch Ihre AWS-Rolle. Beispiel: 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@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 }}/

# 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@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 }}/

Weitere Informationen

• Verwenden von OpenID Connect mit wiederverwendbaren Workflows
• Referenzen zu selbstgehosteten Runnern