Configurar o compartilhamento de credenciais integrado em sites e apps Android

1. Visão geral

Seus usuários acessam seu serviço em sites e apps Android? Obrigar os usuários a fazer login separadamente em cada plataforma cria atrito desnecessário e pode levar a desistências.

Os Digital Asset Links (DAL) resolvem isso permitindo que você declare associações entre seus sites e apps. Isso permite que gerenciadores de senhas, como o Gerenciador de Senhas do Google, compartilhem senhas e chaves de acesso salvas entre si.

Especificamente, a configuração do arquivo Digital Asset Links exige relações diferentes, dependendo do que você quer compartilhar:

• Para senhas: incluir delegate_permission/common.get_login_creds permite que os gerenciadores de senhas compartilhem senhas salvas entre seu site e app.
• Para chaves de acesso: como elas estão estritamente vinculadas a um domínio da Web específico, o Android exige comprovação de propriedade do domínio. Portanto, você precisa incluir delegate_permission/common.handle_all_urls. Embora você possa reconhecer isso como a permissão usada para Links do App Android (links diretos), também é o requisito estrito para permitir que chaves de acesso criadas em uma plataforma sejam usadas na outra.

O resultado? Os usuários podem fazer login sem problemas em todas as plataformas afiliadas usando as senhas ou chaves de acesso salvas para apenas uma delas.

Implementar o compartilhamento de credenciais integrado pode melhorar significativamente a experiência do usuário. Por exemplo, o eBay teve um aumento de 10% no sucesso do login depois de implementar a DAL para compartilhamento de credenciais.

Neste codelab, você vai aprender a usar os Digital Asset Links para ativar o compartilhamento de credenciais entre seu site e app Android.

Pré-requisitos

• Conhecimento básico de JSON e desenvolvimento para Android.
• Familiaridade com os pré-requisitos do Credential Manager do Android.

O que você vai aprender

• Como configurar o compartilhamento de credenciais usando o Google Play Console (recomendado).
• Como criar manualmente um arquivo assetlinks.json.
• Como configurar um app Android para associação manual.
• Como ativar chaves de acesso em um app Android associando-o a um domínio de site.
• Como usar ferramentas para gerar e validar sua configuração.

O que é necessário

• Um site: a capacidade de hospedar um arquivo JSON em https://{your-domain}/.well-known/assetlinks.json.
• Um app Android:
  • Para o método do Play Console: um app publicado no Google Play.
  • Para o método manual: um projeto do Android que pode ser modificado e criado. Para que o compartilhamento de credenciais com o Gerenciador de senhas do Google funcione, o app precisa ser publicado no Google Play.

Como funciona

Para que o compartilhamento de credenciais funcione, é preciso estabelecer uma confiança bidirecional:

1. Web -> app: seu site precisa hospedar um arquivo assetlinks.json declarando que confia no seu app Android.
2. App -> Web: seu app Android precisa ser configurado para confiar no seu site.

Vamos abordar duas maneiras de fazer isso: a automática usando o Google Play Console (recomendado) e a manual usando Digital Asset Links diretamente.

2. Configurar usando o Google Play Console (recomendado)

A maneira mais fácil de ativar o compartilhamento de credenciais entre seu site e app Android é pelo Google Play Console. Com esse método, é possível associar o app ao site sem precisar modificar o manifesto do app ou publicar uma nova versão dele. O Google Play gerencia a associação do lado do app para você.

Pré-requisitos

• Permissões do Play Console para acessar a página Links diretos.
• Capacidade de publicar um arquivo /.well-known/assetlinks.json no seu domínio.

Para mais informações sobre links diretos, consulte Links do App Android.

Etapas

1. No Play Console, acesse Crescimento > Links diretos.
2. Se o domínio não estiver listado, clique em Adicionar domínio em Configuração do app.
3. Encontre seu domínio e localize a coluna Compartilhamento de credenciais. Clique em Ativar (ou confira se a opção Ativar o compartilhamento de credenciais está ativada para novos domínios).
4. Copie o snippet JSON gerado pelo Play Console.
5. Publique este conteúdo JSON em https://{your-domain}/.well-known/assetlinks.json. Se você já tiver esse arquivo, adicione a nova instrução a ele.
6. De volta ao Play Console, clique em Criar associação de sites ou Ativar compartilhamento de credenciais.

O Play Console vai verificar sua configuração de hospedagem.

Para que o compartilhamento de credenciais funcione, o host do seu site precisa atender aos seguintes requisitos:

• O URL está acessível por HTTPS.
• O servidor responde com Content-Type: application/json.
• O URL pode ser acessado sem redirecionamentos.

Depois da verificação, o compartilhamento de credenciais fica ativo. As mudanças de configuração podem levar de uma a duas semanas para serem propagadas.

3. Configurar manualmente usando Digital Asset Links

Precisa de mais controle? Ou não tem acesso ao Play Console? É possível configurar o compartilhamento de credenciais entre seu site e app Android manualmente. Isso envolve duas tarefas principais: hospedar o arquivo JSON no seu site e atualizar o manifesto do app Android.

Importante: para que o Gerenciador de senhas do Google compartilhe credenciais com seu app, ele precisa ser publicado no Google Play, mesmo que você configure Digital Asset Links manualmente. O compartilhamento de credenciais não funciona para apps criados localmente que não são publicados no Google Play.

1. Gerar a impressão digital do app

Antes de configurar o compartilhamento de credenciais integrado, verifique se você tem o seguinte para cada plataforma:

Para cada app Android:

• O ID do app Android, conforme declarado no arquivo build.gradle do app.
• As impressões digitais SHA256 do certificado de assinatura.
• (Recomendado) Login do usuário implementado com a API Credential Manager.

2. Criar o arquivo de associação

Você precisa criar um arquivo assetlinks.json que declare as relações entre seu site e app. Use delegate_permission/common.get_login_creds para conceder permissão para compartilhar senhas e delegate_permission/common.handle_all_urls para ativar links diretos e compartilhar chaves de acesso.

Crie um arquivo chamado assetlinks.json com o conteúdo a seguir. Substitua os valores de exemplo pelo URL do seu site, nome do pacote e impressão digital:

[{
  "relation": [
    "delegate_permission/common.handle_all_urls",
    "delegate_permission/common.get_login_creds"
    ],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

O sha256_cert_fingerprints é uma matriz. Portanto, é possível incluir impressões digitais para várias chaves de assinatura, se necessário (por exemplo, chaves de depuração e de lançamento ou chaves para diferentes versões do app).

3. Hospedar o arquivo

Faça upload do arquivo assetlinks.json para o diretório .well-known na raiz do seu domínio.

Local: https://{your-domain}/.well-known/assetlinks.json

Para que o compartilhamento de credenciais funcione, o host do seu site precisa atender aos seguintes requisitos:

• O URL está acessível por HTTPS.
• O servidor responde com Content-Type: application/json.
• O URL pode ser acessado sem redirecionamentos.

4. Configurar o app Android

Agora, diga ao seu app Android para confiar no site. Você vai adicionar uma referência no manifesto que aponta para um arquivo de recursos contendo seu URL assetlinks.json.

1. Adicionar um recurso de string

Em res/values/strings.xml, adicione uma nova string asset_statements. Observe as aspas de escape.

<resources>
    <string name="asset_statements" translatable="false">
      [{
        \"include\": \"https://www.example.com/.well-known/assetlinks.json\"
      }]
    </string>
</resources>

2. Adicionar metadados ao manifesto

Em AndroidManifest.xml, adicione uma tag <meta-data> dentro do elemento <application> que faz referência a este recurso de string:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="asset_statements"
            android:resource="@string/asset_statements" />

        <activity android:name=".MainActivity">
                <intent-filter>
                    <action android:name="android.intent.action.MAIN" />
                    <category android:name="android.intent.category.LAUNCHER" />
                </intent-filter>
            </activity>
        </application>
    </manifest>

Depois de concluir essas etapas e publicar uma nova versão do seu app Android, os gerenciadores de senhas que oferecem suporte a Digital Asset Links (como o Gerenciador de senhas do Google) poderão sugerir credenciais salvas para www.example.com quando o usuário tentar fazer login em com.example.app e vice-versa.

As mudanças de configuração podem levar de uma a duas semanas para serem propagadas.

4. Verificar sua configuração

Antes de enviar, é fundamental verificar sua configuração de Digital Asset Links. JSON incorreto ou arquivos inacessíveis vão falhar sem aviso.

Use a ferramenta oficial Gerador e validador de declarações.

1. Insira o domínio do site e o nome do pacote do app.
2. Clique em Extrato de teste.
3. A ferramenta vai verificar se o arquivo assetlinks.json está hospedado corretamente e contém a associação válida.

5. Compartilhamento de credenciais entre vários sites

Se você tiver vários sites compartilhando o mesmo sistema de login (por exemplo, example.com e example.co.uk), poderá declará-los como afiliados para que as credenciais sejam compartilhadas entre eles.

Compartilhar senhas entre vários sites

Para compartilhar senhas entre sites, declare uma associação web para web usando delegate_permission/common.get_login_creds.

Por exemplo, para que example.com compartilhe senhas com example.co.uk, o arquivo assetlinks.json hospedado em https://example.com/.well-known/assetlinks.json precisa incluir uma declaração direcionada a example.co.uk:

[{
  "relation": ["delegate_permission/common.get_login_creds"],
  "target": {
    "namespace": "web",
    "site": "https://example.co.uk"
  }
}]

Da mesma forma, https://example.co.uk/.well-known/assetlinks.json precisa incluir uma declaração de segmentação example.com.

Observação: embora o Chrome compartilhe automaticamente as credenciais salvas entre sites do mesmo site (por exemplo, www.example.com e m.example.com), o compartilhamento entre sites e apps Android (incluindo App WebViews) funciona de maneira diferente. Para a integração de apps, é necessário configurar os Digital Asset Links (DALs) colocando um arquivo assetlinks.json válido em /.well-known/assetlinks.json no subdomínio em que os logins acontecem para ativar o compartilhamento de credenciais.

Compartilhar chaves de acesso entre vários sites

Para permitir que vários sites compartilhem as mesmas chaves de acesso, eles precisam usar o mesmo ID da parte confiável (RP ID). No WebAuthn e nas chaves de acesso, o ID da RP especifica o escopo de uma credencial por nome de domínio. Quando você cria uma chave de acesso, ela é vinculada a um ID de RP específico e só pode ser usada em domínios que estão dentro do escopo desse ID. Definir o ID da RP corretamente garante uma experiência de chave de acesso integrada em subdomínios, origens entre sites e apps móveis próprios. Saiba mais sobre como definir o ID da RP em Entender o ID da parte confiável (RP ID). Com as Solicitações de origem relacionadas, um site pode especificar outras origens autorizadas a usar o ID do RP dele, permitindo que os usuários reutilizem a mesma chave de acesso em vários sites que você opera. Note que isso é diferente do compartilhamento de chaves de acesso entre um site e um app Android, que usa delegate_permission/common.handle_all_urls em Digital Asset Links.

Por exemplo, se você quiser que example.com e example.co.uk compartilhem chaves de acesso, poderá decidir que example.com será o ID da RP canônico. Para que isso funcione, example.co.uk precisa usar rpId: 'example.com' nas chamadas da API WebAuthn, e example.com precisa hospedar um arquivo em https://example.com/.well-known/webauthn para permitir example.co.uk:

{
  "origins": [
    "https://example.co.uk"
  ]
}

Isso permite que o example.co.uk crie e use chaves de acesso associadas ao example.com.

O Gerenciador de senhas trata as relações de compartilhamento de credenciais como transitivas. Se as entidades A e B (que podem ser sites ou apps) forem afiliadas à entidade C, A e B também vão compartilhar credenciais automaticamente entre si.

6. Conclusão

Parabéns! Você configurou o compartilhamento de credenciais integrado.

Agora os usuários podem salvar uma senha e uma chave de acesso no seu site e usá-las para fazer login no app Android com um único toque (e vice-versa). Essa simples mudança pode aumentar significativamente as taxas de conversão de login e a satisfação do usuário.

A seguir

• Confira a documentação oficial do Digital Asset Links.
• Saiba mais sobre os fundamentos do compartilhamento de credenciais.
• Leia o estudo de caso do eBay para conferir o impacto.