Partilhar via

Guia de início rápido: iniciar sessão de utilizadores numa aplicação móvel de exemplo

  • Artigo

Antes de começar, use o seletor Escolha um tipo de locatário na parte superior desta página para selecionar o tipo de locatário. O Microsoft Entra ID fornece duas configurações de inquilino, força de trabalho e externo . Uma estrutura de ambiente laboral é destinada aos seus colaboradores, aplicações internas e outros recursos organizacionais. Um inquilino externo é para as suas aplicações voltadas para os clientes.

Neste guia de início rápido, o utilizador descarrega e executa um exemplo de código que demonstra como uma aplicação Android pode iniciar sessão para utilizadores e obter um token de acesso para chamar a API do Microsoft Graph.

Os aplicativos devem ser representados por um objeto de aplicativo no Microsoft Entra ID para que a plataforma de identidade da Microsoft possa fornecer tokens para seu aplicativo.

Pré-requisitos

Registar a candidatura

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à sua solução manualmente, siga estas etapas:

  1. Entre no centro de administração do Microsoft Entra como no mínimo um Programador de Aplicações.

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

  3. Navegue até Identidade>Aplicativos>Registros de aplicativos.

  4. Selecione Novo registo.

  5. Introduza um Nome para a sua aplicação. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

  6. Para Tipos de conta suportados, selecione Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra - Multitenant) e contas pessoais da Microsoft (por exemplo, Skype, Xbox). Para obter informações sobre diferentes tipos de conta, selecione a opção Ajude-me a escolher.

  7. Selecione Registrar.

  8. Em Gerir, selecione Autenticação>Adicionar plataforma>Android.

  9. Insira o nome do pacote do seu projeto com base no tipo de exemplo que você baixou acima.

    • Exemplo Java - com.azuresamples.msalandroidapp
    • Amostra de Kotlin - com.azuresamples.msalandroidkotlinapp

  10. Na seção de hash de assinatura do painel Configurar a sua aplicação Android , selecione Gerar um hash de assinatura de desenvolvimento e copie o comando KeyTool para a sua linha de comandos.

    • KeyTool.exe é instalado como parte do Java Development Kit (JDK). Você também deve instalar a ferramenta OpenSSL para executar o comando KeyTool. Para obter mais informações, consulte documentação do Android sobre como gerar um de chave para obter mais informações.

  11. Insira o hash Signature gerado pelo KeyTool.

  12. Selecione Configurar e guarde a Configuração do MSAL que aparece no painel de configuração do Android para que possa inseri-la ao configurar a sua aplicação mais tarde.

  13. Selecione Concluído.

Obter a aplicação de exemplo

Configurar o aplicativo de exemplo

  1. No painel de projeto do Android Studio, navegue até app\src\main\res.

  2. Clique com o botão direito do mouse res e escolha New>Directory. Digite raw como o novo nome do diretório e selecione OK.

  3. Em aplicação>src>main>res>raw, vá para o arquivo JSON chamado auth_config_single_account.json e cole a configuração MSAL que guardou anteriormente.

    Abaixo do URI de redirecionamento, cole:

      "account_mode" : "SINGLE",

    Seu arquivo de configuração deve ser semelhante a este exemplo:

    {
  "client_id": "00001111-aaaa-bbbb-3333-cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D",
  "broker_redirect_uri_registered": true,
  "account_mode": "SINGLE",
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

    Como este tutorial demonstra apenas como configurar um aplicativo no modo de Conta Única, consulte modo de conta única versus múltipla e como configurar seu aplicativo para obter mais informações

Executar o aplicativo de exemplo

Selecione o seu emulador ou dispositivo físico na lista pendente de dispositivos disponíveis do Android Studio e execute a aplicação.

A aplicação de exemplo começa na tela Modo de Conta Única. Um escopo padrão, user.read, é fornecido por padrão, que é usado ao ler seus próprios dados de perfil durante a chamada à API do Microsoft Graph. A URL para a chamada da API do Microsoft Graph é fornecida por padrão. Você pode alterar ambos se desejar.

Captura de tela do aplicativo de exemplo MSAL mostrando o uso de uma e várias contas.

Use o menu do aplicativo para alternar entre os modos de conta única e múltipla.

No modo de conta única, inicie sessão com uma conta profissional ou doméstica:

  1. Selecione Obter dados do gráfico interativamente para solicitar ao usuário suas credenciais. Você verá a saída da chamada para a API do Microsoft Graph na parte inferior da tela.
  2. Depois de iniciar sessão, selecione Obter dados do gráfico silenciosamente para fazer uma chamada para a API do Microsoft Graph sem solicitar credenciais ao utilizador novamente. Você verá a saída da chamada para a API do Microsoft Graph na parte inferior da tela.

No modo de conta múltipla, você pode repetir as mesmas etapas. Além disso, você pode remover a conta conectada, que também remove os tokens armazenados em cache para essa conta.

Como funciona a amostra

Diagrama mostrando como funciona o aplicativo de exemplo gerado por este início rápido.

O código é organizado em fragmentos que mostram como escrever um aplicativo MSAL de contas únicas e múltiplas. Os arquivos de código são organizados da seguinte forma:

Ficheiro Demonstra
Atividade Principal Gerencia a interface do usuário
MSGraphRequestWrapper Chama a API do Microsoft Graph usando o token fornecido pela MSAL
FragmentoModoDeMúltiplasContas Inicializa um aplicativo de várias contas, carrega uma conta de usuário e obtém um token para chamar a API do Microsoft Graph
SingleAccountModeFragment Inicializa um aplicativo de conta única, carrega uma conta de usuário e obtém um token para chamar a API do Microsoft Graph
res/auth_config_multiple_account.json O arquivo de configuração de várias contas
res/auth_config_single_account.json O arquivo de configuração de conta única
Gradle Scripts/build.grade (Módulo:aplicativo) As dependências da biblioteca MSAL são adicionadas aqui

Agora vamos analisar esses arquivos com mais detalhes e destacar o código específico do MSAL em cada um.

Próximos passos

Passe para o tutorial do Android no qual você cria um aplicativo Android que obtém um token de acesso da plataforma de identidade da Microsoft e o usa para chamar a API do Microsoft Graph.

Tutorial: Inicie sessão em utilizadores e chame o Microsoft Graph a partir de uma aplicação Android

O guia de início rápido orienta-o na configuração dos aplicativos de exemplo Android, .NET MAUI Android e iOS/macOS para autenticar utilizadores, registando as aplicações, configurando os URLs de redirecionamento, atualizando as configurações e testando a aplicação.

Pré-requisitos

Registar a candidatura

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, a ID externa 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 Aplicações.

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

  3. Navegue até Identidade>Aplicativos>Registros de aplicativos.

  4. Selecione + Novo registo.

  5. Na página Registar uma aplicação que aparece;

    1. Insira um nome significativo para a aplicação Nome que é exibido para os utilizadores da app, por exemplo, ciam-client-app.
    2. Em Tipos de conta suportados, selecione Apenas contas neste diretório organizacional.

  6. Selecione Registo.

  7. O separador Visão Geral do aplicativo é exibido após o registo bem-sucedido. Registe o ID da aplicação (cliente) a ser usado no código-fonte da sua aplicação.

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 de configurações da plataforma , selecione Adicionar uma plataformae, 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 o seu aplicativo Android, selecione Gerar 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 Terminal.
  5. Insira o hash Signature gerado pelo KeyTool.
  6. Selecione Configurar.
  7. Copie o MSAL Configuration do painel de configuração do Android e salve-o para configuração futura do aplicativo.
  8. Selecione 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 partilhados, 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 é um locatário externo, os próprios usuários do cliente não podem consentir com essa permissão. Você, como administrador do locatário, deve consentir com essa permissão em nome de todos os usuários no locatário:

  1. Na página registros do 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 Conceder consentimento de administrador para <nome do seu arrendatário>e selecione Sim.
    2. Selecione Atualizare, em seguida, verifique se Concedido para <o nome do locatário> aparece em Estado da permissão.

Aplicação de exemplo de clonagem

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

Para habilitar a autenticação e o acesso aos recursos do Microsoft Graph, configure o exemplo seguindo estas etapas:

  1. No Android Studio, abra o projeto clonado.

  2. Abra o ficheiroauth_config_ciam.jsonem /app/src/main/res/raw/.

  3. Encontre o espaço reservado:

    • Enter_the_Application_Id_Here e substitua-o pelo ID do Aplicativo (cliente) do aplicativo que você registrou anteriormente.
    • 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 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 arquivoAndroidManifest.xmlem /app/src/main/.

  5. Encontre o espaço reservado:

    • ENTER_YOUR_SIGNATURE_HASH_HERE e substitua-o pelo Hash de Assinatura que o utilizador 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 chamada scopes e defina os escopos registados em . Conceda o consentimento de administrador. Se você não registrou nenhum escopo, pode deixar essa lista de escopo vazia.

    private const val scopes = "" // Developers should set the respective scopes of their Microsoft Graph resources 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 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 Executar.

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

  5. Se você selecionar API - Executar GET para chamar uma API da Web ASP.NET Core protegida, receberá um erro.

Para obter mais informações sobre como chamar uma API da Web protegida, consulte nossas próximas etapas

Próximos passos