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

Aplica-se a: Inquilinos externos (saiba 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

• Inicie sessão para os utilizadores na aplicação móvel Android (Kotlin) de exemplo utilizando autenticação nativa.
• No centro de administração do Microsoft Entra, registre um novo aplicativo para sua API da Web com a seguinte configuração. Para obter etapas detalhadas, consulte Registrar um aplicativo. Registre a ID do aplicativo (cliente) e a ID do diretório (locatário) para uso posterior.
  • Nome: ciam-ToDoList-api.
  • Tipos de conta suportados: Contas somente neste diretório organizacional (Cliente único)

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 os seguintes passos:

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.Ler
   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

Saiba mais sobre o princípio de menor privilégio na publicação de permissões para uma API da Web.

Configurar funções do 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 obtenham 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 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'
   Deseja ativar esta função de aplicação?	Mantenha-o verificado

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'
   Deseja ativar esta função de aplicação?	Mantenha-o verificado

Configurar declarações opcionais

Você pode adicionar a declaração opcional idtyp para ajudar a API da web a determinar se um token é um token de aplicativo ou um token de aplicativo + usuário . 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 desta declaração é app quando o token é um token apenas de aplicação.

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 Configurações de permissões, selecione a permissão ToDoList.Read e a permissão 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 Directório (inquilino). Por exemplo, se o domínio principal do arrendatário for contoso.onmicrosoft.com, utilize 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