Kimlik bilgisi verme işlemlerini kart sahibi uygulamanızla yönetme

Kartı veren kuruluşlardan kimlik bilgilerini alıp depolamak için kart sahibi uygulamanızın, kart verme akışlarını işlemesi gerekir. Kimlik bilgisi verme işlemi iki şekilde tetiklenebilir:

• Veren tarafından başlatılan akış: Kullanıcı, veren kuruluşun uygulamasından veya web sitesinden VDC verilmesi için bir istek tetikler. Örneğin, bir web sitesi kullanıcılarına "Pasaportunuzu cüzdanınıza ekleyin" seçeneği sunabilir. Veren, OpenID4VCI kimlik bilgisi teklifi isteğinde bulunmak için Kimlik Bilgisi Yöneticisi verme API'sini çağırır. Bu tür istekleri işlemek için, kart sahibinin önce meta verilerini kaydetmek üzere Kimlik Bilgisi Yöneticisi ile entegre olması gerekir. Kimlik Bilgisi Yöneticisi, kullanıcının seçebileceği alakalı seçenekleri gösterir. Kullanıcı bir cüzdan seçeneği belirledikten sonra cüzdan uygulaması çağrılır ve kart verme işlemini tamamlamak için gereken adımlara devam edebilir.
• Kart sahibi tarafından başlatılan akış: Kullanıcı, kart sahibi uygulamasından VDC ekleme isteğinde bulunur. Örneğin, bir kart sahibi "Pasaportunuzu ekleyin" düğmesi sunabilir. Bu durumda, kart sahibi desteklenen veren listesini ve meta verilerini korur. Bu işlevi tamamlamak için Android Kimlik Bilgisi Yöneticisi ile entegre olması gerekmez.

Kimlik bilgilerinin Holder API ile nasıl çalıştığı hakkında daha fazla bilgi için Dijital kimlik bilgilerini saklama hakkında başlıklı makaleyi inceleyin.

Android sürümü uyumluluğu

Holder API, Android 6 (API düzeyi 23) ve sonraki sürümlerde desteklenir.

Uygulama

Kimlik Bilgisi Yöneticisi Holder API'yi kullanmak için uygulama modülünüzün derleme komut dosyasına aşağıdaki bağımlılıkları ekleyin:

dependencies {
    // Use to implement credentials registrys

    implementation "androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04"

}

dependencies {
    // Use to implement credentials registrys

    implementation("androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04")

}

RegistryManager'ı oluşturma

Bir RegistryManager örneği oluşturun ve bu örnekle bir RegisterCreationOptionsRequest isteği kaydedin.

val registryManager = RegistryManager.create(context)

try {
    registryManager.registerCreationOptions(object :
        RegisterCreationOptionsRequest(
            creationOptions = buildIssuanceData(),
            matcher = loadIssuanceMatcher(),
            type = DigitalCredential.TYPE_DIGITAL_CREDENTIAL,
            id = "openid4vci",
        ) {}
    )
} catch (e: Exception) {
    Log.e(TAG, "Issuance registration failed.", e)
}

Eşleştirici, kayıt sırasında ayarlanan creationOptions ve veren tarafından gönderilen kimlik bilgisi teklifini alarak Kimlik Bilgisi Yöneticisi kullanıcı arayüzünde gösterilen girişleri belirleyen bir WebAssembly (Wasm) ikili program dosyasıdır. Eşleştirici örneği için açık kaynak örnek cüzdan uygulamasına bakın.

Kart oluşturma isteğini işleme

Ardından, kullanıcı bir kimlik bilgisi oluşturma seçeneği belirlediğinde cüzdanın bu işlemi işlemesi gerekir. Örnek cüzdanda gösterildiği gibi, androidx.credentials.registry.provider.action.CREATE_CREDENTIAL intent filtresini dinleyen bir etkinlik tanımlayın.

Etkinliği başlatan intent, oluşturma isteğini ve arama kaynağını içerir. Bunları PendingIntentHandler.retrieveProviderCreateCredentialRequest işleviyle ayıklayabilirsiniz. API, oluşturma isteğiyle ilişkili tüm bilgileri içeren bir ProviderCreateCredentialRequest döndürür. İki temel bileşen vardır:

• İsteği gönderen uygulama. Bu bilgiyi getCallingAppInfo ile alabilirsiniz.
• Arama uygulamasından gelen istek. Bu isteği, CreateCredentialRequest döndüren getCallingRequest ile alabilirsiniz. İstek, dijital kimlik bilgileri içinse requestJson özelliğinde düzenleme isteği JSON'unu içeren bir CreateDigitalCredentialRequest örneğidir. Bunu aşağıdaki örnek kodla işleyebilirsiniz:

val pendingIntentRequest =
    PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val request = pendingIntentRequest!!.callingRequest
if (request is CreateDigitalCredentialRequest) {
    Log.i(TAG, "Got DC creation request: ${request.requestJson}")
    processCreationRequest(request.requestJson)
}

Anahtar onayı

Anahtar onayıyla ilgili aşağıdaki noktalara dikkat edin:

• Anahtar onayı oluştururken anahtar malzemelerini JSON web anahtarı gibi bir biçime dönüştürmek için BigInteger.toByteArray kullanıyor olabilirsiniz. Bu yöntem bazen bir işaret baytı ekleyebilir ve doğrulama hatasına neden olabilir. Bu durumda, anahtar onayını veren kuruluşa göndermeden önce bu baytları kaldırın.
• Anahtar kanıt türü olarak android_key_attestation kullanmanızı öneririz.

Oluşturma yanıtını döndürme

Cüzdan, kimlik bilgisini kaydetmek için gereken adımları tamamladıktan sonra etkinliği kimlik bilgisi yanıtıyla tamamlayın:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialResponse(
    resultData,
    CreateDigitalCredentialResponse(response.responseJson)
)
setResult(RESULT_OK, resultData)
finish()

Bir istisna varsa kimlik bilgisi istisnasını da benzer şekilde gönderebilirsiniz:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialException(
    resultData,
    CreateCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

Kimlik bilgisi yanıtını bağlam içinde döndürmenin tam bir örneğini görmek için örnek uygulamaya bakın.