Credential Manager: API Holder

A API Credential Manager - Holder permite que apps Android gerenciem e apresentem credenciais digitais a verificadores.

Primeiros passos

Para usar a API Credential Manager - Holder, adicione as seguintes dependências ao script de build do módulo do app:

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

Registrar credenciais com o Gerenciador de credenciais

Uma carteira precisa registrar metadados de credenciais para que o Gerenciador de credenciais possa filtrar e mostrar essas informações no seletor de credenciais quando uma solicitação for recebida.

Figura 1. A interface das credenciais digitais.

A interface do seletor do Credential Manager

O formato desses metadados é transmitido para um RegisterCredentialsRequest. Crie um [RegistryManager][1] e registre as credenciais:

Neste exemplo, os metadados são compilados de um banco de dados de entradas de credenciais. Encontre uma referência na nossa carteira de amostra, que registra os metadados no carregamento do app. No futuro, a composição do banco de dados de credenciais será compatível com a API Jetpack. Nesse momento, você pode registrar os metadados de credenciais como estruturas de dados bem definidas.

O registro é mantido em todas as reinicializações do dispositivo. O novo registro do mesmo ID e tipo vai substituir o registro anterior. Portanto, você só precisa se registrar novamente quando os dados da sua credencial mudarem.

Opcional: criar um matcher

O Credential Manager é independente de protocolo. Ele trata o registro de metadados como um blob opaco e não verifica nem confere o conteúdo dele. Portanto, a carteira precisa fornecer um comparador, um binário executável que pode processar os próprios dados da carteira e gerar os metadados de exibição com base em uma solicitação recebida. O Credential Manager executa o matcher em um ambiente sandbox sem acesso à rede ou ao disco para que nada vaze para uma carteira antes que a interface seja renderizada para o usuário.

A API Credential Manager vai fornecer correspondências para protocolos conhecidos, como o OpenID4VP. Ele ainda não foi lançado oficialmente. Por enquanto, use nosso comparador de amostras para o protocolo OpenID4VP.

Processar uma credencial selecionada

Em seguida, a carteira precisa processar quando uma credencial é selecionada pelo usuário. É possível definir uma atividade que detecta o filtro de intent androidx.credentials.registry.provider.action.GET_CREDENTIAL. Nossa carteira de amostra demonstra esse procedimento.

O intent que inicia a atividade vai conter a solicitação do verificador e a origem da chamada, que pode ser extraída com a função PendingIntentHandler.retrieveProviderGetCredentialRequest. A API retorna um ProviderGetCredentialRequest que contém todas as informações associadas à solicitação de verificação. Há três componentes principais:

• O app que fez a solicitação. É possível recuperar isso com getCallingAppInfo.
• A credencial selecionada. Você pode saber qual candidato o usuário escolheu usando o método de extensão selectedEntryId, que corresponde ao ID da credencial registrada.
• Quaisquer solicitações específicas feitas pelo verificador. Você encontra esse ID no método getCredentialOptions. Nesse caso, você vai encontrar um GetDigitalCredentialOption nessa lista, contendo a solicitação de credenciais digitais.

Normalmente, o verificador faz uma solicitação de apresentação de credencial digital para que você possa processá-la com o seguinte exemplo de código:

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

Confira um exemplo na nossa carteira de amostra.

Renderizar a interface da carteira

Depois que a credencial é selecionada, a carteira é invocada e o usuário é levado pela interface dela. No exemplo, é um comando biométrico.

Retornar a resposta de credencial

Quando a carteira estiver pronta para enviar o resultado, conclua a atividade com a resposta da credencial:

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

Se houver uma exceção, você poderá enviar a exceção de credencial da mesma forma:

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

Consulte o app de exemplo para ver como retornar a resposta de credencial no contexto.