Signieren von Containerimages in GitHub-Workflows mithilfe von Notation und Artefaktsignierung

Dieser Artikel ist Teil einer Reihe zur Sicherstellung der Integrität und Authentizität von Containerimages und anderen Open Container Initiative (OCI)-Artefakten. Für einen vollständigen Überblick beginnen Sie mit der Übersicht, in der erklärt wird, warum das Signieren wichtig ist und die verschiedenen Szenarien skizziert werden.

In diesem Artikel erfahren Sie, wie Sie einen GitHub-Aktionen-Workflow erstellen, um:

• Erstellen Sie ein Image, und übertragen Sie es an die Azure-Containerregistrierung.
• Signieren Sie das Bild mithilfe von GitHub-Notation-Aktionen und der Artefaktsignierung.
• Speichern Sie die generierte Signatur automatisch in der Containerregistrierung.

Voraussetzungen

• Richten Sie ein Artefaktsignierungskonto und ein Zertifikatprofil ein. Ihr Artefaktsignierungszertifikatprofil muss die folgenden Attribute im Betreff enthalten:

  • Land/Region (C)
  • Bundesland oder Provinz (ST oder S)
  • Organisation (O)

  Für die Spezifikation des Notarprojekts sind diese Felder erforderlich.

• Erstellen oder Verwenden einer Containerregistrierung.

• Erstellen oder verwenden Sie ein GitHub-Repository, um Ihre Workflowdatei und GitHub-Geheimnisse zu speichern.

Authentifizieren von Azure auf GitHub

Gemäß der Verwendung von GitHub-Aktionen zum Herstellen einer Verbindung mit Azure müssen Sie sich mit Azure in Ihrem Workflow authentifizieren, indem Sie die Azure-Anmeldeaktion verwenden, bevor Sie Azure CLI- oder Azure PowerShell-Befehle ausführen. Die Azure-Anmeldeaktion unterstützt mehrere Authentifizierungsmethoden.

In diesem Leitfaden melden Sie sich mit OpenID Connect (OIDC) an, verwenden eine vom Benutzer zugewiesene verwaltete Identität, und führen Sie die Schritte unter Verwenden der Azure-Anmeldeaktion mit OpenID Connect aus.

1. Erstellen Sie eine benutzerseitig zugewiesene verwaltete Identität. Überspringen Sie diesen Schritt, wenn Sie über eine vorhandene verwaltete Identität verfügen.

   • Linux
   • Windows

   az login
   az identity create -g <identity-resource-group> -n <identity-name>
   

2. Rufen Sie die Client-ID Ihrer verwalteten Identität ab:

   • Linux
   • Windows

   CLIENT_ID=$(az identity show -g <identity-resource-group> -n <identity-name> --query clientId -o tsv)
   

3. Weisen Sie der verwalteten Identität Rollen für den Zugriff auf die Azure-Containerregistrierung zu.

   Für Registries, die nicht mit attributbasierter Zugriffssteuerung (ABAC) aktiviert sind, weisen Sie die Rollen AcrPush und AcrPull zu.

   • Linux
   • Windows

   ACR_SCOPE=/subscriptions/<subscription-id>/resourceGroups/<acr-resource-group>
   az role assignment create --assignee $CLIENT_ID --scope $ACR_SCOPE --role "acrpush" --role "acrpull"
   

   Weisen Sie für ABAC-fähige Registrierungen die Rollen Container Registry Repository Reader und Container Registry Repository Writer zu:

   • Linux
   • Windows

   ACR_SCOPE=/subscriptions/<subscription-id>/resourceGroups/<acr-resource-group>
   az role assignment create --assignee $CLIENT_ID --scope $ACR_SCOPE --role "Container Registry Repository Reader" --role "Container Registry Repository Writer"
   

4. Weisen Sie die Artifact Signing Certificate Profile Signer Rolle der verwalteten Identität für den Zugriff auf Artifact Signing zu.

   • Linux
   • Windows

   AS_SCOPE=/subscriptions/<subscription-id>/resourceGroups/<ts-account-resource-group>/providers/Microsoft.CodeSigning/codeSigningAccounts/<ts-account>/certificateProfiles/<ts-cert-profile>
   az role assignment create --assignee $CLIENT_ID --scope $AS_SCOPE --role "Artifact Signing Certificate Profile Signer"
   

5. Konfigurieren Sie GitHub, um Ihrer Identität zu vertrauen. Folgen Sie der Konfiguration einer vom Benutzer zugewiesenen verwalteten Identität, um einem externen Identitätsanbieter zu vertrauen.

6. Erstellen Sie GitHub-Geheimnisse, indem Sie geheime Schlüssel für ein Repository erstellen.

   Ordnen Sie die verwalteten Identitätswerte diesen geheimen Schlüsseln zu:

   GitHub-Geheimnis	Verwalteter Identitätswert
   AZURE_CLIENT_ID	Kunden-ID
   AZURE_SUBSCRIPTION_ID	Abonnement-ID
   AZURE_TENANT_ID	Verzeichnis-ID (Mandant)

Speichern des TSA-Stammzertifikats

Die Zeitstempelung (RFC 3161) erweitert die Vertrauensstellung für Signaturen über den Gültigkeitszeitraum des Signaturzertifikats hinaus. Die Artefaktsignierung verwendet kurzlebige Zertifikate, daher ist die Zeitstempelung von entscheidender Bedeutung. Die Server-URL für die Zeitstempelautorität (TSA) ist verfügbar unter http://timestamp.acs.microsoft.com/, wie in Zeitstempel-Gegensignaturen empfohlen.

1. Laden Sie das TSA-Stammzertifikat herunter:

   • Linux
   • Windows

   curl -o msft-tsa-root-certificate-authority-2020.crt "http://www.microsoft.com/pkiops/certs/microsoft%20identity%20verification%20root%20certificate%20authority%202020.crt"
   

2. Speichern Sie das Stammzertifikat in Ihrem Repository; beispiel: .github/certs/msft-identity-verification-root-cert-authority-2020.crt. Sie verwenden den Dateipfad im Workflow.

Erstellen des GitHub-Aktionsworkflows

1. Erstellen Sie ein .github/workflows Verzeichnis in Ihrem Repository, falls es nicht vorhanden ist.

2. Erstellen einer neuen Workflowdatei; beispiel: .github/workflows/sign-with-artifact-signing.yml.

3. Kopieren Sie die folgende Signaturworkflowvorlage in Ihre Datei.

# Build and push an image to Azure Container Registry, set up notation, and sign the image
name: notation-github-actions-sign-with-artifact-signing-template

on:
  push:

env:
  ACR_LOGIN_SERVER: <registry-login-server>             # example: myregistry.azurecr.io
  ACR_REPO_NAME: <repository-name>                      # example: myrepo
  IMAGE_TAG: <image-tag>                                # example: v1
  PLUGIN_NAME: azure-artifactsigning                     # name of Notation Artifact Signing plug-in; do not change
  PLUGIN_DOWNLOAD_URL: <plugin-download-url>            # example: "https://github.com/Azure/artifact-signing-notation-plugin/releases/download/v1.0.0/notation-azure-artifactsigning_1.0.0_linux_amd64.tar.gz"
  PLUGIN_CHECKSUM: <plugin-package-checksum>            # example: 2f45891a14aa9c88c9bee3d11a887c1adbe9d2d24e50de4bc4b4fa3fe595292f
  TSA_URL: "http://timestamp.acs.microsoft.com/"        # timestamping server URL
  TSA_ROOT_CERT: <root-cert-file-path>                  # example: .github/certs/msft-identity-verification-root-cert-authority-2020.crt
  AS_ACCOUNT_NAME: <artifact-signing-account-name>       # Artifact Signing account name
  AS_CERT_PROFILE: <artifact-signing-cert-profile-name>  # Artifact Signing certificate profile name 
  AS_ACCOUNT_URI: <artifact-signing-account-uri>         # Artifact Signing account URI; for example, "https://eus.codesigning.azure.net/"

jobs:
  notation-sign:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
     # packages: write
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: prepare
        id: prepare
        run: |
          echo "target_artifact_reference=${{ env.ACR_LOGIN_SERVER }}/${{ env.ACR_REPO_NAME }}:${{ env.IMAGE_TAG }}" >> "$GITHUB_ENV"
      
      # Log in to Azure with your service principal secret
      # - name: Azure login
      #  uses: Azure/login@v1
      #  with:
      #    creds: ${{ secrets.AZURE_CREDENTIALS }}
      # If you're using OIDC and federated credentials, make sure to replace the preceding step with the following:
      - name: Azure login
        uses: Azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      # Log in to your container registry
      - name: ACR login
        run: |
            az acr login --name ${{ env.ACR_LOGIN_SERVER }}
      # Build and push an image to the registry
      # Use `Dockerfile` as an example to build an image
      - name: Build and push
        id: push
        uses: docker/build-push-action@v4
        with:
          push: true
          tags: ${{ env.target_artifact_reference }}
          build-args: |
            IMAGE_TAG={{ env.IMAGE_TAG }}
      # Get the manifest digest of the OCI artifact
      - name: Retrieve digest
        run: |
          echo "target_artifact_reference=${{ env.ACR_LOGIN_SERVER }}/${{ env.ACR_REPO_NAME }}@${{ steps.push.outputs.digest }}" >> "$GITHUB_ENV" 
      # Set up the Notation CLI
      - name: setup notation
        uses: notaryproject/notation-action/setup@v1.2.2
      # Sign your container images and OCI artifacts by using a private key stored in Azure Key Vault
      - name: sign OCI artifacts with Artifact Signing
        uses: notaryproject/notation-action/sign@v1
        with:
          timestamp_url: ${{ env.TSA_URL}}
          timestamp_root_cert: ${{env.TSA_ROOT_CERT }}
          plugin_name: ${{ env.PLUGIN_NAME }}
          plugin_url: ${{ env.PLUGIN_DOWNLOAD_URL }}
          plugin_checksum: ${{ env.PLUGIN_CHECKSUM }}
          key_id: ${{ env.AS_CERT_PROFILE }}
          target_artifact_reference: ${{ env.target_artifact_reference }}
          signature_format: cose
          plugin_config: |-
            accountName=${{ env.AS_ACCOUNT_NAME }}
            baseUrl=${{ env.AS_ACCOUNT_URI }}
            certProfile=${{ env.AS_CERT_PROFILE }}
          force_referrers_tag: 'false'

Hinweise zu Umgebungsvariablen:

• PLUGIN_NAME: Immer verwenden azure-artifactsigning.
• PLUGIN_DOWNLOAD_URL: Rufen Sie die URL von der Release-Seite des Artifact Signing Plug-ins ab.
• PLUGIN_CHECKSUM: Verwenden Sie die Prüfsummendatei auf der Releaseseite; beispiel: notation-azure-artifactsigning_<version>_checksums.txt.
• AS_ACCOUNT_URI: Verwenden Sie den Endpunkt für Ihr Artefaktsignierungskonto, der spezifischen Region angepasst; Beispiel: https://eus.codesigning.azure.net/.

Auslösen des GitHub-Aktionsworkflows

Die on:push Syntax löst den Beispielworkflow aus. Das Übernehmen von Änderungen startet den Workflow. Wählen Sie unter ihrem GitHub-Repositorynamen "Aktionen " aus, um die Workflowprotokolle anzuzeigen.

Bei Erfolg erstellt der Workflow das Image, pusht es in die Azure-Containerregistrierung und signiert es mithilfe der Artifact-Signierung. Sie können die Workflowprotokolle anzeigen, um zu bestätigen, dass das azure-artifactsigning Plug-In installiert wurde und das Image erfolgreich signiert wurde.

Darüber hinaus können Sie Ihre Containerregistrierung im Azure-Portal öffnen. Wechseln Sie zu Repositorys, wechseln Sie zu Ihrem Bild, und wählen Sie dann "Referrers" aus. Vergewissern Sie sich, dass Artefakte (Signaturen) des Typs application/vnd.cncf.notary.signature aufgelistet sind.

Verwandte Inhalte

• Überprüfen von Containerimages in GitHub-Workflows mithilfe von Notation und Artefaktsignierung