在原生 iOS/macOS 應用程式中新增註冊 - Microsoft identity platform

發行項
03/05/2025

適用於：白色圓圈中有灰色 X 符號勞動力租戶綠色圓圈含白色核取標記符號。外部租戶（了解更多）

本教學課程示範如何使用電子郵件一次性密碼或使用者名稱（電子郵件）和密碼註冊使用者，並使用原生驗證收集 iOS/macOS 應用程式中的使用者屬性。

使用電子郵件一次性密碼或使用者名稱（電子郵件）和密碼註冊使用者。
在註冊期間收集用戶屬性。
處理註冊錯誤。

先決條件

教學課程：準備 iOS/macOS 應用程式以進行原生驗證。
如果您要在註冊期間收集使用者屬性，請在建立註冊和登入使用者流程時設定使用者屬性，。

若要使用電子郵件一次性密碼或使用者名稱（電子郵件）和密碼註冊使用者，請從使用者收集電子郵件，然後將包含電子郵件一次性密碼的電子郵件傳送給使用者。使用者輸入有效的電子郵件一次性密碼來驗證其用戶名稱。

若要註冊使用者，您需要：

建立使用者介面（UI）以：
- 從使用者收集電子郵件。將驗證新增至您的輸入，以確保使用者輸入有效的電子郵件位址。
- 如果您使用使用者名稱（電子郵件）和密碼註冊，請收集密碼。
- 從使用者收集電子郵件一次性密碼。
- 如有需要，請收集用戶屬性。
- 如果使用者未收到密碼，請重新傳送一次性密碼。
- 啟動註冊流程。
在您的應用程式中，新增按鈕，其 select 事件會觸發下列代碼段：
```
@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)
}
```
- 若要使用 Email 單次密碼註冊用戶，我們會使用連結庫的 signUp(parameters:delegate) 方法，此方法會透過呼叫傳遞的委派物件上的其中一種方法以異步方式回應，該方法必須實作 SignUpStartDelegate 通訊協定。下列程式代碼行會啟動使用者註冊流程：
```
nativeAuth.signUp(parameters: parameters, delegate: self)
```
  在 signUp(parameters:delegate) 方法中，我們會傳送 MSALNativeAuthSignUpParameters 實例，當中包含從提交表單取得的使用者電子郵件地址，及代理（實作 SignUpStartDelegate 通訊協定的類別）。
- 若要使用 Email 搭配密碼註冊使用者，請使用下列代碼段：
```
@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)
}
```
  我們使用連結庫的 signUp(parameters:delegate) 方法，此方法會藉由呼叫傳遞的委派物件上的其中一個方法以異步方式回應，這個方法必須實作 SignUpStartDelegate 通訊協定。下列代碼行會啟動使用者註冊程序：
```
nativeAuth.signUp(parameters: parameters, delegate: self)
```
  在 signUp(parameters:delegate) 方法中，我們會將包含使用者電子郵件位址及其密碼的 MSALNativeAuthSignUpParameters 實例與委派一起傳遞（實作 SignUpStartDelegate 通訊協定的類別）。
- 若要將 SignUpStartDelegate 通訊協定實作為類別的延伸模組，請使用：
```
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)"
    }
}
```
  呼叫 signUp(parameters:delegate)將導致呼叫 onSignUpCodeRequired() 或 onSignUpStartError() 的委派方法。使用 onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength) 來表示已發送驗證碼以確認使用者的電子郵件信箱。除了程式碼被發送到的位置和包含位數的詳細資訊外，這個委派方法還有一個類型為 SignUpCodeRequiredState的 newState 參數，這使我們可以存取兩個新方法：
  - submitCode(code:delegate)
  - resendCode(delegate)
  若要提交使用者提供給我們的程式代碼，請使用：
```
newState.submitCode(code: userSuppliedCode, delegate: self)
```
  - 若要將 SignUpVerifyCodeDelegate 通訊協定實作為類別的延伸模組，請使用：
```
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) 接受委派參數，我們必須在 SignUpVerifyCodeDelegate 通訊協議中實作必要的方法。在最常見的案例中，我們會收到呼叫 onSignUpCompleted(newState)，指出用戶已註冊且流程已完成。

無論您是使用電子郵件一次性密碼或使用者名稱（電子郵件）和密碼註冊使用者，都可以在建立用戶帳戶之前收集用戶屬性。您可以使用具有 attributes 屬性的 MSALNativeAuthSignUpParameters 來呼叫 signUp(parameters:delegate) 方法。

若要收集使用者屬性，請使用下列代碼段：

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

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

signUp(parameters:delegate)會導致呼叫 onSignUpCodeRequired() 或 onSignUpStartError() 委派方法，或者如果在委派中實作，則呼叫 onSignUpAttributesInvalid(attributeNames: [String])。

若要實作 SignUpStartDelegate 通訊協定作為類別的延伸模組，請使用下列代碼段：
```
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)"
    }
}
```
如果屬性無效，則會呼叫方法 onSignUpAttributesInvalid(attributeNames: [String])。在此情況下，我們會向用戶顯示無效的屬性清單。否則，會呼叫 onSignUpCodeRequired(newState:sentTo:channelTargetType:codeLength)，表示已傳送驗證碼來驗證使用者的電子郵件地址。除了程式代碼收件者和程式代碼位數等詳細數據之外，此委派方法具有類型為 SignUpCodeRequiredState的 newState 參數，這可讓我們存取兩個新方法：
- submitCode(code:delegate)
- resendCode(delegate)

跨一或多個頁面的用戶屬性

若要將屬性分散到一或多個頁面，我們必須將我們想要收集的屬性設定為客戶身分識別和存取管理（CIAM）租用戶設定中的必要屬性。

我們會呼叫 signUp(parameters:delegate)，而不傳遞 MSALNativeAuthSignUpParameters 實例中的任何屬性。下一個步驟是呼叫 newState.submitCode(code: userSuppliedCode, delegate: self) 以確認使用者的電子郵件。

我們將 SignUpVerifyCodeDelegate 通訊協定實作成我們類別的延伸，就像以往一樣，但這次除了必要的方法外，我們還必須實作選擇性的方法 onSignUpAttributesRequired(attributes:newState)。

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!"
    }
}

此委派方法具有類型為 SignUpAttributesRequiredState的 newState 參數，可讓我們存取新的方法：

submitAttributes(attributes:delegate)

若要提交使用者提供給我們的屬性，請使用下列代碼段：

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

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

我們也會將 SignUpAttributesRequiredDelegate 通訊協定實作為類別的延伸模組：

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!"
    }
}

當使用者未提供所有必要的屬性，或屬性無效時，會呼叫這些委派方法：

onSignUpAttributesInvalid：表示發送的屬性中，有一個或多個未通過輸入驗證。此錯誤包含 attributeNames 參數，這是開發人員傳送且輸入驗證失敗的所有屬性清單。
onSignUpAttributesRequired：表示伺服器需要傳送一或多個屬性，才能建立用戶帳戶。當租用戶組態中設定一或多個屬性為必要時，就會發生這種情況。此結果包含屬性參數，這是一份 MSALNativeAuthRequiredAttribute 物件清單，其中概述 API 所需使用者屬性的詳細數據。

這兩個委派方法都包含新的狀態參考。我們會使用 newState 參數，以新的屬性再次呼叫 submitAttributes(attributes:delegate)。

註冊期間，並非每個動作都成功。例如，使用者可能會嘗試使用已使用的電子郵件地址註冊，或提交無效的程序代碼。

在先前的 SignUpStartDelegate 通訊協定實作中，我們只會在處理 onSignUpStartError(error) 委派函式時顯示錯誤。

若要藉由管理特定錯誤類型來增強使用者體驗，請使用下列代碼段：

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

成功註冊流程之後，您可以登入使用者，而不需要起始登入流程。若要深入瞭解，請參閱教學課程：在iOS/macOS 應用程式註冊後自動登入使用者一文。

下一步

教學：使用原生驗證在iOS/macOS應用程式中新增登入和登出

共用方式為

先決條件

跨一或多個頁面的用戶屬性

下一步

意見反應

其他資源

共用方式為

教學課程：使用原生驗證在iOS/macOS應用程式中新增註冊

先決條件

註冊使用者

在註冊期間收集用戶屬性

跨一或多個頁面的用戶屬性

處理註冊錯誤

可以選擇在註冊流程之後登入。

下一步

意見反應

其他資源