Conectar usuários e chamar uma API Web protegida no aplicativo Android (Kotlin) de exemplo

  • Artigo

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

Neste artigo, você executará as seguintes tarefas:

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

Pré-requisitos

  • Android Studio.

  • Um locatário externo. Caso ainda não tenha uma, inscreva-se em 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. Caso você ainda não tenha feito isso, siga as instruções para chamar uma API em um aplicativo móvel Android de exemplo para ter uma API Web do ASP.NET Core funcional e protegida. Certifique-se de concluir as seguintes etapas:

    • Registrar um aplicativo da API Web
    • Configurar escopos de API
    • Configurar funções de aplicativo
    • Configurar declarações opcionais
    • Clonar ou fazer download da API Web de exemplo
    • Configurar e executar a API Web de exemplo

Registrar um aplicativo

Para permitir a entrada de usuários com o Microsoft Entra no seu aplicativo, a ID externa do Microsoft Entra deve estar ciente do aplicativo criado. O registro do aplicativo estabelece uma relação de confiança entre o aplicativo e o Microsoft Entra. Quando você registra um aplicativo, o External ID 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. 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;

    1. Insira um Nome de aplicativo relevante que será exibido aos usuários do aplicativo, por exemplo,ciam-client-app.
    2. Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.

  6. Selecione Registrar.

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

Adicionar uma URL de redirecionamento de plataforma

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

  1. Em Gerenciar, 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 será com.azuresamples.msaldelegatedandroidkotlinsampleapp.
  4. Na seção Hash de assinatura do painel Configurar seu aplicativo Android, selecione Como gerar um Hash de Assinatura de desenvolvimento. Isso mudará para cada ambiente de desenvolvimento. Copie e execute o comando KeyTool do seu sistema operacional em seu Terminal.
  5. Insira o Hash de assinatura gerado por KeyTool.
  6. Selecione Configurar.
  7. Copie a Configuração MSAL do painel de Configuração do Android e salve-a para configurar o aplicativo mais tarde.
  8. Selecione Concluído.

Habilitar fluxo de cliente público

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

  1. Em Gerenciar, selecione Autenticação.

  2. Em Configurações avançadas, na opção Permitir fluxos de clientes públicos, selecione Sim.

  3. Selecione Salvar para salvar as alterações.

Depois de registrar seu aplicativo, ele recebe a permissão User.Read. No entanto, como o locatário é externo, os próprios usuários clientes não podem consentir com esta permissão. Você, como administrador, deve consentir com essa permissão em nome de todos os usuários no locatário:

  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.

    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 a permissão.

Conceder permissões da API Web ao aplicativo Android de exemplo

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 um aplicativo móvel de exemplo do 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 insira o seguinte comando:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-android-sample

Configurar o aplicativo móvel de exemplo do Android

Para habilitar a autenticação e o acesso aos recursos da API 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. Localize o espaço reservado:

    • Enter_the_Application_Id_Here e substitua pela ID do Aplicativo (cliente) referente ao aplicativo registrado antes.
    • Enter_the_Redirect_Uri_Here e substitua-o pelo valor de redirect_uri no arquivo de configuração da Microsoft Authentication Library (MSAL) que você baixou anteriormente quando adicionou a URL de redirecionamento da plataforma.
    • 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 sabe o subdomínio do seu locatário, confira como ler os detalhes do locatário.

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

  5. Localize o espaço reservado:

    • ENTER_YOUR_SIGNATURE_HASH_HERE e substitua-o pelo Hash de assinatura que você gerou anteriormente ao adicionar o URL de redirecionamento da plataforma.

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

  7. Localize a propriedade chamada WEB_API_BASE_URL e defina a URL para sua API Web.

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

    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 de exemplo do Android

Para compilar 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 deseja executar seu aplicativo.

    Caso você não tenha nenhum dispositivo configurado, crie um AVD para usar o Android Emulator ou conecte um dispositivo Android físico.

  3. Selecione o botão Executar.

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

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

Conteúdo relacionado