חדש: רמזים, בקשות מקור קשורות וסריאליזציה של JSON ל-WebAuthn ב-Chrome

גרסאות 128 ו-129 של Chrome עם תכונות חדשות ומלהיבות עבור WebAuthn שבבסיס ה-API לפיתוח מערכות אימות שמבוססות על מפתחות גישה.

Eiji Kitamura

• רמזים: רמזים מעניקים לצדדים נסמך (RP) שליטה טובה יותר ב-WebAuthn ממשק המשתמש בדפדפן. הם שימושיים במיוחד למשתמשים ארגוניים שרוצים כדי להשתמש במפתחות אבטחה.
• בקשות מקור קשורות: עם מקור קשור גורמים מוגבלים יכולים להגדיר מפתחות גישה תקפים בכמה דומיינים. אם יש בבעלותך כמה עכשיו אפשר לאפשר למשתמשים לעשות שימוש חוזר במפתח הגישה שלהם בכל האתרים בלי חיכוך על ההתחברות.
• סריאליזציה ל-JSON: ממשקי API ליצירת סריאליזציה ל-JSON מאפשרים לכם לפשט את הקוד הקדמי של ה-RP באמצעות אפשרויות קידוד ופענוח פרטי כניסה שמועברים אל WebAuthn API וממנו.

רמזים

בעזרת hints, גורמים מהימנים (RP) יכולים עכשיו לציין העדפות בממשק המשתמש ליצירת מפתח גישה או אימות באמצעות מפתח גישה.

בעבר, כשהגורם המוגבל (RP) רצה להגביל את המאמת שמותר למשתמש להשתמש בו ליצור מפתח גישה או לבצע אימות באמצעותו, הם יוכלו להשתמש authenticatorSelection.authenticatorAttachment כדי לציין "platform" או "cross-platform". הם מגבילים בהתאמה את מאמת החשבונות לפלטפורמה מאמת חשבונות או נדידה לאימות חשבונות. עם hints, המפרט הזה יכול להיות גמיש יותר.

הגורם המוגבל (RP) יכול להשתמש במאפיין hints האופציונלי בPublicKeyCredentialCreationOptions או PublicKeyCredentialRequestOptions כדי לציין "security-key", "client-device" ו-"hybrid" בסדר העדפה במערך.

הדוגמה הבאה היא בקשה ליצירת פרטי כניסה מועדפת "cross-platform" מאמתי נתונים עם "security-key" כרמז. זה אומר Chrome להצגת ממשק משתמש שמתמקד במפתח אבטחה למשתמשים בגרסה הארגונית.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: *****,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

כשגורם מוגבל (RP) רוצה לתת עדיפות לתרחיש של אימות בין מכשירים, הוא יכול שליחת בקשת אימות עם העדפה ל-"cross-platform" מאמתי עם "hybrid" כרמז.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: *****,
    residentKey: true,
    hints: ['hybrid']
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

בקשות מקור קשורות

עם מקור קשור בקשות, הגורמים המוגבלים יכולים לאפשר שימוש במפתחות גישה מכמה דומיינים. בניית התחברות מרוכזת השימוש בפרוטוקולים של איחוד עדיין הוא הפתרון המומלץ ברוב האתרים. אבל אם יש לכם כמה דומיינים והאיחוד לא אפשרי, מקורות קשורים עשויים להיות פתרון.

כל בקשות לאימות אינטרנט חייבות לציין מזהה של גורם נסמך (מזהה RP) ואת כל מפתחות הגישה משויכים למזהה גורם מוגבל (RP) אחד. בדרך כלל, מקור יכול לציין רק מזהה RP שמבוסס על הדומיין שלו, כך שבמקרה הזה www.example.co.uk יכול לציין מזהה הגורם המוגבל (RP) של example.co.uk, אבל לא של example.com. עם מקור קשור בקשות, אפשר לאמת מזהה גורם מוגבל (RP) שנתבעה עליו בעלות על ידי אחזור קובץ JSON ידוע נמצא ב-/.well-known/webauthn מדומיין היעד. כך example.co.uk (וגם example.in, example.de וכן הלאה) יכולים להשתמש במזהה גורם מוגבל (RP) של example.com אם example.com מציין אותם בפורמט הבא:

כתובת אתר: https://example.com/.well-known/webauthn

{
  "origins": [
    "https://example.co.uk",
    "https://example.de",
    "https://example.sg",
    "https://example.net",
    "https://exampledelivery.com",
    "https://exampledelivery.co.uk",
    "https://exampledelivery.de",
    "https://exampledelivery.sg",
    "https://myexamplerewards.com",
    "https://examplecars.com"
  ]
}

מידע נוסף על הגדרת בקשות מקור קשורות זמין במאמר איך לאפשר שימוש חוזר במפתחות גישה בכל המכשירים אתרים עם מקור קשור בקשות.

סריאליזציה ל-JSON

לאובייקטים של בקשה ותגובה של WebAuthn יש כמה שדות שמכילים נתוני RAW נתונים בינאריים ב-ArrayBuffer, כמו מזהה פרטי הכניסה, מזהה המשתמש או האתגר. אם אתר רוצה להשתמש ב-JSON כדי להחליף את הנתונים האלה עם השרת שלו, הקובץ הבינארי הנתונים צריכים להיות מקודדים תחילה, לדוגמה באמצעות Base64URL. הוספה של למפתחים שרוצים להתחיל להשתמש במפתחות גישה באתרים שלהם.

WebAuthn מציעה עכשיו ממשקי API לניתוח PublicKeyCredentialCreationOptions וגם PublicKeyCredentialRequestOptions אובייקטים של בקשת WebAuthn ישירות מ-JSON ועושים סריאליזציה PublicKeyCredential את התשובה ישירות ל-JSON. כל השדות בעלי ערך של ArrayBuffer ששומרים נתונים בינאריים גולמיים הנתונים מומרים באופן אוטומטי מהערכים שלהם בקידוד Base64URL או אליהם. ממשקי ה-API האלה זמינים ב-Chrome מגרסה 129.

לפני שיוצרים מפתח גישה, צריך לאחזר קוד JSON אובייקט PublicKeyCredentialCreationOptions מהשרת ולפענח אותו באמצעות PublicKeyCredential.parseCreationOptionsFromJSON().

export async function registerCredential() {

  // Fetch encoded `PublicKeyCredentialCreationOptions`
  // and JSON decode it.
  const options = await fetch('/auth/registerRequest').json();

  // Decode `PublicKeyCredentialCreationOptions` JSON object
  const decodedOptions = PublicKeyCredential.parseCreationOptionsFromJSON(options);  

  // Invoke the WebAuthn create() function.
  const cred = await navigator.credentials.create({
    publicKey: decodedOptions,
  });
  ...

אחרי שיוצרים מפתח גישה, מקודדים את פרטי הכניסה שמתקבלים באמצעות toJSON(). שאפשר לשלוח אותו לשרת.

  ...
  const cred = await navigator.credentials.create({
    publicKey: options,
  });

  // Encode the credential to JSON and stringify
  const credential = JSON.stringify(cred.toJSON());

  // Send the encoded credential to the server
  await fetch('/auth/registerResponse', credential);
  ...

לפני אימות באמצעות מפתח גישה, צריך לאחזר קוד JSON מקודד PublicKeyRequestCreationOptions מהשרת ולפענח אותו באמצעות PublicKeyCredential.parseRequestOptionsFromJSON().

export async function authenticate() {

  // Fetch encoded `PublicKeyCredentialRequestOptions`
  // and JSON decode it.
  const options = await fetch('/auth/signinRequest').json();

  // Decode `PublicKeyCredentialRequestOptions` JSON object
  const decodedOptions = PublicKeyCredential.parseRequestOptionsFromJSON(options);

  // Invoke the WebAuthn get() function.
  const cred = await navigator.credentials.get({
    publicKey: options
  });
  ...

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

  ...
  const cred = await navigator.credentials.get({
    publicKey: options
  });

  // Encode the credential to JSON and stringify
  const credential = JSON.stringify(cred.toJSON());

  // Send the encoded credential to the server
  await fetch(`/auth/signinResponse`, credential);
  ...

מידע נוסף

למידע נוסף על WebAuthn ועל מפתחות גישה, אפשר לעיין במקורות המידע הבאים:

• מפתחות גישה | Chrome למפתחים
• מבוא למפתח גישה בצד השרת הטמעה
• passkeys.dev