רישום של מפתח גישה בצד השרת

סקירה כללית

הנה סקירה כללית של השלבים העיקריים ברישום מפתח גישה:

תהליך הרישום של מפתח הגישה

  • להגדיר אפשרויות ליצירת מפתח גישה. שולחים אותם ללקוח, כדי שתוכלו להעביר אותם לקריאה ליצירת מפתח הגישה: הקריאה ל-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 הוא בדרך כלל כתובת אימייל, והוא ייחודי ל-RP. ‫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, שמייצג את התגובה של ספק מפתח הגישה להוראה של הלקוח ליצור מפתח גישה. הוא מכיל מידע על פרטי הכניסה החדשים שאתם צריכים כ-RP כדי לאמת את המשתמש בהמשך. מידע נוסף על AuthenticatorAttestationResponse זמין בנספח: AuthenticatorAttestationResponse.

שולחים את האובייקט PublicKeyCredential לשרת. אחרי שמקבלים את הקוד, מאמתים אותו.

מעבירים את שלב האימות הזה לספרייה בצד השרת של FIDO. בדרך כלל, תהיה פונקציה בסיסית למטרה הזו. לדוגמה, SimpleWebAuthn מציעה verifyRegistrationResponse. בנספח: אימות התגובה לרישום מוסבר מה קורה מאחורי הקלעים.

אחרי שספריית ה-FIDO בצד השרת מאמתת את התגובה, צריך לוודא שמזהה פרטי הכניסה הוא ייחודי לכל המשתמשים לפני ששומרים את פרטי הכניסה במסד הנתונים.

אימות הייחודיות של מזהה פרטי הכניסה

שולחים שאילתה למסד הנתונים כדי לוודא שמזהה פרטי הכניסה שהוחזר (credential.id) לא רשום כבר לאף משתמש, כפי שנדרש בשלבי הרישום של WebAuthn. לספריות ללא שמירת מצב בצד השרת של FIDO אין גישה למסד הנתונים שלכם, והן לא יכולות לבדוק אם יש מזהי פרטי כניסה כפולים. אם מזהה פרטי הכניסה כבר קיים במקום כלשהו במסד הנתונים, צריך לדחות את בקשת הרישום באופן מיידי.

שמירת פרטי הכניסה במסד הנתונים

אחרי שמאמתים את התגובה לרישום ומוודאים שמזהה פרטי הכניסה לא בשימוש, שומרים את פרטי הכניסה במסד הנתונים כדי שהמשתמש יוכל לאמת את הזהות שלו מאוחר יותר באמצעות מפתח הגישה שמשויך לפרטי הכניסה האלה.

משתמשים בטבלה ייעודית לפרטי כניסה של מפתחות ציבוריים שמשויכים למפתחות גישה. למשתמש יכולה להיות רק סיסמה אחת, אבל יכולים להיות לו כמה מפתחות גישה – לדוגמה, מפתח גישה שמסונכרן דרך צרור המפתחות של Apple iCloud ומפתח גישה שמסונכרן דרך מנהל הסיסמאות של Google.

הנה סכימה לדוגמה שאפשר להשתמש בה כדי לאחסן פרטי כניסה:

סכימת מסד נתונים למפתחות גישה

  • הטבלה Users:
    • ‫user_id: מזהה המשתמש הראשי. מזהה אקראי, ייחודי וקבוע של המשתמש. אפשר להשתמש בזה כמפתח ראשי בטבלה Users.
    • ‫username. שם משתמש שהוגדר על ידי המשתמש, ואולי אפשר לערוך אותו.
    • ‫passkey_user_id: מזהה המשתמש הספציפי למפתח הגישה, ללא פרטים אישיים מזהים, שמיוצג על ידי user.id באפשרויות הרישום. כשהמשתמש ינסה לבצע אימות בהמשך, המאמת יהפוך את passkey_user_id לזמין בתגובת האימות שלו ב-userHandle. מומלץ לא להגדיר את passkey_user_id כמפתח ראשי. מפתחות ראשיים נוטים להפוך לפרטים אישיים מזהים בפועל במערכות, כי משתמשים בהם הרבה.
  • הטבלה Public key credentials:
    • ‫id: מזהה פרטי הכניסה. השתמשו בזה כמפתח הראשי היחיד (או אכפו אילוץ UNIQUE גלובלי על id בלבד) בטבלת פרטי כניסה של מפתח ציבורי. אל תשתמשו במפתח ייחודיות מורכב עם passkey_user_id שיאפשר את אותו מזהה פרטי כניסה בכמה חשבונות משתמשים, והגדירו שהוספות ייכשלו במקום להחליף או למחוק שורה קיימת במקרה של התנגשות ייחודיות.
    • ‫public_key: המפתח הציבורי של פרטי הכניסה.
    • ‫passkey_user_id: משמש כמפתח זר כדי ליצור קישור לטבלה Users.
    • ‫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 הם נתונים כפי שהם מוצגים על ידי ספק מפתח הגישה. כ-RP, קריאת authenticatorData נותנת לך גישה לנתונים שספק מפתח הגישה רואה ומוחזרים בזמן הבקשה של create.

‫authenticatorData מכיל מידע חיוני על פרטי הכניסה של המפתח הציבורי שמשויך למפתח הגישה החדש שנוצר:

  • פרטי הכניסה של המפתח הציבורי עצמו, ומזהה ייחודי של פרטי הכניסה.
  • מזהה הגורם המוגבל (RP) שמשויך לפרטי הכניסה.
  • דגלים שמתארים את סטטוס המשתמש כשהמפתח הגישה נוצר: אם המשתמש באמת היה נוכח, ואם המשתמש אומת בהצלחה (ראו מידע מעמיק על userVerification).
  • ‫AAGUID הוא מזהה של ספק מפתחות הגישה, כמו מנהל הסיסמאות של Google. על סמך ה-AAGUID, אתם יכולים לזהות את ספק מפתח הגישה ולהציג את השם בדף ניהול מפתחות הגישה. (ראו זיהוי ספק מפתח הגישה באמצעות AAGUID)

למרות ש-authenticatorData מקונן בתוך attestationObject, המידע שהוא מכיל נדרש להטמעה של מפתח הגישה, בין אם אתם משתמשים באימות ובין אם לא. authenticatorData מקודד ומכיל שדות שמקודדים בפורמט בינארי. בדרך כלל, הספרייה בצד השרת תטפל בניתוח ובפענוח. אם אתם לא משתמשים בספרייה בצד השרת, כדאי להשתמש ב-getAuthenticatorData() בצד הלקוח כדי לחסוך חלק מעבודת הניתוח והפענוח בצד השרת.

נספח: אימות התגובה לרישום

מאחורי הקלעים, אימות התגובה לרישום כולל את הבדיקות הבאות:

  • מוודאים שמזהה ה-RP תואם לאתר.
  • מוודאים שמקור הבקשה הוא מקור צפוי לאתר (כתובת ה-URL של האתר הראשי, אפליקציה ל-Android).
  • אם אתם דורשים אימות משתמש, ודאו שדגל אימות המשתמש authenticatorData.uv הוא true.
  • הערך של דגל נוכחות המשתמש authenticatorData.up אמור להיות בדרך כלל true, אבל אם פרטי הכניסה נוצרו באופן מותנה, הערך אמור להיות false.
  • צריך לוודא שהלקוח הצליח לספק את האתגר שנתת לו. אם אתם לא משתמשים באימות, הבדיקה הזו לא חשובה. עם זאת, מומלץ להטמיע את הבדיקה הזו כדי לוודא שהקוד מוכן למקרה שתחליטו להשתמש באימות בעתיד.
  • מוודאים שמזהה פרטי הכניסה עדיין לא רשום לאף משתמש. ספריות בלי שמירת מצב בצד השרת של FIDO לא יכולות לגשת למסד הנתונים שלכם, לכן אתם צריכים להטמיע את הבדיקה הזו בשרת שלכם ולדחות כפילויות במקום להחליף, להוסיף או למחוק פרטי כניסה קיימים. איך מוודאים שמזהה פרטי הכניסה הוא ייחודי
  • מוודאים שהאלגוריתם שבו ספק מפתחות הגישה משתמש כדי ליצור את פרטי הכניסה הוא אלגוריתם שציינתם (בכל שדה alg של publicKeyCredentialCreationOptions.pubKeyCredParams, שבדרך כלל מוגדר בספרייה בצד השרת ולא גלוי לכם). כך אפשר לוודא שהמשתמשים יכולים להירשם רק באמצעות אלגוריתמים שבחרתם לאשר.

כדי לקבל מידע נוסף, אפשר לעיין בקוד המקור של SimpleWebAuthn עבור verifyRegistrationResponse או לעיין ברשימה המלאה של האימותים במפרט.

הבאים בתור

אימות מפתח גישה בצד השרת