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 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.

• 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: Sie können den Zugriff auf die OIDC-Endpunkte einschränken, indem Sie nur AWS-IP-Adressbereiche zulassen.

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

Informationen zum Konfigurieren der Rolle und Vertrauensstellung in IAM finden Sie in der AWS-Dokumentation "Configure AWS Credentials for GitHub Actions" und "Configuring a role for GitHub OIDC identity provider".

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:OWNER/REPOSITORY:environment:NAME. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.

"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

 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 und ACTIONS_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

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. Zum Beispiel:

permissions:
  id-token: write # This is required for requesting the JWT

permissions:
  id-token: write # This is required for requesting the JWT

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@v4
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v3
        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 }}/

# 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@v4
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v3
        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 }}/

Weitere Informationsquellen

• Verwenden von OpenID Connect mit wiederverwendbaren Workflows - Informationen zu selbstgehosteten Runnern