این راهنما جهت‌گیری با تراکم بالا و کنش‌محور برای پیاده‌سازی اصالت‌سنجی گذرکلید امن و مستقل از چارچوب و مدیریت اطلاعات کاربری در برنامه‌های وب مدرن ارائه می‌دهد.
۱. پیش‌نیازهای اصلی برای گذرکلیدها
گذرکلیدها به Web Authentication API (WebAuthn) متکی هستند که محدودیت‌های امنیتی متقاطع سخت‌گیرانه‌ای را اعمال می‌کند که باید قبل‌از هرگونه تلاش برای پیاده‌سازی برآورده شوند:
- بافتارهای امن: روش‌های WebAuthn (
navigator.credentials.createوnavigator.credentials.get) به‌شدت پشت «بافتارهای امن» محدود شده‌اند. برنامه‌ها باید درhttps://در تولید، یاhttp://localhostبرای توسعه محلی اجرا شوند. - شناسه طرف اتکا (RP): هر اعتبارنامه به یک شناسه RP (اساساً نام دامنه برنامه) مرتبط است. شناسه RP ارسال‌شده در گزینه‌های سمت سرور باید با نام دامنه مبدأ فعلی مطابقت داشته باشد یا پسوند معتبری از آن باشد (برای مثال،
example.comبرایlogin.example.comمعتبر است). عدم تطابق منجر به استثناهایSecurityErrorدر سمت کارخواه می‌شود.
۲. هشدار تجربه کاربری AAGUID
«شناسه منحصربه‌فرد جهانی گواهی اصالت‌سنج» (AAGUID) یک شناسه ۱۲۸ بیتی است که در داده‌های گواهی ثبت برگردانده می‌شود و نشان‌دهنده مدل/ ارائه‌دهنده اصالت‌سنج است (برای مثال، «مدیر گذرواژه Google»، iCloud Keychain، 1Password).
- فقط اشاره‌های تجربه کاربری: طرف‌های متکی باید از AAGUID منحصراً برای اشاره‌های تجربه کاربری (مانند ارائه نام و نماد ارائه‌دهنده گذرکلید در فهرست مدیریت برای کمک به کاربر) استفاده کنند.
- بدون وابستگی‌های امنیتی: برنامه‌ها نباید از AAGUID برای امنیت رمزنگاری یا تصمیم‌گیری‌های دسترسی استفاده کنند. گذرکلیدهای پلاتفرم درحال‌حاضر گواهی رمزنگاری برای AAGUID خود ارائه نمی‌دهند، یعنی نماینده‌های کاربر می‌توانند آن را تغییر دهند یا شبیه‌سازی کنند.
۳. توصیه‌های کتابخانه جداشده
برای تولید گزینه‌های FIDO2/WebAuthn در پس‌زمینه و درستی‌سنجی امضا، توسعه‌دهندگان باید به‌جای رمزنگاری دستی، به کتابخانه‌های متن‌باز بررسی‌شده برای هر زبان تکیه کنند:
- جاوا اسکریپت/ تایپ‌اسکریپت: SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
- Python: py_webauthn (github.com/duo-labs/py_webauthn)
- Java: Java WebAuthn Server (github.com/Yubico/java-webauthn-server)، WebAuthn4J (github.com/webauthn4j/webauthn4j)
- .NET: کتابخانه .NET برای FIDO2 (github.com/abergs/fido2-net-lib)
- Go: کتابخانه Go برای WebAuthn (github.com/go-webauthn/webauthn)
- Ruby: WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
- PHP: چارچوب WebAuthn (github.com/web-auth/webauthn-framework)
۴. ماتریس مرجع مورد استفاده
مورد استفاده منطبق را در زیر شناسایی کنید و راهنمای پیاده‌سازی کامل آن را بازیابی کنید. هر مورد استفاده دارای میاناهای برنامه‌سازی کاربردی حیاتی (PublicKeyCredential.parseCreationOptionsFromJSON، parseRequestOptionsFromJSON، signalAllAcceptedCredentials، signalCurrentUserDetails، signalUnknownCredential، میانجی‌گری شرطی، مدیریت AAGUID، و غیره) است که فقط در راهنمای هر مورد استفاده مستند شده است. این مرحله بازیابی را رد نکنید و پوشاننده‌های کتابخانه شخص ثالث (مانند startAuthentication/startRegistration SimpleWebAuthn) را در کارخواه جایگزین نکنید — مستقیماً با میاناهای برنامه‌سازی کاربردی مرورگر WebAuthn بومی تماس بگیرید. توصیه‌های کتابخانه در بخش ۳ فقط برای سمت سرور (درستی‌سنجی FIDO2 در پس‌بست) اعمال می‌شود.
جزئیات پیاده‌سازی WebAuthn و گذرکلید خاص در راهنماهای زیر نگاشت شده است:
- ثبت گذرکلید: ثبت گذرکلید — ارائه ثبت گذرکلید جدید و تبلیغات.
- ایجاد شرطی گذرکلید: ایجاد شرطی گذرکلید (تبلیغ پس‌از ورود به سیستم) — ثبت بی‌صدا گذرکلیدها بلافاصله پس‌از ورود موفق به سیستم با گذرواژه.
- اصالت‌سنجی با گذرکلید: اصالت‌سنجی با گذرکلید — تکمیل خودکار قابل‌کشف و ورود به سیستم با دکمه.
- ورود سریع به سیستم: ورود سریع به سیستم با حالت میانای کاربر فوری — ورود به سیستم زمینه‌ای درجا با گذرکلیدهای محلی و گذرواژه‌های ذخیره‌شده قبل‌از پیمایش صفحه.
- مدیریت گذرکلید: مدیریت گذرکلید — همگام‌سازی فهرست‌ها، تغییر نام‌ها، و حذف‌ها با مدیران گذرواژه.
- اصالت‌سنجی مجدد با گذرکلید: اصالت‌سنجی مجدد با گذرکلید — درستی‌سنجی مجدد کاربران واردشده به سیستم که برای مراحل حساس برمی‌گردند.