‫گذر از کلیدهای ثابت به احراز هویت بدون رمز (Secretless): راهنمای پیاده‌سازی OIDC در انتشار بسته‌های NuGet

چکیده: با اعلام سیاست‌های جدید مایکروسافت و مایکروسافت نُگِت (NuGet.org)، طول عمر کلیدهای دسترسی API از تاریخ ۱۷ اوت به حداکثر ۳۰ روز کاهش یافته و کلیه کلیدهای طولانی‌مدت قدیمی در اول نوامبر غیرفعال می‌شوند. این تغییر سیاست، چالش‌های عملیاتی متعددی را برای چرخه‌های یکپارچه‌سازی و تحویل مداوم (CI/CD) و مدیریت سنتی کلیدها در GitHub Actions ایجاد می‌کند. راهکار مدرن و ایمن مایکروسافت برای حل این مشکل، استفاده از پروتکل OpenID Connect (OIDC) و قابلیت Trusted Publishing است. در این مقاله، ضمن بررسی تعاملی این الگوی احراز هویت بدون کلید (Secretless)، شیوه تنظیم آن بر روی بسته‌های دات‌نت (.NET) و خودکارسازی چرخه انتشار در پلتفرم GitHub Actions تشریح می‌شود.

[GitHub Runner] ---- (۱. درخواست Token با ادعاهای OIDC) ----> [GitHub OIDC Provider]
[GitHub Runner] <--- (۲. دریافت JSON Web Token / JWT امضا شده) -- [GitHub OIDC Provider]
[GitHub Runner] ---- (۳. تبادل JWT با کلید موقت ۱ ساعته) -----> [NuGet.org]
[GitHub Runner] <--- (۴. دریافت Short-lived API Key) -------- [NuGet.org]

• صدور توکن ادعا (OIDC Token): هنگام اجرای Workflow در GitHub Actions، موتور اجراکننده از OIDC Providerِ اختصاصی GitHub درخواست یک توکن امضاشده (JWT) می‌کند. این توکن حاوی مشخصاتی چون نام مخزن، نام مالک، شاخه (Branch) و نام فایل Workflow است.
• اعتبارسنجی توسط NuGet: توکن به NuGet.org ارسال می‌شود. NuGet امضای دیجیتال توکن را بررسی کرده و ادعاهای داخل آن را با «سیاست اعتماد» (Trust Policy) که قبلاً در حساب کاربری ثبت کرده‌اید، تطبیق می‌دهد.
• تولید کلید کوتاه‌مدت: در صورت انطباق کامل اطلاعات، NuGet یک کلید API یک‌بارمصرف با اعتبار یک ساعته صادر کرده و بسته .nupkg را دریافت می‌کند.

• وارد حساب کاربری خود در NuGet.org شده و به بخش Account Settings (یا Organization Settings) Trusted Publishing بروید.
• گزینه Add Policy را انتخاب کرده و فیلدها را به شکل زیر تنظیم کنید:
• Repository Owner: نام کاربری یا سازمان در گیت‌هاب (مثلاً my_name).
• Repository: نام دقیق مخزن پروژه‌تان (مثلاً PersianCalendar).
• Workflow File: نام دقیق فایل ورک‌فلو بدون مسیر (مثلاً publish.yml).
• Environment (اختیاری): در صورت استفاده از GitHub Environments (مانند release) نام آن را ذکر کنید.

نکته برای مخازن خصوصی (Private Repositories): زمانی که برای یک مخزن خصوصی policy تعریف می‌کنید، NuGet آن را به مدت ۷ روز فعال موقت نگه می‌دارد. پس از اولین انتشار موفق، این وضعیت به صورت دائمی تثبیت می‌شود.

name: Publish to NuGet

on:
  release:
    types: [published] # اجرا هنگام انتشار یک Release جدید
  workflow_dispatch:      # امکان اجرای دستی ورک‌فلو

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
      id-token: write # الزام دسترسی برای احراز هویت OIDC

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup .NET SDK
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '9.0.x' # نسخه SDK مورد نظر شما

      - name: Restore dependencies
        run: dotnet restore

      - name: Build project
        run: dotnet build --configuration Release --no-restore

      - name: Run Tests
        run: dotnet test --configuration Release --no-build

      - name: Pack Package
        run: dotnet pack --configuration Release --no-build --output ./artifacts

      # ۱. تبادل توکن OIDC با کلید موقت ۱ ساعته NuGet
      - name: NuGet Login via OIDC
        id: login
        uses: NuGet/login@v1
        with:
          user: ${{ secrets.NUGET_USER }} # نام کاربری پروفایل NuGet (نه ایمیل)

      # ۲. ارسال بسته به NuGet با کلید موقت دریافت شده
      - name: Push Package to NuGet.org
        run: |
          dotnet nuget push ./artifacts/*.nupkg \
            --source https://api.nuget.org/v3/index.json \
            --api-key "${{ steps.login.outputs.NUGET_API_KEY }}" \
            --skip-duplicate

• در مخزن گیت‌هاب به Settings ، Secrets and variables ، Actions بروید.
• یک Secret جدید با نام NUGET_USER تعریف کرده و مقدار آن را برابر با نام کاربری خود در NuGet (برای مثال my_name) قرار دهید.

• خودکارسازی شماره‌گذاری نسخه (Versioning Automation):
• به جای تغییر دستی نسخه در فایل .csproj پیش از هر انتشار، پیشنهاد می‌شود از ابزارهایی مانند MinVer یا GitVersion استفاده کنید. این ابزارها بر اساس Tagهای Git (مانند v1.2.0)، نسخه بسته را به صورت خودکار در زمان Build تعیین می‌کنند.
• امضای دیجیتال بسته‌ها (Package Signing):
• علاوه بر احراز هویت OIDC در زمان انتشار، می‌توانید با استفاده از گواهی‌های دیجیتال (Code Signing Certificate) و دستور dotnet nuget sign بسته‌های خود را امضا کنید تا اصالت فایل پس از دانلود توسط کاربران قابل راستی‌آزمایی باشد.
• استفاده از سیستم Reproducible Builds:
• افزودن تنظیمات در فایل پروژه دات‌نت هنگام اجرا در محیط CI، باعث می‌شود که فایل‌های DLL و nupkg تولیدشده کاملاً قطعی و بدون وابسته بودن به محیط سیستم‌عامل محلی امضا و بسته بندی شوند.