Compartilhar via

Inicie sessão de utilizadores e chame uma API numa aplicação Android de exemplo usando autenticação nativa

  • Artigo

Aplica-se a: Círculo branco com um símbolo X cinza. Os locatários do Workforce círculo verde com um símbolo de marca de seleção branco. Inquilinos externos (saber mais)

Neste guia de início rápido, você aprenderá a 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 clientes, utilize o ícone Configurações no menu superior para alternar para o seu cliente externo a partir do menu Diretórios + subscrições.

  3. Navegue até Identidade>Aplicações>Registos de Aplicações.

  4. Selecione + Novo registo.

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

    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 Registrar para criar o aplicativo.

  7. O painel de Visão Geral do aplicativo é exibido quando o registo está concluído. Registre o de 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

Para que os aplicativos cliente possam obter com sucesso um token de acesso para um usuário, uma API precisa publicar pelo menos um escopo, também chamado de Permissão Delegada. Para publicar um escopo, siga estas etapas:

  1. Na página Registos de aplicações, seleccione a aplicação API que criou (ciam-ToDoList-api) para abrir a sua página Visão Geral.

  2. Em Gerenciar, selecione Expor uma API.

  3. Na parte superior da página, ao lado de URI de ID do Aplicativo, selecione o link Adicionar para gerar um URI exclusivo para esta aplicação.

  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:

    Propriedade Valor
    Nome do escopo ToDoList.Read
    Quem pode consentir apenas administradores
    Nome de exibição do consentimento do administrador Leia a lista de ToDo dos usuários usando o 'TodoListApi'
    Descrição do consentimento do administrador Permitir que a aplicação leia a lista de tarefas do utilizador 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 guardar as suas alterações:

    Propriedade Valor
    Nome do escopo ListaDeTarefas.LerEscrever
    Quem pode consentir apenas administradores
    Nome de exibição do consentimento do administrador Ler e escrever a lista de tarefas dos utilizadores usando a 'ToDoListApi'
    Descrição do consentimento do administrador Permitir que a aplicação leia e escreva a lista de tarefas do utilizador usando a 'ToDoListApi'
    Estado ativado

  8. Em Gerir, selecione Manifest de modo a abrir o editor de manifestos da API.

  9. Defina a propriedade accessTokenAcceptedVersion como 2.

  10. Selecione Salvar.

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

Configurar funções do aplicativo

Uma API precisa publicar pelo menos uma função aplicacional, também chamada de Permissão de Aplicação , para que as aplicações cliente obtenham um token de acesso em seu próprio nome. 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 por conta própria e não necessitem que os utilizadores iniciem sessão. Para publicar uma permissão de aplicativo, execute estas etapas:

  1. Na página de Registos de aplicações, selecione a aplicação que criou (como ciam-ToDoList-api) para abrir a sua página de Resumo .

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

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

    Propriedade Valor
    Nome de exibição ToDoList.Read.All
    Tipos de membros permitidos Aplicações
    Valor ToDoList.Read.All
    Descrição Permita que o aplicativo leia a lista de ToDo de cada usuário usando o '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 as alterações:

    Propriedade Valor
    Nome de exibição ToDoList.ReadWrite.All
    Tipos de membros permitidos Aplicações
    Valor ToDoList.ReadWrite.All
    Descrição Permita que a aplicação leia e escreva as listas de tarefas de cada utilizador usando a 'ToDoListApi'

Configurar declarações opcionais

Você pode adicionar a reivindicação opcional idtyp para ajudar a API da Web a determinar se um token é um token de aplicativo ou um token de aplicativo e de utilizador. Embora possas usar uma combinação de scp e funções para a mesma finalidade, usar a claim idtyp é a maneira mais fácil de distinguir entre um token de aplicação e um token de aplicação + utilizador. Por exemplo, o valor dessa declaração é de aplicativo quando o token é um token somente de aplicativo.

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 Registos de Aplicações, selecione a aplicação que criou (como ciam-client-app) para abrir a sua página de Resumo.

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

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

  4. Selecione o separador APIs que a minha organização utiliza.

  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 Atualizare, em seguida, verifique se Concedido para <o nome do locatário> aparece em Status para ambas as permissões.

  10. Na lista de permissões configuradas, selecione o ToDoList.Read e as permissões 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

  • Baixe o arquivo .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ódigo, abra o arquivo 2-Authorization/1-call-own-api-aspnet-core-mvc/ToDoListAPI/appsettings.json.

  2. Encontre o espaço reservado:

    • Enter_the_Application_Id_Here e substitua pelo ID de Aplicação (cliente) da API da Web que copiou anteriormente.
    • Enter_the_Tenant_Id_Here e substitua pelo ID do Diretório (locatário) que copiou 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 a sua API web para que a aplicação de exemplo Android a possa chamar. Siga Guia de início rápido: implantar um aplicativo Web ASP.NET para implantar a sua API da Web.

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

O exemplo permite configurar múltiplos endpoints de URL de API Web e conjuntos de permissões. Neste caso, configura-se apenas um ponto de extremidade de URL da API Web e os seus âmbitos associados.

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

  2. Encontre a propriedade chamada WEB_API_URL_1 e defina o 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 chamada 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

Tutorial: Prepare seu aplicativo Android para autenticação nativa.