Lernprogramm: Vorbereiten Ihrer mobilen Android-App für die native Authentifizierung

Gilt für: Mitarbeitermieter Externe Mieter (weitere Informationen)

In diesem Lernprogramm wird veranschaulicht, wie Sie einer mobilen Android-App das systemeigene Authentifizierungs-SDK (Microsoft Authentication Library, MSAL) hinzufügen.

In diesem Tutorial werden Sie:

Voraussetzungen

• Falls noch nicht geschehen, folgen Sie den Anweisungen in Anmelden von Benutzern in einer mobilen Android-Beispiel-App (Kotlin) mithilfe der nativen Authentifizierung, und registrieren Sie eine App in Ihrem externen Mandanten. Stellen Sie sicher, dass Sie die folgenden Schritte ausführen:
  • Registrieren einer Anwendung.
  • Aktivieren Sie öffentliche Client- und systemeigene Authentifizierungsflüsse.
  • API-Berechtigungen erteilen.
  • Erstellen Sie einen Benutzerablauf.
  • Ordnen Sie die App dem Benutzerablauf zu.
• Ein Android-Projekt. Wenn Sie kein Android-Projekt haben, erstellen Sie es.

Hinzufügen von MSAL-Abhängigkeiten

1. Öffnen Sie Ihr Projekt in Android Studio, oder erstellen Sie ein neues Projekt.

2. Öffnen Sie das build.gradle-Element Ihrer Anwendung, und fügen Sie die folgenden Abhängigkeiten hinzu:

   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. Wählen Sie in Android Studio " Dateisynchronisierungsprojekt>mit Gradle-Dateien" aus.

Erstellen einer Konfigurationsdatei

Sie übergeben die erforderlichen Mandanten-IDs, z. B. die Anwendungs-ID (Client-ID), über eine JSON-Konfigurationseinstellung an das MSAL SDK.

Führen Sie die folgenden Schritte aus, um eine Konfigurationsdatei zu erstellen:

1. Navigieren Sie im Projektbereich von Android Studio zu app\src\main\res.

2. Klicken Sie mit der rechten Maustaste auf "Res", und wählen Sie "Neues Verzeichnis"> aus. Geben Sie raw als neuen Verzeichnisnamen ein, und wählen Sie OK.

3. Erstellen Sie in app\src\main\res\raw, eine neue JSON-Datei namens auth_config_native_auth.json.

4. Fügen Sie in der auth_config_native_auth.json Datei die folgenden MSAL-Konfigurationen hinzu:

   { 
     "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. Ersetzen Sie die folgenden Platzhalter durch Ihre Mandantenwerte, die Sie im Microsoft Entra Admin Center finden:

   • Ersetzen Sie den Enter_the_Application_Id_Here Platzhalter durch die Anwendungs-ID (Client-ID) der App, die Sie zuvor registriert haben.
   • Ersetzen Sie Enter_the_Tenant_Subdomain_Here durch die untergeordnete Domäne des Verzeichnisses (des Mandanten). Wenn Ihre primäre Mandantendomäne z. B. contoso.onmicrosoft.comist, verwenden Sie contoso. Wenn Sie Ihren Mandantennamen nicht kennen, lesen Sie die Informationen unter Abrufen der Details des Mandanten.

   Die Abfragetypen sind eine Liste von Werten, die von der App verwendet werden, um Microsoft Entra über die von ihr unterstützte Authentifizierungsmethode zu benachrichtigen.

   • Verwenden Sie ["oob"] für Registrierungs- und Anmeldeabläufe mit einem Einmalpasscode per E-Mail.
   • Verwenden Sie ["oob","password"] für Registrierungs- und Anmeldeabläufe mit E-Mail und Kennwort.
   • Verwenden Sie ["oob"]für die Self-Service-Kennwortzurücksetzung (Self-Service Password Reset, SSPR).

   Erfahren Sie mehr über Herausforderungstypen.

Optional: Protokollierungskonfiguration

Aktivieren Sie die Protokollierung bei der App-Erstellung, indem Sie einen Protokollierungsrückruf erstellen, damit das SDK Protokolle ausgeben kann.

import com.microsoft.identity.client.Logger

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

Um den Logger zu konfigurieren, müssen Sie einen Abschnitt in der Konfigurationsdatei hinzufügen: auth_config_native_auth.json

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

1. logcat_enabled: Aktiviert die Protokollierungsfunktionalität der Bibliothek.
2. pii_enabled: Gibt an, ob Nachrichten mit personenbezogenen Daten oder Organisationsdaten protokolliert werden. Wenn dieser Wert auf "false" festgelegt ist, enthalten Protokolle keine personenbezogenen Daten. Bei Festlegung auf "true" können die Protokolle personenbezogene Daten enthalten.
3. log_level: Verwenden Sie sie, um zu entscheiden, welche Protokollierungsebene aktiviert werden soll. Android unterstützt die folgenden Protokollebenen:
   1. FEHLER
   2. WARNUNG
   3. INFORMATIONEN
   4. WEITSCHWEIFIG

Weitere Informationen zur MSAL-Protokollierung finden Sie unter Protokollierung in MSAL für Android.

Erstellen einer MSAL SDK-Instanz für die native Authentifizierung

Erstellen Sie in der onCreate() Methode eine MSAL-Instanz, damit die App die Authentifizierung mit Ihrem Mandanten über die systemeigene Authentifizierung durchführen kann. Die createNativeAuthPublicClientApplication() Methode gibt eine Instanz namens authClient zurück. Übergeben Sie die JSON-Konfigurationsdatei, die Sie zuvor als Parameter erstellt haben.

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

Ihr Code sollte ähnlich aussehen wie der folgende Codeausschnitt:

    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" 
        } 
    } 

• Rufen Sie das zwischengespeicherte Konto mithilfe des getCurrentAccount(), das ein Objekt zurückgibt, accountResultab.
• Wenn ein Konto in Persistenz gefunden wurde, verwenden Sie GetAccountResult.AccountFound, um den Anmeldestatus anzuzeigen.
• Verwenden Sie andernfalls GetAccountResult.NoAccountFound zur Anzeige eines abgemeldeten Zustands.

Stellen Sie sicher, dass Sie die Importanweisungen hinzufügen. Android Studio sollte die Importanweisungen automatisch enthalten.

Nächster Schritt