인증 관리자 - Holder API

인증 관리자 - 보유자 API를 사용하면 Android 앱이 디지털 사용자 인증 정보를 관리하고 인증 기관에 제공할 수 있습니다.

시작하기

인증 관리자 - 보유자 API를 사용하려면 앱 모듈의 빌드 스크립트에 다음 종속 항목을 추가하세요.

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

인증 관리자로 사용자 인증 정보 등록

지갑은 요청이 들어올 때 사용자 인증 정보 관리자가 사용자 인증 정보를 필터링하고 사용자 인증 정보 선택기에 표시할 수 있도록 사용자 인증 정보 메타데이터를 등록해야 합니다.

인증 관리자의 디지털 사용자 인증 정보 UI를 보여주는 이미지
그림 1. 디지털 인증 UI

인증 관리자 선택기 UI

이 메타데이터의 형식은 RegisterCredentialsRequest에 전달됩니다. [RegistryManager][1]를 만들고 사용자 인증 정보를 등록합니다.

이 예에서는 사용자 인증 정보 항목의 데이터베이스에서 메타데이터가 컴파일됩니다. 앱 로드 시 메타데이터를 등록하는 샘플 지갑의 참조를 확인할 수 있습니다. 향후에는 Jetpack API에서 사용자 인증 정보 데이터베이스 구성을 지원할 예정입니다. 이때 사용자 인증 정보 메타데이터를 잘 정의된 데이터 구조로 등록할 수 있습니다.

레지스트리는 기기 재부팅 시 유지됩니다. 동일한 ID + 유형의 동일한 레지스트리를 다시 등록하면 이전 레지스트리 레코드가 덮어쓰여집니다. 따라서 사용자 인증 정보 데이터가 변경된 경우에만 다시 등록하면 됩니다.

선택사항: 매처 만들기

인증 관리자는 프로토콜에 구애받지 않습니다. 메타데이터 레지스트리를 불투명한 blob으로 취급하며 콘텐츠를 확인하거나 검사하지 않습니다. 따라서 지갑은 지갑의 자체 데이터를 처리하고 수신 요청에 따라 표시 메타데이터를 생성할 수 있는 실행 가능한 바이너리인 매처를 제공해야 합니다. 사용자 인증 정보 관리자는 네트워크 또는 디스크 액세스 없이 샌드박스 환경에서 매처를 실행하므로 UI가 사용자에게 렌더링되기 전에 지갑으로 유출되는 항목이 없습니다.

Credential Manager API는 오늘날 OpenID4VP와 같은 인기 프로토콜의 매처를 제공합니다. 아직 공식적으로 출시되지 않았으므로 현재는 OpenID4VP 프로토콜에 샘플 매처를 사용하세요.

선택한 사용자 인증 정보 처리

다음으로, 지갑은 사용자가 사용자 인증 정보를 선택할 때 이를 처리해야 합니다. androidx.credentials.registry.provider.action.GET_CREDENTIAL 인텐트 필터를 수신하는 활동을 정의할 수 있습니다. 샘플 지갑에서 이 절차를 보여줍니다.

활동을 실행하는 인텐트에는 인증자 요청과 호출 출처가 포함되며, 이는 PendingIntentHandler.retrieveProviderGetCredentialRequest 함수로 추출할 수 있습니다. API는 지정된 인증 기관 요청과 관련된 모든 정보가 포함된 ProviderGetCredentialRequest를 반환합니다. 세 가지 주요 구성요소가 있습니다.

  • 요청을 한 앱입니다. getCallingAppInfo을 사용하여 이를 검색할 수 있습니다.
  • 선택한 사용자 인증 정보입니다. selectedEntryId 확장 프로그램 메서드를 통해 사용자가 선택한 후보에 관한 정보를 확인할 수 있습니다. 이는 등록한 사용자 인증 정보 ID와 일치합니다.
  • 인증자가 요청한 사항이 있는 경우 getCredentialOptions 메서드에서 가져올 수 있습니다. 이 경우 디지털 사용자 인증 정보 요청이 포함된 GetDigitalCredentialOption이 목록에 표시됩니다.

일반적으로 인증 기관은 디지털 사용자 인증 정보 제출 요청을 하므로 다음 샘플 코드로 처리할 수 있습니다.

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

샘플 월렛에서 이 예시를 확인할 수 있습니다.

월렛 UI 렌더링

사용자 인증 정보가 선택되면 지갑이 호출되고 사용자가 지갑의 UI를 통해 안내됩니다. 샘플에서는 생체 인식 프롬프트입니다.

사용자 인증 정보 응답 반환

지갑이 결과를 다시 보낼 준비가 되면 사용자 인증 정보 응답으로 활동을 완료하여 결과를 보낼 수 있습니다.

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

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

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

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