Sdílet prostřednictvím

Důvěryhodné publikování v nuget.org

Důvěryhodné publikování je lepší způsob, jak publikovat balíčky NuGet. Už nemusíte spravovat dlouhodobé klíče rozhraní API. Místo toho použijete krátkodobé přihlašovací údaje vydané systémem CI/CD, jako je GitHub Actions.

Díky tomu je proces publikování bezpečnější tím, že snížíte riziko úniku přihlašovacích údajů. Automatizace je také jednodušší, protože nemusíte obměňovat ani ukládat tajné kódy. Tento přístup je součástí širšího odvětví posunu směrem k zabezpečenému bezklíčovém publikování. Pokud vás zajímá, podívejte se na iniciativu OpenSSF: https://repos.openssf.org/trusted-publishers-for-all-package-repositories.

⚠✔ Pozor: Pokud ve vašem účtu na nuget.org nevidíte možnost Důvěryhodné publikování, může pro vás zatím nemusí být dostupná. Postupně ho zavádíme.

Jak to funguje

Když se pracovní postup GitHub Actions spustí, vyžádá si šifrovaný token OIDC z github.com. Tento token obsahuje informace o vašem úložišti a pracovním postupu a je kryptograficky podepsaný GitHub Actions, aby se zabránilo manipulaci. Pracovní postup tento token předá nuget.org, který bezpečně ověří pravost tokenu pomocí github.com pomocí standardních kryptografických metod. Koncový bod výměny tokenů na nuget.org pak zkontroluje, že podrobnosti tokenu odpovídají důvěryhodným zásadám publikování, které jste nakonfigurovali. Pokud se všechno shoduje, nuget.org vydá krátkodobý klíč rozhraní API pro váš pracovní postup, který se použije při publikování balíčku.

Tady je základní tok.

  1. Váš systém CI/CD (například GitHub Actions) spouští pracovní postup.
  2. Vydává krátkodobý token.
  3. Tento token se odešle do nuget.org.
  4. NuGet ho ověří a vrátí dočasný klíč rozhraní API.
  5. Váš pracovní postup používá ten klíč k nahrání balíčku.

Snímek obrazovky zobrazující stránku důvěryhodného publikování

Dočasné klíče rozhraní API NuGet jsou platné 1 hodinu, takže váš pracovní postup by si měl klíč vyžádat krátce před publikováním. Pokud o to požádáte příliš brzy, může vypršet, než se uskuteční provedeni aktualizace.

Každý krátkodobý token lze použít pouze jednou k získání jednoho dočasného klíče rozhraní API – jednoho tokenu, jednoho klíče rozhraní API.

Toto nastavení poskytuje bezpečný a automatizovaný způsob publikování balíčků bez rizik, která jsou součástí dlouhodobých tajných kódů.

Nastavení GitHub Actions

Jak začít:

  1. Přihlaste se k nuget.org.
  2. Klikněte na své uživatelské jméno a zvolte Důvěryhodné publikování.
  3. Přidejte novou důvěryhodnou zásadu publikování. Pro úložiště GitHub https://github.com/contoso/contoso-sdk s pracovním souborem .github/workflows/build.yml zadejte následující podrobnosti o důvěryhodných zásadách (nerozlišují se malá a velká písmena):
    • Vlastník úložiště:contoso
    • Skladiště:contoso-sdk
    • Soubor pracovního postupu:build.yml

      To odpovídá vašemu pracovnímu postupu na adrese .github/workflows/build.yml. Zadejte pouze název souboru (build.yml)– nezahrnujte .github/workflows/ cestu.

    • Prostředí (volitelné):release

      Zadejte prostředí, pokud váš pracovní postup používá například environment: release a chcete tuto zásadu omezit na toto prostředí. Pokud nepoužíváte prostředí GitHub Actions, ponechte tuto prázdnou hodnotu.

  4. V úložišti GitHub aktualizujte pracovní postup tak, aby nejprve požádal o krátkodobý klíč rozhraní API a poté odeslal váš balíček.
    Tady je základní příklad:
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

Vlastnictví zásad

Při vytváření zásad důvěryhodného publikování je potřeba zvolit, kdo je vlastníkem. Vlastník může být následující:

  • Vy (jednotliví uživatelé)
  • Organizace, do které patříte

Zásada se použije pro všechny balíčky vlastněné vybraným vlastníkem. To znamená, že řídí, kdo může publikovat nebo upravovat tyto balíčky pomocí důvěryhodného publikování.

Pokud zvolíte organizaci, ujistěte se, že jste aktivním členem. Pokud organizaci opustíte později, politika se může stát neaktivní, dokud se nepřidáte zpět.

Volba správného vlastníka pomáhá zajistit, aby nastavení publikování zůstalo zabezpečené a sladěné se strukturou vašeho týmu.

Zásady čekající na úplnou aktivaci

Když někdy vytvoříte důvěryhodnou zásadu publikování, začne se dočasně aktivovat po dobu 7 dnů. K tomu obvykle dochází u privátních úložišť GitHubu. Tento stav se zobrazí v uživatelském rozhraní. V tomto období se chová jako běžná politika. Pokud se ale během těchto 7 dnů nepublikuje, zásady se automaticky stanou neaktivními. 7denní okno můžete kdykoli restartovat – i po vypršení jeho platnosti.

Proč je tato dočasná doba nezbytná? Vzhledem k tomu, že NuGet potřebuje id úložiště GitHub a id vlastníka, aby zásady uzamknuly do původního úložiště a vlastníka. Pomáhá to předcházet útokům typu zmrtvýchvstání. Bez těchto ID by někdo mohl odstranit úložiště, znovu ho vytvořit se stejným názvem a pokusit se publikovat, jako by se nic nezměnilo.

Jakmile úspěšné publikování poskytne ID (jako součást krátkodobého tokenu GitHubu), zásada se trvale aktivuje.

Upozornění na vlastnictví politiky

Důvěryhodné zásady publikování jsou svázané s konkrétním vlastníkem – buď s konkrétním uživatelem, nebo s organizací. Pokud se něco změní s tímto vlastnictvím, může se politika stát neaktivní. V takovém případě se v uživatelském rozhraní zobrazí upozornění.

Běžné případy

  • Uživatel odebraný z organizace
    Pokud zásadu vlastní organizace a uživatel, který ji vytvořil, se později z této organizace odebere, stane se tato zásada neaktivní.
    Pokud se uživatel přidá zpět do organizace, zásada se automaticky aktivuje.

  • Organizace už není aktivní
    Pokud je organizace, která tuto zásadu vlastní, uzamčená nebo odstraněná, stane se zásada neaktivní.

Tato upozornění pomáhají zajistit, aby se při publikování balíčků používaly jenom aktivní a zabezpečené zásady.

  • Last updated on