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 çeşitli standartlar önerilmiştir. 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 Credential Manager 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ışı açıklanmaktadır. Akışta, alkol teslimatı için bir uygulamaya yaş sunma işlemi gösterilmektedir ancak kullanıcı deneyimi, web ve diğer sunum türlerinde 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 API üzerinden Google Cüzdan'ın ötesinde seçeneklerin sunulacağını düşündüğümüz için "Dijital kimlikle doğrulama" 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 ekleme akışı
Kullanıcının kimliği yoksa "Dijital kimlikle doğrulayın" düğmesinin yanında, kullanıcının dijital kimlik ekleyebilmesi için Google Cüzdan'a derin bağlantı veren bir bağlantı sağlamanızı ö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ğrulayın" seçeneğini belirlerse bu hata mesajı gösterilir.
|
 |
| Kullanıcıdan uygulama veya web sitesinde yaşını doğrulaması istenir. | Kullanıcıda dijital kimlik yoksa hata gösteriliyor |
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-v1-unsigned",
"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ı depolamanız ve bunları, cüzdan uygulamasından aldığınız jetonun kimliğini doğrulamak ve yetkilendirmek için kullanmanız gerekir.
requestJson içindeki credential_request parametresi aşağıdaki alanları içerir.
Belirli kimlik bilgisi
{
"response_type": "vp_token",
"response_mode": "dc_api.jwt", // change this to dc_api if you want to demo with a non encrypted response.
"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", // This is required
"alg" : "ECDH-ES", // This is required
}
]
},
"vp_formats_supported": {
"mso_mdoc": {
"deviceauth_alg_values": [
-7
],
"isserauth_alg_values": [
-7
]
}
}
}
}
Uygun Kimlik Bilgileri
Hem mDL hem de kimlik kartı için örnek istek aşağıda verilmiştir. Kullanıcı bu iki yöntemden birini kullanarak devam edebilir.
{
"response_type": "vp_token",
"response_mode": "dc_api.jwt", // change this to dc_api if you want to demo with a non encrypted response.
"nonce": "1234",
"dcql_query": {
"credentials": [
{
"id": "mdl-request",
"format": "mso_mdoc",
"meta": {
"doctype_value": "org.iso.18013.5.1.mDL"
},
"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
}
]
},
{ // Credential type 2
"id": "id_pass-request",
"format": "mso_mdoc",
"meta": {
"doctype_value": "com.google.wallet.idcard.1"
},
"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
}
]
}
]
credential_sets : [
{
"options": [
[ "mdl-request" ],
[ "id_pass-request" ]
]
}
]
},
"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", // This is required
"alg" : "ECDH-ES", // This is required
}
]
},
"vp_formats_supported": {
"mso_mdoc": {
"deviceauth_alg_values": [
-7
],
"isserauth_alg_values": [
-7
]
}
}
}
}
Google Cüzdan'da saklanan herhangi bir kimlik belgesinden 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")
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)
İstek kimliği özellikleri
Uygulama, kimlik istekleri için ayrı ayrı parametreler belirtmek yerine bunların hepsini 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şturmalarını öneririz.
İstek Biçimi'ndeki requestJson değerini, GetDigitalCredentialOption() işlev çağrısında request olarak kullanacaksınız.
// 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ıktan sonra 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-v1-unsigned",
"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 veya desteklenen diğer tarayıcılarda Digital Credentials API'yi kullanarak kimlik bilgisi istemek için aşağıdaki isteği gönderin.
const credentialResponse = await navigator.credentials.get({
digital : {
requests : [
{
protocol: "openid4vp-v1-unsigned",
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 elde etmektir.
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) # Save public key thumbprint for session transcript encryption_public_jwk_thumbprint = reader_private_jwk.thumbprint() # 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, kimlik bilgisini içerenvp_tokenJSON ile sonuçlanır.{ "vp_token": { "cred1": ["<base64UrlNoPadding_encoded_credential>"] // This applies to OpenID4VP 1.0 spec. } }Oturum transkriptini oluşturma
Bir sonraki adım, Android 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 devirlerinde,
credential_requestoluşturmak için kullandığınız nonce'ı kullanmanız gerekir.Android Handover
AndroidHandoverData = [ origin, // "android:apk-key-hash:<base64SHA256_ofAppSigningCert>", nonce, // nonce that was used to generate credential request, encryption_public_jwk_thumbprint, // Encryption public key (JWK) Thumbprint ] AndroidHandoverDataBytes = hashlib.sha256(cbor2.dumps(AndroidHandoverData)).digest()
Tarayıcı Aktarımı
BrowserHandoverData =[ origin, // Origin URL nonce, // nonce that was used to generate credential request encryption_public_jwk_thumbprint, // Encryption public key (JWK) Thumbprint ] BrowserHandoverDataBytes = hashlib.sha256(cbor2.dumps(BrowserHandoverData)).digest()
SessionTranscriptkullanılarak 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ına bakın.
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ü oluşturma
Çözümünüzü oluşturmak için GitHub'daki Identity Verifiers Referans Uygulaması'na bakabilirsiniz.
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) temel alınan gerçek verileri açıklamadan kanıtlamasına olanak tanıyan bir şifreleme yöntemidir. 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ıtlayan: 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ğrulayıcıyı iddiasının doğruluğuna ikna etmesine olanak tanıyan bir şifreleme protokolüdür.
Sıfır Bilgi Kanıtlarının Temel Özellikleri:
- Eksiksizlik: İfade doğruysa ve hem kanıtlayan hem de doğrulayan dürüstse doğrulayan kişi 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ğrulayıcı, ifadenin doğru olmasının dışında hiçbir şey öğrenmez. 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": "f88a39e561ec0be02bb3dfe38fb609ad154e98decbbe632887d850fc612fea6f", // This will differ if you need more than 1 attribute.
"num_attributes": 1, // number of attributes (in claims) this has can support
"version": 5,
"block_enc_hash": 4096,
"block_enc_sig": 2945,
}
{
"system": "longfellow-libzk-v1",
"circuit_hash": "137e5a75ce72735a37c8a72da1a8a0a5df8d13365c2ae3d2c2bd6a0e7197c7c6", // This will differ if you need more than 1 attribute.
"num_attributes": 1, // number of attributes (in claims) this has can support
"version": 6,
"block_enc_hash": 4096,
"block_enc_sig": 2945,
}
],
"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 sertifikası veren kuruluşlara karşı doğrulayabilirsiniz.
Doğrulayıcı hizmeti, yanıtı belirli veren IACA sertifikalarına göre doğrulamanıza olanak tanıyan, dağıtıma hazır ve Docker tabanlı bir sunucu içerir.
Güvenmek istediğiniz IACA veren sertifikalarını yönetmek için certs.pem dosyasını değiştirebilirsiniz.
Daha fazla bilgi için destek ekibinin e-posta adresiyle iletişime geçebilirsiniz:
wallet-identity-rp-support@google.com