Freigeben über

Tutorial: Hinzufügen der Anmeldung in der Android-App mithilfe der systemeigenen Authentifizierung

  • Artikel

In diesem Tutorial wird veranschaulicht, wie Sie Benutzer mithilfe eines E-Mail-Einmal-Passcodes oder Benutzername und Kennwort bei Ihrer mobilen Android-App mit nativer Authentifizierung anmelden und abmelden.

In diesem Tutorial lernen Sie Folgendes:

  • Melden Sie einen Benutzer mithilfe eines E-Mail-Einmal-Passcodes oder mit Benutzername (E-Mail-Adresse) und Kennwort an.
  • Abmelden eines Benutzenden.
  • Behandeln von Anmeldefehlern

Voraussetzungen

Anmelden eines Benutzers

Wenn Sie einen Benutzer mithilfe eines Einmal-Passcode anmelden möchten, erfassen Sie die E-Mail-Adresse, und senden Sie eine E-Mail mit einem Einmal-Passcode, damit der Benutzer seine E-Mail-Adresse bestätigen kann. Wenn der Benutzende einen gültigen Einmal-Passcode eingibt, meldet die App ihn an.

Um einen Benutzer mit Benutzername (E-Mail) und Kennwort anzumelden, erfassen Sie die E-Mail und das Kennwort des Benutzers. Wenn der Benutzername und das Kennwort gültig sind, meldet sich die App beim Benutzer an.

Um sich bei einem Benutzer anzumelden, müssen Sie:

  1. Eine Benutzeroberfläche für Folgendes erstellen:

    • Erfassen einer E-Mail-Adresse des Benutzers. Fügen Sie eine Validierung für die Eingaben hinzu, um sicherzustellen, dass der Benutzer eine gültige E-Mail-Adresse eingibt.
    • Erfassen eines Kennworts, wenn das Anmelden mit Benutzername (E-Mail-Adresse) und Kennwort erfolgt.
    • Sammeln Sie eine einmal vom Benutzer gesendete E-Mail-Kennung, wenn Sie sich mit einer Einmalkennung per E-Mail anmelden.
    • Erneutes Senden einer Einmalkennung (empfohlen), wenn Sie sich mit einer Einmalkennung per E-Mail anmelden.

  2. Fügen Sie auf der Benutzeroberfläche eine Schaltfläche hinzu, deren Auswahlereignis eine Anmeldung startet, wie im folgenden Codeschnipsel gezeigt:

     CoroutineScope(Dispatchers.Main).launch {
     val parameters = NativeAuthSignInParameters(username = email)
     // Assign 'password' param if you sign in with username (email) and password
     // parameters.password = password
     val actionResult: SignInResult = authClient.signIn(parameters)

     if (actionResult is SignInResult.CodeRequired) {
         val nextState = actionResult.nextState
         val submitCodeActionResult = nextState.submitCode(
             code = code
         )
         if (submitCodeActionResult is SignInResult.Complete) {
             // Handle sign in success
             val accountState = submitCodeActionResult.resultValue

             val getAccessTokenParameters = NativeAuthGetAccessTokenParameters()
             val accessTokenResult = accountState.getAccessToken(getAccessTokenParameters)

             if (accessTokenResult is GetAccessTokenResult.Complete) {
                 val accessToken = accessTokenResult.resultValue.accessToken
                 val idToken = accountState.getIdToken()
             }
         }
     }
 }

    Wenn der Benutzer keine Kennung senden muss, z. B. wenn sich ein Benutzer mit E-Mail und Kennwort anmeldet, verwenden Sie den folgenden Codeausschnitt:

    CoroutineScope(Dispatchers.Main).launch {
    val parameters = NativeAuthSignInParameters(username = email)
    parameters.password = password
    val actionResult: SignInResult = authClient.signIn(parameters)

    if (actionResult is SignInResult.Complete) -> {
        // Handle sign in success
        val accountState = actionResult.resultValue

        val getAccessTokenParameters = NativeAuthGetAccessTokenParameters()
        val accessTokenResult = accountState.getAccessToken(getAccessTokenParameters)

        if (accessTokenResult is GetAccessTokenResult.Complete) {
            val accessToken = accessTokenResult.resultValue.accessToken
            val idToken = accountState.getIdToken()
        }
    }
}
    • Verwenden Sie die signIn(parameters)-Methode des SDK, um den Anmeldeablauf zu starten.
    • Eine Instanz der NativeAuthSignInParameters Klasse, die die username enthält, die die E-Mail-Adresse darstellt, die Sie vom Benutzer sammeln.
    • Wenn die Anmeldemethode Benutzername (E-Mail) und Kennwort ist, ist der Parameter der Methode password dann das Kennwort, das Sie vom Benutzer sammeln.
    • In den häufigsten Szenarien gibt die signIn(parameters) ein Ergebnis zurück, SignInResult.CodeRequired, was angibt, dass das SDK erwartet, dass die App die E-Mail-Einmalkennung sendet, die an die E-Mail-Adresse des Benutzers gesendet wird.
    • Das Objekt SignInResult.CodeRequired enthält einen Verweis auf den neuen Zustand, den Sie über actionResult.nextState abrufen können.
    • Der neue Zustand gibt Ihnen Zugriff auf zwei neue Methoden:
      • submitCode() sendet den E-Mail-Einmal-Passcode, den die App vom Benutzer erfasst.
      • resendCode() sendet den E-Mail-Einmal-Passcode erneut, wenn der Benutzer den Code nicht empfängt.

Behandeln von Anmeldefehlern

Bei der Anmeldung sind nicht alle Aktionen erfolgreich. Beispielsweise kann der Benutzende versuchen, sich mit einer E-Mail-Adresse anzumelden, die nicht vorhanden ist oder einen ungültigen Code sendet.

Behandeln von Fehlern beim Starten der Anmeldung

Verwenden Sie den folgenden Codeausschnitt, um Fehler in der signIn(parameters)-Methode zu behandeln:

 val parameters = NativeAuthSignInParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignInResult = authClient.signIn(parameters)

if (actionResult is SignInResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignInError) {
    // Handle sign in errors
    when {
         actionResult.isUserNotFound() -> {
             // Handle "user not found" error
         }
         actionResult.isAuthNotSupported() -> {
             // Handle "authentication type not support" error
         }
         actionResult.isInvalidCredentials() -> {
             // Handle specific errors
         }
         else -> {
             // Handle other errors
         }
     }
}
  • SignInError gibt ein erfolgloses Aktionsergebnis an, das von signIn(parameters) zurückgegeben wird, daher enthält das Aktionsergebnis keinen Verweis auf den neuen Zustand.
  • Bei actionResult is SignUpError stellt das Android SDK Hilfsmethoden bereit, mit denen Sie die spezifischen Fehler weiter analysieren können:
    • Die Methode isUserNotFound() überprüft, ob sich der Benutzer mit einem Benutzernamen (E-Mail-Adresse) anmeldet, der nicht vorhanden ist.
    • Die Methode isBrowserRequired() überprüft die Notwendigkeit eines Browsers (Webfallback), um den Authentifizierungsflow abzuschließen. Dieses Szenario tritt auf, wenn die native Authentifizierung nicht ausreicht, um den Authentifizierungsflow abzuschließen. Beispielsweise kann ein Administrator E-Mail und Kennwort als Authentifizierungsmethode konfigurieren, die App sendet jedoch nicht das Kennwort als Aufforderungstyp oder unterstützt dies einfach nicht. Führen Sie die Schritte unter Unterstützen von Webfallback in Android-Apps aus, um ein Szenario zu behandeln, in dem dies auftritt.
    • Die Methode isAuthNotSupported() überprüft, ob die App einen Aufforderungstyp sendet, den Microsoft Entra nicht unterstützt. Dabei handelt es sich um Aufforderungstypwerte außer oob und Kennwort. Erfahren Sie mehr über Aufforderungstypen.
    • Bei der Anmeldung mit Benutzername (E-Mail) und Kennwort überprüft die Methode isInvalidCredentials(), ob die Kombination aus Benutzername und Kennwort falsch ist.

Behandeln von Fehler beim Übermitteln von Code

Verwenden Sie den folgenden Codeschnipsel, um Fehler bei der Methode submitCode() zu behandeln:

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignInResult.Complete) {
    // Sign in flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
    // Handle "invalid code" error
}
  • Der Fehler SubmitCodeError gibt ein erfolgloses Aktionsergebnis an, das von submitCode() zurückgegeben wird, daher enthält das Aktionsergebnis keinen Verweis auf den neuen Zustand.
  • isInvalidCode() sucht nach dem spezifischen Fehler. In diesem Fall muss der Verweis auf den vorherigen Zustand verwendet werden, um die Aktion erneut auszuführen.

Verwenden Sie den folgenden Codeschnipsel, um den neuen E-Mail-Einmal-Passcode abzurufen:

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignInError && submitCodeActionResult.isInvalidCode) {
    // Inform the user that the submitted code was incorrect or invalid, then ask them to input a new email one-time passcode
    val newCode = retrieveNewCode()
    nextState.submitCode(
        code = newCode
    )
}

Sie haben alle notwendigen Schritte zur erfolgreichen Anmeldung eines Benutzenden in Ihrer Anwendung durchgeführt. Erstellen Sie Ihre Anwendung, und führen Sie sie aus. Wenn alles in Ordnung ist, sollten Sie in der Lage sein, eine E-Mail anzugeben, einen Code per E-Mail zu erhalten und mit diesem den Benutzer erfolgreich anzumelden.

Lesen von ID-Tokenansprüchen

Sobald Ihre App ein ID-Token abruft, können Sie die dem aktuellen Konto zugeordneten Ansprüche abrufen. Verwenden Sie dazu den folgenden Codeschnipsel.

val preferredUsername = accountState.getClaims()?.get("preferred_username")
val city = accountState.getClaims()?.get("City")
val givenName = accountState.getClaims()?.get("given_name")
//custom attribute
val loyaltyNumber = accountState.getClaims()?.get("loyaltyNumber")

Der Schlüssel, den Sie für den Zugriff auf den Anspruchswert verwenden, ist der Name, den Sie beim Hinzufügen des Benutzerattributs als Tokenanspruch angeben.

Informationen zum Hinzufügen integrierter und benutzerdefinierter Attribute als Tokenansprüche finden Sie im Artikel Hinzufügen von Benutzerattributen zu Tokenansprüchen.

Abmelden eines Benutzers

Um einen Benutzer abzumelden, müssen Sie das aktuell im Cache gespeicherte Konto entfernen.

  1. Erstellen Sie Ihre benutzerdefinierte Benutzeroberfläche, die Folgendes umfasst:

    • Eine Schaltfläche zum Abmelden, die der Benutzer zum Senden einer Abmeldeanforderung auswählt

  2. Verwenden Sie zum Abmelden eines Benutzenden den folgenden Code:

    private fun performSignOut(accountState: AccountState) {
     CoroutineScope(Dispatchers.Main).launch {
         val accountResult = authClient.getCurrentAccount()
         if (accountResult is GetAccountResult.AccountFound) {
             val signOutResult = accountResult.resultValue.signOut()
             if (signOutResult is SignOutResult.Complete) {
                 // Show sign out successful UI
             }
         }
     }
 }

Behandeln von Abmeldefehlern

Abmelden sollte fehlerfrei sein. Wenn Fehler auftreten, überprüfen Sie das Fehlerergebnis mithilfe des folgenden Codeschnipsels:

val actionResult = accountResult.signOut()
if (actionResult is SignOutResult.Complete) {
    // Show sign out successful UI
} else {
    // Handle errors
}

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

Sie haben alle erforderlichen Schritte abgeschlossen, um einen Benutzenden von Ihrer Anwendung erfolgreich abzumelden. Erstellen Sie Ihre Anwendung, und führen Sie sie aus. Wenn alles gut ist, sollten Sie die Schaltfläche Abmelden auswählen können, um sich erfolgreich abzumelden.

Konfigurieren eines benutzerdefinierten Anspruchsanbieters

Wenn Sie Ansprüche aus einem externen System in das Token einfügen möchten, das an Ihre Anwendung ausgegeben wird, verwenden Sie einen benutzerdefinierten Anspruchsanbieter. Ein benutzerdefinierter Anspruchsanbieter besteht aus einer benutzerdefinierten Authentifizierungserweiterung, die eine externe REST-API aufruft, um Ansprüche aus externen Systemen abzurufen.

Führen Sie die Schritte unter Konfigurieren eines benutzerdefinierten Anspruchsanbieters durch, um Ansprüche aus einem externen System zu Ihren Sicherheitstoken hinzuzufügen.

Zugehöriger Inhalt