Conectar usuários e chamar uma API em um aplicativo móvel de exemplo do Android usando a autenticação nativa

  • Artigo

Este artigo demonstra como configurar um aplicativo móvel de exemplo do Android para chamar uma API Web do ASP.NET Core.

Pré-requisitos

Registrar um aplicativo da API Web

  1. Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.

  2. Se tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o seu locatário externo no menu Diretórios + assinaturas.

  3. Navegue até Identidade>Aplicativos>Registros do aplicativo.

  4. Selecione + Novo Registro.

  5. Na página Registrar um aplicativo que aparece, insira as informações de registro do aplicativo:

    1. Na seção Nome, insira algo fácil de lembrar para ser exibido aos usuários do aplicativo, por exemplo, ciam-ToDoList-api.

    2. Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.

  6. Selecione Registrar para criar o aplicativo.

  7. O painel Visão geral do aplicativo é exibido quando o registro for concluído. Registre a ID do Diretório (locatário) e a ID do aplicativo (cliente) a ser usada no código-fonte do aplicativo.

Configurar escopos de API

Uma API precisa publicar um mínimo de um escopo, também chamado de permissão delegada, para que os aplicativos cliente obtenham um token de acesso para um usuário com êxito. Para publicar um escopo, siga estas etapas:

  1. Na página Registros de aplicativo, selecione o aplicativo de API que você criou (ciam-ToDoList-api) para abrir a respectiva página Visão geral.

  2. Em Gerenciar, selecione Expor uma API.

  3. Na parte superior da página, ao lado do URI da ID do Aplicativo, selecione o link Adicionar para gerar um URI exclusivo para esse aplicativo.

  4. Aceite o URI da ID do Aplicativo proposto, como api://{clientId}, e selecione Salvar. Quando o aplicativo Web solicita um token de acesso à API Web, ele adiciona esse URI como prefixo para cada escopo que você define para a API.

  5. Em Escopos definidos por esta API, selecione Adicionar um escopo.

  6. Digite os seguintes valores que definem um acesso de leitura à API e selecione Adicionar escopo para salvar as alterações:

    Propriedade Valor
    Nome do escopo ToDoList.Read
    Quem pode consentir Somente administradores
    Nome de exibição de consentimento do administrador Leia a lista de tarefas dos usuários usando a "TodoListApi"
    Descrição do consentimento do administrador Permita que o aplicativo leia a lista de tarefas do usuário usando a TodoListApi".
    Estado Enabled

  7. Selecione Adicionar um escopo novamente e digite os seguintes valores que definem um escopo de acesso de leitura e gravação à API. Selecione Adicionar escopo para salvar as alterações:

    Propriedade Valor
    Nome do escopo ToDoList.ReadWrite
    Quem pode consentir Somente administradores
    Nome de exibição de consentimento do administrador Leia e grave listas ToDo usando “ToDoListApi”
    Descrição do consentimento do administrador Permita que o aplicativo leia e grave na lista ToDo do usuário usando “ToDoListApi”
    Estado Enabled

  8. Em Gerenciar, selecione Manifesto para abrir o editor de manifesto da API.

  9. Defina a propriedade accessTokenAcceptedVersion como 2.

  10. Selecione Salvar.

Saiba mais sobre o princípio do privilégio mínimo ao publicar permissões para uma API Web.

Configurar funções de aplicativo

Uma API precisa publicar pelo menos uma função de aplicativo, também chamada de Permissão de Aplicativo, para que os aplicativos cliente possam obter um token de acesso em nome deles próprios. As permissões de aplicativo são o tipo de permissões que as APIs devem publicar quando desejam permitir que os aplicativos cliente se autentiquem com êxito como eles mesmos e não precisem conectar usuários. Para publicar uma permissão de aplicativo, siga estas etapas:

  1. Na página Registros de aplicativo, selecione o aplicativo que você criou (como ciam-ToDoList-api) para abrir sua página Visão geral.

  2. Em Gerenciar, selecione Funções do aplicativo.

  3. Selecione Criar função do aplicativo, insira os seguintes valores e selecione Aplicar para salvar suas alterações:

    Propriedade Valor
    Nome de exibição ToDoList.Read.All
    Tipos de membro permitidos Aplicativos
    Valor ToDoList.Read.All
    Descrição Permitir que o aplicativo leia a lista ToDo de cada usuário usando "TodoListApi"

  4. Selecione Criar função de aplicativo novamente, insira os seguintes valores para a segunda função de aplicativo e selecione Aplicar para salvar suas alterações:

    Propriedade Valor
    Nome de exibição ToDoList.ReadWrite.All
    Tipos de membro permitidos Aplicativos
    Valor ToDoList.ReadWrite.All
    Descrição Permitir que o aplicativo leia e grave na lista ToDo de cada usuário usando 'TodoListApi'

Configurar declarações opcionais

Você pode incluir a declaração opcional idtyp para ajudar a API Web a determinar se um token é um token de aplicativo ou um token de aplicativo + usuário. Embora você possa usar uma combinação de declarações scp e funções para a mesma finalidade, usar a declaração idtyp é a maneira mais fácil de diferenciar um token de aplicativo e um token de aplicativo + usuário. Por exemplo, o valor dessa declaração é app quando o token é um token somente de aplicativo.

Conceder permissões de API ao aplicativo de exemplo do Android

Depois de registrar o aplicativo cliente e a API Web e expor a API criando escopos, você pode configurar as permissões do cliente para a API seguindo estas etapas:

  1. Na página Registros de aplicativo, selecione o aplicativo que você criou (como ciam-client-app) para abrir sua página Visão geral.

  2. Em Gerenciar, selecione Permissões de API.

  3. Em Permissões Configuradas, selecione Adicionar uma permissão.

  4. Selecione a guia APIs que a minha organização usa.

  5. Na lista de APIs, selecione a API como ciam-ToDoList-api.

  6. Selecione a opção Permissões delegadas.

  7. Na lista de permissões, selecione ToDoList.Read, ToDoList.ReadWrite (use a caixa de pesquisa, se necessário).

  8. Selecione o botão Adicionar permissões.

  9. Neste ponto, você atribuiu as permissões corretamente. No entanto, como o locatário é um locatário do cliente, os próprios usuários consumidores não podem consentir com essas permissões. Para resolver isso, você, como administrador, deve consentir com essas permissões em nome de todos os usuários do locatário:

    1. Selecione Dar consentimento de administrador para <nome do seu locatário> e selecione Sim.

    2. Selecione Atualizar e verifique se Concedido para <nome do seu locatário> aparece em Status para ambas as permissões.

  10. Na lista Permissões configuradas, selecione as permissões ToDoList.Read e ToDoList.ReadWrite, uma de cada vez, e copie o URI completo da permissão para uso posterior. O URI de permissão completa é semelhante a api://{clientId}/{ToDoList.Read} ou api://{clientId}/{ToDoList.ReadWrite}.

Clonar ou fazer download da API Web de exemplo

Para obter o aplicativo de exemplo, você pode cloná-lo do GitHub ou baixá-lo como um arquivo .zip.

  • Para clonar o exemplo, abra um prompt de comando e navegue até onde deseja criar o projeto e insira o seguinte comando:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

  • Baixar o arquivo .zip. Extraia-o para um caminho de arquivo em que o comprimento do nome seja menor que 260 caracteres.

Configurar e executar a API Web de exemplo

  1. No seu editor de código, abra o arquivo 2-Authorization/1-call-own-api-aspnet-core-mvc/ToDoListAPI/appsettings.json.

  2. Localize o espaço reservado:

    • Enter_the_Application_Id_Here e substitua-o pela ID do Aplicativo (cliente) da API Web que você copiou anteriormente.
    • Enter_the_Tenant_Id_Here e substitua-o pela ID do Diretório (locatário) que você copiou anteriormente.
    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio do diretório (locatário). Por exemplo, se o domínio primário do locatário for contoso.onmicrosoft.com, use contoso. Se você não tiver o nome do locatário, saiba como ler os detalhes do locatário.

Você precisa hospedar sua API Web no aplicativo de exemplo do Android para chamá-la. Siga Início Rápido: implantar um aplicativo Web ASP.NET para implantar sua API Web.

Configurar um aplicativo móvel de exemplo do Android para chamar a API Web

O exemplo permite configurar vários pontos de extremidade de URL da API Web e conjuntos de escopos. Nesse caso, você configura apenas um ponto de extremidade de URL da API Web e seus escopos associados.

  1. No seu Android Studio, abra o arquivo /app/src/main/java/com/azuresamples/msalnativeauthandroidkotlinsampleapp/AccessApiFragment.kt.

  2. Localize a propriedade chamada WEB_API_URL_1 e defina a URL para sua API Web.

    private const val WEB_API_URL_1 = "" // Developers should set the respective URL of their web API here

  3. Localize a propriedade chamada scopesForAPI1 e defina os escopos registrados nas Permissões de API de concessão para o aplicativo de exemplo do Android.

    private val scopesForAPI1 = listOf<String>() // Developers should set the respective scopes of their web API here. For example, private val scopes = listOf<String>("api://{clientId}/{ToDoList.Read}", "api://{clientId}/{ToDoList.ReadWrite}")

Execute o aplicativo de exemplo do Android e chame a API Web

Para criar e executar seu aplicativo, siga estas etapas:

  1. Na barra de ferramentas, selecione o aplicativo no menu de configurações de execução.

  2. No menu do dispositivo de destino, selecione o dispositivo no qual você quer executar seu aplicativo.

    Caso você não tenha dispositivos configurados, crie um Android Virtual Device para usar o Android Emulator ou conecte um dispositivo Android físico.

  3. Selecione o botão Executar. O aplicativo é aberto no email e na tela de senha única.

  4. Selecione a guia API para testar a chamada à API. Uma chamada bem-sucedida na API Web retorna o HTTP 200, enquanto o HTTP 403 significa acesso não autorizado.

Próximas etapas