Esercitazione: Aggiungere l'iscrizione in un'app iOS/macOS usando l'autenticazione nativa

Si applica a: cerchio verde con un segno di spunta bianco che indica che il contenuto seguente si applica ai tenant esterni. Tenant esterni (altre informazioni)

Questa esercitazione mostra come registrare un utente usando un passcode monouso tramite e-mail oppure un nome utente (e-mail) e una password nell'app iOS/macOS tramite l'autenticazione nativa. Si apprenderà anche come raccogliere gli attributi utente durante l'iscrizione, incluso un nome utente (alias) e gestire gli errori.

In questa esercitazione, imparerai a:

  • Iscriversi a un utente usando il passcode monouso o il nome utente (indirizzo di posta elettronica) e la password.
  • Raccogliere gli attributi utente durante l'iscrizione, incluso un nome utente (alias).
  • Gestire gli errori di iscrizione.

Prerequisiti

  • Completare i passaggi descritti in Esercitazione: Preparare l'app iOS/macOS per l'autenticazione nativa.
  • Per raccogliere gli attributi durante l'iscrizione, configura gli attributi utente quando crei il flusso utente di iscrizione e accesso.
  • Per specificare un nome utente (alias) durante l'iscrizione, abilita l'attributo utente predefinito Username nel flusso utente di iscrizione del tenant.

Iscriversi a un utente

Per iscriversi a un utente usando il passcode monouso o il nome utente (indirizzo di posta elettronica) e la password, si raccoglie 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 iscriversi a un utente, è necessario:

  1. Creare un'interfaccia utente per:

    • Raccogliere un messaggio di posta elettronica dall'utente. Aggiungere la convalida agli input per assicurarsi che l'utente immetta un indirizzo di posta elettronica valido.
    • Raccogli la password se ti iscrivi con nome utente (email) e password.
    • Raccogliere un nome utente (alias) se l'app supporta l'accesso basato su alias.
    • Raccogliere un passcode monouso tramite posta elettronica dall'utente.
    • Se necessario, raccogliere gli attributi utente.
    • Inviare nuovamente il passcode monouso se l'utente non lo riceve.
    • Avviare il flusso di iscrizione.

  2. Nell'app aggiungere un pulsante, il cui evento select attiva il frammento di codice seguente:

    @IBAction func signUpPressed(_: Any) {
    guard let email = emailTextField.text else {
        resultTextView.text = "Email or password not set"
        return
    }

    let parameters = MSALNativeAuthSignUpParameters(username: email)
    nativeAuth.signUp(parameters: parameters, delegate: self)
}

    • Per registrare un utente con Email one-time-passcode, usare il metodo signUp(parameters:delegate) della libreria, che restituisce la risposta in modo asincrono richiamando uno dei metodi dell'oggetto delegato passato, che deve implementare il protocollo SignUpStartDelegate. La riga di codice seguente avvia il processo di iscrizione dell'utente:

      nativeAuth.signUp(parameters: parameters, delegate: self)

      Nel metodo signUp(parameters:delegate), passa un'istanza MSALNativeAuthSignUpParameters contenente l'indirizzo email dell'utente dal modulo di invio, insieme al delegato (una classe che implementa il protocollo SignUpStartDelegate).

    • Per registrare un utente utilizzando email con password, usare i frammenti di codice seguenti:

      @IBAction func signUpPressed(_: Any) {
    guard let email = emailTextField.text, let password = passwordTextField.text else {
       resultTextView.text = "Email or password not set"
       return
    }

    let parameters = MSALNativeAuthSignUpParameters(username: email)
    parameters.password = password
    nativeAuth.signUp(parameters: parameters, delegate: self)
}

      Il metodo della libreria signUp(parameters:delegate) risponde asincronamente chiamando uno dei metodi dell'oggetto delegato passato, che deve implementare il protocollo SignUpStartDelegate. La riga di codice seguente avvia il processo di iscrizione dell'utente:

      nativeAuth.signUp(parameters: parameters, delegate: self)

      Nel metodo signUp(parameters:delegate), passa un'istanza MSALNativeAuthSignUpParameters contenente l'indirizzo email dell'utente e la relativa password insieme al delegato (una classe che implementa il protocollo SignUpStartDelegate).

    • Per implementare il SignUpStartDelegate protocollo come estensione per la classe, usare:

      extension ViewController: SignUpStartDelegate {
    func onSignUpStartError(error: MSAL.SignUpStartError) {
        resultTextView.text = "Error signing up: \(error.errorDescription ?? "no description")"
    }

    func onSignUpCodeRequired(
        newState: MSAL.SignUpCodeRequiredState,
        sentTo: String,
        channelTargetType: MSAL.MSALNativeAuthChannelType,
        codeLength: Int
    ) {
        resultTextView.text = "Verification code sent to \(sentTo)"
    }
}

      La chiamata a signUp(parameters:delegate) comporta una chiamata ai metodi delegati onSignUpCodeRequired() o onSignUpStartError(). Il onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) viene chiamato per indicare che è stato inviato un codice per verificare l'indirizzo di posta elettronica dell'utente. Oltre ad alcuni dettagli sulla posizione in cui è stato inviato il codice e sul numero di cifre che contiene, questo metodo delegato ha anche un newState parametro di tipo SignUpCodeRequiredState, che consente di accedere a due nuovi metodi:

      • submitCode(code:delegate)
      • resendCode(delegate)

      Per inviare il codice fornito dall'utente, usare:

      newState.submitCode(code: userSuppliedCode, delegate: self)

      • Per implementare il SignUpVerifyCodeDelegate protocollo come estensione per la classe, usare:

        extension ViewController: SignUpVerifyCodeDelegate {
    func onSignUpVerifyCodeError(error: MSAL.VerifyCodeError, newState: MSAL.SignUpCodeRequiredState?) {
        resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
    }

    func onSignUpCompleted(newState: SignInAfterSignUpState) {
        resultTextView.text = "Signed up successfully!"
    }
}

        submitCode(code:delegate) accetta un parametro delegato ed è necessario implementare i metodi necessari nel SignUpVerifyCodeDelegate protocollo. Nello scenario più comune, si riceve una chiamata a onSignUpCompleted(newState) che indica che l'utente è stato registrato e che il flusso è stato completato.

Raccogliere gli attributi dell'utente durante l'iscrizione

Se si effettua l'iscrizione a un utente usando un passcode monouso o un nome utente (indirizzo di posta elettronica) e una password, è possibile raccogliere gli attributi utente prima che venga creato l'account di un utente. Il metodo signUp(parameters:delegate) può essere chiamato usando un MSALNativeAuthSignUpParameters con una proprietà degli attributi.

  1. Per raccogliere gli attributi utente, usare il frammento di codice seguente:

    let attributes = [
    "country": "United States",
    "city": "Redmond"
]

let parameters = MSALNativeAuthSignUpParameters(username: email)
parameters.password = password
parameters.attributes = attributes
nativeAuth.signUp(parameters: parameters, delegate: self)

    Il signUp(parameters:delegate)genera una chiamata ai metodi delegati onSignUpCodeRequired() o onSignUpStartError(), oppure una chiamata a onSignUpAttributesInvalid(attributeNames: [String]) se questo è implementato nel delegato.

  2. Per implementare il SignUpStartDelegate protocollo come estensione per la classe, usare il frammento di codice seguente:

    extension ViewController: SignUpStartDelegate {
    func onSignUpStartError(error: MSAL.SignUpStartError) {
        resultTextView.text = "Error signing up: \(error.errorDescription ?? "no description")"
    }

    func onSignUpCodeRequired(
        newState: MSAL.SignUpCodeRequiredState,
        sentTo: String,
        channelTargetType: MSAL.MSALNativeAuthChannelType,
        codeLength: Int
    ) {
        resultTextView.text = "Verification code sent to \(sentTo)"
    }

    func onSignUpAttributesInvalid(attributeNames: [String]) {
       resultTextView.text = "Invalid attributes  \(attributeNames)"
    }
}

    Se gli attributi non sono validi, viene chiamato il metodo onSignUpAttributesInvalid(attributeNames: [String]). In questo caso, visualizzare l'elenco di attributi non validi per l'utente. In caso contrario, viene chiamato il onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) per indicare che è stato inviato un codice per verificare l'indirizzo di posta elettronica dell'utente. Oltre ai dettagli, ad esempio il destinatario del codice e il numero di cifre del codice, questo metodo delegato ha un newState parametro di tipo SignUpCodeRequiredState, che consente di accedere a due nuovi metodi:

    • submitCode(code:delegate)
    • resendCode(delegate)

Attributi utente in una o più pagine

Per distribuire gli attributi in una o più pagine, impostare gli attributi che si intende raccogliere tra pagine diverse come obbligatori nella configurazione del tenant CIAM (Customer Identity and Access Management).

Richiama signUp(parameters:delegate) senza passare alcun attributo nell'istanza MSALNativeAuthSignUpParameters. Il passaggio successivo consiste nel chiamare newState.submitCode(code: userSuppliedCode, delegate: self) per verificare il messaggio di posta elettronica dell'utente.

Implementare il SignUpVerifyCodeDelegate protocollo come estensione per la classe come in precedenza, ma questa volta è necessario implementare il metodo onSignUpAttributesRequired(attributes:newState) facoltativo oltre ai metodi necessari:

extension ViewController: SignUpVerifyCodeDelegate {
    func onSignUpAttributesRequired(newState: SignUpAttributesRequiredState) {
        resultTextView.text = "Attributes required"
    }

    func onSignUpVerifyCodeError(error: MSAL.VerifyCodeError, newState: MSAL.SignUpCodeRequiredState?) {
        resultTextView.text = "Error verifying code: \(error.errorDescription ?? "no description")"
    }

    func onSignUpCompleted(newState: SignInAfterSignUpState) {
        resultTextView.text = "Signed up successfully!"
    }
}

Questo metodo delegato ha un newState parametro di tipo SignUpAttributesRequiredState, che consente di accedere a un nuovo metodo:

  • submitAttributes(attributes:delegate)

Per inviare gli attributi forniti dall'utente, usare il frammento di codice seguente:

let attributes = [
    "country": "United States",
    "city": "Redmond"
]

newState.submitAttributes(attributes: attributes, delegate: self)

Implementare anche il SignUpAttributesRequiredDelegate protocollo come estensione per la classe:

extension ViewController: SignUpAttributesRequiredDelegate {
    func onSignUpAttributesRequiredError(error: AttributesRequiredError) {
        resultTextView.text = "Error submitting attributes: \(error.errorDescription ?? "no description")"
    }

    func onSignUpAttributesRequired(attributes: [MSALNativeAuthRequiredAttribute], newState: SignUpAttributesRequiredState) {
        resultTextView.text = "Attributes required"
    }

    func onSignUpAttributesInvalid(attributeNames: [String], newState: SignUpAttributesRequiredState) {
        resultTextView.text = "Attributes invalid"
    }

    func onSignUpCompleted(newState: SignInAfterSignUpState) {
        resultTextView.text = "Signed up successfully!"
    }
}

Quando l'utente non fornisce tutti gli attributi necessari o gli attributi non sono validi, questi metodi delegati vengono chiamati:

  • onSignUpAttributesInvalid: indica che uno o più attributi inviati non sono riusciti a convalidare l'input. Questo errore contiene un parametro attributeNames, ovvero un elenco di tutti gli attributi inviati dallo sviluppatore che non ha superato la convalida dell'input.
  • onSignUpAttributesRequired: indica che il server richiede l'invio di uno o più attributi, prima che sia possibile creare l'account utente. Ciò si verifica quando uno o più attributi sono impostati come obbligatori nella configurazione del tenant. Questo risultato contiene i parametri degli attributi, ovvero un elenco di oggetti MSALNativeAuthRequiredAttribute, che descrivono i dettagli sugli attributi utente richiesti dall'API.

Entrambi i metodi delegati contengono un nuovo riferimento di stato. Usare il newState parametro per chiamare submitAttributes(attributes:delegate) di nuovo con i nuovi attributi.

Richiedere un nome utente (alias) durante l'iscrizione

Il nome utente (alias) è un attributo utente speciale. Come altri attributi, ad esempio città o paese, è possibile raccoglierlo durante l'iscrizione. A differenza di questi attributi, l'utente può successivamente usare l'alias per accedere. L'alias (ad esempio, "johndoe") offre agli utenti un modo più breve e più descrittivo per accedere rispetto all'indirizzo di posta elettronica.

Il nome utente (alias) non sostituisce il nome utente (indirizzo di posta elettronica). Durante l'iscrizione, l'app deve sempre raccogliere il nome utente (indirizzo di posta elettronica) come identificatore primario e raccoglie l'alias come attributo insieme al messaggio di posta elettronica. All'accesso, l'utente può quindi scegliere di accedere con il nome utente (indirizzo di posta elettronica) o il nome utente (alias).

Quando l'attributo utente predefinito Username è abilitato nel flusso utente di iscrizione, l'SDK lo accetta tramite lo stesso dizionario attributi usato per altri attributi, come la flatusername chiave. È possibile passare il nome utente (alias) direttamente nella signUp chiamata in modo che l'utente non debba eseguire un passaggio separato obbligatorio per gli attributi.

Per raccogliere un nome utente (alias), aggiungere un campo di input per il nome utente nell'interfaccia utente di iscrizione insieme al campo di posta elettronica, quindi passare l'alias come attributo nella chiamata di iscrizione:

guard let email = emailTextField.text, !email.isEmpty,
      let password = passwordTextField.text, !password.isEmpty,
      let username = usernameTextField.text, !username.isEmpty else {
    showResultText("Please fill in all fields")
    return
}

let attributes: [String: Any] = [
    "flatusername": username
]

let parameters = MSALNativeAuthSignUpParameters(username: email)
parameters.password = password
parameters.attributes = attributes
nativeAuth.signUp(parameters: parameters, delegate: self)

Per i flussi di passcode monouso della posta elettronica (senza password), passare gli attributi senza impostare una password:

let parameters = MSALNativeAuthSignUpParameters(username: email)
parameters.attributes = attributes
nativeAuth.signUp(parameters: parameters, delegate: self)

Quando si gestiscono gli errori di iscrizione al nome utente (alias), la error.isUserAlreadyExists proprietà copre anche un alias duplicato e error.isInvalidAttributes visualizza un valore alias non valido.

Gestire gli errori di iscrizione

Durante l'iscrizione, non tutte le azioni hanno esito positivo. Ad esempio, l'utente potrebbe provare a iscriversi con un indirizzo di posta elettronica già in uso o inviare un codice non valido.

Nell'implementazione precedente del SignUpStartDelegate protocollo, l'errore è stato visualizzato semplicemente quando si gestisce la onSignUpStartError(error) funzione del delegato.

Per migliorare l'esperienza utente gestendo il tipo di errore specifico, usare il frammento di codice seguente:

func onSignUpStartError(error: MSAL.SignUpStartError) {
    if error.isUserAlreadyExists {
        resultTextView.text = "Unable to sign up: User already exists"
    } else if error.isInvalidPassword {
        resultTextView.text = "Unable to sign up: The password is invalid"
    } else if error.isInvalidUsername {
        resultTextView.text = "Unable to sign up: The username is invalid"
    } else {
        resultTextView.text = "Unexpected error signing up: \(error.errorDescription ?? "no description")"
    }
}

Opzionale: accedere dopo una procedura di iscrizione

Dopo aver completato correttamente la procedura di registrazione, è possibile far accedere un utente senza avviare una procedura di accesso. Se l'utente ha effettuato l'iscrizione con un nome utente (alias), può accedere usando il proprio indirizzo di posta elettronica o il relativo alias. Per altre informazioni, vedere l'articolo Tutorial: Sign in user automatically after sign-up in an iOS/macOS app (Esercitazione su : Accedere automaticamente all'utente dopo l'iscrizione a un'app iOS/macOS).

Passaggio successivo

Esercitazione: Aggiungere l'accesso e l'uscita nell'app iOS/macOS usando l'autenticazione nativa

  • Last updated on