Pubblicazione attendibile in nuget.org

La pubblicazione attendibile è un modo migliore per pubblicare pacchetti NuGet. Non è più necessario gestire le chiavi API di lunga durata. Si usano invece credenziali di breve durata rilasciate dal sistema CI/CD, ad esempio GitHub Actions.

In questo modo il processo di pubblicazione è più sicuro riducendo il rischio di perdite di credenziali. Semplifica anche l'automazione perché non è necessario ruotare o archiviare segreti. Questo approccio fa parte di un più ampio cambiamento del settore verso la pubblicazione sicura e senza chiave. Per curiosità, vedere l'iniziativa OpenSSF: https://repos.openssf.org/trusted-publishers-for-all-package-repositories.

⚠️ Attenzione: Se non vedi l'opzione Pubblicazione attendibile nel tuo account su nuget.org, potrebbe non essere ancora disponibile. Lo stiamo implementando gradualmente.

Come funziona

Quando viene eseguito il flusso di lavoro di GitHub Actions, richiede un token OIDC crittografato da github.com. Questo token include informazioni sul repository e sul flusso di lavoro ed è firmato crittograficamente da GitHub Actions per evitare manomissioni. Il flusso di lavoro inoltra questo token a nuget.org, che convalida in modo sicuro l'autenticità del token con github.com usando metodi di crittografia standard del settore. Un endpoint di scambio di token in nuget.org quindi verifica che i dettagli del token corrispondano a un criterio di pubblicazione attendibile configurato. Se tutto corrisponde, nuget.org rilascia una chiave API di breve durata da usare per il flusso di lavoro durante la pubblicazione del pacchetto.

Ecco il flusso di base

1. Il sistema CI/CD (ad esempio GitHub Actions) esegue un flusso di lavoro.
2. Rilascia un token di breve durata.
3. Tale token viene inviato a nuget.org.
4. NuGet lo verifica e restituisce una chiave API temporanea.
5. Il flusso di lavoro usa tale chiave per eseguire il push del pacchetto.

Le chiavi API temporanee di NuGet sono valide per 1 ora, quindi il flusso di lavoro deve richiedere la chiave poco prima della pubblicazione. Se lo si richiede troppo presto, potrebbe scadere prima che si verifichi il push.

Ogni token di breve durata può essere usato una sola volta per ottenere una singola chiave API temporanea, ovvero un token, una chiave API.

Questa configurazione offre un modo sicuro e automatizzato per pubblicare pacchetti, senza i rischi che derivano da segreti di lunga durata.

Installazione di GitHub Actions

Per iniziare:

1. Accedere a nuget.org.
2. Fare clic sul nome utente e scegliere Pubblicazione attendibile.
3. Aggiungere un nuovo criterio di pubblicazione attendibile. Per un repository GitHub https://github.com/contoso/contoso-sdk con un file del flusso di lavoro .github/workflows/build.yml, inserire i seguenti dettagli dei criteri di sicurezza (senza distinzione tra maiuscole e minuscole):
   • Proprietario del repository:contoso
   • Deposito:contoso-sdk
   • File del flusso di lavoro:build.yml

     Corrisponde al flusso di lavoro in .github/workflows/build.yml. Immettere solo il nome file (build.yml) — non includere il .github/workflows/ percorso.

   • Ambiente (facoltativo):release

     Inserisci l'ambiente se il flusso di lavoro utilizza, ad esempio, environment: release e desideri limitare questa policy a quell'ambiente. Lasciare vuoto questo campo se non si usano ambienti GitHub Actions.

4. Nel repository GitHub aggiornare il flusso di lavoro per richiedere una chiave API di breve durata ed eseguire il push del pacchetto.
   Ecco un esempio di base:

jobs:
  build-and-publish:
    permissions:
      id-token: write  # enable GitHub OIDC token issuance for this job
    
    steps:
      # Build your artifacts/my-sdk.nupkg package here
    
      # Get a short-lived NuGet API key
      - name: NuGet login (OIDC → temp API key)
        uses: NuGet/login@v1
        id: login
        with:
          user: contoso-bot # Recommended: use a secret like ${{ secrets.NUGET_USER }} for your nuget.org username (profile name), NOT your email address
    
      # Push the package
      - name: NuGet push
        run: dotnet nuget push artifacts/my-sdk.nupkg --api-key ${{steps.login.outputs.NUGET_API_KEY}} --source https://api.nuget.org/v3/index.json

Proprietà dei criteri

Quando si crea un criterio di pubblicazione attendibile, è necessario scegliere chi lo possiede. Il proprietario può essere:

• L'utente (un singolo utente)
• Un'organizzazione a cui appartiene

Il criterio verrà applicato a tutti i pacchetti di proprietà del proprietario selezionato. Ciò significa che controlla chi può pubblicare o modificare tali pacchetti usando pubblicazione attendibile.

Se si sceglie un'organizzazione, assicurarsi di essere un membro attivo. Se si lascia l'organizzazione in un secondo momento, la politica potrebbe diventare inattiva finché non si viene reinseriti.

La scelta del proprietario corretto consente di garantire che la configurazione della pubblicazione rimanga sicura e allineata alla struttura del team.

Policy in attesa di attivazione completa

In alcuni casi, quando si crea un criterio di pubblicazione attendibile, esso inizia come temporaneamente attivo per 7 giorni. Questo problema si verifica in genere con i repository GitHub privati. Questo stato verrà visualizzato nell'interfaccia utente. Durante questo periodo, si comporta come una politica regolare. Tuttavia, se non viene eseguita alcuna pubblicazione entro questi 7 giorni, il criterio diventa automaticamente inattivo. È possibile riavviare la finestra di 7 giorni in qualsiasi momento, anche dopo la scadenza.

Perché questo periodo temporaneo è necessario? Poiché NuGet necessita degli ID del repository e del proprietario di GitHub per bloccare i criteri sul repository e sul proprietario originali. Ciò aiuta a prevenire gli attacchi di risurrezione. Senza questi ID, qualcuno potrebbe eliminare un repository, ricrearlo con lo stesso nome e provare a pubblicare come se non fosse cambiato nulla.

Una volta che una pubblicazione di successo fornisce gli ID (come parte del token di breve durata di GitHub), la politica diventa attiva in modo permanente.

Avvisi sulla proprietà dei criteri

I criteri di pubblicazione attendibili sono associati a un proprietario specifico, ovvero un singolo utente o un'organizzazione. Se qualcosa cambia con tale titolarità, la politica potrebbe diventare inattiva. In questo caso, verrà visualizzato un avviso nell'interfaccia utente.

Casi comuni

• Utente rimosso dall'organizzazione
  Se un criterio è di proprietà di un'organizzazione e l'utente che lo ha creato viene successivamente rimosso da tale organizzazione, il criterio diventa inattivo.
  Se l'utente viene aggiunto nuovamente all'organizzazione, il criterio verrà nuovamente attivo automaticamente.

• L'organizzazione non è più attiva
  Se l'organizzazione proprietaria dei criteri è bloccata o eliminata, il criterio diventa inattivo.

Questi avvisi consentono di assicurarsi che vengano usati solo i criteri attivi e sicuri durante la pubblicazione di pacchetti.