GitHub Actions OIDC: Hoe je je deployments kunt beveiligen zonder langdurige geheimen
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
- Een geautoriseerde GitHub Actions-taak vraagt een identiteits-token aan.
- GitHub geeft een ondertekend JWT af voor die taak.
- De werkstroom presenteert het token aan de cloudidentiteitservice.
- De cloudprovider valideert het token en evalueert zijn geconfigureerde trustvoorwaarden.
- Als de identiteit is toegestaan, geeft de provider tijdelijke referenties uit.
- 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/*"
}
]
}

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.

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.