Tutorial: Preparar seu aplicativo móvel Android para autenticação nativa

Aplica-se a: Inquilinos externos (saiba mais)

Este tutorial demonstra como adicionar o SDK de autenticação nativo da Microsoft Authentication Library (MSAL) a um aplicativo móvel Android.

Neste tutorial, você:

Pré-requisitos

• Se ainda não o fez, siga as instruções em para iniciar sessão dos utilizadores na aplicação móvel Android (Kotlin) de exemplo, utilizando autenticação nativa, e registe uma aplicação na sua entidade externa. Certifique-se de concluir as seguintes etapas:
  • Registe uma candidatura.
  • Habilite fluxos de autenticação nativa e de cliente público.
  • Conceda permissões de API.
  • Crie um fluxo de usuário.
  • Associe o aplicativo ao fluxo de usuários.
• Um projeto Android. Se você não tiver um projeto Android, crie-o.

Adicionar dependências MSAL

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

2. 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:6.+'
       //...
   }
   

3. No Android Studio, selecione Ficheiro>Sincronizar Projeto com Ficheiros Gradle.

Criar um arquivo de configuração

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

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

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 selecione Novo>Diretório. Digite raw como o novo nome do diretório e selecione OK.

3. Em app\src\main\res\raw, crie um novo arquivo JSON chamado auth_config_native_auth.json.

4. No arquivo auth_config_native_auth.json, adicione as seguintes configurações do MSAL:

   { 
     "client_id": "Enter_the_Application_Id_Here", 
     "authorities": [ 
       { 
         "type": "CIAM", 
         "authority_url": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Subdomain_Here.onmicrosoft.com/" 
       } 
     ], 
     "challenge_types": ["oob"], 
     "logging": { 
       "pii_enabled": false, 
       "log_level": "INFO", 
       "logcat_enabled": true 
     } 
   } 
    //...
   

5. Substitua os placeholders seguintes pelos valores do seu locatário obtidos no portal de administração do Microsoft Entra.

   • Substitua o espaço reservado Enter_the_Application_Id_Here pelo ID da aplicação (cliente) da aplicação que registou anteriormente.
   • Substitua o Enter_the_Tenant_Subdomain_Here pelo subdomínio diretório (locatário). Por exemplo, se o domínio principal do inquilino for contoso.onmicrosoft.com, use contoso. Se não tiver o nome do seu inquilino, saiba como ler os detalhes do seu inquilino.

   Os tipos de desafio são uma lista de valores, que o aplicativo usa para notificar o Microsoft Entra sobre o método de autenticação que ele suporta.

   • Para fluxos de inscrição e login com senha única de e-mail, use ["oob"].
   • Para fluxos de registo e login com e-mail e palavra-passe, use ["oob","password"].
   • Para redefinição automática de senha (SSPR), utilize o ["oob"].

   Saiba mais tipos de desafios.

Opcional: Configuração de registo

Ative o logging ao criar a aplicação por meio da criação de uma função de retorno de log, para que o SDK possa gerar logs.

import com.microsoft.identity.client.Logger

fun initialize(context: Context) {
        Logger.getInstance().setExternalLogger { tag, logLevel, message, containsPII ->
            Logs.append("$tag $logLevel $message")
        }
    }

Para configurar o registrador, você precisa adicionar uma seção no arquivo de configuração, auth_config_native_auth.json:

    //...
   { 
     "logging": { 
       "pii_enabled": false, 
       "log_level": "INFO", 
       "logcat_enabled": true 
     } 
   } 
    //...

1. logcat_enabled: Habilita a funcionalidade de registro em log da biblioteca.
2. pii_enabled: Especifica se as mensagens que contêm dados pessoais ou dados organizacionais são registradas. Quando definido como false, os logs não conterão dados pessoais. Quando definidos como true, os logs podem conter dados pessoais.
3. log_level: Use-o para decidir qual nível de log habilitar. O Android suporta os seguintes níveis de registo:
   1. ERRO
   2. ADVERTÊNCIA
   3. INFORMAÇÃO
   4. Verboso

Para obter mais informações sobre o registo de logs do MSAL, consulte Logging in MSAL for Android.

Criar instância de autenticação nativa do SDK do MSAL

No método onCreate(), crie uma instância MSAL para que o aplicativo possa executar a autenticação com seu locatário por meio da autenticação nativa. O método createNativeAuthPublicClientApplication() retorna uma instância chamada authClient. Passe o arquivo de configuração JSON que você criou anteriormente como um parâmetro.

    //...
    authClient = PublicClientApplication.createNativeAuthPublicClientApplication( 
        this, 
        R.raw.auth_config_native_auth 
    )
    //...

Seu código deve ser semelhante ao seguinte trecho:

    class MainActivity : AppCompatActivity() { 
        private lateinit var authClient: INativeAuthPublicClientApplication 
 
        override fun onCreate(savedInstanceState: Bundle?) { 
            super.onCreate(savedInstanceState) 
            setContentView(R.layout.activity_main) 
 
            authClient = PublicClientApplication.createNativeAuthPublicClientApplication( 
                this, 
                R.raw.auth_config_native_auth 
            ) 
            getAccountState() 
        } 
 
        private fun getAccountState() {
            CoroutineScope(Dispatchers.Main).launch {
                val accountResult = authClient.getCurrentAccount()
                when (accountResult) {
                    is GetAccountResult.AccountFound -> {
                        displaySignedInState(accountResult.resultValue)
                    }
                    is GetAccountResult.NoAccountFound -> {
                        displaySignedOutState()
                    }
                }
            }
        } 
 
        private fun displaySignedInState(accountResult: AccountState) { 
            val accountName = accountResult.getAccount().username 
            val textView: TextView = findViewById(R.id.accountText) 
            textView.text = "Cached account found: $accountName" 
        } 
 
        private fun displaySignedOutState() { 
            val textView: TextView = findViewById(R.id.accountText) 
            textView.text = "No cached account found" 
        } 
    } 

• Recupere a conta armazenada em cache usando o getCurrentAccount(), que retorna um objeto, accountResult.
• Se uma conta for encontrada em persistência, use GetAccountResult.AccountFound para exibir um estado conectado.
• Caso contrário, use GetAccountResult.NoAccountFound para exibir um estado desconectado.

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

Próximo passo