تسجيل مفتاح المرور من جهة الخادم

نظرة عامة

في ما يلي نظرة عامة على الخطوات الرئيسية لتسجيل مفتاح المرور:

مسار تسجيل مفتاح المرور

  • حدِّد خيارات إنشاء مفتاح مرور. أرسِلها إلى العميل لتتمكّن من تمريرها إلى طلب إنشاء مفتاح المرور: طلب بيانات من واجهة برمجة التطبيقات WebAuthn ‏navigator.credentials.create على الويب، وcredentialManager.createCredential على Android. بعد أن يؤكّد المستخدم إنشاء مفتاح المرور، يتم حلّ طلب إنشاء مفتاح المرور وعرض بيانات الاعتماد PublicKeyCredential.
  • التحقّق من بيانات الاعتماد وتخزينها على الخادم

تتناول الأقسام التالية تفاصيل كل خطوة.

إنشاء خيارات إنشاء بيانات الاعتماد

الخطوة الأولى التي عليك اتّخاذها على الخادم هي إنشاء عنصر PublicKeyCredentialCreationOptions.

لإجراء ذلك، يمكنك الاعتماد على مكتبة FIDO من جهة الخادم. وستوفّر عادةً دالة خدمية يمكنها إنشاء هذه الخيارات لك. على سبيل المثال، توفّر SimpleWebAuthn الدالة generateRegistrationOptions.

يجب أن يتضمّن PublicKeyCredentialCreationOptions كل ما يلزم لإنشاء مفتاح المرور: معلومات عن المستخدم وعن الجهة الموثوقة وإعدادات لخصائص بيانات الاعتماد التي يتم إنشاؤها. بعد تحديد كل هذه العناصر، مرِّرها حسب الحاجة إلى الدالة في مكتبة جهة خادم FIDO المسؤولة عن إنشاء عنصر PublicKeyCredentialCreationOptions.

يمكن أن تكون بعض حقول PublicKeyCredentialCreationOptions ثوابت. يجب تحديد العناصر الأخرى ديناميكيًا على الخادم:

  • rpId: لتعبئة معرّف الطرف المعتمِد على الخادم، استخدِم الدوال أو المتغيّرات من جهة الخادم التي تمنحك اسم مضيف تطبيق الويب، مثل example.com.
  • ‫user.name وuser.displayName: لملء هذين الحقلَين، استخدِم معلومات جلسة المستخدم الذي سجّل الدخول (أو معلومات حساب المستخدم الجديد، إذا كان المستخدم ينشئ مفتاح مرور عند الاشتراك). يكون user.name عادةً عنوان بريد إلكتروني، وهو فريد للجهة المعتمِدة. ‫"user.displayName" هو اسم سهل الاستخدام. يُرجى العِلم أنّ بعض المنصات لن تستخدم displayName.
  • ‫user.id: سلسلة عشوائية فريدة يتم إنشاؤها عند إنشاء الحساب. ويجب أن يكون دائمًا، على عكس اسم المستخدم الذي قد يكون قابلاً للتعديل. يحدّد رقم تعريف المستخدم حسابًا، ولكن يجب ألا يحتوي على أي معلومات تكشف الهوية الشخصية. من المحتمل أن يكون لديك رقم تعريف مستخدم في نظامك، ولكن إذا لزم الأمر، يمكنك إنشاء رقم تعريف خاص بمفاتيح المرور لإبقائه خاليًا من أي معلومات تكشف الهوية الشخصية.
  • excludeCredentials: قائمة بمعرّفات بيانات الاعتماد الحالية لمنع تكرار مفتاح مرور من مقدّم مفاتيح المرور. لتعبئة هذا الحقل، ابحث في قاعدة بياناتك عن بيانات الاعتماد الحالية لهذا المستخدم. يمكنك مراجعة التفاصيل في مقالة منع إنشاء مفتاح مرور جديد إذا كان هناك مفتاح مرور حالي.
  • challenge: بالنسبة إلى تسجيل بيانات الاعتماد، لا يكون التحدي ذا صلة إلا إذا كنت تستخدم المصادقة، وهي تقنية أكثر تقدّمًا لإثبات هوية مزوّد مفتاح المرور والبيانات التي يصدرها. ومع ذلك، حتى إذا لم تستخدم المصادقة، يظلّ التحدي حقلاً مطلوبًا. تتوفّر تعليمات إنشاء تحدٍّ آمن للمصادقة في مقالة المصادقة باستخدام مفتاح المرور من جهة الخادم.

الترميز وفك الترميز

‫PublicKeyCredentialCreationOptions التي أرسلها الخادم
PublicKeyCredentialCreationOptions أرسلها الخادم. يتم ترميز الحقول الثنائية، مثل challenge وuser.id، من جهة الخادم إلى base64URL لكي يتم تسليم الخيارات بتنسيق JSON عبر بروتوكول HTTPS.

يتضمّن عنصر PublicKeyCredentialCreationOptions العادي في WebAuthn حقولاً من نوع 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 من بيانات العميل، وهي البيانات التي تظهر للمتصفّح على الويب. ويحتوي على مصدر الجهة المعتمدة والرمز المميّز وandroidPackageName إذا كان العميل تطبيق Android. بصفتك جهة معتمدة، تتيح لك قراءة clientDataJSON الوصول إلى المعلومات التي رآها المتصفّح في وقت طلب create.
  • response.attestationObjectيحتوي على معلومتَين:
    • ‫attestationStatement، وهي غير ذات صلة ما لم تستخدم المصادقة.
    • ‫authenticatorData هي البيانات التي يراها مزوّد مفتاح المرور. بصفتك جهة مستندة، تتيح لك قراءة authenticatorData الوصول إلى البيانات التي يراها موفّر مفتاح المرور والتي يتم عرضها في وقت طلب create.

authenticatorDataيحتوي على معلومات أساسية حول بيانات اعتماد المفتاح العام المرتبطة بمفتاح المرور الذي تم إنشاؤه حديثًا:

على الرغم من أنّ authenticatorData متداخلة ضمن attestationObject، فإنّ المعلومات التي تحتوي عليها مطلوبة لتنفيذ مفتاح المرور سواء كنت تستخدم المصادقة أم لا. يتم ترميز authenticatorData، وتحتوي على حقول مرمّزة بتنسيق ثنائي. ستتولّى عادةً المكتبة من جهة الخادم معالجة التحليل وفك الترميز. إذا لم تكن تستخدم مكتبة من جهة الخادم، ننصحك بالاستفادة من getAuthenticatorData() من جهة العميل لتوفير بعض أعمال التحليل وفك الترميز من جهة الخادم.

الملحق: التحقّق من استجابة التسجيل

في الخلفية، يتألف التحقّق من استجابة التسجيل من عمليات التحقّق التالية:

  • تأكَّد من أنّ معرّف الجهة المعتمدة يتطابق مع موقعك الإلكتروني.
  • تأكَّد من أنّ مصدر الطلب هو مصدر متوقّع لموقعك الإلكتروني (عنوان URL للموقع الإلكتروني الرئيسي أو تطبيق Android).
  • إذا كنت تطلب التحقّق من المستخدم، تأكَّد من أنّ علامة التحقّق من المستخدم authenticatorData.uv هي true.
  • من المتوقّع عادةً أن تكون قيمة علامة حضور المستخدم authenticatorData.up هي true، ولكن إذا تم إنشاء بيانات الاعتماد بشكل مشروط، من المتوقّع أن تكون القيمة false.
  • يُرجى التحقّق من أنّ العميل تمكّن من تقديم التحدي الذي منحته إياه. إذا لم تستخدم المصادقة، لن يكون هذا الفحص مهمًا. ومع ذلك، يُعدّ تنفيذ هذا الإجراء من أفضل الممارسات، فهو يضمن أنّ الرمز البرمجي جاهز في حال قررت استخدام المصادقة في المستقبل.
  • تأكَّد من أنّ معرّف بيانات الاعتماد لم يتم تسجيله بعد لأي مستخدم. لا يمكن لمكتبات FIDO من جهة الخادم عديمة الحالة الوصول إلى قاعدة بياناتك، لذا عليك تنفيذ عملية التحقّق هذه على الخادم ورفض النُسخ المكرّرة بدلاً من استبدال بيانات الاعتماد الحالية أو إلحاقها أو حذفها. يمكنك الاطّلاع على مزيد من المعلومات في مقالة التحقّق من تفرّد معرّف بيانات الاعتماد.
  • تأكَّد من أنّ الخوارزمية التي يستخدمها موفّر مفتاح المرور لإنشاء بيانات الاعتماد هي خوارزمية أدرجتها (في كل حقل alg من publicKeyCredentialCreationOptions.pubKeyCredParams، والذي يتم تحديده عادةً ضمن مكتبة جهة الخادم ولا يظهر لك). يضمن ذلك أنّه لا يمكن للمستخدمين التسجيل إلا باستخدام الخوارزميات التي اخترت السماح بها.

لمزيد من المعلومات، يمكنك الاطّلاع على الرمز المصدر لـ verifyRegistrationResponse في SimpleWebAuthn أو الاطّلاع على القائمة الكاملة لعمليات التحقّق في المواصفات.

التالي

المصادقة باستخدام مفتاح المرور من جهة الخادم