Dela via

Betrodd publicering på nuget.org

Betrodd publicering är ett bättre sätt att publicera NuGet-paket. Du behöver inte längre hantera API-nycklar med lång livslängd. I stället använder du kortlivade autentiseringsuppgifter som utfärdats av ditt CI/CD-system, till exempel GitHub Actions.

Detta gör publiceringsprocessen säkrare genom att minska risken för läckta autentiseringsuppgifter. Det gör också automatisering enklare eftersom du inte behöver rotera eller lagra hemligheter. Den här metoden är en del av en bredare branschförskjutning mot säker, nyckellös publicering. Om du är nyfiken kan du kolla in OpenSSF-initiativet: https://repos.openssf.org/trusted-publishers-for-all-package-repositories.

⚠️ Heads up: Om du inte ser alternativet Betrodd publicering i ditt nuget.org konto kanske det inte är tillgängligt för dig ännu. Vi rullar ut det gradvis.

Så här fungerar det

När ditt GitHub Actions-arbetsflöde körs begär det en krypterad OIDC-token från github.com. Den här token innehåller information om lagringsplatsen och arbetsflödet och är kryptografiskt signerad av GitHub Actions för att förhindra manipulering. Arbetsflödet vidarebefordrar denna token till nuget.org, som på ett säkert sätt validerar tokens äkthet med github.com med hjälp av kryptografiska metoder av branschstandard. En token exchange-slutpunkt på nuget.org kontrollerar sedan att tokens information matchar en betrodd publiceringsprincip som du har konfigurerat. Om allt stämmer utfärdar nuget.org en kortlivad API-nyckel som arbetsflödet ska använda när du publicerar ditt paket.

Här är det grundläggande flödet

  1. Ditt CI/CD-system (till exempel GitHub Actions) kör ett arbetsflöde.
  2. Den utfärdar en kortlivad behörighetsnyckel.
  3. Den här token skickas till nuget.org.
  4. NuGet verifierar det och returnerar en tillfällig API-nyckel.
  5. Arbetsflödet använder den nyckeln för att push-överföra paketet.

Skärmbild som visar sidan Betrodd publicering.

NuGets tillfälliga API-nycklar är giltiga i 1 timme, så arbetsflödet bör begära nyckeln strax före publicering. Om du begär det för tidigt kan det gå ut innan push-överföringen sker.

Varje kortlivad token kan bara användas en gång för att hämta en enda tillfällig API-nyckel – en token, en API-nyckel.

Den här konfigurationen ger dig ett säkert och automatiserat sätt att publicera paket, utan de risker som följer med långvariga hemligheter.

Installation av GitHub Actions

Så här kommer du igång:

  1. Logga in på nuget.org.
  2. Klicka på ditt användarnamn och välj Betrodd publicering.
  3. Lägg till en ny princip för betrodd publicering. För en GitHub-lagringsplats https://github.com/contoso/contoso-sdk med en arbetsflödesfil .github/workflows/build.yml anger du följande betrodda principinformation (skiftlägesokänslig):
    • Lagringsplatsägare:contoso
    • Databasen:contoso-sdk
    • Arbetsflödesfil:build.yml

      Detta motsvarar ditt arbetsflöde på .github/workflows/build.yml. Ange endast filnamnet (build.yml)– inkludera .github/workflows/ inte sökvägen.

    • Miljö (valfritt):release

      Ange miljö om arbetsflödet använder t.ex. environment: release och du vill begränsa den här principen till den miljön. Lämna detta tomt om du inte använder GitHub Actions-miljöer.

  4. På din GitHub-lagringsplats uppdaterar du arbetsflödet för att begära en kortlivad API-nyckel och push-överföra paketet.
    Här är ett grundläggande exempel:
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

Principägarskap

När du skapar en princip för betrodd publicering måste du välja vem som äger den. Ägaren kan vara antingen:

  • Du (en enskild användare)
  • En organisation som du tillhör

Principen gäller för alla paket som ägs av den valda ägaren. Det innebär att den styr vem som kan publicera eller ändra dessa paket med hjälp av betrodd publicering.

Om du väljer en organisation kontrollerar du att du är en aktiv medlem. Om du lämnar organisationen senare kan principen bli inaktiv tills du läggs till igen.

Genom att välja rätt ägare ser du till att publiceringskonfigurationen förblir säker och anpassad till teamets struktur.

Principer som väntar på fullständig aktivering

Ibland när du skapar en princip för betrodd publicering börjar den som tillfälligt aktiv i 7 dagar. Detta sker vanligtvis med privata GitHub-lagringsplatser. Du ser den här statusen i användargränssnittet. Under den tiden fungerar den som en vanlig policy. Men om ingen publicering sker inom dessa sju dagar blir principen automatiskt inaktiv. Du kan när som helst starta om 7-dagarsfönstret, även när det har upphört att gälla.

Varför är den här tillfälliga perioden nödvändig? Eftersom NuGet behöver GitHub-lagringsplats och ägar-ID:n för att låsa principen till den ursprungliga lagringsplatsen och ägaren. Det hjälper till att förhindra återuppståndelseattacker. Utan dessa ID:er kan någon ta bort en lagringsplats, återskapa den med samma namn och försöka publicera som om ingenting hade ändrats.

När en lyckad publicering ger ID:t (som en del av GitHubs kortlivade token) blir principen permanent aktiv.

Varningar om principägarskap

Principer för betrodd publicering är knutna till en specifik ägare – antingen en enskild användare eller en organisation. Om något ändras med ägarskapet kan principen bli inaktiv. När det händer visas en varning i användargränssnittet.

Vanliga fall

  • Användaren har tagits bort från organisationen
    Om en princip ägs av en organisation och användaren som skapade den senare tas bort från organisationen blir principen inaktiv.
    Om användaren läggs till i organisationen igen blir principen aktiv igen automatiskt.

  • Organisationen är inte längre aktiv
    Om den organisation som äger principen är låst eller borttagen blir principen inaktiv.

Dessa varningar hjälper till att se till att endast aktiva, säkra principer används vid publicering av paket.