Credential Manager - Verifier API

Android uygulamalarında dijital kimlik bilgisi doğrulama, kullanıcının kimliğini (ör. resmi kimlik), kullanıcıyla ilgili özellikleri (ör. sürücü belgesi, akademik derece veya yaş ya da adres gibi özellikler) ya da bir kimliğin gerçekliğini onaylamak için kimlik bilgisi verilmesi ve doğrulanması gereken diğer senaryoları doğrulamak ve yetkilendirmek için kullanılabilir.

Dijital Kimlik Bilgileri, kullanıcının doğrulanabilir dijital kimlik bilgilerine dijital cüzdandan nasıl erişileceğini belirten herkese açık bir W3C standardıdır ve W3C Credential Management API ile web kullanım alanları için uygulanır. Android'de, dijital kimlik bilgilerini doğrulamak için Kimlik Bilgisi Yöneticisi'nin DigitalCredential API'si kullanılır.

Uygulama

Android projenizdeki dijital kimlik bilgilerini doğrulamak için aşağıdakileri yapın:

  1. Uygulamanızın derleme komut dosyasına bağımlılıklar ekleyin ve CredentialManager sınıfını başlatın.
  2. Dijital kimlik bilgisi isteği oluşturun ve bunu kullanarak DigitalCredentialOption başlatın, ardından GetCredentialRequest oluşturun.
  3. getCredential akışını başlatarak başarılı bir GetCredentialResponse alın veya oluşabilecek istisnaları ele alın. Başarılı bir şekilde alındıktan sonra yanıtı doğrulayın.

Bağımlılık ekleme ve başlatma

Gradle derleme komut dosyanıza aşağıdaki bağımlılıkları ekleyin:

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-beta01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-beta01")
}

Ardından, CredentialManager sınıfının bir örneğini başlatın.

val credentialManager = CredentialManager.create(context)

Dijital kimlik bilgisi isteği oluşturma

Dijital kimlik bilgisi isteği oluşturun ve bunu DigitalCredentialOption başlatmak için kullanın.

// The request in the JSON format to conform with
// the JSON-ified Credential Manager - Verifier 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)
)

OpenId4Vp isteği örneğini aşağıda görebilirsiniz. Tam referansı bu web sitesinde bulabilirsiniz.

{
  "requests": [
    {
      "protocol": "openid4vp-v1-unsigned",
      "data": {
        "response_type": "vp_token",
        "response_mode": "dc_api",
        "nonce": "OD8eP8BYfr0zyhgq4QCVEGN3m7C1Ht_No9H5fG5KJFk",
        "dcql_query": {
          "credentials": [
            {
              "id": "cred1",
              "format": "mso_mdoc",
              "meta": {
                "doctype_value": "org.iso.18013.5.1.mDL"
              },
              "claims": [
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "family_name"
                  ]
                },
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "given_name"
                  ]
                },
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "age_over_21"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Kimlik bilgisini alma

Oluşturulan istekle getCredential akışını başlatın. İstek başarılı olursa GetCredentialResponse, başarısız olursa GetCredentialException simgesini görürsünüz.

getCredential akışı, kullanıcının mevcut kimlik bilgisi seçeneklerini sunmak ve seçimini toplamak için Android sistem iletişim kutularını tetikler. Ardından, seçilen kimlik bilgisi seçeneğini içeren cüzdan uygulaması, izin almak ve dijital kimlik bilgisi yanıtı oluşturmak için gereken işlemleri gerçekleştirmek üzere kullanıcı arayüzleri gösterir.

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}")
    }
}