Partilhar via

Inicie sessão de utilizadores e chame uma API Web protegida na aplicação Android (Kotlin) de exemplo

  • Artigo

Este guia demonstra como configurar um aplicativo móvel Android de exemplo para entrar usuários e chamar uma API da Web ASP.NET Core.

Neste artigo, você executa as seguintes tarefas:

  • Registe uma aplicação no centro de administração do Microsoft Entra.
  • Adicione um URL de redirecionamento de plataforma.
  • Habilite fluxos de clientes públicos.
  • Atualize o arquivo de exemplo de código de configuração do Android para usar sua própria ID externa do Microsoft Entra para obter detalhes do locatário do cliente.
  • Execute e teste o aplicativo móvel Android de exemplo.
  • Chame uma API da Web protegida.

Pré-requisitos

  • Android Studio.

  • Um locatário externo. Se ainda não tiver uma, inscreva-se para uma avaliação gratuita.

  • Um registro de API que expõe pelo menos um escopo (permissões delegadas) e uma função de aplicativo (permissão de aplicativo), como ToDoList.Read. Se ainda não o fez, siga as instruções para chamar uma API em um aplicativo móvel Android de exemplo para ter uma API da Web ASP.NET Core protegida funcionalmente. Certifique-se de concluir as seguintes etapas:

    • Registrar um aplicativo de API da Web
    • Configurar escopos de API
    • Configurar funções do aplicativo
    • Configurar afirmações opcionais
    • Clonar ou baixar exemplo de API da Web
    • Configurar e executar API Web de exemplo

Registar uma aplicação

Para permitir que seu aplicativo entre usuários com o Microsoft Entra, a ID Externa do Microsoft Entra deve estar ciente do aplicativo criado. O registo da aplicação estabelece uma relação de confiança entre a aplicação e o Microsoft Entra. Quando você registra um aplicativo, o ID externo gera um identificador exclusivo conhecido como ID do aplicativo (cliente), um valor usado para identificar seu aplicativo ao criar solicitações de autenticação.

As etapas a seguir mostram como registrar seu aplicativo no centro de administração do Microsoft Entra:

  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 que aparece;

    1. Insira um Nome de aplicativo significativo que é exibido para os usuários do aplicativo, por exemplo, ciam-client-app.
    2. Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional.

  6. Selecione Registar.

  7. O painel Visão geral do aplicativo é exibido após o registro bem-sucedido. Registre o ID do aplicativo (cliente) a ser usado no código-fonte do aplicativo.

Adicionar um URL de redirecionamento de plataforma

Para especificar o tipo de aplicativo para o registro do aplicativo, siga estas etapas:

  1. Em Gerir, selecione Autenticação.
  2. Na página Configurações da plataforma, selecione Adicionar uma plataforma e, em seguida, selecione a opção Android.
  3. Insira o nome do pacote do seu projeto. Se você baixou o código de exemplo, esse valor é com.azuresamples.msaldelegatedandroidkotlinsampleapp.
  4. Na seção Hash de assinatura do painel Configurar seu aplicativo Android, selecione Gerando um hash de assinatura de desenvolvimento. Isso mudará para cada ambiente de desenvolvimento. Copie e execute o comando KeyTool para o seu sistema operativo no seu Terminal.
  5. Introduza o Hash de assinatura gerado pelo KeyTool.
  6. Selecione Configurar.
  7. Copie a Configuração do MSAL do painel de configuração do Android e salve-a para configuração posterior do aplicativo.
  8. Selecionar Concluído.

Habilitar o fluxo público de clientes

Para identificar seu aplicativo como um cliente público, siga estas etapas:

  1. Em Gerir, selecione Autenticação.

  2. Em Configurações avançadas, para Permitir fluxos de clientes públicos, selecione Sim.

  3. Selecione Guardar para guardar as alterações.

  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. Na lista Permissões configuradas, seu aplicativo recebeu a permissão User.Read. No entanto, como o locatário é um locatário externo, os próprios usuários consumidores não podem consentir com essa permissão. Você, como administrador, deve consentir com essa permissão 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 ambos os escopos.

Conceder permissões de API da Web para o aplicativo de exemplo do 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}.

Clone exemplo de aplicativo móvel Android

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-browser-delegated-android-sample

Configurar o aplicativo móvel Android de exemplo

Para habilitar a autenticação e o acesso aos recursos da API da Web, configure o exemplo seguindo estas etapas:

  1. No Android Studio, abra o projeto clonado.

  2. Abra o arquivo /app/src/main/res/raw/auth_config_ciam.json .

  3. Encontre o espaço reservado:

    • Enter_the_Application_Id_Heree substitua-o pelo ID do aplicativo (cliente) do aplicativo que você registrou anteriormente.
    • Enter_the_Redirect_Uri_Heree substitua-o pelo valor de redirect_uri no arquivo de configuração da Biblioteca de Autenticação da Microsoft (MSAL) que você baixou anteriormente quando adicionou a URL de redirecionamento da plataforma.
    • 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 souber o subdomínio do inquilino, saiba como ler os detalhes do inquilino.

  4. Abra o arquivo /app/src/main/AndroidManifest.xml .

  5. Encontre o espaço reservado:

    • ENTER_YOUR_SIGNATURE_HASH_HERE e substitua-o pelo Hash de Assinatura que você gerou anteriormente quando adicionou a URL de redirecionamento da plataforma.

  6. Abra o arquivo /app/src/main/java/com/azuresamples/msaldelegatedandroidkotlinsampleapp/MainActivity.kt .

  7. Encontre a propriedade nomeada WEB_API_BASE_URL e defina a URL para sua API da Web.

  8. Encontre a propriedade nomeada scopes e defina os escopos registrados em Conceder permissões de API da Web para o aplicativo de exemplo Android.

    private const val scopes = "" // Developers should set the respective scopes of their web API here. For example, private const val scopes = "api://{clientId}/{ToDoList.Read} api://{clientId}/{ToDoList.ReadWrite}"

Você configurou o aplicativo e ele está pronto para ser executado.

Executar e testar o aplicativo móvel Android de exemplo

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, precisará criar um dispositivo virtual Android para usar o emulador Android ou conectar um dispositivo Android físico.

  3. Selecione o botão Run (Executar).

  4. Selecione Adquirir token interativamente para solicitar um token de acesso.

  5. Selecione API - Execute GET para chamar a API Web principal do ASP.NET configurada anteriormente. Uma chamada bem-sucedida para a API da Web retorna HTTP 200, enquanto HTTP 403 significa acesso não autorizado.

Conteúdos relacionados