인증 관리자 - Verifier API

Android 앱 내의 디지털 사용자 인증 정보 확인은 사용자의 신원 (예: 정부 ID), 해당 사용자에 관한 속성 (예: 운전면허증, 학위 또는 연령이나 주소와 같은 속성) 또는 사용자 인증 정보가 발급되고 확인되어 엔티티의 진위성을 주장해야 하는 기타 시나리오를 인증하고 승인하는 데 사용할 수 있습니다.

디지털 사용자 인증 정보는 디지털 월렛에서 사용자의 검증 가능한 디지털 사용자 인증 정보에 액세스하는 방법을 지정하는 공개 W3C 표준이며 W3C 사용자 인증 정보 관리 API를 사용하여 웹 사용 사례에 구현됩니다. Android에서는 Credential Manager의 DigitalCredential API가 디지털 사용자 인증 정보를 확인하는 데 사용됩니다.

Android 버전 호환성

인증 도구 API는 Android 9 (API 수준 28) 이상에서 지원됩니다.

구현

Android 프로젝트에서 디지털 사용자 인증 정보를 확인하려면 다음 단계를 따르세요.

  1. 앱의 빌드 스크립트에 종속 항목을 추가하고 CredentialManager 클래스를 초기화합니다.
  2. 디지털 사용자 인증 정보 요청을 구성하고 이를 사용하여 DigitalCredentialOption를 초기화한 후 GetCredentialRequest를 빌드합니다.
  3. 구성된 요청으로 getCredential 흐름을 실행하여 성공적인 GetCredentialResponse를 수신하거나 발생할 수 있는 예외를 처리합니다. 성공적으로 가져온 후 응답을 검증합니다.

종속 항목 추가 및 초기화

Gradle 빌드 스크립트에 다음 종속 항목을 추가합니다.

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

다음으로 CredentialManager 클래스의 인스턴스를 초기화합니다.

val credentialManager = CredentialManager.create(context)

디지털 사용자 인증 정보 요청 구성

디지털 사용자 인증 정보 요청을 구성하고 이를 사용하여 DigitalCredentialOption을 초기화합니다.

// 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 요청의 예입니다. 전체 참조는 이 웹사이트에서 확인할 수 있습니다.

{
  "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"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

사용자 인증 정보 가져오기

구성된 요청으로 getCredential 흐름을 실행합니다. 요청이 성공하면 GetCredentialResponse가 반환되고 요청이 실패하면 GetCredentialException가 반환됩니다.

getCredential 흐름은 Android 시스템 대화상자를 트리거하여 사용자가 사용할 수 있는 사용자 인증 정보 옵션을 표시하고 선택을 수집합니다. 그런 다음 선택한 사용자 인증 정보 옵션이 포함된 지갑 앱에서 동의를 수집하고 디지털 사용자 인증 정보 응답을 생성하는 데 필요한 작업을 실행하는 UI를 표시합니다.

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