Konfigurieren von OpenID Connect in Amazon Web Services

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.

Hinweis: Die Unterstützung für benutzerdefinierte Ansprüche für OIDC ist in AWS nicht verfügbar.

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
Note

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

Note

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

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

Note

AWS Identity and Access Management (IAM) empfiehlt Benutzern, den IAM-Bedingungsschlüssel token.actions.githubusercontent.com:sub in der Vertrauensrichtlinie einer beliebigen Rolle zu bewerten, die GitHubs OIDC Identitätsanbieter (IdP) vertraut. Die Auswertung dieses Bedingungsschlüssels in der Rollenvertrauensrichtlinie beschränkt, welche GitHub-Aktionen die Rolle übernehmen können.

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

JSON

"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 findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.

Hinweis: Wenn Umgebungen in Workflows oder in OIDC-Richtlinien verwendet werden, empfehlen wir, der Umgebung Schutzregeln für zusätzliche Sicherheit hinzuzufügen. Du kannst z. B. Bereitstellungsregeln für eine Umgebung konfigurieren, um einzuschränken, welche Verzweigungen und Tags in der Umgebung oder in geheimen Umgebungsschlüsseln bereitgestellt werden können. Weitere Informationen findest du unter Verwalten von Umgebungen für die Bereitstellung.

JSON

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

JSON

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

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 permissions-Einstellung mit id-token: write, die es dem OIDC-Anbieter von GitHub erlaubt, für jeden Lauf ein JSON-Web-Token zu erstellen. Sie können das OIDC JWT ID-Token nicht anfordern, wenn permissions für id-token nicht auf writegesetzt ist. Dieser Wert bedeutet jedoch nicht, dass Sie Schreibzugriff auf Ressourcen erhalten, sondern nur, dass Sie das OIDC-Token für eine Aktion oder einen Schritt abrufen und setzen können, um die Authentifizierung mit einem kurzlebigen Zugriffstoken zu ermöglichen. Jede tatsächliche Vertrauenseinstellung wird mithilfe von OIDC-Ansprüchen definiert, weitere Informationen finden Sie unter "Informationen zur Sicherheitshärtung mit OpenID Connect".

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:

YAML

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:

YAML

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

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

Möglicherweise müssen Sie hier zusätzliche Berechtigungen angeben, abhängig von den Anforderungen Ihres Workflows.

Für wiederverwendbare Workflows, die sich im Besitz desselben Benutzers bzw. derselben Benutzerin, derselben Organisation oder desselben Unternehmens wie der Aufruferworkflow befinden, kann aus dem Kontext des Aufrufers auf das im wiederverwendbaren Workflow generierte OIDC-Token zugegriffen werden. Für wiederverwendbare Workflows außerhalb des Unternehmens oder der Organisation muss die permissions-Einstellung für id-token auf Aufruferworkflowebene oder in dem bestimmten Auftrag, der den wiederverwendbaren Workflow aufruft, explizit auf write festgelegt werden. Dadurch wird sichergestellt, dass das im wiederverwendbaren Workflow generierte OIDC-Token nur dann in den Workflows der Aufrufer genutzt werden darf, wenn dies vorgesehen ist.

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.

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

YAML

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

Weitere Informationen

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

Konfigurieren von OpenID Connect in Amazon Web Services

In diesem Artikel