Hinzufügen der Registrierung in einer Android-App mit nativer Authentifizierung - Microsoft Entra External ID

Artikel
02/07/2025

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

Führen Sie die Schritte unter Tutorial: Vorbereiten Ihrer mobilen Android-App für die native Authentifizierung aus.
Wenn Sie während der Registrierung Benutzerattribute erfassen möchten, konfigurieren Sie die Benutzerattribute, wenn Sie Ihren Flow für die Registrierung und Anmeldung von Benutzern erstellen.

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:

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
Fügen Sie in Ihrer App eine Schaltfläche hinzu, deren Auswahlereignis den folgenden Codeschnipsel auslöst:
```
CoroutineScope(Dispatchers.Main).launch {
     val parameters = NativeAuthSignUpParameters(username = email)
     // Assign 'password' param if you sign in with username (email) and password
     // parameters.password = password
     val actionResult: SignUpResult = authClient.signUp(parameters)

     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(parameters)), um den Registrierungsflow zu starten.
- Um sich mit Benutzername (E-Mail-Adresse) und Kennwort zu registrieren, erstellen Sie eine Instanz von NativeAuthSignUpParameters Klasse, und weisen Sie Ihren Benutzernamen und Ihr Kennwort zu.
- Der Registrierungsparameter usernameist die E-Mail-Adresse, die Sie vom Benutzer sammeln.
- In den häufigsten Szenarien gibt die signUp(parameters) ein Ergebnis zurück, SignUpResult.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 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.
- Die signUp(parameters) kann auch SignUpError zurückgeben, um zu kennzeichnen, dass ein Fehler aufgetreten ist.

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 NativeAuthSignUpParameters Instanz akzeptiert einen attributes Parameter:

    CoroutineScope(Dispatchers.Main).launch {
        val parameters = NativeAuthSignUpParameters(username = email)
        // Assign 'password' param if you sign in with username (email) and password
        // parameters.password = password
        parameters.attributes = userAttributes
        val actionResult: SignUpResult = authClient.signUp(parameters)
        //...
    }

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(parameters)-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 parameters = NativeAuthSignUpParameters(username = email)
// Assign 'password' param if you sign in with username (email) and password
// parameters.password = password
parameters.attributes = userAttributes
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpResult.AttributesRequired) {
        val requiredAttributes = actionResult.requiredAttributes 
        // Handle "attributes required" result 
        val nextState = actionResult.nextState
        nextState.submitAttributes(
            attributes = moreAttributes
        )
}

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.

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

 val parameters = NativeAuthSignUpParameters(username = email)
 // Assign 'password' param if you sign in with username (email) and password
 // parameters.password = password
val actionResult: SignUpResult = authClient.signUp(parameters)

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(parameters) 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 parameters = NativeAuthSignUpParameters(username = email)
// Assign 'password' param if you sign in with username (email) and password
// parameters.password = password
parameters.attributes = userAttributes
val actionResult: SignUpResult = authClient.signUp(parameters)

if (actionResult is SignUpError && actionResult.isInvalidAttributes()) {
    val invalidAttributes = actionResult.invalidAttributes

    // Handle "invalid attributes" error, this time submit valid attributes
    val parameters = NativeAuthSignUpParameters(username = email)
    // Assign 'password' param if you sign in with username (email) and password
    // parameters.password = password
    parameters.attributes = userAttributes
    authClient.signUp(parameters)
} 
//...

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.

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

Freigeben über

Voraussetzungen

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

Nächste Schritte

Feedback

Zusätzliche Ressourcen

Freigeben über

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

Voraussetzungen

Registrieren eines Benutzers

Sammeln von Benutzerattributen während der Registrierung

Behandeln von Registrierungsfehlern

Behandeln von Fehlern beim Starten der Registrierung

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

Optional: Anmelden nach einem Registrierungsflow

Nächste Schritte

Feedback

Zusätzliche Ressourcen