Online
Dijital kimlikler hem uygulama içi hem de web akışlarında kabul edilebilir. Google Cüzdan'daki kimlik bilgilerini kabul etmek için:
- Sağlanan talimatları uygulayarak uygulama veya web'i kullanarak entegrasyon yapın ve
- Google Cüzdan'dan kimlik bilgilerini kabul etme isteğinde bulunmak ve hizmet şartlarını kabul etmek için bu formu doldurun.
Ön koşullar
Kimliklerin sunumunu test etmek için önce amaçlanan test hesabını kullanarak herkese açık beta programına kaydolmanız gerekir. Ardından, aşağıdaki ayrıntıları atanan Google temsilcinize iletin.
- Hizmet Şartları bağlantısı
- Logo
- Web sitesi
- Play Store paket kimliği (Android uygulama entegrasyonları için)
- Herkese açık beta sürümüne katılmak için kullanılan Gmail kimliği
Desteklenen Kimlik Bilgisi Biçimleri
Dijital kimlik belgelerinin veri biçimini tanımlayan birkaç önerilen standart vardır. Bunlardan ikisi sektörde önemli bir ilgi görmektedir:
- mdocs: ISO tarafından tanımlanmıştır.
- W3C Doğrulanabilir Kimlik Bilgileri: W3C tarafından tanımlanır.
Android Kimlik Bilgisi Yöneticisi her iki biçimi de desteklese de Google Cüzdan şu anda yalnızca mdoc tabanlı dijital kimlikleri desteklemektedir.
Kullanıcı deneyimi
Bir uygulama kimlik özellikleri istediğinde aşağıdaki işlem gerçekleşir:
Kimlik bilgisi bulma: Uygulama, isteği karşılayabilecek kimlik bilgilerini belirlemek için mevcut cüzdanları sorgular. Ardından Android, paylaşılacak bilgileri gösteren bir sistem kullanıcı arayüzü seçici sunar. Bu sayede kullanıcı, hangi kimlik bilgisini kullanacağı konusunda bilinçli bir karar verebilir.
Kullanıcı Seçimi ve Cüzdan Etkileşimi: Kullanıcı bir kimlik bilgisi seçer ve Android, işlemi tamamlamak için ilgili cüzdan uygulamasını çağırır. Cüzdan uygulaması kendi izin ekranını gösterebilir veya biyometrik onay isteyebilir.
Sonuç: Kullanıcı izin verirse seçilen kimlik kimlik bilgileri, istek gönderen uygulamayla paylaşılır. Kullanıcı reddederse bir hata döndürülür.
Uygulama İçi
Android uygulamalarınızdan kimlik kimlik bilgilerini istemek için aşağıdaki adımları uygulayın:
Bağımlılıkları güncelleme
Projenizin build.gradle dosyasında, Kimlik Bilgisi Yöneticisi'ni (beta) kullanacak şekilde bağımlılıkları güncelleyin:
dependencies {
implementation("androidx.credentials:credentials:1.5.0-beta01")
// optional - needed for credentials support from play services, for devices running Android 13 and below.
implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01")
}
Kimlik Bilgisi Yöneticisi'ni yapılandırma
Bir CredentialManager nesnesini yapılandırmak ve başlatmak için aşağıdakine benzer bir mantık ekleyin:
// Use your app or activity context to instantiate a client instance of CredentialManager.
val credentialManager = CredentialManager.create(context)
Kimlik özellikleri isteğinde bulunma
Uygulama, kimlik istekleri için ayrı ayrı parametreler belirtmek yerine hepsini CredentialOption içinde JSON dizesi olarak birlikte sağlar. Kimlik Bilgisi Yöneticisi, bu JSON dizesini içeriğini incelemeden mevcut dijital cüzdanlara iletir. Ardından her cüzdan aşağıdakilerden sorumludur: - Kimlik isteğini anlamak için JSON dizesini ayrıştırma. - Depolanan kimlik bilgilerinden hangisinin (varsa) isteği karşıladığını belirleme.
W3C'nin, web API spesifikasyonunun bir parçası olarak bu JSON isteğinin yapısını resmi olarak tanımlaması beklenmektedir. Ancak spesifikasyonun taslak halinde olduğunu ve değişebileceğini unutmayın.
Başlangıçta, Google Cüzdan'dan kimlik almak için önizleme protokolünü kullanacağız. Bu sayede, web API spesifikasyonu tamamlanırken entegrasyona ve testlere başlayabiliriz.
Önizleme protokolü için mdoc requestJson örneğini aşağıda bulabilirsiniz:
{
identity: {
providers: [{
holder: {
selector: {
format: ['mdoc'],
type: 'org.iso.18013.5.1.mDL',
fields: [
'org.iso.18013.5.1.family_name',
'org.iso.18013.5.1.portrait',
]
},
params: {
nonce: '1234',
readerPublicKey: '<public_key>',
extraParamAsNeededByWallets: true,
},
},
}]
}
}
// The request in the JSON format to conform with
// the JSON-ified Digital Credentials API request definition.
val requestJson = generateRequestFromServer()
val digitalCredentialOption =
GetDigitalCredentialOption(requestJson = requestJson)
// Use the option from the previous step to build the `GetCredentialRequest`.
val getCredRequest = GetCredentialRequest(
listOf(digitalCredentialOption)
)
coroutineScope.launch {
try {
val result = credentialManager.getCredential(
context = activityContext,
request = getCredRequest
)
verifyResult(result)
} catch (e : GetCredentialException) {
handleFailure(e)
}
}
// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
val credential = result.credential
when (credential) {
is DigitalCredential -> {
val responseJson = credential.credentialJson
validateResponseOnServer(responseJson)
}
else -> {
// Catch any unrecognized credential type here.
Log.e(TAG, "Unexpected type of credential ${credential.type}")
}
}
}
// Handle failure.
fun handleFailure(e: GetCredentialException) {
when (e) {
is GetCredentialCancellationException -> {
// The user intentionally canceled the operation and chose not
// to share the credential.
}
is GetCredentialInterruptedException -> {
// Retry-able error. Consider retrying the call.
}
is NoCredentialException -> {
// No credential was available.
}
is CreateCredentialUnknownException -> {
// An unknown, usually unexpected, error has occurred. Check the
// message error for any additional debugging information.
}
is CreateCredentialCustomException -> {
// You have encountered a custom error thrown by the wallet.
// If you made the API call with a request object that's a
// subclass of CreateCustomCredentialRequest using a 3rd-party SDK,
// then you should check for any custom exception type constants
// within that SDK to match with e.type. Otherwise, drop or log the
// exception.
}
else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
}
}
Yanıt, W3C tarafından tanımlanan bir identityToken (json dizesi) döndürür. Bu yanıtı oluşturmaktan Cüzdan uygulaması sorumludur.
Örnek:
{
"token": "<base64 encoded response>"
}
Sunucuda jeton gönderme ve işleme
Uygulamanız, identityToken'u aldıktan sonra doğrulama için uygulama sunucunuza iletmelidir. İlk adım, jetonun base64 biçimindeki kodunu çözmektir. Elde edilen bayt dizisi, aşağıdaki CDDL'ye uyan CBOR verilerini temsil eder.
CredentialDocument = {
"version": tstr, // Set to "ANDROID-HPKE-v1"
"pkEm": bstr, // Public key, in uncompressed form
"cipherText": bstr // The encrypted data
}
Sonraki adım, ISO/IEC 18013-5:2021'den Android'e özgü bir Aktarım yapısıyla SessionTranscript'i hesaplamaktır:
SessionTranscript = [
null, // DeviceEngagementBytes not available
null, // EReaderKeyBytes not available
AndroidHandover // Defined below
]
AndroidHandover = [
"AndroidHandoverv1", // Version number
nonce, // nonce that comes from request
appId, // RP package name
pkRHash, // The SHA256 hash of the recipient public key
]
cipherText, HPKE şifrelemesi kullanılarak şifrelenir. Şifresini çözmek için, daha önce oluşturulan EC özel anahtarının yanı sıra ek kimlik doğrulanmış veri olarak SessionTranscript'i ve aşağıdaki ayarları kullanın:
- KEM: DHKEM(P-256, HKDF-SHA256)
- KDF: HKDF-SHA256
- AEAD: AES-128-GCM
Elde edilen açık metin, ISO/IEC 18013-5:2021'de tanımlanan DeviceResponse CBOR baytlarıdır. DeviceResponse, ISO/IEC 18013-5:2021 9. fıkra uyarınca doğrulanmalıdır. Bu işlem, mdoc'nun güvenilir bir sağlayıcıdan geldiğinin ve yanıtın istenen cihaz tarafından imzalanmasının doğrulanması gibi çeşitli adımları içerir. Bu doğrulama sürecinin bir kısmı için OpenWallet Foundation Identity Credential projesindeki DeviceResponseParser sınıfı kullanılabilir.
Web
Chrome'da Digital Credentials API'yi kullanarak kimlik kimlik bilgilerini istemek için Digital Credentials API kaynak denemesine kaydolmanız gerekir.
Yüz Yüze
Google Cüzdan'dan kimlik kabul etmek için aşağıdaki adımları uygulamanız gerekir:
- ISO 18013-5'te tanımlanan kimlikleri kabul edecek bir okuyucu oluşturma veya edinme
- Kabul edilen kimliklerin gerçek olduğundan emin olmak için okuyucuya IACA sertifikalarını yükleme
- Çözümünüzü test etme
- Uygulamanızı Google Cüzdan'a kaydetme
ISO 18013-5'te tanımlanan kimlikleri kabul edecek bir okuyucu oluşturma veya edinme
Cüzdan'daki kimlikler, mobil sürücü belgeleri için ISO 18013-5 standardına göre uygulanır. Veri aktarma mekanizması olarak BLE ile birlikte NFC tabanlı veya QR kodu etkileşimini kullanırlar. Bu nedenle, standardın bu özelliklerini uygulayabilen herhangi bir cihaz, okuyucu olarak işlev görebilir. Hatta mobil uygulama olarak da kullanılabilir. Standart açık olduğu için piyasada çeşitli üçüncü taraf uygulamaları mevcuttur. Ayrıca, gerekirse işlevi doğrudan da uygulayabilirsiniz.
Bu işlevi kendiniz nasıl uygulayacağınızla ilgili bilgi edinmek için açık kaynak referans okuyucu Android uygulamamıza göz atın. Bu uygulama, ISO standardını uygular ve Google Cüzdan'dan mDL'leri kabul edebilir.
Referans okuyucu uygulamasını oluşturup çalıştırarak başlayabilirsiniz:
- Referans uygulama deposunu klonlayın
- Projeyi Android Studio'da açın
- Android cihazınızda veya emülatörünüzde
appverifierhedefini derleyip çalıştırın.
Kabul edilen kimliklerin gerçek olduğundan emin olmak için okuyucuya IACA sertifikalarını yükleme
Gerçek kimlik bilgilerini doğrulamak için desteklenen bir sağlayıcıdan cüzdanınızda kimlik bilgisi bulundurmanız gerekir. Google Cüzdan tarafından desteklenen kartların listesini ve doğrulama için sertifikalarının bağlantılarını aşağıda bulabilirsiniz.
Çözümünüzü test etme
Çözümünüzü test etmek için açık kaynak referans tutucumuz olan Android uygulamamızı oluşturup çalıştırın. Referans sahibi uygulamasını oluşturma ve çalıştırma adımları aşağıda verilmiştir:
- Referans uygulama deposunu klonlayın
- Projeyi Android Studio'da açın
- Android cihazınızda veya emülatörünüzde
appholderhedefini derleyip çalıştırın.
(İsteğe bağlı) Uygulamanızı Google Cüzdan'a kaydetme
Bu formu doldurarak uygulamanızı Google Cüzdan'a kaydedin.