Web e sviluppo

GitHub Actions OIDC: Come proteggere i tuoi deployment senza segreti a lungo termine

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

Scopri come rafforzare la sicurezza dei deployment di GitHub Actions con OIDC. Sostituisci le credenziali cloud a lungo termine con token a breve termine, limita l'accesso utilizzando le politiche di fiducia IAM e proteggi i tuoi pipeline CI/CD.

GitHub Actions OIDC: come proteggere i tuoi deployment senza segreti a lunga scadenza

Eseguire il deployment di un'applicazione da GitHub Actions richiede solitamente l'accesso a infrastrutture esterne. Un flusso di lavoro potrebbe caricare file su Amazon S3, pubblicare container o aggiornare risorse cloud. Tradizionalmente, i team memorizzano una chiave di accesso cloud in GitHub Secrets. Questo funziona, ma una credential a lunga scadenza rimane utile per un attaccante se un flusso di lavoro, una dipendenza o un log la espongono.

OpenID Connect (OIDC) aiuta a rafforzare la sicurezza di CI/CD sostituendo le credenziali cloud a lunga scadenza con un accesso temporaneo concesso solo a identità di flusso autorizzate. Ciò riduce l'esposizione delle credenziali, limita l'accesso non autorizzato e supporta deployment di produzione più rigorosamente controllati.

Questo tutorial spiega i vantaggi in termini di sicurezza, mostra una configurazione pratica di AWS e identifica le protezioni di cui hai ancora bisogno. OIDC non è un interruttore magico per la sicurezza: la politica di fiducia, le autorizzazioni del ruolo e i controlli del flusso di lavoro sono importanti quanto lo scambio di token.

Perché la sicurezza del deployment è importante

I pipeline CI/CD sono un'automazione privilegiata. Possono essere in grado di sostituire il codice di produzione, caricare asset, leggere configurazioni di deployment o modificare l'infrastruttura. Pertanto, un pipeline compromesso può avere un impatto maggiore rispetto a una workstation di sviluppo compromessa.

Tre rischi comuni meritano particolare attenzione:

  • Esposizione delle credenziali: una chiave cloud statica rubata da un ambiente di build può rimanere valida fino a quando qualcuno non la revoca.
  • Privilegi eccessivi: una credential di deployment con autorizzazioni di amministratore può influenzare servizi non correlati.
  • Deployment non autorizzato: un ramo o un flusso di lavoro non affidabile potrebbe ottenere l'accesso alla produzione se i controlli di identità sono troppo ampi.

OIDC risolve parte di questo problema legando l'autenticazione a un'identità di flusso di Supplemental material, verificabile e di breve durata. Non sostituisce il principio del minimo privilegio di IAM, la revisione del codice o la protezione dell'ambiente.

Cos'è OIDC in GitHub Actions?

OpenID Connect è uno strato di identità costruito su OAuth 2.0. GitHub Actions può richiedere un token JWT firmato dal provider OIDC di GitHub:

https://token.actions.githubusercontent.com

Il token contiene affermazioni che descrivono l'identità del lavoro e il contesto di esecuzione. Un servizio di identità cloud convalida la firma del token, l'emittente, il pubblico e le affermazioni pertinenti, quindi decide se emettere credenziali temporanee.

Il servizio esterno deve esplicitamente fidarsi dell'identità del flusso di lavoro GitHub prevista. Abilitare OIDC in un file YAML non concede automaticamente l'accesso.

Vedi la documentazione OIDC di GitHub.

Credenziali statiche vs OIDC: confronto della sicurezza

Considerazione di sicurezza Chiave di accesso a lunga scadenza Federazione OIDC
Credential cloud permanente in GitHub Spesso richiesto Non richiesto per i provider supportati
Durata della credential Fino all’espirazione o alla revoca Sessione temporanea
Responsabilità di rotazione Il team deve gestire il ciclo di vita della chiave Il provider cloud emette credenziali di breve durata
Restrizioni di identità Dipende dallo storage delle credenziali e da IAM La politica di fiducia può limitare l'identità del flusso di lavoro
Autorizzazione Autorizzazioni IAM Le autorizzazioni IAM sono ancora richieste
Rischio residuo Furto e riutilizzo di una chiave statica Flusso di lavoro autorizzato compromesso o fiducia troppo ampia

OIDC riduce il rischio e l'impatto del furto di credenziali, ma non elimina ogni segreto. Le applicazioni potrebbero ancora aver bisogno di password di database, chiavi di firma o token API di terze parti.

Come funziona il flusso di autenticazione OIDC

  1. Un lavoro autorizzato di GitHub Actions richiede un token di identità.
  2. GitHub emette un JWT firmato per quel lavoro.
  3. Il flusso di lavoro presenta il token al servizio di identità cloud.
  4. Il provider cloud convalida il token e valuta le sue condizioni di fiducia configurate.
  5. Se l'identità è autorizzata, il provider emette credenziali temporanee.
  6. Il flusso di lavoro utilizza tali credenziali nell'ambito consentito dal ruolo.

Il provider cloud deve rifiutare un token il cui soggetto, pubblico o altre condizioni richieste non corrispondono. Questa convalida è il confine tra un deployment sicuro e uno che si fida troppo.

Passo 1: Configurare il provider OIDC di GitHub in AWS

AWS IAM supporta i provider di identità OpenID Connect. Crea un provider di identità utilizzando:

| Impostazione | Valore | |---|---|---| | URL del provider | https://token.actions.githubusercontent.com | | Pubblico | sts.amazonaws.com | | Tipo di provider | OpenID Connect |

Il pubblico identifica il destinatario previsto del token. L'azione delle credenziali AWS utilizza normalmente sts.amazonaws.com.

Vedi la configurazione del ruolo OIDC di AWS IAM.

Passo 2: Limitare chi può assumere il ruolo di deployment

Crea un ruolo IAM la cui politica di fiducia consenta sts:AssumeRoleWithWebIdentity solo dal provider di identità GitHub e dall'identità del flusso di lavoro prevista.

L'esempio seguente utilizza il formato del soggetto tradizionale di GitHub basato sui rami:

{
  "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"
        }
      }
    }
  ]
}

Sostituisci il numero dell'account AWS, l'organizzazione e il repository.

Non copiare ciecamente la condizione del soggetto. GitHub ha introdotto un formato del soggetto predefinito immutabile per i repository creati dopo il 15 luglio 2026. Verifica il formato del soggetto effettivo utilizzato dal tuo repository e configura AWS per corrispondere a esso. I flussi di lavoro basati sull'ambiente possono anche utilizzare un formato del soggetto diverso. Consulta Riferimento ai token OIDC di GitHub.

Una politica di fiducia restrittiva è uno dei modi più importanti per impedire che flussi di lavoro non autorizzati ottengano credenziali di produzione. Evita i soggetti jolly che autorizzano accidentalmente repository o contesti non correlati.

Passo 3: Limitare ciò che il ruolo può fare

La fiducia determina chi può assumere un ruolo. Le autorizzazioni IAM determinano cosa il ruolo può fare dopo l'autenticazione.

Per un deployment che carica solo file in un bucket S3, una policy semplificata è:

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

Questo esempio consente il caricamento di oggetti, non l'amministrazione del conto o la cancellazione del bucket. Se il tuo deployment rimuove anche file obsoleti o elenca i contenuti del bucket, concedi solo le operazioni aggiuntive richieste, come s3:DeleteObject o s3:ListBucket con ambito specifico.

Non concedere mai AdministratorAccess solo per far funzionare un deployment. Le credenziali temporanee con privilegi eccessivi possono comunque causare gravi danni.

Passo 4: Richiedere credenziali temporanee da un flusso di lavoro

Un lavoro di deployment deve essere autorizzato a richiedere un token OIDC. L'esempio seguente carica una directory prebuild dist/ su 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

L'esempio utilizza i riferimenti alle azioni con versione principale per chiarezza. In produzione, rivedi le versioni correnti supportate e preferibilmente fissale le azioni di terze parti a SHA completi del commit. L'esempio presuppone che il sito web sia già stato costruito in dist/.

Nota cosa manca: non è memorizzata alcuna chiave di accesso AWS permanente o chiave di accesso segreta nel flusso di lavoro.

L'azione ufficiale delle credenziali AWS scambia il token OIDC con credenziali AWS temporanee.

Passo 5: Comprendere id-token: write

Questo permesso:

permissions:
  id-token: write

permette a un lavoro di richiedere un token di identità OIDC di GitHub. Non conferisce al lavoro il permesso di scrivere nei repository GitHub o di accedere ad AWS da solo.

Il provider cloud decide comunque se fidarsi dell'identità, e il ruolo IAM controlla ancora quali operazioni sono consentite.

Concedi id-token: write solo ai lavori che si autenticano effettivamente al cloud. I lavori di build, lint e test generalmente non ne hanno bisogno.

Passo \ra6: Proteggere gli ambienti di produzione

OIDC non può compensare un flusso di lavoro autorizzato che esegue codice dannoso. Se un attaccante può modificare un flusso di lavoro di deployment affidabile o eseguire codice non revisionato in quel contesto, potrebbe essere in grado di ottenere credenziali temporanee.

Gli ambienti GitHub possono aggiungere controlli come restrizioni di ramo di deployment e revisori richiesti, soggetti alle impostazioni del repository e alla disponibilità del piano.

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

    permissions:
      contents: read
      id-token: write

Quando il flusso di lavoro utilizza un ambiente, il soggetto OIDC può identificare quell'ambiente piuttosto che un ramo. Aggiorna la politica di fiducia di IAM per corrispondere alle affermazioni effettive e proteggere l'ambiente stesso.

Per la produzione, combina identità restrittive con protezione dei rami, revisione del codice, autorizzazioni limitate per i flussi di lavoro e regole di approvazione degli ambienti dove appropriato. È così che OIDC diventa parte di una postura di sicurezza del deployment più forte, non solo un sostituto delle credenziali.

Passo 7: Verificare l'identità assunta e testare i rifiuti

Dopo aver configurato l'autenticazione AWS, aggiungi un passaggio diagnostico:

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

Verifica che la risposta identifichi l'account AWS e il ruolo di deployment previsti. Il comando non rivela la chiave di accesso segreta.

Verifica inoltre che un ramo, un repository o un ambiente non autorizzato non possa assumere il ruolo di produzione. Un deployment non autorizzato fallito è un test di sicurezza riuscito.

Non loggare token OIDC grezzi o credenziali temporanee durante il debug.

Errori comuni di sicurezza e configurazione OIDC

Manca id-token: write

Il lavoro non può richiedere un token OIDC a meno che non abbia il permesso. I permessi a livello di lavoro possono sovrascrivere i permessi a livello di flusso di lavoro.

Technical workflow illustration

AWS restituisce AccessDenied per l'assunzione del ruolo

Controlla il provider di identità, il pubblico, l'ARN del ruolo e la condizione del soggetto. In particolare, verifica il formato del soggetto GitHub effettivo piuttosto che assumere che ogni repository utilizzi lo stesso predefinito.

L'autenticazione ha successo, ma il caricamento fallisce

La relazione di fiducia può essere corretta mentre il ruolo manca delle autorizzazioni S3 richieste. Corrige la policy di autorizzazione IAM con ambito ristretto piuttosto che ampliare la fiducia nell'identità.

L'accesso alla produzione è consentito da troppi contesti

Un soggetto jolly o restrizioni insufficienti sull'ambiente possono rendere le credenziali di produzione disponibili a flussi di lavoro che non dovrebbero mai riceverle. Limita la politica di fiducia e testa i casi non autorizzati.

Un pull request non può eseguire il deployment

I pull request possono avere affermazioni diverse e codice non affidabile. Non indebolire le condizioni di fiducia della produzione solo per consentire a un pull request di assumere il ruolo di deployment. Esegui la convalida separatamente dal deployment di produzione.

È possibile utilizzare OIDC con Azure o Google Cloud?

Sì. Il meccanismo di federazione è simile, ma la configurazione dell'identità è diversa.

Cloud Meccanismo di federazione Azione GitHub
AWS Provider OIDC di IAM e ruolo aws-actions/configure-aws-credentials
Microsoft Azure Credenziali di identità federata azure/login
Google Cloud Workload Identity Federation google-github-actions/auth

Azure di solito associa una credential federata a un'applicazione o a un'identità gestita. Google Cloud utilizza un pool di identità di lavoro e un provider, con accesso diretto alle risorse o all'impersonificazione dell'account di servizio a seconda della configurazione.

Ogni piattaforma ha il proprio pubblico, il controllo del soggetto e le regole di autorizzazione. Rivedi la documentazione ufficiale corrente del provider prima di copiare un esempio.

E i siti web PHP su hosting tradizionale?

Non tutti gli host web accettano identità OIDC di GitHub. L'hosting condiviso e l'hosting gestito PHP potrebbero ancora utilizzare chiavi SSH, credenziali SFTP, webhook di deployment o token API del provider.

Abilitare OIDC in GitHub Actions non sostituisce automaticamente una chiave SSH se il server di destinazione non ha un meccanismo di federazione.

Dove OIDC non è disponibile, usa un account di deployment dedicato, autorizzazioni con ambito ristretto, segreti protetti e rotazione delle credenziali. Limita l'accesso al file system e ai comandi dove possibile.

L'obiettivo della sicurezza è il minimo privilegio e la limitata esposizione delle credenziali, che OIDC sia supportato o no.

Checklist di sicurezza del deployment

Prima di eseguire il deployment in produzione, verifica che:

  • L'emittente e il pubblico OIDC siano configurati correttamente.
  • La politica di fiducia corrisponda solo al repository e al contesto di deployment previsti.
  • La condizione del soggetto rifletta il formato effettivo del token GitHub del tuo repository.
  • Il ruolo IAM abbia solo le autorizzazioni richieste dal deployment.
  • Solo i lavori di deployment ricevano id-token: write.
  • I rami e gli ambienti di produzione abbiano una protezione appropriata.
  • Le azioni di terze parti siano revisionate e preferibilmente fissate a SHA immutabili del commit.
  • I pull request non affidabili non possano assumere ruoli di produzione.
  • I rami e i repository non autorizzati falliscano l'autenticazione.
  • I token e le credenziali temporanee non siano mai loggati o memorizzati inutilmente.

Domande frequenti

OIDC è più sicuro delle chiavi di accesso statiche di AWS?

Riduce l'esposizione al furto di credenziali a lunga scadenza. Politiche di fiducia forti, autorizzazioni limitate e flussi di lavoro protetti sono ancora essenziali.

OIDC elimina i segreti di GitHub?

Sostituisce alcune credenziali di autenticazione cloud, non ogni segreto di applicazione o token API.

Cosa concede id-token: write?

Permette a un flusso di lavoro di richiedere un token di identità. Le autorizzazioni cloud sono determinate separatamente dal provider.

I pull request non affidabili possono usare le credenziali OIDC di produzione?

Non dovrebbero. Configura condizioni di fiducia restrittive e mantieni i deployment di produzione separati dal codice non affidabile.

OIDC funziona con qualsiasi provider di hosting?

No. Il servizio di destinazione o un broker di identità deve supportare e fidarsi dei token OIDC di GitHub.

Conclusione: rafforzare la sicurezza, non solo l'autenticazione

GitHub Actions OIDC è un modo efficace per aumentare la sicurezza del deployment per i servizi cloud supportati. Rimuove la necessità di mantenere chiavi cloud permanenti in GitHub, consente un accesso di breve durata e permette alle politiche di fiducia cloud di limitare quali flussi di lavoro possono eseguire il deployment.

Ma il design più forte combina OIDC con il principio del minimo privilegio di IAM, ambienti protetti, codice di flusso di lavoro revisionato e test espliciti che le identità non autorizzate vengano rifiutate.

L'obiettivo non è semplicemente sostituire un segreto. È garantire che solo il flusso di lavoro giusto possa accedere alle risorse giuste, con i permessi minimi e per il tempo più breve praticabile.

Riferimenti ufficiali