הנפקת Digital Credentials API ב-Chrome 155

Natalia Markoborodova

תאריך פרסום: 23 באוקטובר 2026

בגרסה 155 של Chrome ואילך, הנפקת Digital Credentials API מופעלת כברירת מחדל, כך שכבר לא צריך אסימון של גרסת מקור לניסיון או דגל כדי להשתמש בה. ‫Digital Credentials API הוא שכבת תעבורה שמאפשרת לאתרים להתחבר לאפליקציות של ארנקים שמותקנות במכשיר הנייד של המשתמש. הנפקה מאפשרת למנפיקים להוסיף מסמכי אימות חדשים (כמו תעודות מזהות דיגיטליות) ישירות לאפליקציית הארנק של המשתמש.

רקע

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

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

איך פועלת הנפקת אישורים דיגיטליים

כדי לייעל את התהליך הזה, Chrome תומך בהנפקה באמצעות W3C Digital Credentials API. התכונה הזו מתווספת ליכולות ההצגה (שיתוף נתונים ספציפיים מבוקשים מתעודה דיגיטלית עם גורם מאמת), שהושקו ב-Chrome 141. כשאתר של מנפיק קורא ל-navigator.credentials.create() עם איבר digital שמכיל בקשת הנפקה, Chrome מעביר את הבקשה למערכת ההפעלה (ב-Android, ל-Credential Manager). מערכת ההפעלה מציגה ממשק משלה שבו המשתמש בוחר אפליקציית ארנק. ה-API פועל עם פרוטוקולים סטנדרטיים בתחום, כמו OpenID להנפקת פרטי כניסה ניתנים לאימות (OpenID4VCI). ההנפקה תומכת בשני תהליכים: תהליך באותו מכשיר ב-Android, ותהליך במכשירים שונים שמתחיל במחשב ומסתיים במכשיר Android.

תהליך באותו מכשיר ב-Android

ב-Android, דפדפן Chrome מעביר את בקשת ההנפקה אל Credential Manager של Android, שמציג רשימה של אפליקציות ארנק תואמות במכשיר. המשתמש בוחר ארנק ומאשר את הוספת התעודה. לאחר מכן, אפליקציית הארנק מקבלת את פרטי הכניסה מהמנפיק באמצעות פרוטוקול ההנפקה, כמו OpenID4VCI.

תהליך במכשירים שונים במחשב

במחשב, Chrome מציג קוד QR. המשתמש סורק את הקוד באמצעות מכשיר Android ומשלים את התהליך במכשיר הזה, כמו שמתואר בקטע הקודם. המכשירים משתמשים ב-Bluetooth כדי לוודא שהם קרובים זה לזה, ולכן Chrome מבקש מהמשתמש להפעיל את ה-Bluetooth אם הוא כבוי. Chrome משתמש באותו מנגנון חוצה-מכשירים להצגת Digital Credentials API.

הטמעת הנפקה באמצעות ה-API

כדי להתחיל את תהליך ההנפקה, צריך להפעיל את navigator.credentials.create() ולהעביר את בקשות ההנפקה בתוך איבר digital. צריך לבצע את הקריאה הזו מ-click handler או מ-handler של תנועה של המשתמש אחר, כי הקריאה דורשת הפעלה זמנית של המשתמש. בדוגמה הבאה נעשה שימוש בהצעת פרטי כניסה של OpenID4VCI עם תהליך קוד מורשה מראש:

// Call this function from a user gesture handler, for example, a button's
// click handler. The pre-authorized code is a short-lived, single-use code
// that your server generates for the signed-in user.
async function issueDigitalCredential(preAuthorizedCode) {
  // Check for Digital Credentials API and protocol support.
  if (!window.DigitalCredential ||
      !DigitalCredential.userAgentAllowsProtocol('openid4vci-v1')) {
    // Provide an alternative issuance method.
    showAlternativeIssuanceFlow();
    return;
  }

  // Construct a credential offer according to the OpenID4VCI
  // specification. This example uses the format that the
  // demo CMWallet supports.
  const credentialOffer = {
    credential_issuer: 'https://issuer.example',
    credential_configuration_ids: ['org.iso.18013.5.1.mDL'],
    grants: {
      'urn:ietf:params:oauth:grant-type:pre-authorized_code': {
        'pre-authorized_code': preAuthorizedCode
      }
    },
    // Metadata that the wallet uses to request and display the credential.
    credential_issuer_metadata: {
      credential_issuer: 'https://issuer.example',
      credential_endpoint: 'https://issuer.example/openid4vci/credential',
      nonce_endpoint: 'https://issuer.example/openid4vci/nonce',
      credential_configurations_supported: {
        'org.iso.18013.5.1.mDL': {
          format: 'mso_mdoc',
          doctype: 'org.iso.18013.5.1.mDL',
          // Bind the credential to a key that the wallet generates.
          cryptographic_binding_methods_supported: ['cose_key'],
          proof_types_supported: {
            jwt: { proof_signing_alg_values_supported: ['ES256'] }
          },
          credential_metadata: {
            display: [{ name: 'Mobile driving license', locale: 'en-US' }],
            // The claims that this credential contains. For a full list of
            // standard mDL claims, see the ISO/IEC 18013-5 specification.
            claims: [{
              path: ['org.iso.18013.5.1', 'family_name'],
              display: [{ name: 'Family name', locale: 'en-US' }]
            }
            // ... Add any other claims for your credential here.
            ]
          }
        }
      }
    },
    // Metadata of the authorization server that issues access tokens.
    authorization_server_metadata: {
      issuer: 'https://issuer.example',
      token_endpoint: 'https://issuer.example/openid4vci/token'
    }
  };

  try {
    const credential = await navigator.credentials.create({
      digital: {
        requests: [{
          // The protocol identifier for OpenID4VCI 1.0.
          protocol: 'openid4vci-v1',
          // Pass the offer as an object, not as a JSON string.
          data: credentialOffer
        }]
      }
    });

    // The wallet handled the request. credential.data is an object that
    // contains the wallet's protocol-specific response. It is not the issued
    // credential, and it does not necessarily mean that issuance is complete.
    // Your server knows when the wallet retrieves the credential from your
    // credential endpoint.
    // Implement your custom logic here as needed.
    showIssuanceStatus(credential);
  } catch (error) {
    switch (error.name) {
      case 'NotAllowedError':
        // The user canceled the flow, no wallet can handle the request, or
        // the call does not have transient user activation.
        break;
      case 'NotSupportedError':
        // The browser does not support Digital Credentials API issuance.
        // Fall back to your custom alternative flow logic.
        showAlternativeIssuanceFlow();
        break;
      case 'TypeError':
        // The request is malformed, for example, data is not an object.
        console.error('Invalid issuance request:', error);
        break;
      default:
        // For example, AbortError or NetworkError.
        console.error('Credential issuance failed:', error);
    }
  }
}

const addButton = document.querySelector('#add-to-wallet');
addButton.addEventListener('click', () => {
  // Your server adds a pre-authorized code for the signed-in user
  // to the button's data-pre-authorized-code attribute.
  issueDigitalCredential(addButton.dataset.preAuthorizedCode);
});

בדוגמה הזו, showAlternativeIssuanceFlow() ו-showIssuanceStatus() מייצגים את הלוגיקה של האפליקציה שלכם.

כדי להפעיל את create() מ-iframe ממקורות שונים, הדף המוטמע צריך לאפשר את תכונת מדיניות ההרשאות של digital-credentials-create. אחרת, הבקשה נדחית עם השגיאה NotAllowedError:

<iframe src="https://issuer.example" allow="digital-credentials-create">
</iframe>

שינויים מאז גרסת המקור לניסיון

השיטות והפרמטרים של ה-API לא השתנו מאז גרסת המקור לניסיון. עם זאת, השינויים הבאים הושקו בין Chrome 143 ל-Chrome 155, ויכול להיות שחלק מהם יחייבו אתכם לעדכן את הקוד. בטבלה הבאה מפורטים השינויים, ובקטעים שאחריה מוסבר כל אחד מהם.

אזור גרסת מקור לניסיון (Chrome 143) Chrome 155
זמינות אסימון של גרסת מקור לניסיון או הדגל chrome://flags/#web-identity-digital-credentials-creation מופעלת כברירת מחדל
הפעלת משתמשים נדרש, אבל לא בשימוש נדרש ונצרך על ידי כל קריאה ל-create() (Chrome 146)
שגיאות בביטול NetworkError NotAllowedError (Chrome 148)
מזהי פרוטוקולים ‫Chrome מעביר כל מזהה למערכת ההפעלה מזהים לא מוכרים מפעילים אזהרה על הוצאה משימוש (Chrome 151)
מקורות אטומים מותר נחסם באמצעות NotAllowedError (Chrome 151)
בדיקות אוטומטיות אין תמיכה מובנית ארנק וירטואלי בפרוטוקול כלי הפיתוח ל-Chrome‏ (Chrome 152)

פעילות המשתמשים נצרכת

החל מגרסה 146 של Chrome, קריאה ל-create() עם איבר digital צורכת את ההפעלה הזמנית של המשתמש, כפי שנדרש במפרט. במהלך גרסת המקור לניסיון, Chrome בדק אם המשתמשים הפעילו את התכונה, אבל לא השתמש בה.

לכן, כל קריאה ל-create() צריכה תנועה משלה של המשתמש, למשל לחיצה על כפתור. בלי הפעלת משתמש, ה-promise נדחה עם NotAllowedError. אחרי הקריאה, window.open() וממשקי API אחרים שדורשים הפעלה על ידי המשתמש לא יכולים להשתמש באותה תנועה.

דחיית הביטול עם NotAllowedError

החל מגרסה 148 של Chrome, ההבטחה שמוחזרת על ידי create() נדחית עם NotAllowedError כשהמשתמש מבטל את התהליך, למשל על ידי סגירת בורר הארנק ב-Android או סגירת תיבת הדו-שיח של קוד ה-QR במחשב. ההבטחה גם נדחית עם NotAllowedError כשאין אפליקציית ארנק שיכולה לטפל בבקשה. במהלך גרסת המקור לניסיון, המקרים האלה נדחו עם NetworkError.

אם הקוד שלכם בודק אם יש NetworkError כדי לזהות ביטול, צריך לעדכן אותו כך שיבדוק אם יש NotAllowedError במקום זאת.

מזהי פרוטוקול לא מזוהים מפעילים אזהרה

המפרט מגדיר מזהה פרוטוקול הנפקה יחיד, openid4vci-v1, ל-OpenID4VCI 1.0. גרסה 155 של Chrome מזהה את openid4vci-v1 וגם את openid4vci. המאפיין openid4vci לא נכלל במפרט, ולכן מומלץ להשתמש במאפיין openid4vci-v1.

‫Chrome מעביר לפלטפורמה בקשות עם כל מזהה פרוטוקול. עם זאת, החל מגרסה 151 של Chrome, כלי הפיתוח מציגים אזהרה על הוצאה משימוש כשדף קורא ל-create() עם מזהה פרוטוקול לא מזוהה. אנחנו מתכוונים לחסום ב-Chrome בקשות עם מזהי פרוטוקול לא מזוהים. הסטטוס מפורט בקטע "סינון פרוטוקולים ספציפי יותר ב-Digital Credential API".

כדי לבדוק את ההתנהגות הזו, מפעילים את chrome://flags/#enable-experimental-web-platform-features. כשהדגל הזה מופעל, create() מתעלם מבקשות עם מזהי פרוטוקול לא מזוהים ודוחה אותן עם TypeError אם לא נותרו בקשות. בנוסף, הפונקציה DigitalCredential.userAgentAllowsProtocol() מחזירה את הערך true רק לפרוטוקולים מזוהים. בלי הדגל, המערכת רק בודקת שהמזהה תקין. לכן, אל תסתמכו רק על userAgentAllowsProtocol() כדי לזהות תכונות. מטפלים ב-NotSupportedError כמו שמוצג בדוגמה.

מקורות אטומים חסומים

החל מגרסה 151 של Chrome, ‏create() דוחה עם NotAllowedError כשמסמך עם מקור אטום קורא לו, כמו iframe בארגז חול (sandbox) בלי האסימון allow-same-origin. במהלך גרסת המקור לניסיון, Chrome לא חסם את הקריאות האלה.

בדיקה באמצעות ארנק וירטואלי

החל מגרסה 152 של Chrome, אתם יכולים לבדוק את תהליך ההנפקה בלי מכשיר Android או אפליקציית ארנק. הפקודה הניסיונית DigitalCredentials.setVirtualWalletBehavior בפרוטוקול כלי הפיתוח ל-Chrome‏ (CDP) מטמיעה את הארנק הווירטואלי שהמפרט מגדיר לבדיקה אוטומטית. הארנק הווירטואלי יכול להגיב עם הנתונים שאתם מספקים, לדחות בקשות כאילו המשתמש ביטל את התהליך, או להשאיר בקשות בהמתנה כדי לבדוק זמנים קצובים לתפוגה וביטולים.

בבדיקה הבאה של Puppeteer, הארנק הווירטואלי מוגדר להגיב לבקשות openid4vci-v1, ואז לוחצים על הכפתור שמתחיל את ההנפקה:

const client = await page.createCDPSession();
await client.send('DigitalCredentials.setVirtualWalletBehavior', {
  action: 'respond',
  protocol: 'openid4vci-v1',
  response: {}
});

// Clicking the button provides the user activation that create() requires.
await page.click('#add-to-wallet');

אימוץ בתעשייה

אנחנו רואים שיש אימוץ של הנפקת Digital Credentials API. לדוגמה, המוסד הפיננסי הגרמני Sparkasse משתמש ב-Digital Credentials API כדי לאפשר לבעלי חשבונות לשמור ב-Google Wallet פרטי כניסה מאומתים שכוללים את הגיל שלהם. בעלי החשבונות יכולים להשתמש בפרטי הכניסה האלה כדי לאמת את הגיל שלהם אונליין ובאופן פיזי.

רוצה לנסות?

לפני שאתם בודקים את ההנפקה של Digital Credentials API, ודאו שיש לכם את הדברים הבאים:

  • מעדכנים ל-Chrome בגרסה 155 ואילך.
  • מתקינים במכשיר Android אפליקציית ארנק נתמכת, לדוגמה הדגמה של CMWallet.
  • חיבור Bluetooth מופעל בשני המכשירים (תהליך בין מכשירים בלבד).

כדי לבדוק את התהליך במכשירים שונים:

  1. במחשב, פותחים את אתר ההדגמה של המנפיק.
  2. לוחצים על הכפתור הוספה.
  3. סורקים את קוד ה-QR באמצעות מכשיר Android ופועלים לפי ההוראות במסך.

כדי לבדוק את התהליך באותו מכשיר, פותחים את אתר ההדגמה של המנפיק ב-Chrome במכשיר Android.

משאבים למפתחים

כדי להתחיל לשלב את הנפקת Digital Credentials API באתר, אתם יכולים להשתמש במקורות המידע הבאים:

שיתוף משוב

כדי לדווח על באג או לבקש תכונה, צריך לשלוח פנייה בכלי למעקב אחרי באגים ב-Chromium.