Web & Ontwikkeling

GitHub Actions OIDC: Hoe je je deployments kunt beveiligen zonder langdurige geheimen

GitHub Actions OIDC: How to Secure Your Deployments Without Long-Lived Secrets

Leer hoe je de beveiliging van GitHub Actions-deployments kunt versterken met OIDC. Vervang langdurige cloudreferenties door kortdurende tokens, beperk toegang met behulp van IAM-trustbeleid, en bescherm je CI/CD-pijplijnen.

GitHub Actions OIDC: Hoe je je implementaties kunt beveiligen zonder langlevende geheimen

Het implementeren van een applicatie vanuit GitHub Actions vereist meestal toegang tot externe infrastructuren. Een workflow kan bijvoorbeeld bestanden uploaden naar Amazon S3, containers publiceren of cloudresources bijwerken. Teams slaan traditioneel een cloudtoegangsleutel op in GitHub Secrets. Dit werkt weliswaar, maar een langlevende referentie blijft nuttig voor een aanvaller als een workflow, afhankelijkheid of log deze onbedoeld onthult.

OpenID Connect (OIDC) helpt de beveiliging van CI/CD te verbeteren door langlevende cloudreferenties te vervangen door tijdelijke toegang die uitsluitend wordt verleend aan geautoriseerde workflowidentiteiten. Het beperkt blootstelling aan referenties, beperkt ongeoorloofde toegang en ondersteunt strengere controle over productiedeploylingen.

Deze tutorial legt de beveiligingsvoordelen uit, toont een praktische AWS-configuratie en identificeert de beschermingsmaatregelen die je nog steeds nodig hebt. OIDC is geen magische beveiligingsknop: het vertrouwensbeleid, de rolpermissies en de werkstroomcontroles zijn net zo belangrijk als de tokenuitwisseling.

Waarom implementatiebeveiliging belangrijk is

CI/CD-pijplijnen zijn bevoegde automatiseringstools. Ze kunnen productiecode vervangen, assets uploaden, implementatieconfiguraties lezen of infrastructure bijwerken. Een gecompromitteerde pijplijn kan daarom meer impact hebben dan een gecompromitteerde ontwikkelomgeving.

Drie veelvoorkomende risico’s verdienen bijzondere aandacht:

  • Blootstelling van referenties: een gestolen statische cloudleutel uit een buildomgeving kan geldig blijven totdat iemand deze intrekt.
  • Overmatige privileges: een implementatie-referentie met beheerdersrechten kan ongerelateerde services beïnvloeden.
  • Onbevoegde implementatie: een niet-vertrouwde branch of workflow kan productie-toegang krijgen als identiteitscontroles te breed zijn.

OIDC lost een deel van dit probleem op door authenticatie te koppelen aan een korte, verifieerbare workflowidentiteit. Het vervangt geen least-privilege IAM, code review of omgevingsbescherming.

Wat is OIDC in GitHub Actions?

OpenID Connect is een identiteitslaag die is gebaseerd op OAuth 2.0. GitHub Actions kan een ondertekend JSON Web Token (JWT) aanvragen van GitHub’s OIDC-provider:

https://token.actions.githubusercontent.com

Het token bevat claims die de identiteit en de uitvoeringscontext van de taak beschrijven. Een cloudidentiteitservice valideert de handtekening, uitgever, audience en relevante claims van het token, en beslist vervolgens of deze tijdelijke referenties wil uitgeven.

De externe service moet de beoogde GitHub-werkstroomidentiteit expliciet vertrouwen. Het alleen maar inschakelen van OIDC in een YAML-bestand verleent geen toegang.

Zie GitHub’s OIDC-documentatie.

Statische referenties versus OIDC: beveiligingsvergelijking

Beveiligingsaspect Langlevende toegangssleutel OIDC-federatie
Permanente cloudreferentie in GitHub Veelgebruikt Niet vereist voor ondersteunde providers
Levensduur van referentie Tot expiratie of intrede Tijdelijke sessie
Verantwoordelijkheid voor rotatie Team moet levenscyclus van sleutel beheren Cloudprovider issue kortlevende referenties
Identiteitsbeperkingen Afhankelijk van referentieopslag en IAM Trustbeleid kan workflowidentiteit beperken
Autorisatie IAM-rechten IAM-rechten zijn nog steeds vereist
Overige risico’s Diefstal en hergebruik van statische sleutel Gecompromitteerde geautoriseerde werkstroom of brede vertrouwen

OIDC vermindert het risico en de impact van referentiediefstal; het elimineert niet elke secret. Applicaties kunnen nog steeds databasepasswoorden, signing keys of third-party API-tokens nodig zijn.

Hoe het OIDC-authenticatieflow werkt

  1. Een geautoriseerde GitHub Actions-taak vraagt een identiteits-token aan.
  2. GitHub geeft een ondertekend JWT af voor die taak.
  3. De werkstroom presenteert het token aan de cloudidentiteitservice.
  4. De cloudprovider valideert het token en evalueert zijn geconfigureerde trustvoorwaarden.
  5. Als de identiteit is toegestaan, geeft de provider tijdelijke referenties uit.
  6. De werkstroom gebruikt die referenties binnen de toegestede scope van de rol.

De cloudprovider moet een token afwijzen waarvan het subject, de audience of andere vereistevoorwaarden niet overeenkomen. Die validatie is de grens tussen een veilzeflede implementatie en een implementatie die te veel vertrouwen.

Stap 1: Configureer GitHub’s OIDC-provider in AWS

AWS IAM ondersteunt OpenID Connect-identiteitservices. Maak een identiteitservice met behulp van:

| Setting | Waarde | |---|---|---| | Provider-URL | https://token.actions.githubusercontent.com | | Audience | sts.amazonaws.com | | Provider type | OpenID Connect |

De audience identificeert de beoogde ontvanger van het token. De AWS-credentialenactie gebruikt normaal gesproken sts.amazonaws.com.

Zie AWS IAM OIDC-rolconfiguratie.

Stap 2: Beperk wie de implementatieregel mag overnemen

Maak een IAM-rolle waarvan het trustbeleid uitsluitend sts:AssumeRoleWithWebIdentity toestaat vanaf de GitHub-identiteitservice en de beoogde workflowidentiteit.

Het volgende voorbeeld gebruikt GitHub’s traditionele branchgebaseerde subjectformaat:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:example-org/example-app:ref:refs/heads/main"
        }
      }
    }
  ]
}

Vervang het AWS-accountnummer, de organisatie en de repository.

Kopieer de subjectconditie niet blindelings. GitHub heeft een onveranderlijke standaard subjectformaat geïntroduceerd voor repositories die na voltijd 2026 zijn aangemaakt. Controleer het werkelijke subjectformaat dat door je repository wordt gebruikt en configureer AWS om dit te matchen. Omgevingsgebaseerde werkstromen kunnen ook een ander subjectvorm gebruiken. Raadpleeg GitHub’s OIDC tokenreferentie.

Een restrictief trustbeleid is een van de belangrijkste manieren om onbevoegde werkstromen te voorkomen die productiereferenties verkrijgen. Vermijd wildcardsubjects die per ongeluk unrelated repositories of contexten autoriseren.

Stap 3: Beperk wat de rol kan doen

Vertrouwen bepaalt wie een rol mag overnemen. IAM-rechten bepalen wat de rol na authenticatie kan doen.

Voor een implementatie die alleen bestanden uploadt naar één S3-bucket, is een vereenvoudigd beleid:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": "arn:aws:s3:::example-deploy-bucket/*"
    }
  ]
}
Illustration of the article's main concept

Dit voorbeeld staat objectuploads toe, maar niet accountbeheer of bucketverwijdering. Als je implementatie ook verouderde bestanden verwijdert of bucketinhoud lijst, verleen dan alleen de extra bewerkingen die nodig zijn, zoals gescopte s3:DeleteObject of s3:ListBucket.

Verleen nooit AdministratorAccess alleen maar om een implementatie te laten werken. Tijdelijke referenties met overmatige privileges kunnen nog steeds ernstige schade aanrichten.

Stap 4: Vraag tijdelijke referenties aan vanuit een werkstroom

Een implementatietaak moet zijn toegestaan om een OIDC-token aan te vragen. Het volgende voorbeeld uploadt een vooraf gebouwde dist/-directory naar S3:

name: Deploy website

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy-role
          aws-region: eu-west-1

      - name: Deploy website
        run: |
          aws s3 cp ./dist/ s3://example-deploy-bucket/ --recursive

Het voorbeeld gebruikt hoofdontwerpactiereferenties voor leesbaarheid. In productie moet je de huidige ondersteunde versies controleren en third-party acties het liefst vastmaken aan volledige commit SHAs. Het voorbeeld veronderstelt dat de website al is gebouwd in dist/.

Let op wat er ontbreekt: er wordt geen permanente AWS-toegangsleutel of secret access key opgeslagen in de werkstroom.

De officiële AWS credentials actie ruovt het OIDC-token uitwisselen voor tijdelijke AWS-credentials.

Stap 5: Begrijp id-token: write

Dit permission:

permissions:
  id-token: write

laat een taak toe om een GitHub OIDC identiteits-token aan te vragen. Het geeft niet op zichzelf de taak toestemming om te schrijven naar GitHub-repositories of toegang tot AWS te krijgen.

De cloudprovider beslist nog steeds of deze de identiteit vertrouwt, en de IAM-rolle controleert nog steeds welke bewerkingen zijn toegestaan.

Verleen id-token: write alleen aan taken die daadwerkelijk aan de cloud authenticeren. Build-, lint- en testtaken hebben het generally niet nodig.

Stap 6: Bescherm productieomgevingen

OIDC kan niet compenseren voor een geautoriseerde werkstroom die kwaadaardige code uitvoert. Als een aanvaller in staat is om een vertrouwde implementatiewerkstroom te wijzigen of onbeoordeelde code uit te voeren in die context, kan hij mogelijk tijdelijke referenties verkrijgen.

GitHub-omgevingen kunnen controles toevoegen zoals implementatiebranchbeperkingen en vereisereviewers, onderworpen aan repositoryinstellingen en planbeschikbaarheid.

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

    permissions:
      contents: read
      id-token: write

Wanneer de werkstroom een omgeving gebruikt, kan het OIDC-subject die omgeving identificeren in plaats van een branch. Werk het IAM-trustbeleid bij om de actual claims te matchen en de omgeving zelf te beschermen.

Voor productie combineer beperkte identiteiten met branchbescherming, code review, beperkte werkstroomrechten en omgevingsgoedkeilingsregels waar toepasselijk. Dit is hoe OIDC deel uitmaakt van een sterker implementatiebeveiligingpositie in plaats van een referentievervacing alleen.

Stap 7: Verifiseer de overgenemende identiteit en test afwijgingen

Na het configureren van AWS-authenticatie, voeg een diagnostische stap toe:

- name: Verify AWS identity
  run: aws sts get-caller-identity

Controleer dat het antwoord het bedoelde AWS-account en de implementatieregel identificeert. De command onthult de secret access key niet.

Test ook of een onbevoegde branch, repository of omgeving de productieregel niet kan overnemen. Een mislukte onbevoegde implementatie is een succesvolle beveiligingstest.

Log nooit ruwe OIDC-tokens of tijdelijke referenties tijdens het debuggen.

Veelvoorkomende OIDC-beveiligings- en configuratiefouten

Ontbrekende id-token: write

De taak kan geen OIDC-token aanvragen tenzij deze de toestemming heeft. Taakniveau-rechten kunnen werkstroomniveau-rechten overschrijven.

Technical workflow illustration

AWS returned AccessDenied for roleovername

Controleer de identiteitservice, audience, rol-ARN en subjectconditie. Controleer in het bijzonder het werkelijke GitHub-subjectformaat in plaats van te veronderstellen dat elke repository hetzelfde standaardformaat gebruikt.

Authenticatie slaagt, maar upload faalt

De trustrelatie kan correct zijn terwijl de rol de vereiste S3-rechten mist. Los het narrowly scoped IAM-rechtenbeleid op in plaats van het identiteitvertrouwbeleid te verbreden.

Productietoegang is toegestaan vanaf te veel contexten

Een wildcardsubject of onvoldoende omgevingsbeperkingen kan productiereferenties beschikbaar maken voor werkstromen die nooit mogen deze ontvangen. Beperkt het trustbeleid en test onbevoegde gevallen.

Een pull request kan niet implementeren

Pull requests kunnen andere claims hebben en onbetrouwde code bevatten. Verzwak niet de productievertrustcondities alleen maar om een pull request toe te staan om de implementatieregel over te nemen. Voer validatie uit afzonderlijk van productieimplementatie.

Kan je OIDC gebruiken met Azure of Google Cloud?

Ja. Het federatiemechanisme is vergelijkbaar, maar de identiteitsconfiguratie verschilt.

| Cloud | Federatiemechanisme | GitHub-actie | |---|---|--- bak| | AWS | IAM OIDC-provider en -regel | aws-actions/configure-aws-credentials | | Microsoft Azure | Federated identity credentials | azure/login | | Google Cloud | Workload Identity Federation | google-github-actions/auth |

Azure koppelt normaal gesproken een federated credential aan een applicatie of beheerde identiteit. Google Cloud gebruikt een workload-identiteitspool en -provider, met directe resourceaccess of serviceaccountimpersonatie, afhankelijk van de instellingen.

Elk platform heeft zijn eigen audience, subjectmatching en autorisatieregels. Bekijk de huidige officiële documentatie van de provider voordat je een voorbeeld kopieert.

Wat met PHP-websites op traditionele hosting?

Niet elke webhost accepteert GitHub OIDC-identiteiten. Shared hosting en managed PHP hosting kunnen nog steeds SSH-sleutels, SFTP-credentials, implementatiewebhooks of provider API-tokens gebruiken.

Het inschakelen van OIDC in GitHub Actions vervangt niet automatisch een SSH-sleutel als de bestemmingserver geen federatiemechanisme heeft.

Waar OIDC niet beschikbaar is, gebruik een dedicated implementatie-account, narrowly scoped permissions, protected secrets en referentierotatie. Beperkt bestandssysteem- en commando-toegang waar mogelijk.

Het beveiligingsdoel is least privilege en beperkte referentieblootstelling, ongeacht of OIDC wordt ondersteund.

Checklist voor implementatiebeveiliging

Controleer voordat je naar productie implementeert of het volgende geldt:

  • De OIDC-uitgever en -audience zijn correct geconfigureerd.
  • Het trustbeleid komt uitsluitend overeen met de bedoelde repository en implementatiecontext.
  • De subjectconditie weerspiegelt het werkelijke GitHub-tokenformaat van je repository.
  • De IAM-rolle heeft uitsluitend de permissions die nodig zijn voor de implementatie.
  • Alleen implementatietaken ontvangen id-token: write.
  • Productiebranches en -omgevingen hebben passende bescherming.
  • Third-party acties zijn beoordeeld en het liefst vastgemaakt aan onveranderlijke commit SHAs.
  • Onbetrouwde pull requests kunnen geen productieregelnemen.
  • Onbevoegde branches en repositories falen bij authenticatie.
  • Tokens en tijdelijke referenties worden nooit gelogd of opgeslagen zonder noodzaak.

Veelgestelde vragen

Is OIDC veiliger dan statische AWS-toegangssleutels?

Het vermindert blootstelling aan langlevende referentiediefstal. Sterke trustbeleidsregels, beperkte rechten en beschermde werkstromen zijn nog steeds essentieel.

Verwijdert OIDC GitHub Secrets?

Het vervangt uitsluitend sommige cloudautenticatie-referenties, niet elke applicatiegeheim of API-key.

Wat verleent id-token: write?

Het laat een werkstroom toe om een identiteits-token aan te vragen. Cloudrechten worden uitsluitend bepaald door de provider.

Kunnen onbetrouwde pull requests productie-OIDC-referenties gebruiken?

Ze zouden dat niet moeten doen. Configureer restrictieve vertrouwcondities en houd productieimplementaties gescheiden van onbetrouwde code.

Werkt OIDC met elke hostingprovider?

Nee. De bestemmingsservice of een identiteitsbroker moet GitHub’s OIDC-tokens ondersteigen en vertrouwen.

Conclusie: versterk de beveiliging, niet alleen de authenticatie

GitHub Actions OIDC is een effectieve manier om de implementatiebeveiling te verhogen voor ondersteide cloudservices. Het verwijdert de noodzaak om permanente cloudkeys in GitHub op te slaan, maakt kortelevende access mogelijk en laat cloudtrustbeleidsregels toe om te beperken welke werkstromen kunnen implementeren.

Maar het sterkste ontwerp combineert OIDC met least-privilege IAM, beschermde omgevingen, beoordeelde werkstroomcode en expliciete tests dat onbevoegde identiteiten worden afgewezen.

Het doel is niet eenvoudigweg een secret te vervangen. Het doel is om ervoor te zorgen dat alleen de juiste werkstroom de juiste resources kan benaderen, met de minimale privileges en voor de kortest mogelijke tijd.

Officiële referenties