Compartilhar via

Tutorial: Configurar um aplicativo Android para conectar usuários usando a plataforma de identidade da Microsoft

Aplica-se a: Círculo verde com um símbolo de marca de seleção branco. Locatários da força de trabalho Círculo verde com um símbolo de marca de seleção branco. Locatários externos (saiba mais)

Neste tutorial, você pode adicionar a MSAL (Biblioteca de Autenticação da Microsoft) para Android ao seu aplicativo Android. A MSAL permite que aplicativos Android autentiquem usuários com o Microsoft Entra.

Neste tutorial você irá aprender;

  • Adicionar uma dependência da MSAL
  • Adicionar configuração
  • Criar uma instância do SDK da MSAL

Pré-requisitos

  • Um locatário da força de trabalho. Você pode usar o Diretório Padrão ou configurar um novo locatário.
  • Registre um novo aplicativo no Centro de administração do Microsoft Entra, configurado apenas para Contas neste diretório organizacional. Consulte Registrar um aplicativo para obter mais detalhes. Registre os seguintes valores na página visão geral do aplicativo para uso posterior:
    • ID do aplicativo (cliente)
    • ID do diretório (locatário)
  • Um projeto android. Se você não tiver um projeto android, crie-o.

Adicionar um URI de redirecionamento

Você deve configurar URIs de redirecionamento específicos no registro do aplicativo para garantir a compatibilidade com o exemplo de código baixado. Essas URIs são essenciais para redirecionar os usuários de volta ao aplicativo depois que eles entrarem com êxito.

  1. Em Gerenciar, selecione Autenticação>Adicionar uma plataforma>Android.

  2. Digite o Nome do Pacote do seu projeto com base no tipo de amostra que você baixou acima.

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

  3. Em Hash de assinatura, que é uma seção do painel Configurar seu aplicativo Android, selecione Gerar um Hash de Assinatura de desenvolvimento e copie o comando KeyTool para a linha de comando.

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

  4. Insira o Hash de assinatura gerado por KeyTool.

  5. Selecione Configurar e salve a Configuração da MSAL exibida no painel Configuração do Android, de modo que você possa inseri-la quando configurar o aplicativo mais tarde.

  6. Selecione Concluído.

Adicionar a dependência MSAL e as bibliotecas relevantes ao seu projeto

Para adicionar as dependências da MSAL no projeto Android, siga estas etapas:

  1. Abra seu projeto no Android Studio ou crie um novo projeto.

  2. Abra o aplicativo build.gradle e adicione as seguintes dependências:

    allprojects {
repositories {
    //Needed for com.microsoft.device.display:display-mask library
    maven {
        url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
        name 'Duo-SDK-Feed'
    }
    mavenCentral()
    google()
    }
}
//...

dependencies { 
    implementation 'com.microsoft.identity.client:msal:5.+'
    //...
}

    Nos repositórios da configuração build.gradle, são definidas as dependências de projeto. Ele inclui uma URL do repositório Maven para a com.microsoft.device.display:display-mask biblioteca do Azure DevOps. Além disso, ele utiliza repositórios do Maven Central e do Google. A seção dependências especifica a implementação da MSAL versão 5 e, potencialmente, de outras dependências.

  3. No Android Studio, selecione Arquivo>Sincronizar Projeto com Arquivos Gradle.

Adicionar configuração

Você passa os identificadores de locatário necessários, como a ID do aplicativo (cliente), para o SDK da MSAL por meio de uma configuração JSON.

Use estas etapas para criar o arquivo de configuração:

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

  2. Clique com o botão direito do mouse em res e escolha Novo>Diretório. Insira raw como o nome do novo diretório e selecione OK.

  3. Em app>src>main>res>raw, crie um arquivo JSON chamado auth_config_single_account.json e cole a Configuração da MSAL salva 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 Conta Única, confira o modo de conta única versus múltipla e como configurar seu aplicativo para obter mais informações

  4. É recomendável usar 'WEBVIEW'. Caso deseje configurar "authorization_user_agent" como "BROWSER" em seu aplicativo, você precisará fazer as atualizações a seguir. a) Atualizar auth_config_single_account.json com “authorization_user_agent”: “Browser”. b) Atualização AndroidManifest.xml. No aplicativo, vá para app>src>main>AndroidManifest.xml, adicione a atividade BrowserTabActivity como um filho do elemento <application>. Essa inserção permite que o Microsoft Entra ID faça uma chamada de retorno ao seu aplicativo após concluir a autenticação:

    <!--Intent filter to capture System Browser or Authenticator calling back to our app after sign-in-->
<activity
    android:name="com.microsoft.identity.client.BrowserTabActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="msauth"
            android:host="Enter_the_Package_Name"
            android:path="/Enter_the_Signature_Hash" />
    </intent-filter>
</activity>
    • Use o Nome do pacote para substituir o valor android:host=.. Ela deve ter aparência semelhante a com.azuresamples.msalandroidapp.
    • Use o Hash de Assinatura para substituir o valor android:path=. Verifique se há um / inicial no começo do seu hash de assinatura. Ela deve ter aparência semelhante a /aB1cD2eF3gH4+iJ5kL6-mN7oP8q=.

    Você também encontra esses valores na folha Autenticação do registro do aplicativo.

Criar uma instância do SDK da MSAL

Para inicializar a instância do SDK da MSAL, use o seguinte código:

PublicClientApplication.createSingleAccountPublicClientApplication(
    getContext(),
    R.raw.auth_config_single_account,
    new IPublicClientApplication.ISingleAccountApplicationCreatedListener() {
        @Override
        public void onCreated(ISingleAccountPublicClientApplication application) {
            // Initialize the single account application instance
            mSingleAccountApp = application;
            loadAccount();
        }

        @Override
        public void onError(MsalException exception) {
            // Handle any errors that occur during initialization
            displayError(exception);
        }
    }
);

Esse código cria um aplicativo cliente público de conta única usando o arquivo de configuração auth_config_single_account.json. Quando o aplicativo é criado com êxito, ele atribui a instância mSingleAccountApp e chama o loadAccount() método. Se ocorrer um erro durante a criação, ele manipulará o erro chamando o método displayError(exception).

Lembre-se de incluir as instruções de importação. O Android Studio deve incluir automaticamente as instruções de importação para você.

Próximas etapas

Tutorial: Adicionar login em seu aplicativo Android.