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

  • Artigo

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

Pré-requisitos

Registrar um aplicativo de API da Web

  1. Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.

  2. Se tiver acesso a vários inquilinos, utilize o ícone Definições no menu superior para mudar para o inquilino externo a partir do menu Diretórios + subscrições.

  3. Navegue até Registros do aplicativo Identity>Applications>.

  4. Selecione + Novo registo.

  5. Na página Registar uma candidatura apresentada, introduza as informações de registo da sua candidatura:

    1. Na seção Nome, insira um nome de aplicativo significativo que será exibido para os usuários do aplicativo, por exemplo , ciam-ToDoList-api.

    2. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional.

  6. Selecione Registar para criar a aplicação.

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

Configurar escopos de API

Uma API precisa publicar no mínimo 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 aplicativos, selecione o aplicativo de API que você criou (ciam-ToDoList-api) para abrir sua página Visão geral.

  2. Em Gerenciar, selecione Expor uma API.

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

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

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

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

    Property valor
    Nome do âmbito ToDoList.Leia
    Quem pode consentir Apenas administradores
    Nome a apresentar do consentimento do administrador Leia a lista de ToDo dos usuários usando o 'TodoListApi'
    Descrição do consentimento do administrador Permita que o aplicativo leia a lista de ToDo do usuário usando o 'TodoListApi'.
    Estado Ativado

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

    Property valor
    Nome do âmbito ToDoList.ReadWrite
    Quem pode consentir Apenas administradores
    Nome a apresentar do consentimento do administrador Leia e escreva a lista de ToDo dos usuários usando o 'ToDoListApi'
    Descrição do consentimento do administrador Permitir que o aplicativo leia e escreva a lista de ToDo do usuário usando o 'ToDoListApi'
    Estado Ativado

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

  9. Defina accessTokenAcceptedVersion a propriedade como 2.

  10. Selecione Guardar.

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

Configurar funções do aplicativo

Uma API precisa publicar um mínimo de uma função de aplicativo para aplicativos, também chamada de Permissão de Aplicativo, para que os aplicativos cliente obtenham um token de acesso como eles mesmos. 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 entrar usuários. Para publicar uma permissão de aplicativo, execute estas etapas:

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

  2. Em Gerir, selecione Funções da aplicação.

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

    Property valor
    Display name ToDoList.Read.All
    Tipos de membros permitidos Aplicações
    Value ToDoList.Read.All
    Description Permita que o aplicativo leia a lista de ToDo de cada usuário usando o 'TodoListApi'

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

    Property valor
    Display name ToDoList.ReadWrite.All
    Tipos de membros permitidos Aplicações
    Value ToDoList.ReadWrite.All
    Description Permita que o aplicativo leia e escreva a lista de ToDo de cada usuário usando o 'ToDoListApi'

Configurar afirmações opcionais

Você pode idtyp declaração opcional para ajudar a API da Web a determinar se um token é um token de aplicativo ou um token de aplicativo + de usuário. Embora você possa usar uma combinação de declarações scp e roles 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 app.

Conceder permissões de API para o aplicativo de exemplo Android

Depois de registrar seu aplicativo cliente e a API da 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 aplicativos, selecione o aplicativo que você criou (como ciam-client-app) para abrir a 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 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 é locatário de um 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 no locatário:

    1. Selecione Conceder consentimento de administrador para <o nome> do seu inquilino e, em seguida, selecione Sim.

    2. Selecione Atualizar e verifique se Concedido para <o nome> do 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 total é semelhante a api://{clientId}/{ToDoList.Read} ou api://{clientId}/{ToDoList.ReadWrite}.

Clonar ou baixar exemplo de API da Web

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 digite o seguinte comando:

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

  • Transfira o ficheiro .zip. Extraia-o para um caminho de arquivo onde o comprimento do nome é inferior a 260 caracteres.

Configurar e executar API Web de exemplo

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

  2. Encontre o espaço reservado:

    • Enter_the_Application_Id_Heree substitua-o pelo ID do aplicativo (cliente) da API da Web que você copiou anteriormente.
    • Enter_the_Tenant_Id_Heree substitua-o pelo ID do diretório (locatário) copiado anteriormente.
    • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do locatário for contoso.onmicrosoft.com, use contoso. Se não tiver o nome do inquilino, saiba como ler os detalhes do inquilino.

Você precisa hospedar sua API da Web para o aplicativo de exemplo Android chamá-lo. Siga Guia de início rápido: implante um aplicativo Web ASP.NET para implantar sua API Web.

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

O exemplo permite configurar vários pontos de extremidade de URL de 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 /app/src/main/java/com/azuresamples/msalnativeauthandroidkotlinsampleapp/AccessApiFragment.kt ficheiro.

  2. Encontre a propriedade nomeada WEB_API_URL_1 e defina a URL para sua API da Web.

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

  3. Encontre a propriedade nomeada scopesForAPI1 e defina os escopos registrados em Conceder permissões de API para o aplicativo de exemplo 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 da Web

Para criar e executar seu aplicativo, siga estas etapas:

  1. Na barra de ferramentas, selecione seu aplicativo no menu Executar configurações.

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

    Se você não tiver nenhum dispositivo configurado, será necessário criar um dispositivo virtual Android para usar o emulador Android ou conectar um dispositivo físico.

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

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

Próximos passos