ثبت گذرکلید سمت سرور

نمای کلی

در اینجا نمای کلی سطح بالایی از مراحل کلیدی مربوط به ثبت گذرکلید ارائه شده است:

جریان ثبت گذرکلید

  • گزینه‌های ایجاد گذرکلید را تعریف می‌کند. آن‌ها را به مشتری ارسال کنید تا بتوانید آن‌ها را به فراخوانی ایجاد گذرکلیدتان منتقل کنید: فراخوانی WebAuthn API navigator.credentials.create در وب، و credentialManager.createCredential در Android. پس‌از اینکه کاربر ایجاد گذرکلید را تأیید کرد، فراخوانی ایجاد گذرکلید حل‌وفصل می‌شود و اطلاعات اعتباری PublicKeyCredential را برمی‌گرداند.
  • اعتبارنامه را تأیید و آن را در سرور ذخیره می‌کند.

بخش‌های زیر جزئیات هر مرحله را شرح می‌دهند.

ایجاد گزینه‌های ساختن اطلاعات کاربری

اولین گامی که باید در سرور بردارید ایجاد شیء PublicKeyCredentialCreationOptions است.

برای انجام این کار، به کتابخانه سمت سرور FIDO خود تکیه کنید. این کتابخانه معمولاً تابع سودمندی ارائه می‌دهد که می‌تواند این گزینه‌ها را برای شما ایجاد کند. برای مثال، SimpleWebAuthn generateRegistrationOptions را ارائه می‌دهد.

PublicKeyCredentialCreationOptions باید شامل همه چیزهایی باشد که برای ایجاد گذرکلید لازم است: اطلاعات مربوط به کاربر، اطلاعات مربوط به RP، و پیکربندی برای ویژگی‌های اطلاعات اعتباری که ایجاد می‌کنید. پس‌از تعریف همه این موارد، آن‌ها را درصورت نیاز به تابع موجود در کتابخانه سمت سرور FIDO که مسئول ایجاد شیء PublicKeyCredentialCreationOptions است ارسال کنید.

برخی‌از فیلدهای PublicKeyCredentialCreationOptions می‌توانند ثابت باشند. سایر موارد باید به‌صورت پویا در سرور تعریف شوند:

  • rpId: برای پر کردن شناسه RP در سرور، از توابع یا متغیرهای سمت سرور استفاده کنید که نام میزبان برنامه وب شما را ارائه می‌دهند، مانند example.com.
  • user.name و user.displayName: برای پر کردن این فیلدها، از اطلاعات جلسه کاربر واردشده به سیستم (یا اطلاعات حساب کاربری جدید، اگر کاربر درحال ایجاد گذرکلید هنگام ثبت‌نام است) استفاده کنید. user.name معمولاً نشانی ایمیل است و برای «طرف تکیه‌کننده» منحصربه‌فرد است. user.displayName نامی کاربرپسند است. توجه داشته باشید که همه پلاتفرم‌ها از displayName استفاده نمی‌کنند.
  • ‫user.id: رشته‌ای تصادفی و یکتا که هنگام ایجاد حساب تولید می‌شود. این شناسه باید دائمی باشد، برخلاف نام کاربری که ممکن است قابل‌ویرایش باشد. شناسه کاربر حساب را شناسایی می‌کند، اما نباید حاوی هیچ‌گونه اطلاعات شناساننده شخصی (PII) باشد. احتمالاً ازقبل شناسه کاربری در سیستم خود دارید، اما درصورت نیاز، شناسه‌ای مخصوص گذرکلیدها ایجاد کنید تا عاری از هرگونه اطلاعات شناساننده شخصی باشد.
  • excludeCredentials: فهرستی از شناسه‌های اطلاعات اعتباری موجود برای جلوگیری از تکرار گذرکلید از ارائه‌دهنده گذرکلید. برای پر کردن این فیلد، اطلاعات کاربری موجود برای این کاربر را در پایگاه داده‌تان جستجو کنید. جزئیات را در جلوگیری از ایجاد گذرکلید جدید درصورت وجود گذرکلید مرور کنید.
  • challenge: برای ثبت اطلاعات کاربری، چالش مربوط نیست مگراینکه از گواهی استفاده کنید که تکنیک پیشرفته‌تری برای درستی‌سنجی هویت ارائه‌دهنده گذرکلید و داده‌هایی است که منتشر می‌کند. بااین‌حال، حتی اگر از گواهی استفاده نکنید، چالش همچنان فیلد الزامی است. دستورالعمل‌های ایجاد چالش امن برای اصالت‌سنجی در اصالت‌سنجی گذرکلید سمت سرور دردسترس است.

کدبندی و رمزگشایی

PublicKeyCredentialCreationOptions ارسال‌شده توسط سرور
PublicKeyCredentialCreationOptions ارسال‌شده توسط سرور. فیلدهای دودویی مانند challenge و user.id در سمت سرور به base64URL کدگذاری می‌شوند تا گزینه‌ها بتوانند به‌عنوان JSON ازطریق HTTPS ارائه شوند.

شیء استاندارد WebAuthn PublicKeyCredentialCreationOptions شامل فیلدهایی است که ArrayBuffer هستند و نمی‌توانند مستقیماً با JSON.stringify() سریال‌سازی شوند. برای ارسال این گزینه‌ها ازطریق HTTPS، فیلدهای دودویی باید به‌صورت رشته‌های base64URL کدگذاری شوند:

  • در سرور، کتابخانه سمت سرور FIDO شما (مانند SimpleWebAuthn) به‌طور خودکار یک شیء گزینه‌های قابل‌سریال‌سازی JSON (مانند PublicKeyCredentialCreationOptionsJSON) با فیلدهای کدگذاری‌شده Base64URL تولید می‌کند.
  • در سمت کارخواه، مرورگرهای نو از PublicKeyCredential.parseCreationOptionsFromJSON() برای تبدیل مستقیم گزینه‌های JSON به PublicKeyCredentialCreationOptions پشتیبانی می‌کنند. هنگام استفاده از کتابخانه‌های سمت کارخواه مانند @simplewebauthn/browser، توابعی مانند startRegistration({ optionsJSON: options }) این تبدیل را به‌طور خودکار انجام می‌دهند.

کد نمونه: ایجاد گزینه‌های ایجاد اعتبارنامه

ما در مثال‌هایمان از کتابخانه SimpleWebAuthn استفاده می‌کنیم. در اینجا، ایجاد گزینه‌های اطلاعات اعتباری کلید عمومی را به تابع generateRegistrationOptions آن واگذار می‌کنیم.

import {
  generateRegistrationOptions,
  verifyRegistrationResponse,
} from '@simplewebauthn/server';
import { isoBase64URL, isoUint8Array } from '@simplewebauthn/server/helpers';

router.post('/registerRequest', csrfCheck, sessionCheck, async (req, res) => {
  const { user } = res.locals;
  // Ensure you nest verification function calls in try/catch blocks.
  // If something fails, throw an error with a descriptive error message.
  // Return that message with an appropriate error code to the client.
  try {
    // `excludeCredentials` prevents users from re-registering existing
    // credentials for a given passkey provider
    const excludeCredentials = [];
    const credentials = Credentials.findByUserId(user.id);
    if (credentials.length > 0) {
      for (const cred of credentials) {
        excludeCredentials.push({
          id: cred.id,
          type: 'public-key',
          transports: cred.transports,
        });
      }
    }

    // Generate registration options for WebAuthn create
    const options = await generateRegistrationOptions({
      rpName: process.env.RP_NAME,
      rpID: process.env.HOSTNAME,
      userID: isoUint8Array.fromUTF8String(user.id),
      userName: user.username,
      userDisplayName: user.displayName || '',
      attestationType: 'none',
      excludeCredentials,
      authenticatorSelection: {
        authenticatorAttachment: 'platform',
        residentKey: 'required',
        userVerification: 'preferred',
      },
    });

    // Keep the challenge in the session
    req.session.challenge = options.challenge;

    return res.json(options);
  } catch (e) {
    console.error(e);
    return res.status(400).send({ error: e.message });
  }
});

ذخیره کردن کلید عمومی

PublicKeyCredentialCreationOptions ارسال‌شده توسط سرور
navigator.credentials.create شیء PublicKeyCredential را برمی‌گرداند.

وقتی navigator.credentials.create باموفقیت در کارخواه حل شود، یعنی گذرکلید باموفقیت ایجاد شده است. یک شیء PublicKeyCredential برگردانده می‌شود.

شیء PublicKeyCredential حاوی شیء AuthenticatorAttestationResponse است که نشان‌دهنده پاسخ ارائه‌دهنده گذرکلید به دستور مشتری برای ایجاد گذرکلید است. این پاسخ حاوی اطلاعاتی درباره اطلاعات اعتباری جدید است که شما به‌عنوان «طرف اتکاکننده» برای اصالت‌سنجی کاربر در آینده به آن نیاز دارید. درباره AuthenticatorAttestationResponse در پیوست: AuthenticatorAttestationResponse بیشتر بدانید.

شیء PublicKeyCredential را به سرور ارسال کنید. وقتی آن را دریافت کردید، درستی‌سنجی‌اش کنید.

این مرحله درستی‌سنجی را به کتابخانه سمت سرور FIDO خود واگذار کنید. معمولاً برای این منظور یک تابع سودمندی ارائه می‌دهد. برای مثال، SimpleWebAuthn verifyRegistrationResponse را ارائه می‌دهد. در پیوست: درستی‌سنجی پاسخ ثبت‌نام با آنچه در پشت صحنه اتفاق می‌افتد آشنا شوید.

پس‌از اینکه کتابخانه سمت سرور FIDO پاسخ را درستی‌سنجی کرد، قبل‌از ذخیره کردن اعتبارنامه در پایگاه داده‌تان، مطمئن شوید که شناسه اعتبارنامه در بین همه کاربران یکتا باشد.

درستی‌سنجی یکتایی شناسه اطلاعات کاربری

پایگاه داده‌تان را جستجو کنید تا مطمئن شوید شناسه اطلاعات اعتباری برگردانده‌شده (credential.id) قبلاً برای هیچ کاربری ثبت نشده باشد، همان‌طور که در مراحل ثبت WebAuthn الزامی است. کتابخانه‌های بی‌حالت سمت سرور FIDO به پایگاه داده شما دسترسی ندارند و نمی‌توانند وجود شناسه‌های تکراری اطلاعات اعتباری را بررسی کنند. اگر شناسه اطلاعات اعتباری ازقبل در جایی از پایگاه داده شما وجود دارد، درخواست ثبت‌نام را فوراً رد کنید.

اطلاعات اعتباری را در پایگاه داده‌تان ذخیره کنید

پس‌از درستی‌سنجی پاسخ ثبت و تأیید اینکه شناسه اطلاعات کاربری استفاده نشده است، اطلاعات کاربری را در پایگاه داده‌تان ذخیره کنید تا کاربر بتواند بعداً با گذرکلید منسوب به آن اطلاعات کاربری اصالت‌سنجی کند.

از جدول اختصاصی برای اطلاعات کاربری کلید عمومی مرتبط با گذرکلیدها استفاده کنید. کاربر فقط می‌تواند یک گذرواژه داشته باشد، اما می‌تواند چندین گذرکلید داشته باشد — برای مثال، یک گذرکلید همگام‌سازی‌شده ازطریق Apple iCloud Keychain و یک گذرکلید ازطریق «مدیر گذرواژه Google».

در اینجا نمونه‌ای از طرح‌واره‌ای که می‌توانید برای ذخیره اطلاعات اعتبارنامه استفاده کنید آورده شده است:

طرح پایگاه داده برای گذرکلیدها

  • جدول کاربران:
    • user_id: شناسه کاربر اصلی. شناسه دائمی، یکتا، و تصادفی برای کاربر. از این به‌عنوان کلید اصلی برای جدول کاربران استفاده کنید.
    • username. نام کاربری تعریف‌شده توسط کاربر، احتمالاً قابل‌ویرایش.
    • passkey_user_id: شناسه کاربر مختص گذرکلید و فاقد اطلاعات شناساننده شخصی که با user.id در گزینه‌های ثبت‌نام شما نشان داده می‌شود. وقتی کاربر بعداً تلاش می‌کند اصالت‌سنجی کند، اصالت‌سنج این passkey_user_id را در پاسخ اصالت‌سنجی خود در userHandle دردسترس قرار می‌دهد. توصیه می‌کنیم passkey_user_id را به‌عنوان کلید اصلی تنظیم نکنید. کلیدهای اصلی معمولاً در سیستم‌ها به اطلاعات شناساننده شخصی تبدیل می‌شوند، زیرا به‌طور گسترده استفاده می‌شوند.
  • جدول اعتبارنامه کلید عمومی:
    • id: شناسه اطلاعات اعتباری. از این به‌عنوان تنها کلید اصلی استفاده کنید (یا یک محدودیت سراسری UNIQUE را فقط روی id اعمال کنید) در جدول اعتبارنامه‌های کلید عمومی خود. از کلید یکتایی ترکیبی با passkey_user_id که به شناسه اطلاعات اعتباری یکسان در چندین حساب کاربری اجازه می‌دهد استفاده نکنید، و درج‌ها را به‌گونه‌ای پیکربندی کنید که درصورت تداخل یکتایی، به‌جای رونویسی یا حذف ردیف موجود، ناموفق شوند.
    • public_key: کلید عمومی اعتبارنامه.
    • ‫passkey_user_id: از این به‌عنوان کلید خارجی برای ایجاد پیوند با جدول کاربران استفاده کنید.
    • backed_up: اگر گذرکلید توسط ارائه‌دهنده گذرکلید همگام‌سازی شده باشد، پشتیبان‌گیری شده است. ذخیره کردن وضعیت پشتیبان‌گیری زمانی مفید است که بخواهید در آینده گذرواژه‌ها را برای کاربرانی که گذرکلید backed_up دارند حذف کنید. می‌توانید با بررسی پرچم BE در authenticatorData یا بااستفاده از ویژگی کتابخانه سمت سرور FIDO که معمولاً برای دسترسی آسان به این اطلاعات دردسترس است، بررسی کنید که آیا از گذرکلید پشتیبان‌گیری شده است یا نه. ذخیره کردن واجدشرایط بودن پشتیبان‌گیری می‌تواند برای رسیدگی به پرسش‌های احتمالی کاربر مفید باشد.
    • name: به‌صورت اختیاری، نام نمایشی برای اطلاعات اعتباری تا کاربران بتوانند نام‌های سفارشی به اطلاعات اعتباری بدهند.
    • transports: آرایه‌ای از انتقال‌ها. ذخیره کردن انتقال‌ها برای تجربه کاربری اصالت‌سنجی مفید است. وقتی انتقال‌ها دردسترس باشند، مرورگر می‌تواند مطابق با آن رفتار کند و میانای کاربری را نمایش دهد که با انتقالی که ارائه‌دهنده گذرکلید برای برقراری ارتباط با کارخواه‌ها استفاده می‌کند مطابقت داشته باشد—به‌ویژه برای موارد استفاده از اصالت‌سنجی مجدد که allowCredentials خالی نیست.

اطلاعات دیگری نیز می‌تواند برای اهداف تجربه کاربری مفید باشد، ازجمله مواردی مانند ارائه‌دهنده گذرکلید، زمان ایجاد اعتبارنامه، و زمان آخرین استفاده. در طراحی میانای کاربر گذرکلید بیشتر بخوانید.

کد نمونه: ذخیره کردن اطلاعات اعتباری

ما در مثال‌هایمان از کتابخانه SimpleWebAuthn استفاده می‌کنیم. در اینجا، درستی‌سنجی پاسخ ثبت‌نام را به تابع verifyRegistrationResponse آن واگذار می‌کنیم.

import { isoBase64URL } from '@simplewebauthn/server/helpers';


router.post('/registerResponse', csrfCheck, sessionCheck, async (req, res) => {
  const expectedChallenge = req.session.challenge;
  const expectedOrigin = getOrigin(req.get('User-Agent'));
  const expectedRPID = process.env.HOSTNAME;
  const response = req.body;
  // This sample code is for registering a passkey for an existing,
  // signed-in user

  // Ensure you nest verification function calls in try/catch blocks.
  // If something fails, throw an error with a descriptive error message.
  // Return that message with an appropriate error code to the client.
  try {
    // Verify the credential
    const { verified, registrationInfo } = await verifyRegistrationResponse({
      response,
      expectedChallenge,
      expectedOrigin,
      expectedRPID,
      requireUserVerification: false,
    });

    if (!verified) {
      throw new Error('Verification failed.');
    }

    const {
      aaguid,
      credential,
      credentialBackedUp
    } = registrationInfo;

    // Ensure the credential ID isn't already registered for any user.
    // Stateless libraries like SimpleWebAuthn don't check your database for
    // collisions.
    const existingCredential = await Credentials.findById(credential.id);
    if (existingCredential) {
      throw new Error('Credential ID is already registered.');
    }

    // Name the credential based on AAGUID
    const name =
      aaguid === undefined ||
      aaguid === '00000000-0000-0000-0000-000000000000' ?
        req.useragent?.platform : aaguids[aaguid]?.name;

    const base64PublicKey = isoBase64URL.fromBuffer(credential.publicKey);

    // Existing, signed-in user
    const { user } = res.locals;

    // Insert the new credential. Use an insert-only operation (never an
    // update or upsert) backed by a global unique constraint on `id` so
    // concurrent duplicate requests fail instead of overwriting a credential.
    await Credentials.create({
      id: credential.id,
      passkey_user_id: user.passkey_user_id,
      publicKey: base64PublicKey,
      name,
      aaguid,
      transports: credential.transports || response.response.transports,
      backed_up: credentialBackedUp,
      registered_at: new Date().getTime()
    });

    // Kill the challenge for this session
    delete req.session.challenge;

    return res.json(user);
  } catch (e) {
    delete req.session.challenge;

    console.error(e);
    return res.status(400).send({ error: e.message });
  }
});

ضمائم: AuthenticatorAttestationResponse

AuthenticatorAttestationResponse شامل دو شیء مهم است:

  • response.clientDataJSON نسخه JSON داده‌های کارخواه است که در وب، داده‌ها همان‌طور که توسط مرورگر دیده می‌شوند هستند. این پاسخ حاوی مبدأ RP، چالش، و androidPackageName است (اگر کلاینت برنامه Android باشد). به‌عنوان RP، خواندن clientDataJSON به شما امکان می‌دهد به اطلاعاتی که مرورگر در زمان درخواست create دیده است دسترسی پیدا کنید.
  • response.attestationObjectحاوی دو بخش اطلاعات است:
    • attestationStatement که مربوط نیست مگراینکه از گواهی استفاده کنید.
    • authenticatorData داده‌هایی است که ارائه‌دهنده گذرکلید می‌بیند. به‌عنوان «طرف معتمد»، خواندن authenticatorData به شما امکان می‌دهد به داده‌هایی که ارائه‌دهنده گذرکلید می‌بیند و در زمان درخواست create برگردانده می‌شود دسترسی داشته باشید.

authenticatorDataحاوی اطلاعات ضروری درباره اطلاعات کاربری کلید عمومی است که با گذرکلید جدیداً ایجادشده مرتبط است:

  • خود اطلاعات اعتباری کلید عمومی و شناسه اطلاعات اعتباری یکتا برای آن.
  • شناسه «طرف محدود» مرتبط با اطلاعات اعتباری.
  • پرچم‌هایی که وضعیت کاربر را هنگام ایجاد گذرکلید توصیف می‌کنند: اینکه آیا کاربر واقعاً حضور داشته است یا نه، و اینکه آیا کاربر با موفقیت درستی‌سنجی شده است یا نه (به بررسی عمیق userVerification مراجعه کنید).
  • AAGUID شناسه‌ای برای ارائه‌دهنده گذرکلید، مثل «مدیر گذرواژه Google»، است. براساس AAGUID، می‌توانید ارائه‌دهنده گذرکلید را شناسایی کنید و نام را در صفحه مدیریت گذرکلید نمایش دهید. (به تعیین ارائه‌دهنده گذرکلید با AAGUID مراجعه کنید)

اگرچه authenticatorData در attestationObject تودرتو شده است، اطلاعاتی که دربردارد برای پیاده‌سازی گذرکلید شما لازم است، چه از گواهی استفاده کنید چه نکنید. authenticatorData کدگذاری شده است و حاوی فیلدهایی است که در قالب دودویی کدگذاری شده‌اند. کتابخانه سمت سرور شما معمولاً تجزیه و رمزگشایی را انجام می‌دهد. اگر از کتابخانه سمت سرور استفاده نمی‌کنید، از getAuthenticatorData() سمت کارخواه استفاده کنید تا در تجزیه و رمزگشایی سمت سرور صرفه‌جویی کنید.

پیوست: درستی‌سنجی پاسخ ثبت‌نام

در پشت صحنه، درستی‌سنجی پاسخ ثبت شامل بررسی‌های زیر است:

  • مطمئن شوید شناسه RP با سایتتان مطابقت داشته باشد.
  • مطمئن شوید که مبدأ درخواست، مبدأ موردانتظار برای سایت شما (نشانی وب سایت اصلی، برنامه Android) باشد.
  • اگر به درستی‌سنجی کاربر نیاز دارید، مطمئن شوید که پرچم درستی‌سنجی کاربر authenticatorData.uv روی true تنظیم شده باشد.
  • پرچم حضور کاربر authenticatorData.up معمولاً باید true باشد، اما اگر اعتبارنامه به‌صورت مشروط ایجاد شده باشد، باید false باشد.
  • بررسی کنید که کارخواه توانسته باشد چالشی را که به آن داده‌اید ارائه دهد. اگر از گواهی استفاده نمی‌کنید، این بررسی اهمیتی ندارد. بااین‌حال، پیاده‌سازی این بررسی روال مطلوبی است: این کار تضمین می‌کند که اگر در آینده تصمیم به استفاده از گواهی بگیرید، کد شما آماده است.
  • مطمئن شوید که شناسه اطلاعات کاربری هنوز برای هیچ کاربری ثبت نشده باشد. بدون حالت کتابخانه‌های سمت سرور FIDO به پایگاه داده شما دسترسی ندارند، بنابراین باید این بررسی را در سرور خود پیاده‌سازی کنید و موارد تکراری را رد کنید، نه اینکه اعتبارنامه‌های موجود را رونویسی، اضافه، یا حذف کنید. در درستی‌سنجی یکتایی شناسه اطلاعات کاربری بیشتر بدانید.
  • تأیید کنید که الگوریتم مورداستفاده ارائه‌دهنده گذرکلید برای ایجاد اطلاعات کاربری، الگوریتمی است که شما فهرست کرده‌اید (در هر فیلد alg از publicKeyCredentialCreationOptions.pubKeyCredParams، که معمولاً در کتابخانه سمت سرور شما تعریف شده است و برای شما قابل‌مشاهده نیست). این کار تضمین می‌کند که کاربران فقط می‌توانند با الگوریتم‌هایی که شما اجازه داده‌اید ثبت‌نام کنند.

برای کسب اطلاعات بیشتر، کد منبع SimpleWebAuthn برای verifyRegistrationResponse را بررسی کنید یا فهرست کامل درستی‌سنجی‌ها را در مشخصات بررسی کنید.

بعدی

اصالت‌سنجی گذرکلید سمت سرور