Dijital kimlikler hem uygulama içi hem de web akışlarında kabul edilebilir. Google Cüzdan'dan kimlik bilgilerini kabul etmek için:
- Verilen talimatları uygulayarak uygulama veya web üzerinden entegrasyon yapın.
- Google Cüzdan korumalı alanını kullanarak akışınızı test etmek için test kimliğini kullanın.
- Canlı yayına başlamak için bu formu doldurarak erişim isteğinde bulunun ve Google Cüzdan kimlik bilgisi hizmet şartlarını kabul edin. Bu formu her bir bağlı işletmeniz için doldurmanız gerekir. Formu doldurduktan sonra ekibimiz sizinle iletişime geçecektir.
- Sorularınız varsa
wallet-identity-rp-support@google.comile iletişime geçebilirsiniz.
Desteklenen Kimlik Bilgisi Biçimleri
Dijital kimlik belgelerinin veri biçimini tanımlayan birkaç standart önerisi vardır. Bunlardan ikisi sektörde önemli bir ilgi görmüştür:
- mdocs: ISO tarafından tanımlanır.
- w3c Verifiable Credentials: w3c tarafından tanımlanır.
Android Kimlik Bilgisi Yöneticisi her iki biçimi de desteklerken Google Cüzdan şu anda yalnızca mdoc tabanlı dijital kimlikleri desteklemektedir.
Desteklenen kimlik bilgileri
Google Cüzdan 2 tür kimlik bilgisini destekler:
- Mobil sürücü belgesi (mDL)
- Kimlik kartı
Tek bir parametre değişikliğiyle akışınızda her iki kimlik bilgisini de isteyebilirsiniz.
Kullanıcı deneyimi
Bu bölümde, önerilen online sunum akışı ele alınmaktadır. Akışta, alkol teslimatı için bir uygulamaya yaş sunma işlemi gösterilmektedir. Ancak kullanıcı deneyimi, web'de ve diğer sunum türlerinde de benzerdir.
 |
 |
 |
 |
 |
| Kullanıcıdan uygulama veya web sitesinde yaşını doğrulaması istenir. | Kullanıcı, uygun kimlik bilgilerini görür. | Kullanıcı, Google Cüzdan'da onay sayfasını görür. | Kullanıcı, paylaşımı onaylamak için kimliğini doğrular. | Uygulamaya veya web sitesine gönderilen veriler |
Önemli Notlar
- Uygulama veya web sitesi, API'ye giriş noktasını oluşturma konusunda esnektir. 1. adımda gösterildiği gibi, zaman içinde Google Cüzdan'ın ötesinde seçeneklerin API üzerinden kullanıma sunulacağını düşündüğümüz için "Dijital kimlikle doğrulayın" gibi genel bir düğme göstermenizi öneririz.
- 2. adımdaki seçici ekranı Android tarafından oluşturulur. Uygun kimlik bilgileri, her bir Cüzdan tarafından sağlanan kayıt mantığı ile güvenen tarafın gönderdiği istek arasındaki eşleşmeye göre belirlenir.
- 3. adım, Google Cüzdan tarafından oluşturulur. Google Cüzdan, bu ekranda geliştiricinin sağladığı adı, logoyu ve gizlilik politikasını gösterir.
Dijital kimlik akışı ekleme
Kullanıcının kimlik bilgisi yoksa "Dijital kimlikle doğrulayın" düğmesinin yanına, kullanıcının dijital kimlik eklemesine olanak tanımak için Google Cüzdan'a derin bağlantı veren bir bağlantı eklemenizi öneririz.
 |
 |
| Kullanıcıdan uygulama veya web sitesinde yaşını doğrulaması istenir. | Kullanıcı, dijital kimlik almak için Google Cüzdan'a yönlendirilir. |
Dijital kimlik yok
Kullanıcı, dijital kimliği olmadan "Dijital kimlikle doğrulama" seçeneğini belirlerse bu hata mesajı gösterilir.
|
 |
| Kullanıcıdan uygulama veya web sitesinde yaşını doğrulaması istenir. | Kullanıcıya dijital kimliği yoksa hata gösterilir. |
API, kullanıcının gizliliğini korumak için kullanıcının kullanılabilir dijital kimliklerinin olup olmadığını sessizce öğrenme özelliğini desteklemez. Bu nedenle, gösterildiği gibi ilk katılım bağlantısı seçeneğini eklemenizi öneririz.
Cüzdandan kimlik bilgisi isteme için istek biçimi
Android cihazda veya web'de herhangi bir cüzdandan kimlik bilgisi almak için yapılan mdoc requestJson isteğinin örneğini aşağıda bulabilirsiniz.
{
"requests" : [
{
"protocol": "openid4vp",
"data": {<credential_request>} // This is an object, shouldn't be a string.
}
]
}
Şifreleme İsteği
client_metadata, her istek için şifreleme ortak anahtarını içerir.
Her istek için özel anahtarları saklamanız ve bunları, cüzdan uygulamasından aldığınız jetonu kimlik doğrulamak ve yetkilendirmek için kullanmanız gerekir.
requestJson içindeki credential_request parametresi aşağıdaki alanlardan oluşur.
{
"response_type": "vp_token",
"response_mode": "dc_api",
"nonce": "1234",
"dcql_query": {
"credentials": [
{
"id": "cred1",
"format": "mso_mdoc",
"meta": {
"doctype_value": "org.iso.18013.5.1.mDL" // this is for mDL. Use com.google.wallet.idcard.1 for ID pass
},
"claims": [
{
"path": [
"org.iso.18013.5.1",
"family_name"
],
"intent_to_retain": false // set this to true if you are saving the value of the field
},
{
"path": [
"org.iso.18013.5.1",
"given_name"
],
"intent_to_retain": false
},
{
"path": [
"org.iso.18013.5.1",
"age_over_18"
],
"intent_to_retain": false
}
]
}
]
},
"client_metadata": {
"jwks": {
"keys": [ // sample request encryption key
{
"kty": "EC",
"crv": "P-256",
"x": "pDe667JupOe9pXc8xQyf_H03jsQu24r5qXI25x_n1Zs",
"y": "w-g0OrRBN7WFLX3zsngfCWD3zfor5-NLHxJPmzsSvqQ",
"use": "enc",
"kid" : "1",
"alg" : "ECDH-ES",
}
]
},
"authorization_encrypted_response_alg": "ECDH-ES",
"authorization_encrypted_response_enc": "A128GCM"
}
}
Google Cüzdan'da saklanan kimlik bilgilerinden istediğiniz sayıda desteklenen özelliği isteyebilirsiniz.
Uygulama İçi
Android uygulamalarınızdan kimlik bilgisi istemek için aşağıdaki adımları uygulayın:
Bağımlılıkları güncelleme
Projenizin build.gradle dosyasında, bağımlılıklarınızı Kimlik Bilgisi Yöneticisi'ni (beta) kullanacak şekilde 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öneticisini 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)
İstek kimliği özellikleri
Uygulama, kimlik istekleri için ayrı ayrı parametreler belirtmek yerine tümünü CredentialOption içinde bir JSON dizesi olarak sağlar. Kimlik Bilgisi Yöneticisi, bu JSON dizesini içeriğini incelemeden kullanılabilir dijital cüzdanlara iletir. Her cüzdan daha sonra şunlardan sorumludur: - Kimlik isteğini anlamak için JSON dizesini ayrıştırma. - Kayıtlı kimlik bilgilerinden hangisinin (varsa) isteği karşıladığını belirleme
İş ortaklarının, Android uygulaması entegrasyonları için bile isteklerini sunucuda oluşturmasını öneririz.
requestJson işlev çağrısında request içeren İstek Biçimi'nden requestJson öğesini kullanacaksınız.GetDigitalCredentialOption()
// 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)
}
}
Yanıtı doğrulama ve onaylama
Cüzdandan yanıt aldığınızda yanıtın başarılı olup olmadığını ve credentialJson yanıtını içerip içermediğini doğrulayın.
// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
val credential = result.credential
when (credential) {
is DigitalCredential -> {
val responseJson = credential.credentialJson
validateResponseOnServer(responseJson) // make a server call to validate the response
}
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.
}
else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
}
}
credentialJson yanıtı, W3C tarafından tanımlanan şifrelenmiş bir identityToken (JWT) içerir. Bu yanıtı oluşturmaktan Cüzdan uygulaması sorumludur.
Örnek:
{
"protocol" : "openid4vp",
"data" : {
<encrpted_response>
}
}
Bu yanıtı, geçerliliğini doğrulamak için sunucuya geri iletirsiniz. Kimlik bilgisi yanıtını doğrulama adımlarını inceleyebilirsiniz.
Web
Chrome'da Digital Credentials API'yi kullanarak kimlik bilgisi istemek için Digital Credentials API kaynak denemesine kaydolmanız gerekir.
const credentialResponse = await navigator.credentials.get({
digital : {
requests : [
{
protocol: "openid4vp",
data: {<credential_request>} // This is an object, shouldn't be a string.
}
]
}
})
Kimlik bilgisi yanıtını doğrulamak için bu API'den gelen yanıtı sunucunuza geri gönderin.
Kimlik bilgisi yanıtını doğrulama adımları
Uygulamanızdan veya web sitenizden şifrelenmiş identityToken alındıktan sonra, yanıta güvenmeden önce yapmanız gereken birden fazla doğrulama vardır.
Özel anahtarı kullanarak yanıtın şifresini çözme
İlk adım, kaydedilen özel anahtarı kullanarak jetonun şifresini çözmek ve bir yanıt JSON'u almaktır.
Python örneği:
from jwcrypto import jwe, jwk # Retrieve the Private Key from Datastore reader_private_jwk = jwk.JWK.from_json(jwe_private_key_json_str) # Decrypt the JWE encrypted response from Google Wallet jwe_object = jwe.JWE() jwe_object.deserialize(encrypted_jwe_response_from_wallet) jwe_object.decrypt(reader_private_jwk) decrypted_payload_bytes = jwe_object.payload decrypted_data = json.loads(decrypted_payload_bytes)decrypted_data,vp_tokenkimlik bilgisini içeren bir JSON ile sonuçlanır.{ "vp_token": { "cred1": "<credential_token>" } }Oturum transkriptini oluşturma
Bir sonraki adım, Android'e veya web'e özel bir devretme yapısıyla ISO/IEC 18013-5:2021'den SessionTranscript oluşturmaktır:
SessionTranscript = [ null, // DeviceEngagementBytes not available null, // EReaderKeyBytes not available [ "OpenID4VPDCAPIHandover", AndroidHandoverDataBytes // BrowserHandoverDataBytes for Web ] ]Hem Android hem de web devir teslimleri için
credential_requestoluştururken kullandığınız nonce değerini kullanmanız gerekir.Android Handover
AndroidHandoverData = [ origin, // "android:apk-key-hash:<base64SHA256_ofAppSigningCert>", clientId, // "android-origin:<app_package_name>", nonce, // nonce that was used to generate credential request ] AndroidHandoverDataBytes = hashlib.sha256(cbor2.dumps(AndroidHandoverData)).digest()
Tarayıcı Aktarımı
BrowserHandoverData =[ origin, // Origin URL clientId, // "web-origin:<origin>" nonce, // nonce that was used to generate credential request ] BrowserHandoverDataBytes = hashlib.sha256(cbor2.dumps(BrowserHandoverData)).digest()
SessionTranscriptkullanıldığında DeviceResponse, ISO/IEC 18013-5:2021 bölüm 9'a göre doğrulanmalıdır. Bu süreçte aşağıdaki gibi çeşitli adımlar yer alır:Eyalet Tarafından Verilen Sertifikayı Kontrol Edin. Desteklenen kuruluşun IACA sertifikalarını inceleyin.
MSO imzasını doğrulama (18013-5 Bölüm 9.1.2)
Veri öğeleri için ValueDigest'leri hesaplama ve kontrol etme (18013-5 Bölüm 9.1.2)
deviceSignatureimzasını doğrulama (18013-5 Bölüm 9.1.3)
{
"version": "1.0",
"documents": [
{
"docType": "org.iso.18013.5.1.mDL",
"issuerSigned": {
"nameSpaces": {...}, // contains data elements
"issuerAuth": [...] // COSE_Sign1 w/ issuer PK, mso + sig
},
"deviceSigned": {
"nameSpaces": 24(<< {} >>), // empty
"deviceAuth": {
"deviceSignature": [...] // COSE_Sign1 w/ device signature
}
}
}
],
"status": 0
}
Çözümünüzü test etme
Çözümünüzü test etmek için açık kaynak referans tutucumuz olan Android uygulamasını oluşturup çalıştırın. Referans tutucu uygulamasını oluşturma ve çalıştırma adımları aşağıda verilmiştir:
- Referans uygulamaları deposunu klonlayın.
- Projeyi Android Studio'da açın.
- Android cihazınızda veya emülatörünüzde
appholderhedefini oluşturun ve çalıştırın.
Sıfır bilgi kanıtı (ZKP) tabanlı doğrulama
Sıfır bilgi kanıtı (ZKP), bir kişinin (kanıtlayıcı) doğrulayıcıya, belirli bir kimlik bilgisine sahip olduğunu veya belirli bir ölçütü karşıladığını (ör.18 yaşından büyük olmak, geçerli bir kimlik belgesine sahip olmak) kanıtlamasına olanak tanıyan bir şifreleme yöntemidir. Bu yöntem, temel alınan verilerin kendisini ifşa etmez. Temel olarak, hassas bilgileri gizli tutarken kimlikle ilgili bir ifadenin doğruluğunu onaylamanın bir yoludur.
Kimlik verilerinin doğrudan paylaşımına dayanan dijital kimlik sistemleri genellikle kullanıcıların aşırı kişisel bilgi paylaşmasını gerektirir. Bu durum, veri ihlalleri ve kimlik hırsızlığı riskini artırır. ZKPs, minimum açıklama ile doğrulama yapılmasını sağlayarak paradigma değişikliği sunar.
Dijital kimlikte ZKP'lerin temel kavramları:
- Kanıtlayıcı: Kimliğinin bir yönünü kanıtlamaya çalışan kişi.
- Doğrulayıcı: Bir kimlik özelliğinin kanıtını isteyen tüzel kişi.
- Kanıt: Kanıtlayanın, gizli bilgileri açıklamadan doğrulayanı iddiasının doğruluğuna ikna etmesine olanak tanıyan bir şifreleme protokolü.
Sıfır Bilgi Kanıtlarının Temel Özellikleri:
- Eksiksizlik: İfade doğruysa ve hem kanıtlayıcı hem de doğrulayıcı dürüstse doğrulayıcı ikna olur.
- Sağlamlık (Soundness): İfade yanlışsa dürüst olmayan bir kanıtlayıcı, dürüst bir doğrulayıcıyı ifadenin doğru olduğuna (çok yüksek bir olasılıkla) ikna edemez.
- Sıfır bilgi: Doğrulayan taraf, ifadenin doğru olmasının dışında hiçbir bilgi edinmez. Kanıtlayanın kimliğine ait gerçek veriler açığa çıkarılmaz.
Google Cüzdan'dan sıfır bilgi kanıtı almak için istek biçimini mso_mdoc_zk olarak değiştirmeniz ve İstek'inize zk_system_type eklemeniz gerekir.
...
"dcql_query": {
"credentials": [{
"id": "cred1",
"format": "mso_mdoc_zk",
"meta": {
"doctype_value": "org.iso.18013.5.1.mDL"
"zk_system_type": [
{
"system": "longfellow-libzk-v1",
"circuit_hash": "bd3168ea0a9096b4f7b9b61d1c210dac1b7126a9ec40b8bc770d4d485efce4e9", // This will differ if you need more than 1 attribute.
"num_attributes": 1, // number of attributes (in claims) this has can support
"version": 3
},
{
"system": "longfellow-libzk-v1",
"circuit_hash": "89288b9aa69d2120d211618fcca8345deb4f85d2e710c220cc9c059bbee4c91f", // This will differ if you need more than 1 attribute.
"num_attributes": 1, // number of attributes (in claims) this has can support
"version": 4
}
],
"verifier_message": "challenge"
},
"claims": [{
...
"client_metadata": {
"jwks": {
"keys": [ // sample request encryption key
{
...
Cüzdandan şifrelenmiş bir sıfır bilgi kanıtı alırsınız. Google'ın longfellow-zk kitaplığını kullanarak bu kanıtı, IACA sertifikaları veren kuruluşlara karşı doğrulayabilirsiniz.
Daha fazla bilgi için destek e-posta adresinden bize ulaşabilirsiniz.
wallet-identity-rp-support@google.com