Delen via

Zelfstudie: Registreren toevoegen in een mobiele Android-app met systeemeigen verificatie

  • Artikel

In deze zelfstudie ziet u hoe u een gebruiker registreert met eenmalige wachtwoordcode of gebruikersnaam (e-mailadres) en wachtwoord, en gebruikerskenmerken verzamelt in uw mobiele Android-app met behulp van systeemeigen verificatie.

In deze zelfstudie leert u het volgende:

  • Registreer een gebruiker met een eenmalige wachtwoordcode of gebruikersnaam (e-mail) en wachtwoord.
  • Gebruikerskenmerken verzamelen tijdens de registratie.
  • Registratiefouten afhandelen.

Vereisten

Een gebruiker registreren

Als u een gebruiker wilt registreren met behulp van de eenmalige wachtwoordcode of gebruikersnaam (e-mailadres) en wachtwoord van een e-mail, verzamelt u een e-mailbericht van de gebruiker en verzendt u vervolgens een e-mail met een eenmalige wachtwoordcode naar de gebruiker. De gebruiker voert een geldige eenmalige wachtwoordcode voor een e-mail in om de gebruikersnaam te valideren.

Als u zich wilt registreren voor een gebruiker, moet u het volgende doen:

  1. Maak een gebruikersinterface (UI) om:

    • Verzamel een e-mailbericht van de gebruiker. Voeg validatie toe aan uw invoer om ervoor te zorgen dat de gebruiker een geldig e-mailadres invoert.
    • Verzamel een wachtwoord als u zich registreert met gebruikersnaam (e-mailadres) en wachtwoord.
    • Verzamel een eenmalige wachtwoordcode voor e-mail van de gebruiker.
    • Verzamel indien nodig gebruikerskenmerken.
    • Eenmalige wachtwoordcode opnieuw verzenden (aanbevolen).
    • Registratiestroom starten.

  2. Voeg in uw app een knop toe waarvan de geselecteerde gebeurtenis het volgende codefragment activeert:

    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
        }
    }
}
    • Gebruik de instantiemethode signUp(username) van de SDK om de registratiestroom te starten.
      • Als u zich wilt registreren met de gebruikersnaam (e-mailadres) en het wachtwoord, geeft u de wachtwoordparameter door aan de signUp functie signUp(username, password).
    • De parameter van de methode, usernameis vervolgens het e-mailadres dat u van de gebruiker verzamelt.
    • In het meest voorkomende scenario retourneert het signUp(username) of signUp(username, password) een resultaat, SignUpResult.CodeRequiredwat aangeeft dat de SDK verwacht dat de app de e-mail eenmalige wachtwoordcode verzendt die naar het e-mailadres van de gebruiker wordt verzonden.
    • Het SignUpResult.CodeRequired object bevat een nieuwe statusverwijzing, die we kunnen ophalen via actionResult.nextState.
    • De nieuwe status geeft ons toegang tot twee nieuwe methoden:
      • submitCode() verzendt de eenmalige wachtwoordcode van de e-mail die door de app van de gebruiker wordt verzameld.
      • resendCode() Hiermee wordt de eenmalige wachtwoordcode van het e-mailbericht opnieuw verzonden als de gebruiker de code niet ontvangt.
    • De submitCode() retourneert SignUpResult.Complete, wat aangeeft dat de stroom is voltooid en dat de gebruiker is geregistreerd.
    • De signUp(username) of signUp(username, password) kan ook terugkeren SignUpError om aan te geven dat er een fout is opgetreden.

Gebruikerskenmerken verzamelen tijdens het registreren

Of u nu een gebruiker registreert met een eenmalige wachtwoordcode of gebruikersnaam (e-mail) en wachtwoord, u kunt gebruikerskenmerken verzamelen voordat het account van een gebruiker wordt gemaakt:

  • De signUp() methode accepteert een attributes parameter 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
        )
        //...
    }

  • De Android SDK biedt een hulpprogrammaklasse UserAttribute.Builder die u gebruikt om gebruikerskenmerken te maken. Als u bijvoorbeeld gebruikerskenmerken voor plaats en land wilt verzenden, gebruikt u het volgende codefragment om de userAttributes variabele te bouwen:

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

    De methodenamen in de UserAttribute.Builder klasse zijn hetzelfde als de programmeerbare namen van de gebruikerskenmerken die ze bouwen. Meer informatie over de opbouwfunctie voor Android SDK-kenmerken.

  • De signUp(username, attributes) of signUp(username, attributes, password)methode kan terugkeren SignUpResult.AttributesRequired om aan te geven dat de app een of meer vereiste kenmerken moet indienen voordat Microsoft Entra een account maakt. Deze kenmerken worden door de beheerder geconfigureerd als verplicht in het Microsoft Entra-beheercentrum. Microsoft Entra vraagt niet expliciet om optionele gebruikerskenmerken.

  • Het SignUpResult.AttributesRequired resultaat bevat een requiredAttributes parameter. requiredAttributes is een lijst RequiredUserAttribute met objecten die details bevatten over de gebruikerskenmerken die de app moet verzenden. Gebruik het volgende codefragment om te verwerken actionResult is SignUpResult.AttributesRequired:

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

Registratiefouten afhandelen

Tijdens het registreren slagen niet alle acties. De gebruiker kan bijvoorbeeld proberen zich aan te melden met een al gebruikt e-mailadres of een ongeldige wachtwoordcode voor eenmalige e-mail verzenden.

Aanmeldingsfout afhandelen

Als u fouten voor de signUp() methode wilt afhandelen, gebruikt u het volgende codefragment:

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) of signUp(username, password, attributes) kan retourneren SignUpError.

  • SignUpError geeft een mislukt actieresultaat aan dat is geretourneerd door signUp() en bevat geen verwijzing naar de nieuwe status.

  • Als actionResult is SignUpErrorMSAL Android SDK hulpprogramma's biedt waarmee u de specifieke fouten verder kunt analyseren:

    • De methode isUserAlreadyExists() controleert of de gebruikersnaam al is gebruikt om een account te maken.
    • isInvalidAttributes() controleert of een of meer kenmerken die door de app zijn verzonden, mislukte validatie, zoals een onjuist gegevenstype. Het bevat een invalidAttributes parameter, een lijst met alle kenmerken die door de apps zijn verzonden, maar de validatie is mislukt.
    • isInvalidPassword() controleer of het wachtwoord ongeldig is, bijvoorbeeld wanneer het wachtwoord niet voldoet aan alle vereisten voor wachtwoordcomplexiteit. Meer informatie over het wachtwoordbeleid van Microsoft Entra
    • isInvalidUsername() controleer of de gebruikersnaam ongeldig is, bijvoorbeeld wanneer het e-mailadres van de gebruiker ongeldig is.
    • isBrowserRequired() controleert of een browser (terugval op internet) nodig is om de verificatiestroom te voltooien. Dit scenario treedt op wanneer systeemeigen verificatie niet voldoende is om de verificatiestroom te voltooien. Een beheerder configureert bijvoorbeeld e-mail en wachtwoord als verificatiemethode, maar de app kan geen wachtwoord verzenden als een uitdagingstype of ondersteunt het gewoon niet. Gebruik de stappen in de ondersteuningswebback in de Android-app om scenario's af te handelen wanneer dit gebeurt.
    • isAuthNotSupported() controleert of de app een vraagtype verzendt dat niet door Microsoft Entra wordt ondersteund. Dit is een andere waarde voor het uitdagingstype dan een oob of wachtwoord. Meer informatie over uitdagingstypen.

    Informeer de gebruiker dat het e-mailbericht al in gebruik is of dat sommige kenmerken ongeldig zijn met behulp van een vriendelijk bericht in de gebruikersinterface van de app.

  • Gebruik het volgende codefragment om de fout van ongeldige kenmerken af te handelen:

    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
    )
} 
//...

Fout met eenmalige wachtwoordcode verzenden van e-mail afhandelen

Als u fouten voor de submitCode() methode wilt afhandelen, gebruikt u het volgende codefragment:

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() kan retourneren SubmitCodeError.

  • Gebruik de isInvalidCode() methode om te controleren op de specifieke fout, zoals dat de ingediende code ongeldig is. In dit geval moet de vorige statusverwijzing worden gebruikt om de actie opnieuw uit te voeren.

  • Als u een nieuwe wachtwoordcode voor een e-mail wilt ophalen, gebruikt u het volgende codefragment:

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

Zorg ervoor dat u de importinstructies opneemt. Android Studio moet automatisch de importinstructies voor u bevatten.

U hebt alle benodigde stappen voltooid om u aan te melden bij uw app. Bouw uw toepassing en voer deze uit. Als alles goed is, kunt u zich aanmelden voor de gebruiker met behulp van een eenmalige wachtwoordcode of e-mail en wachtwoord.

Optioneel: Aanmelden na een registratiestroom

Na een geslaagde aanmeldingsstroom kunt u zich aanmelden bij een gebruiker zonder dat u een aanmeldingsstroom hoeft in teitiëren. Meer informatie in de zelfstudie: Gebruiker aanmelden na aanmelding in Android-artikel .

Volgende stappen

Zelfstudie: Eenmalige wachtwoordcode voor e-mail toevoegen en afmelden in de Android-app.