Opublikowano: 23 października 2026 r.
W Chrome 155 i nowszych wersjach wydawanie cyfrowych dokumentów tożsamości jest domyślnie włączone, więc nie potrzebujesz już tokena wersji próbnej origin ani flagi, aby korzystać z tej funkcji. Interfejs Digital Credentials API to warstwa transportowa, która umożliwia witrynom łączenie się z aplikacjami portfela zainstalowanymi na urządzeniu mobilnym użytkownika. Dzięki wydawaniu dokumentów wydawcy mogą dodawać nowe dokumenty (takie jak cyfrowe dokumenty tożsamości) bezpośrednio do aplikacji portfela użytkownika.
Tło
Ekosystem cyfrowej tożsamości składa się z 3 stron: wydawców, weryfikatorów (nazywanych też stronami polegającymi) i posiadaczy (aplikacji portfela). Użytkownicy często dodają cyfrowy dokument tożsamości do aplikacji portfela za pomocą przekazywania danych karty, gdzie użytkownik rozpoczyna proces wydawania na stronie internetowej lub w aplikacji wydawcy. Na przykład student na stronie internetowej swojej uczelni (wydawcy) może zapisać swoją cyfrową legitymację studencką w preferowanej aplikacji portfela (posiadacza).
Aby ten model działał, wydawca musi mieć bezpieczny i niezawodny sposób wywoływania aplikacji portfela w celu wydania dokumentu tożsamości. Przed wprowadzeniem tego interfejsu API każdy wydawca musiał stworzyć własny sposób otwierania aplikacji portfela, z którymi współpracował, zwykle za pomocą niestandardowych schematów URI. Wydawcy musieli utrzymywać oddzielny mechanizm dla każdej aplikacji portfela, a użytkownicy nie mieli spójnego sposobu wyboru aplikacji portfela.
Jak działa wydawanie cyfrowych dokumentów tożsamości
Aby usprawnić ten proces, Chrome obsługuje wydawanie za pomocą interfejsu W3C Digital Credentials API. Uzupełnia to możliwości prezentacji (udostępnianie żądanych, wybranych danych z cyfrowego dokumentu tożsamości weryfikatorowi), które zostały wprowadzone w Chrome 141. Gdy witryna wydawcy wywołuje funkcję navigator.credentials.create() z elementem digital zawierającym żądanie wydania, Chrome przekazuje żądanie do systemu operacyjnego (na Androidzie jest to Credential Manager). System operacyjny wyświetla wtedy własny interfejs, w którym użytkownik wybiera aplikację portfela. Interfejs API działa ze standardowymi protokołami branżowymi, takimi jak OpenID for Verifiable Credential Issuance (OpenID4VCI).
Wydawanie obsługuje 2 procesy: proces na tym samym urządzeniu z Androidem oraz proces na różnych urządzeniach, który rozpoczyna się na komputerze, a kończy na urządzeniu z Androidem.
Proces na tym samym urządzeniu z Androidem
Na Androidzie Chrome przekazuje żądanie wydania do Credential Manager, który wyświetla listę zgodnych aplikacji portfela na urządzeniu. Użytkownik wybiera portfel i wyraża zgodę na dodanie dokumentu. Następnie aplikacja portfela pobiera dokument od wydawcy za pomocą protokołu wydawania, takiego jak OpenID4VCI.
Proces na różnych urządzeniach na komputerze
Na komputerze Chrome wyświetli kod QR. Użytkownik skanuje kod za pomocą urządzenia z Androidem i kończy proces na tym urządzeniu, jak opisano w poprzedniej sekcji. Urządzenia używają Bluetootha, aby potwierdzić, że znajdują się blisko siebie, więc Chrome prosi użytkownika o włączenie Bluetootha, jeśli jest wyłączony. Chrome używa tego samego mechanizmu między urządzeniami do prezentacji interfejsu Digital Credentials API.
Wdrażanie wystawiania za pomocą interfejsu API
Aby rozpocząć proces wydawania, wywołaj navigator.credentials.create() i przekaż żądania wydania w elemencie digital. Wywołaj tę funkcję z poziomu modułu obsługi kliknięć lub innego modułu obsługi gestów użytkownika, ponieważ wywołanie wymaga tymczasowej aktywacji użytkownika. W poniższym przykładzie użyto oferty danych uwierzytelniających OpenID4VCI z przepływem kodu wstępnie autoryzowanego:
// 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);
});
W tym przykładzie showAlternativeIssuanceFlow() i showIssuanceStatus() reprezentują logikę Twojej aplikacji.
Aby wywołać create() z elementu iframe współdzielenia, strona umieszczająca musi zezwalać na funkcję zasad dotyczących uprawnień digital-credentials-create. W przeciwnym razie wywołanie zostanie odrzucone z błędem NotAllowedError:
<iframe src="https://issuer.example" allow="digital-credentials-create">
</iframe>
Zmiany od czasu testowania origin
Metody i parametry interfejsu API nie zmieniły się od czasu testowania origin. Jednak w wersjach Chrome od 143 do 155 wprowadziliśmy te zmiany, z których niektóre mogą wymagać aktualizacji kodu. W tabeli poniżej znajdziesz podsumowanie zmian, a w sekcjach pod nią – ich szczegółowe opisy.
| Obszar | Testowanie origin (Chrome 143) | Chrome 155 |
|---|---|---|
| Dostępność | Token testowania origin lub flaga chrome://flags/#web-identity-digital-credentials-creation |
Ta opcja jest domyślnie włączona. |
| Aktywacja użytkownika | Wymagane, ale nieużywane | Wymagane i wykorzystywane przez każde wywołanie create() (Chrome 146) |
| Błędy anulowania | NetworkError |
NotAllowedError (Chrome 148) |
| Identyfikatory protokołów | Chrome przekazuje dowolny identyfikator do systemu operacyjnego. | Nierozpoznane identyfikatory powodują wyświetlenie ostrzeżenia o wycofaniu (Chrome 151) |
| Nieprzezroczyste źródła | Dozwolone | Zablokowane przez NotAllowedError (Chrome 151) |
| Automatyczne testy | Brak wbudowanej obsługi | Wirtualny portfel w protokole narzędzi deweloperskich w Chrome (Chrome 152) |
Aktywacja użytkownika została wykorzystana
Od Chrome 146 wywołanie create() z elementem digital wykorzystuje tymczasową aktywację użytkownika, zgodnie z wymaganiami specyfikacji. Podczas testowania origin Chrome sprawdzał aktywację użytkownika, ale jej nie wykorzystywał.
W związku z tym każde wywołanie create() wymaga własnego gestu użytkownika, np. kliknięcia przycisku. Bez aktywacji użytkownika obietnica zostanie odrzucona z błędem NotAllowedError. Po wywołaniu window.open() i inne interfejsy API, które wymagają aktywacji przez użytkownika, nie mogą używać tego samego gestu.
Anulowanie odrzuca z błędem NotAllowedError
Od wersji Chrome 148 obietnica zwracana przez create() odrzuca NotAllowedError, gdy użytkownik anuluje proces, na przykład przez odrzucenie selektora portfela na Androidzie lub zamknięcie okna z kodem QR na komputerze. Obiekt Promise odrzuca też błąd NotAllowedError, gdy żadna aplikacja portfela nie może obsłużyć żądania.
W trakcie testowania origin takie przypadki były odrzucane z błędem NetworkError.
Jeśli Twój kod sprawdza NetworkError, aby wykryć anulowanie, zaktualizuj go, aby sprawdzał NotAllowedError.
Nierozpoznane identyfikatory protokołów powodują wyświetlenie ostrzeżenia.
Specyfikacja definiuje jeden identyfikator protokołu wydawania, openid4vci-v1, dla OpenID4VCI 1.0. Chrome 155 rozpoznaje openid4vci-v1, a także openid4vci. Atrybut openid4vci nie jest częścią specyfikacji, dlatego zalecamy używanie atrybutu openid4vci-v1.
Chrome przekazuje do platformy żądania z dowolnym identyfikatorem protokołu. Jednak od Chrome 151 Narzędzia deweloperskie wyświetlają ostrzeżenie o wycofaniu, gdy strona wywołuje create() z nierozpoznanym identyfikatorem protokołu. Chrome zamierza blokować żądania z nierozpoznanymi identyfikatorami protokołów. Stan znajdziesz we wpisie Bardziej szczegółowe filtrowanie protokołów w interfejsie Digital Credential API.
Aby przetestować to działanie, włącz chrome://flags/#enable-experimental-web-platform-features. Gdy ta flaga jest włączona, create() ignoruje żądania z nierozpoznanymi identyfikatorami protokołów i odrzuca je z błędem TypeError, jeśli nie ma już żadnych żądań. Ponadto DigitalCredential.userAgentAllowsProtocol() zwraca true tylko w przypadku rozpoznanych protokołów. Bez tej flagi sprawdza tylko, czy identyfikator jest prawidłowo sformułowany.
Dlatego nie polegaj wyłącznie na userAgentAllowsProtocol() do wykrywania funkcji.
Użyj uchwytu NotSupportedError, jak pokazano na przykładzie.
Nieprzezroczyste źródła są blokowane
Od Chrome 151 metoda create() odrzuca żądanie z błędem NotAllowedError, gdy wywołuje ją dokument z nieprzezroczystym źródłem, np. element iframe w piaskownicy bez tokena allow-same-origin.
W trakcie testowania origin Chrome nie blokował tych wywołań.
Testowanie za pomocą wirtualnego portfela
Od wersji Chrome 152 możesz testować proces wydawania bez urządzenia z Androidem ani aplikacji portfela. Eksperymentalne polecenie DigitalCredentials.setVirtualWalletBehavior w protokole narzędzi deweloperskich w Chrome (CDP) implementuje wirtualny portfel, który jest zdefiniowany w specyfikacji na potrzeby testów automatycznych. Portfel wirtualny może odpowiadać danymi, które podasz, odrzucać żądania, tak jakby użytkownik anulował proces, lub pozostawiać żądania oczekujące na przetestowanie limitów czasu i przerwania.
Ten test Puppeteer ustawia portfel wirtualny tak, aby odpowiadał na żądania openid4vci-v1, a następnie klika przycisk, który rozpoczyna wydawanie:
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');
Wdrożenie w branży
Obserwujemy coraz częstsze korzystanie z interfejsu Digital Credentials API. Na przykład niemiecka instytucja finansowa Sparkasse używa interfejsu Digital Credentials API, aby umożliwić właścicielom kont zapisywanie zweryfikowanych danych dotyczących wieku w Portfelu Google. Właściciele kont mogą następnie używać tych danych logowania do potwierdzania swojego wieku online i osobiście.
Wypróbuj
Zanim przetestujesz wydawanie cyfrowych dokumentów tożsamości za pomocą interfejsu Digital Credentials API, upewnij się, że masz:
- Zaktualizuj Chrome do wersji 155 lub nowszej.
- Zainstaluj na urządzeniu z Androidem obsługiwaną aplikację portfela, np. wersję demonstracyjną CMWallet.
- Bluetooth musi być włączony na obu urządzeniach (tylko w przypadku procesu obejmującego wiele urządzeń).
Aby przetestować proces na różnych urządzeniach:
- Na komputerze otwórz witrynę demonstracyjną wydawcy.
- Kliknij przycisk Dodaj.
- Zeskanuj kod QR urządzeniem z Androidem i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.
Aby przetestować proces na tym samym urządzeniu, otwórz witrynę demonstracyjną wydawcy w Chrome na urządzeniu z Androidem.
Materiały dla programistów
Aby rozpocząć integrację wydawania cyfrowych dokumentów tożsamości w swojej witrynie, skorzystaj z tych zasobów:
- Przeczytaj przewodnik dla programistów opracowany przez grupę społecznościową W3C Web Identity & Credentials Adoption Community Group.
- Zapoznaj się ze specyfikacją cyfrowych dokumentów tożsamości W3C.
- Zapoznaj się ze specyfikacją OpenID for Verifiable Credential Issuance 1.0.
- Zapoznaj się z kodem źródłowym aplikacji demonstracyjnej CMWallet, która jest aplikacją portfela open source na Androida.
- Dowiedz się, jak aplikacje portfela na Androida obsługują żądania wydania z Credential Manager.
- Wypróbuj witrynę demonstracyjną wydawcy z zainstalowanym na urządzeniu z Androidem demonstracyjnym Portfelem CM.
- Zapoznaj się z demonstracją konstruktora żądań cyfrowych dokumentów tożsamości, aby zobaczyć, jak wygląda ładunek żądania.
Prześlij opinię
Aby zgłosić błąd lub poprosić o dodanie funkcji, zgłoś problem w narzędziu do śledzenia błędów Chromium.