Tutorial: Preparar seu aplicativo Android (Kotlin) para autenticação

Artigo
07/28/2024

Este é o segundo tutorial da série de tutoriais que demonstra como adicionar a Biblioteca de Autenticação da Microsoft (MSAL) para Android ao seu aplicativo Android (Kotlin). A MSAL permite que os aplicativos Android autentiquem usuários com o Microsoft Entra.

Neste tutorial, você aprenderá a:

Adicionar dependências da MSAL.
Adicionar Configuração.

Pré-requisitos

Android Studio
Se você ainda não o fez, siga as instruções em Tutorial: Registrar e configurar o aplicativo móvel Android (Kotlin) e registrar um aplicativo no seu locatário externo.
Um projeto Android. Se você não tiver um projeto Android, crie-o.

Adicionar dependências da MSAL

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

Abra seu projeto no Android Studio ou crie um projeto.
Abra o build.gradle do aplicativo 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.+'
    //...
}
```
Na configuração build.gradle, os repositórios são definidos para as dependências do projeto. Ela inclui uma URL do repositório Maven para a biblioteca com.microsoft.device.display:display-mask do Azure DevOps. Além disso, ele utiliza os repositórios Maven Central e Google. A seção de dependências especifica a implementação do MSAL versão 5 e possivelmente outras dependências.
No Android Studio, selecione Arquivo>Sincronizar Projeto com Arquivos do 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:

No painel do projeto do Android Studio, navegue até app\src\main\res.
Clique com o botão direito do mouse em res e selecione Novo>Diretório. Insira raw como o nome do novo diretório e selecione OK.
Em app\src\main\res\raw, crie um novo arquivo JSON chamado auth_config_ciam_auth.json.
No arquivo auth_config_ciam_auth.json, adicione as seguintes configurações da MSAL:
```
{
  "client_id" : "Enter_the_Application_Id_Here",
  "authorization_user_agent" : "DEFAULT",
  "redirect_uri" : "Enter_the_Redirect_Uri_Here",
  "account_mode" : "SINGLE",
  "authorities" : [
    {
      "type": "CIAM",
      "authority_url": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Subdomain_Here.onmicrosoft.com/"
    }
  ]
}
```
O arquivo de configuração JSON especifica várias configurações para um aplicativo Android. Ele inclui a ID do cliente, o agente de usuário de autorização, o URI de redirecionamento e o modo da conta. Além disso, ele define uma autoridade para autenticação, especificando o tipo e a URL da autoridade.

Substitua os seguintes espaços reservados pelos valores de locatário obtidos no Centro de administração do Microsoft Entra:
- 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.
Abra o arquivo /app/src/main/AndroidManifest.xml.
Em AndroidManifest.xml, adicione a seguinte especificação de dados a um filtro de intenção:
```
<data
    android:host="ENTER_YOUR_PROJECT_PACKAGE_NAME_HERE"
    android:path="/ENTER_YOUR_SIGNATURE_HASH_HERE"
    android:scheme="msauth" />
```
Localize o espaço reservado:
- INSIRA_O_NOME_DO_PACOTE_DO_SEU_PROJETO_AQUI e substitua-a pelo nome do pacote do seu projeto Android.
- INSIRA_O_HASH_DA_SUA_ASSINATURA_AQUI e substitua-o pelo Hash de assinatura que você gerou anteriormente quando adicionou a URL de redirecionamento da plataforma.

Usar um domínio de URL personalizado (opcional)

Use um domínio personalizado para marcar totalmente a URL de autenticação. Do ponto de vista do usuário, os usuários permanecem no seu domínio durante o processo de autenticação, em vez de serem redirecionados para o nome de domínio ciamlogin.com.

Use as etapas a seguir para usar um domínio personalizado:

Use as etapas em Habilitar domínios de URL personalizados para aplicativos em locatários externos para habilitar domínio de URL personalizado para seu locatário externo.
Abra o arquivo auth_config_ciam_auth.json:
1. Atualize o valor da propriedade authority_url para https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here. Substitua Enter_the_Custom_Domain_Here pelo domínio de URL personalizado e Enter_the_Tenant_ID_Here pela ID do locatário. Se você não tiver o nome do locatário, saiba como ler os detalhes do locatário.
2. Adicione a propriedade knownAuthorities com um valor [Insira_o_Domínio_Personalizado_Aqui].

Depois que você fizer as alterações no arquivo auth_config_ciam_auth.json, se o seu domínio de URL personalizado for login.contoso.com e a sua ID de locatário for aaaabbbb-0000-cccc-1111-dddd2222eeee, seu arquivo será semelhante ao seguinte snippet:

{
    "client_id" : "Enter_the_Application_Id_Here",
    "authorization_user_agent" : "DEFAULT",
    "redirect_uri" : "Enter_the_Redirect_Uri_Here",
    "account_mode" : "SINGLE",
    "authorities" : [
    {
        "type": "CIAM",
        "authority_url": "https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "knownAuthorities": ["login.contoso.com"]
    }
    ]
}

Criar instância do SDK da MSAL

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

private suspend fun initClient(): ISingleAccountPublicClientApplication = withContext(Dispatchers.IO) {
    return@withContext PublicClientApplication.createSingleAccountPublicClientApplication(
        this@MainActivity,
        R.raw.auth_config_ciam_auth
    )
}

O código inicializa um aplicativo cliente público da conta única de forma assíncrona. Ele usa o arquivo de configuração de autenticação fornecido e é executado no dispatcher de E/S.

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

Próximas etapas

Tutorial: Conectar usuários no aplicativo móvel Android (Kotlin)

Compartilhar via