Härtung von Deployment Pipelines mit Workload Identity Federation

Traditionell verwenden Deployment Pipelines in der Regel langlebige Anmeldeinformationen für den Zugriff auf Cloud-Anbieter wie Microsoft Azure. Diese Identitäten mussten im Identity Provider (IdP) wie Microsoft Entra ID erstellt, geschützt und aktualisiert werden. Eine Kopie der Anmeldedaten wird in DevOps-Plattformen wie Azure DevOps oder GitHub Enterprise als Geheimnis gespeichert. Bei jeder Ausführung der Pipeline werden die Anmeldedaten an die durch einen Identity Provider geschützten Cloud Ressourcen übermittelt, so dass Artefakte ausgerollt oder Cloud Infrastruktur Ressourcen provisioniert werden können. Ein typisches Beispiel ist die Provisionierung von Infrastruktur mit Terraform.

Welche typischen technischen und organisatorischen Probleme hat der traditionelle Ansatz?

Beim Aufsetzen der Pipelines müssen die Anmeldedaten aus dem Identity Provider (IdP) sicher in der DevOps-Plattform gespeichert werden. In Projekten sind dazugehörige Verantwortlichkeiten oft getrennt. Die Einrichtung von Pipelines liegt in der Verantwortung des Projekts, die Verwaltung der Identitäten gehört zu den Kernaufgaben des IT-Betriebs des jeweiligen Unternehmens. IT-Dienstleister wie adesso beantragen die Anmeldedaten, der IT-Betrieb stellt die sensiblen Informationen über einen sicheren Kommunikationsweg bereit oder speichert diese direkt in der DevOps-Plattform. Diese Anmeldedaten sind in der Regel langlebig - je nach Umfeld ist eine Gültigkeitsdauer von drei Monaten bis 24 Monaten in der Praxis üblich.

Nach Ablauf der Gültigkeit müssen sie erneuert werden und der oben skizzierte Prozess wird erneut durchlaufen. Ein Problem ist, dass die Gültigkeitsdauer unerwartet oder zu ungünstigen Zeitpunkten endet, etwa zum Jahreswechsel oder während Urlaubsphasen.

Ein moderner Ansatz

Mit OpenID Connect (OIDC) kann ein anderer Ansatz verwendet werden. Pipelines fordern einen kurzlebigen Token an, der nur für die Laufzeit der Pipeline gültig ist. Das Speichern der duplizierten Anmeldeinformation in der DevOps-Plattform und das regelmäßige Rotieren entfällt ersatzlos. Aus technischer und organisatorischer Sicht ist das ein signifikanter Vorteil.

Der Cloud-Provider muss OIDC unterstützen und eine Vertrauensbeziehung (Trust Relationship) muss etabliert werden. Die Vertrauensbeziehung zwischen OIDC-Provider und Cloud-Provider stellt sicher, dass nur vertrauenswürdige Ressourcen in der DevOps-Plattform einen Token für den Zugriff auf Ressourcen im Cloud-Provider anfordern können.

Cloud-Provider mit Unterstützung für OIDC sind Microsoft Azure, Amazon Web Services und Google Cloud Platform. DevOps-Plattformen mit Unterstützung für OIDC sind Azure DevOps, GitLab, GitHub und HashiCorp. Microsoft bezeichnet das Feature als “Workload Identity Federation”, GitLab nennt es “ID Token authentication” und bei HashiCorp heisst es “Dynamic Credentials”.

Die Public Preview in Azure DevOps startete im September 2023. Im Sommer 2024 wurde in den Release Notes bekanntgegeben, dass die Integration von OIDC vollständig abgeschlossen ist.

Austausch der Tokens

Das folgende Diagramm zeigt den allgemeinen Ablauf wie ein Workload außerhalb der Cloud-Plattform einen externen Token gegen einen Access Token tauscht und damit Zugriff auf geschützte Cloud-Ressourcen erhält.

Zunächst muss eine OIDC-Vertrauensstellung im Cloud-Provider erstellt werden. Im Diagramm ist das Microsoft Azure. Beim Start der Pipeline in der DevOps-Plattform wird automatisch ein OIDC-Token generiert. Dieser Token beinhaltet spezifische Informationen, sogenannte Claims, über die anfragende Ressource. Der Cloud-Provider verifiziert den Aussteller des Tokens und die spezifischen Informationen/Claims der anfragenden Identität. Nach einer erfolgreichen Validierung der Identität liefert der Cloud-Provider einen kurzlebigen Access Token an die DevOps-Plattform. Die Pipeline verwendet diesen Access Token für den Zugriff auf die Ressourcen im Cloud-Provider. Der Token verliert seine Gültigkeit, wenn die Pipeline beendet ist.

Verständnis des OIDC-Token

Betrachten wir den OIDC beziehungsweise Workload Identity Token etwas genauer. Das folgende Beispiel zeigt einen dekodierten GitHub Enterprise Token.

Die Header typ, alg und kid sind sogenannte Header-Elemente aus dem Javascript Object Signing and Encryption Framework (JOSE) und beschreiben kryptographische Eigenschaften des Tokens.

	
	{
	  "typ": "JWT",
	  "alg": "RS256",
	  "kid": "j-fFp9evPJAzV5I2_58HY5UvdCK6Q4LLB1rnPOUfQAk"
	}
	

Der Payload des Tokens beinhaltet neben den Standard Claims aud, sub und iss für den Aufbau der Vertrauensbeziehung auch JOSE-Claims wie exp, iat, jti und nbf. Ein OIDC-Provider kann sogenannte “Custom Claims” definieren. GitHub unterstützt die Custom Claims repository, environment und ref. Mit diesen Claims kann die Vertrauensbeziehung beispielsweise auf Git Repositories einer spezifischen GitHub Organisation eingegrenzt werden.

	
	{
	  "sub": "repo:octo-org/octo-repo:environment:prod",
	  "iss": "https://token.actions.githubusercontent.com",
	  "aud": "https://github.com/octo-org",
	  "jti": "1192426d-b525-4fde-9d42-f238be437bbd",
	  "nbf": 1632492967,
	  "exp": 1632493867,
	  "iat": 1632493567,
	  "environment": "prod",
	  "repository": "octo-org/octo-repo",
	  "ref": "refs/heads/main",
	  "ref_type": "branch",
	  "event_name": "workflow_dispatch",
	  "repository_owner": "octo-org",
	  "repository_visibility": "private",
	  "workflow": "example-workflow",
	  "workflow_ref": "octo-org/octo-repo/.github/workflows/oidc.yml@refs/heads/main"
	}
	

Im oben gezeigten Beispiel wird im subject claim "repo:octo-org/octo-repo:environment:prod" ein Repository octo-org/octo-repo und ein Job Environment prod referenziert.

OIDC-Vertrauensstellung im Cloud-Provider

Die Konfiguration einer OIDC-Vertrauensbeziehung im Cloud-Provider soll bewirken, dass nur dann ein kurzlebiger Access Token ausgestellt wird, wenn der subject Claim und gegegebenfalls andere Claims im OIDC-Token identisch zur Konfiguration der OIDC-Vertrauensbeziehung im Cloud-Provider sind.

Die OIDC-Vertrauensbeziehung ist spezifisch für jeden Cloud-Provider. Microsoft Entra definiert die Claims subject und issuer als essentiell für die Vertrauensbeziehung. Microsoft Entra prüft, dass mindestens diese Claims im OIDC-Token identisch zu den Werten für subject und issuer in der OIDC-Vertrauensbeziehung sind. In Microsoft Entra wird eine OIDC-Vertrauensbeziehung über Federated Identity Credentials abgebildet.

Beispiel mit GitHub Actions und Microsoft Azure

Eine beispielhafte Implementierung mit GitHub Actions und Microsoft Entra ID erfordert die Erstellung von Federated Credentials in Entra ID und die Erstellung von GitHub Actions Workflows.

Federated Credentials

Eine benutzerseitig zugewiesene verwaltete Identität beziehungsweise eine “user-assigned managed identity” wird im Entra ID Tenant erstellt. Für die Erstellung der Vertrauensstellung wird das Szenario “GitHub Actions deploying Azure resources” ausgewählt, so dass spezifische Entitäten von GitHub für die Konfiguration der Vertrauensstellung verwendet werden können.

Die gewählte Sicherheitsstrategie zur Allokation von Access Tokens soll Anfragen via OIDC-Token nur dann als vertrauenswürdig bewerten, wenn ein GitHub Actions Workflow aus dem Repository octo-org/octo-repo ein Job Environment prod referenziert. Eine Anfrage aus einem anderen GitHub Repository oder für ein anderes Job Environment würde nicht als vertrauenswürdig validiert werden.

Der Inhalt des subject claims wird durch die Angabe der GitHub-Organisation octo-org, des Repositories octo-repo, das den GitHub Actions Workflow enthält, und dem Job Environment prod bestimmt.

Subject claim als zusammengesetzte Information:

repo:octo-org/octo-repo:environment:prod

Zusammenfassung der Vertrauensstellung:

• Der Claim für subject ist repo:octo-org/octo-repo:environment:prod.
• Der Claim für issuer hat für den GitHub OIDC Provider den Wert https://token.actions.githubusercontent.com.
• Der Claim für audience ist api://AzureADTokenExchange.

GitHub Actions

Der Workflow benötigt im Schlüsselwort permissions eine Berechtigung id-token: write, die es dem OIDC-Provider von GitHub erlaubt, für jede Ausführung des GitHub Actions Workflows einen JSON Web Token zu erstellen.

	
	permissions:
	  id-token: write
	

Die Konfiguration des Terraform Providers azurerm erfolgt idealerweise über Umgebungsvariablen. Mit den Umgebungsvariablen ARM_CLIENT_ID, ARM_SUBCRIPTION_ID und ARM_TENANT_ID wird die “user-assigned managed identity” im Entra ID Tenant referenziert. Diese Informationen zur Identität werden in GitHub Secrets gespeichert. Mit den Umgebungsvariablen ARM_USE_AZUREAD und ARM_USE_OIDC wird Entra Authentifizierung und die Verwendung von OIDC beziehungsweise Workload Identity Federation aktiviert. Wichtig ist, dass nun kein langlebiges Passwort mehr in GitHub beziehungsweise in einem GitHub Secret gespeichert wird und auch nicht per Umgebungsvariable ARM_CLIENT_SECRET an den Terraform Provider übergeben wird.

Workflow im Repository octo-org/octo-repo

	
	name: "Terraform Plan"
	permissions:
	  id-token: write
	  contents: read
	jobs:
	  plan:
	    name: Terraform Plan
	    environment: prod
	    env:
	      ARM_CLIENT_ID: "[null]"
	      ARM_SUBSCRIPTION_ID: "[null]"
	      ARM_TENANT_ID: "[null]"
	      ARM_USE_AZUREAD: true
	      ARM_USE_OIDC: true
	    steps:
	      - name: Checkout Code
	        uses: actions/checkout@v4
	      - name: Install Terraform
	        uses: hashicorp/setup-terraform@v3
	      - name: Terraform Init
	        run: |
	          terraform init
	      - name: Terraform Plan
	        run: |
	          terraform plan
	

Die Verwendung des Schlüsselworts environment und die Referenzierung des Jobs Environments prod ist essentiell für die korrekte Generierung des subject Claims im ausgestellten OIDC-Token.

Beim Start des oben aufgeführten Workflows im Repository octo-org/octo-repo wird ein OIDC-Token mit folgendem subject Claim generiert, der vom Cloud Provider als vertrauenswürdig validiert wird.

repo:octo-org/octo-repo:environment:prod

Unsere Fachleute können euch unterstützen bei der Aktualisierung von GitHub Actions Workflows zur Anwendung von verwalteten Identitäten und Workload Identity Federation für den Zugriff auf Ressourcen in Microsoft Azure.

Wiederverwendbare Workflows

Ein konsistentes Verhalten für Workload Identity Federation über mehrere GitHub Actions Workflows kann durch die Verwendung von sogenannten “Reusable Workflows” gewährleistet werden. Dazu werden Workflows wie oben im Codebeispiel in einem dedizierten GitHub Repository wie octo-org/octo-workflows abgelegt. Damit ein Workflow durch andere Workflows aufgerufen bzw. referenziert werden kann, braucht dieser im Schlüsselwort on den Wert workflow_call.

	
	on:
	  workflow_call:
	

Aufrufende Workflows

Aufrufende Workflows in anderen Repositories einer GitHub-Organisation können wiederverwendbare Workflows in privaten oder öffentlichen Repositories mit dem Schlüsselwort uses und der folgenden Syntax referenzieren:

• {owner}/{repo}/.github/workflows/{filename}@{ref}

Beispiel: Aufrufender Workflow

	
	name: Terraform plan
	jobs:
	  terraform-plan:
	    uses: octo-org/octo-workflows/.github/workflows/terraform-plan.yml@v0.4.0
	    secrets: inherit
	

Die Übergabe von Secrets aus dem Kontext des aufrufenden Workflows an den wiederverwendbaren Workflow gelingt mit secrets: inherit. Aufrufende Workflows, die wiederverwendbare Workflows referenzieren, werden kompakt und übersichtlich.

Ein Beispiel aus einem Kundenprojekt

Im konkreten Projekt wurde eine Azure Landing Zone mit dem Cloud Adoption Framework - Enterprise Scale Terraform Modul aufgebaut. Mit dem Ansatz “Modul Komposition” wurde die Azure Landing Zone in drei Bereiche segmentiert: “Connectivity”, “Core” und “Management”. Für jedes Segment beziehungsweise Modul wurde ein GitHub Repository und ein Terraform Workspace erstellt. In allen drei Repositories wurden GitHub Actions Workflows für den Core Terraform Workflow (write, plan, apply) bereitgestellt. Ein konsistentes Verhalten der Workflows in den jeweiligen Repositories wurde über die Verwendung von versionierten, wiederverwendbaren Workflows in einem dedizierten, privaten Repository gewährleistet. Die Konfiguration für die Authentifizierung mit dem Terraform Azure Provider azurerm wurde in jedem Repository über GitHub Variablen beziehungsweise Secrets externalisiert, so dass eine Trennung von Verantwortlichkeiten ermöglicht wurde. Durch die Verwendung von OpenID Connect oder kurzlebigen Tokens entfällt für den Kunden künftig der Wartungsaufwand für die manuelle Verwaltung und Erneuerung von Anmeldeinformationen und das Risiko, dass Geheimnisse preisgegeben werden, besteht nicht mehr.