Aggiungere l'iscrizione in un'app Android usando l'autenticazione nativa - Microsoft Entra External ID

Articolo
02/07/2025

Questa esercitazione illustra come iscrivere un utente usando il passcode monouso o il nome utente (e-mail) e la password e acquisire gli attributi utente nell'app per dispositivi mobili Android usando l'autenticazione nativa.

In questa esercitazione apprenderai a:

Iscrivere un utente usando il passcode monouso o il nome utente (e-mail) e la password.
Raccogliere gli attributi utente durante l'iscrizione
Gestire gli errori di iscrizione.

Prerequisiti

Completare la procedura descritta nell'articolo Esercitazione: preparare l'app Android per l'autenticazione nativa.
Se si desidera raccogliere gli attributi utente durante l'iscrizione, configurare gli attributi utente quando si crea il flusso iscrizione e accesso utente.

Per iscrivere un utente usando il passcode monouso o il nome utente (e-mail) e la password, si acquisisce un messaggio di posta elettronica dall'utente, quindi si invia un messaggio di posta elettronica contenente un passcode monouso all'utente. L'utente immette un passcode monouso di posta elettronica valido per convalidare il proprio nome utente.

Per iscrivere un utente, è necessario:

Creare un'interfaccia utente (IU) per:
- Acquisire un’e-mail dall'utente. Aggiungere la convalida agli input per accertarsi che l'utente immetta un indirizzo di posta elettronica valido.
- Acquisire una password se si effettua l'iscrizione con il nome utente (e-mail) e la password.
- Acquisire un passcode monouso tramite e-mail dall'utente.
- Se necessario, acquisire gli attributi utente.
- Inviare nuovamente il passcode monouso (scelta consigliata).
- Avviare il flusso di iscrizione.
Nell'app, aggiungere un pulsante, il cui evento select attiva il frammento di codice seguente:
```
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
         }
    }
}
```
- Usare il metodo di istanza dell'SDK, signUp(parameters), per avviare il flusso di iscrizione.
- Per iscriversi usando nome utente (indirizzo di posta elettronica) e password, creare un'istanza della classe NativeAuthSignUpParameters e assegnare il nome utente e la password.
- Il parametro di iscrizione, username, è l'indirizzo di posta elettronica raccolto dall'utente.
- Nello scenario più comune, il signUp(parameters) restituisce un risultato, SignUpResult.CodeRequired, che indica che l'SDK prevede che l'app invii il passcode monouso di posta elettronica inviato all'indirizzo di posta elettronica dell'utente.
- L'oggetto SignUpResult.CodeRequired contiene un nuovo riferimento di stato, che è possibile recuperare tramite actionResult.nextState.
- Il nuovo stato consente di accedere a due nuovi metodi:
  - submitCode() invia l’e-mail passcode monouso che l'app acquisisce dall'utente.
  - resendCode() invia nuovamente l’e-mail passcode monouso se l'utente non riceve il codice.
- submitCode() restituisce SignUpResult.Complete, che indica che il flusso è completo e che l'utente è stato registrato.
- Il signUp(parameters) può restituire anche SignUpError per indicare che si è verificato un errore.

Se si effettua l'iscrizione di un utente usando il passcode monouso o il nome utente (e-mail) e la password, è possibile acquisire gli attributi utente prima che venga creato l'account dell’utente:

L'istanza di NativeAuthSignUpParameters accetta un parametro attributes:

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

Android SDK fornisce una classe di utilità UserAttribute.Builder usata per creare attributi utente. Ad esempio, per inviare attributi utente città e paese, usare il frammento di codice seguente per compilare la variabile userAttributes:
```
     val userAttributes = UserAttributes.Builder ()
    .country(country) 
    .city(city) 
    .build()   
```
I nomi dei metodi nella classe UserAttribute.Builder sono uguali ai nomi programmabili degli attributi utente compilati. Altre informazioni sul generatore di attributi di Android SDK.
Il metodo signUp(parameters) può restituire SignUpResult.AttributesRequired per indicare che l'app deve inviare uno o più attributi obbligatori prima che Microsoft Entra crei un account. Questi attributi vengono configurati dall'amministratore come obbligatori nell'interfaccia di amministrazione di Microsoft Entra. Microsoft Entra non richiede esplicitamente gli attributi utente facoltativi.

Il risultato SignUpResult.AttributesRequired contiene un parametro requiredAttributes. requiredAttributes è un elenco di RequiredUserAttribute oggetti che contiene dettagli sugli attributi utente che l'app deve inviare. Per gestire actionResult is SignUpResult.AttributesRequired, usare il frammento di codice seguente:

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

Durante l'iscrizione, non tutte le azioni hanno esito positivo. Ad esempio, l'utente potrebbe tentare di iscriversi con un indirizzo di posta elettronica già usato o inviare un’e-mail passcode monouso non valida.

Per gestire gli errori per il metodo signUp(), usare il frammento di codice seguente:

 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) può restituire SignUpError.
SignUpError indica un risultato di azione non riuscito restituito da signUp() e non includerà un riferimento al nuovo stato.
Se actionResult is SignUpError, MSAL Android SDK fornisce metodi per consentire di analizzare ulteriormente gli errori specifici:
- Il metodo isUserAlreadyExists() controlla se il nome utente è già stato usato per creare un account.
- isInvalidAttributes() controlla se uno o più attributi inviati dall'app hanno avuto esito negativo, come ad esempio un tipo di dati errato. Contiene un parametro invalidAttributes, ovvero un elenco di tutti gli attributi inviati dalle app, ma la conferma non è andata a buon fine.
- isInvalidPassword() verificare che la password sia valida, ovvero che soddisfi tutti i requisiti di complessità delle password. Ulteriori informazioni sui criteri password di Microsoft Entra
- isInvalidUsername() verificare che il nome utente sia valido, ad esempio che il messaggio di posta elettronica dell'utente sia valido.
- isBrowserRequired() verificare la necessità di un browser (fallback Web), per completare il flusso di autenticazione. Questo scenario si verifica quando l'autenticazione nativa non è sufficiente per completare il flusso di autenticazione. Ad esempio, un amministratore configura l’e-mail e la password come metodo di autenticazione, ma l'app non riesce a inviare la password come tipologia di verifica o semplicemente non la supporta. Usare la procedura descritta in Supportare il fallback Web nell'app Android per gestire lo scenario in cui si verifica.
- isAuthNotSupported() verifica se l'app invia un tipo di verifica non supportato da Microsoft Entra, ovvero un valore del tipo di verifica diverso da oob o password. Altre informazioni sulle tipologie di verifica.
Notifica all'utente che l’e-mail è già in uso o che alcuni attributi non sono validi usando un messaggio informale nell'IU dell'app.

Per gestire l'errore degli attributi non validi, usare il frammento di codice seguente:

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

Gestire l'errore di invio del passcode monouso tramite e-mail

Per gestire gli errori per il metodo submitCode(), usare il frammento di codice seguente:

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() può restituire SubmitCodeError.
Usare il metodo isInvalidCode() per verificare la presenza dell'errore specifico, ad esempio il codice inviato non è valido. In questo caso, il riferimento allo stato precedente deve essere usato per ripetere l'azione.

Per recuperare una nuova e-mail passcode monouso, usare il frammento di codice seguente:

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

Accertarsi di includere le istruzioni per l’importazione. Android Studio deve includere automaticamente le istruzioni import.

Sono stati completati tutti i passaggi necessari per registrare correttamente un utente nell'app. Compilare ed eseguire l'applicazione. Se tutto va bene, si dovrebbe poter iscrivere correttamente l’utente usando un passcode monouso o un’e-mail e una password.

Dopo un flusso di iscrizione andato a buon fine, è possibile far accedere l’utente senza avviare un flusso di accesso. Per altre informazioni, vedere l'articolo Esercitazione: far accedere l'utente dopo l'iscrizione in Android.

Passaggi successivi

Esercitazione: aggiungere l'accesso e disconnettersi con e-mail passcode monouso nell'app Android.

Condividi tramite

Prerequisiti

Gestire l'errore di invio del passcode monouso tramite e-mail

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Esercitazione: Aggiungere l'iscrizione in un'app per dispositivi mobili Android usando l'autenticazione nativa

Prerequisiti

Iscrivere un utente

Raccogliere gli attributi utente durante l'iscrizione

Gestire gli errori di iscrizione

Gestire l'errore di iscrizione all'avvio

Gestire l'errore di invio del passcode monouso tramite e-mail

Facoltativo: accedere dopo un flusso di iscrizione

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive