Freigeben über

Tutorial: Hinzufügen der Registrierung in einer mobilen Android-App mit nativer Authentifizierung

  • Artikel

In diesem Tutorial wird gezeigt, wie Sie einen Benutzer mithilfe eines E-Mail-Einmal-Passcodes oder mit Benutzername (E-Mail-Adresse) und Kennwort registrieren und mit der nativen Authentifizierung in Ihrer mobilen Android-App Benutzerattribute erfassen.

In diesem Tutorial lernen Sie Folgendes:

  • Registrieren Sie einen Benutzer mithilfe eines E-Mail-Einmal-Passcodes oder mit Benutzername (E-Mail-Adresse) und Kennwort.
  • Erfassen von Benutzerattributen während der Registrierung.
  • Behandeln von Registrierungsfehlern

Voraussetzungen

Registrieren eines Benutzers

Um einen Benutzer mithilfe des E-Mail-Einmal-Passcodes oder mit Benutzername (E-Mail-Adresse) und Kennwort zu registrieren, erfassen Sie eine E-Mail-Adresse des Benutzers und senden ihm eine E-Mail mit einem E-Mail-Einmal-Passcode. Der Benutzer gibt einen gültigen E-Mail-Einmal-Passcode ein, um seinen Benutzernamen zu validieren.

Zum Registrieren eines Benutzers 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 die Registrierung mit Benutzername (E-Mail-Adresse) und Kennwort erfolgt
    • Erfassen eines E-Mail-Einmal-Passcodes vom Benutzer
    • Erfassen von Benutzerattributen bei Bedarf
    • Erneutes Senden eines Einmal-Passcodes (empfohlen)
    • Starten des Registrierungsflows

  2. Fügen Sie in Ihrer App eine Schaltfläche hinzu, deren Auswahlereignis den folgenden Codeschnipsel auslöst:

    CoroutineScope(Dispatchers.Main).launch {
    val actionResult = authClient.signUp(
        username = emailAddress
        //password = password, Pass 'password' param if you sign up with username (email) and password
    )
    if (actionResult is SignUpResult.CodeRequired) {
        val nextState = actionResult.nextState
        val submitCodeActionResult = nextState.submitCode(
            code = code
        )
        if (submitCodeActionResult is SignUpResult.Complete) {
            // Handle sign up success
        }
    }
}
    • Verwenden Sie die Instanzmethode des SDK (signUp(username)), um den Registrierungsflow zu starten.
      • Übergeben Sie bei der Registrierung mit Benutzername (E-Mail-Adresse) und Kennwort den Kennwortparameter an die signUp-Funktion: signUp(username, password).
    • Der Parameter username der Methode ist dann die E-Mail-Adresse, die Sie vom Benutzer erfassen.
    • Im gängigsten Szenario gibt signUp(username) oder signUp(username, password) das Ergebnis SignUpResult.CodeRequired zurück. Dieses gibt an, dass das SDK erwartet, dass die App den E-Mail-Einmal-Passcode übermittelt, der an die E-Mail-Adresse des Benutzers gesendet wurde.
    • Das Objekt SignUpResult.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.
    • submitCode() gibt SignUpResult.Complete zurück, was angibt, dass der Flow abgeschlossen und der Benutzer registriert ist.
    • signUp(username) oder signUp(username, password) kann auch SignUpError zurückgeben, um anzugeben, dass ein Fehler aufgetreten ist.

Sammeln von Benutzerattributen während der Registrierung

Unabhängig davon, ob Sie einen Benutzer mit einem E-Mail-Einmal-Passcode oder mit Benutzername (E-Mail-Adresse) und Kennwort registrieren, können Sie Benutzerattribute erfassen, bevor das Konto eines Benutzers erstellt wird:

  • Die signUp()-Methode akzeptiert einen Parameter attributes als signUp(username, attributes):

        CoroutineScope(Dispatchers.Main).launch {
        val actionResult = authClient.signUp(
            username = emailAddress,
            attributes = userAttributes
            //password = password, Pass 'password' param if you sign up with username (email) and password
        )
        //...
    }

  • Das Android SDK stellt die Hilfsklasse UserAttribute.Builder bereit, die Sie für die Erstellung von Benutzerattributen verwenden. Wenn Sie z. B. die Benutzerattribute city und country übermitteln möchten, verwenden Sie den folgenden Codeschnipsel, um die Variable userAttributes zu erstellen:

         val userAttributes = UserAttributes.Builder 
    .country(country) 
    .city(city) 
    .build()

    Die Methodennamen in der UserAttribute.Builder-Klasse entsprechen den programmierbaren Namen der erstellten Benutzerattribute. Erfahren Sie mehr über den Android SDK-Attribut-Generator.

  • Die signUp(username, attributes)- oder signUp(username, attributes, password)-Methode kann SignUpResult.AttributesRequired zurückgeben, um anzugeben, dass die App mindestens ein erforderliches Attribut übermitteln muss, bevor Microsoft Entra ein Konto erstellt. Diese Attribute werden vom Administrator im Microsoft Entra Admin Center als obligatorisch konfiguriert. Microsoft Entra fordert optionale Benutzerattribute nicht explizit an.

  • Das Ergebnis SignUpResult.AttributesRequired enthält den Parameter requiredAttributes. requiredAttributes ist eine Liste von RequiredUserAttribute-Objekten, die Details zu den von der App zu übermittelnden Benutzerattributen enthalten. Verwenden Sie den folgenden Codeschnipsel, um actionResult is SignUpResult.AttributesRequired zu behandeln:

    val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
    //password = password, Pass 'password' param if you sign up with username (email) and password
)
if (actionResult is SignUpResult.AttributesRequired) {
        val requiredAttributes = actionResult.requiredAttributes 
        // Handle "attributes required" result 
        val nextState = actionResult.nextState
        nextState.submitAttributes(
            attributes = moreAttributes
        )
}

Behandeln von Registrierungsfehlern

Während der Registrierung sind nicht alle Aktionen erfolgreich. Beispielsweise kann der Benutzer versuchen, sich mit einer bereits verwendeten E-Mail-Adresse zu registrieren oder einen ungültigen E-Mail-Einmal-Passcode zu senden.

Behandeln von Fehlern beim Starten der Registrierung

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

val actionResult = authClient.signUp(
    username = email
)
if (actionResult is SignUpResult.CodeRequired) {
    // Next step: submit code
} else if (actionResult is SignUpError) {
     when {
         actionResult.isUserAlreadyExists() -> {
             // Handle "user already exists" error
         }
         else -> {
             // Handle other errors
         }
     }
}

  • signUp(username, attributes) oder signUp(username, password, attributes) kann SignUpError zurückgeben.

  • SignUpError gibt ein erfolgloses Aktionsergebnis an, das von signUp() zurückgegeben wird und enthält keinen Verweis auf den neuen Zustand.

  • Wenn actionResult is SignUpError, stellt das MSAL Android SDK Hilfsmethoden bereit, mit denen Sie die spezifischen Fehler weiter analysieren können:

    • Die Methode isUserAlreadyExists() überprüft, ob der Benutzername bereits zum Erstellen eines Kontos verwendet wurde.
    • isInvalidAttributes() überprüft, ob bei der Validierung eines oder mehrerer der von der App übermittelten Attribute ein Fehler aufgetreten ist, z. B. wegen eines falschen Datentyps. Sie enthält den Parameter invalidAttributes, d. h. eine Liste aller Attribute, die von den Apps gesendet wurden und nicht validiert werden konnten.
    • isInvalidPassword() überprüft, ob das Kennwort ungültig ist, z. B. wenn das Kennwort nicht allen Anforderungen zur Kennwortkomplexität entspricht. Weitere Informationen zu den Kennwortrichtlinien für Microsoft Entra finden Sie unter diesem Link.
    • isInvalidUsername() überprüft, ob der Benutzername ungültig ist, z. B. wenn die E-Mail-Adresse des Benutzers ungültig ist.
    • 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.
    • isAuthNotSupported() überprüft, ob die App einen Aufforderungstyp sendet, den Microsoft Entra nicht unterstützt. Dabei handelt es sich um Aufforderungstypwerte außer oob oder Kennwort. Erfahren Sie mehr über Aufforderungstypen.

    Informieren Sie den Benutzer mit einer freundlichen Benachrichtigung in der Benutzeroberfläche der App darüber, dass die E-Mail-Adresse bereits verwendet wird oder einige Attribute ungültig sind.

  • Verwenden Sie den folgenden Codeschnipsel, um den Fehler aufgrund ungültiger Attribute zu behandeln:

    val actionResult = authClient.signUp(
    username = email,
    attributes = attributes
    //password = password, Pass 'password' param if you sign up with username (email) and password
)
if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
    val invalidAttributes = actionResult.invalidAttributes
    // Handle "invalid attributes" error, this time submit valid attributes
    authClient.signUp(
        username = emailAddress,
        attributes = resubmittedAttributes
        //password = password, Pass 'password' param if you sign up with username (email) and password
    )
} 
//...

Behandeln von Fehlern beim Übermitteln eines E-Mail-Einmal-Passcodes

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

val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SignUpResult.Complete) {
    // Sign up flow complete, handle success state.
} else if (submitCodeActionResult is SubmitCodeError) {
    // Handle errors under SubmitCodeError
     when {
         submitCodeActionResult.isInvalidCode() -> {
             // Handle "code invalid" error
         }
         else -> {
             // Handle other errors
         }
     }
}

  • submitCode() kann SubmitCodeError zurückgeben.

  • Verwenden Sie die Methode isInvalidCode() für die Überprüfung auf den spezifischen Fehler, etwa, dass der übermittelte Code ungültig ist. In diesem Fall muss der Verweis auf den vorherigen Zustand verwendet werden, um die Aktion erneut auszuführen.

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

    val submitCodeActionResult = nextState.submitCode(
    code = code
)
if (submitCodeActionResult is SubmitCodeError && submitCodeActionResult.isInvalidCode()) {
    // Inform the user that the submitted code was incorrect or invalid and ask for a new code to be supplied
    val newCode = retrieveNewCode()
    nextState.submitCode(
        code = newCode
    )
}

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

Sie haben alle erforderlichen Schritte abgeschlossen, um einen Benutzer erfolgreich bei Ihrer App zu registrieren. Erstellen Sie Ihre Anwendung, und führen Sie sie aus. Wenn alles gut ist, sollten Sie den Benutzer mithilfe eines E-Mail-Einmal-Passcodes oder mit einer E-Mail-Adresse und einem Kennwort erfolgreich registrieren können.

Optional: Anmelden nach einem Registrierungsflow

Nach einem erfolgreichen Registrierungsflow können Sie einen Benutzer anmelden, ohne einen Anmeldeflow zu initiieren. Weitere Informationen finden Sie unter Tutorial: Anmelden von Benutzern nach der Registrierung in Android.

Nächste Schritte

Tutorial: An- und Abmeldung mit Einmal-E-Mail-Passcode in Android-App hinzufügen