보유자 앱으로 사용자 인증 정보 발급 처리

발급기관으로부터 사용자 인증 정보를 수신하고 저장하려면 소지자 앱에서 발급 흐름을 처리해야 합니다. 사용자 인증 정보 발급은 다음 두 가지 방법으로 트리거할 수 있습니다.

  • 발급기관에서 시작하는 흐름: 사용자가 발급기관 애플리케이션 또는 웹사이트에서 VDC를 발급하라는 요청을 트리거합니다. 예를 들어 웹사이트에서 사용자에게 '월렛에 여권 추가' 옵션을 제공할 수 있습니다. 발급기관은 Credential Manager 발급 API를 호출하여 OpenID4VCI 사용자 인증 정보 제공 요청을 합니다. 이러한 요청을 처리하려면 소지자가 먼저 인증 관리자와 통합하여 메타데이터를 등록해야 합니다. 인증 관리자는 사용자가 선택할 수 있는 관련 옵션을 표시합니다. 사용자가 소지자 옵션을 선택하면 소지자 애플리케이션이 호출되고 발급을 완료하는 데 필요한 단계를 진행할 수 있습니다.
  • 소지자 시작 흐름: 사용자가 소지자 애플리케이션에서 VDC를 추가하도록 요청합니다. 예를 들어 홀더는 '여권 추가' 버튼을 제공할 수 있습니다. 이 경우 소지자는 지원되는 발급기관 목록과 메타데이터를 유지합니다. 이 기능을 완료하기 위해 Android 인증 관리자와 통합할 필요는 없습니다.

사용자 인증 정보가 Holder API와 작동하는 방식에 관한 자세한 내용은 디지털 사용자 인증 정보 저장 정보를 참고하세요.

Android 버전 호환성

Holder API는 Android 6 (API 수준 23) 이상에서 지원됩니다.

구현

Credential Manager Holder API를 사용하려면 앱 모듈의 빌드 스크립트에 다음 종속 항목을 추가하세요.

Groovy

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"

}

Kotlin

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 만들기

RegistryManager 인스턴스를 만들고 여기에 RegisterCreationOptionsRequest 요청을 등록합니다.

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

매처는 등록 중에 설정된 creationOptions와 발급기관에서 전송한 사용자 인증 정보 제안을 수신하여 인증 관리자 UI에 표시되는 항목을 결정하는 WebAssembly (Wasm) 바이너리 파일입니다. 일치자의 예는 오픈소스 예시 월렛 앱을 참고하세요.

발급 요청 처리

다음으로, 사용자가 사용자 인증 정보 생성 옵션을 선택할 때 월렛에서 처리해야 합니다. 샘플 월렛에 나와 있는 것처럼 androidx.credentials.registry.provider.action.CREATE_CREDENTIAL 인텐트 필터를 수신 대기하는 활동을 정의합니다.

활동을 실행하는 인텐트에는 생성 요청과 호출 출처가 포함되며, 이는 PendingIntentHandler.retrieveProviderCreateCredentialRequest 함수를 사용하여 추출할 수 있습니다. API는 생성 요청과 관련된 모든 정보가 포함된 ProviderCreateCredentialRequest를 반환합니다. 두 가지 핵심 구성요소가 있습니다.

  • 요청을 보낸 앱입니다. getCallingAppInfo를 사용하여 검색할 수 있습니다.
  • 호출 앱의 요청입니다. CreateCredentialRequest를 반환하는 getCallingRequest를 사용하여 이를 가져올 수 있습니다. 요청이 디지털 사용자 인증 정보에 관한 요청인 경우 requestJson 속성에 발급 요청 JSON이 포함된 CreateDigitalCredentialRequest의 인스턴스입니다. 다음 샘플 코드로 이를 처리할 수 있습니다.
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)
}

키 증명

키 증명에 관해 다음 사항에 유의하세요.

  • 키 증명을 생성할 때 BigInteger.toByteArray를 사용하여 키 자료를 JSON 웹 키 등으로 변환할 수 있습니다. 이 메서드는 경우에 따라 부호 바이트를 추가하고 유효성 검사 오류를 일으킬 수 있습니다. 이 경우 발급기관에 키 증명을 전송하기 전에 이러한 바이트를 삭제하세요.
  • android_key_attestation를 키 증명 유형으로 사용하는 것이 좋습니다.

생성 응답 반환

월렛에서 사용자 인증 정보를 저장하는 데 필요한 단계를 완료하면 사용자 인증 정보 응답으로 활동을 완료합니다.

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

예외가 있는 경우 다음과 같이 사용자 인증 정보 예외를 전송할 수 있습니다.

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

컨텍스트에서 사용자 인증 정보 응답을 반환하는 전체 예는 샘플 앱을 참고하세요.