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.

• Sie müssen sicherstellen, dass auf die folgenden OIDC-Endpunkte von Ihrem Cloudanbieter zugegriffen werden kann:

  • https://HOSTNAME/_services/token/.well-known/openid-configuration
  • https://HOSTNAME/_services/token/.well-known/jwks

  Hinweis

  Du kannst den Zugriff auf die OIDC-Endpunkte einschränken, indem du nur AWS-IP-Adressbereiche zulässt.

  Hinweis

  GitHub unterstützt AWS-Sitzungstags nicht nativ.

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

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

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

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