使用 Azure AD B2C 在 iOS Swift 應用程式中啟用驗證選項

本文所說明的方法是有關啟用、自訂和增強 iOS Swift 應用程式的 Azure Active Directory B2C (Azure AD B2C) 驗證體驗。

開始之前，請先閱讀下列文章：

• 使用 Azure AD B2C 在範例 iOS Swift 應用程式中設定驗證
• 使用 Azure AD B2C 在您自己的 iOS Swift 應用程式中啟用驗證

使用自訂網域

透過使用自訂網域，您可以完全標記驗證 URL。 就使用者而言，使用者在驗證過程中一直停留在您的網域中，並沒有重新導向至 Azure AD B2C b2clogin.com 網域名稱。

若要移除 URL 中對 "b2c" 的所有參考，您也可以將驗證要求 URL 中的 B2C 租用戶名稱 contoso.onmicrosoft.com 換成您自己的租用戶識別碼 GUID。 例如，您可以將 https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ 變更為 https://account.contosobank.co.uk/<tenant ID GUID>/。

若要在驗證 URL 中使用自訂網域和您的租用戶識別碼，請執行下列動作：

1. 遵循啟用自訂網域中的指導。
2. 使用自訂網域來更新 kAuthorityHostName 類別成員。
3. 使用租用戶識別碼來更新 kTenantName 類別成員。

下列 Swift 程式碼顯示變更前的應用程式設定：

let kTenantName = "contoso.onmicrosoft.com" 
let kAuthorityHostName = "contoso.b2clogin.com" 

下列 Swift 程式碼顯示變更後的應用程式設定：

let kTenantName = "00000000-0000-0000-0000-000000000000" 
let kAuthorityHostName = "login.contoso.com" 

預先填入登入名稱

在登入使用者旅程圖中，您的應用程式可能會將特定使用者當作目標。 當應用程式將使用者當作目標時，可在授權要求中指定 login_hint 查詢參數與使用者的登入名稱。 Azure AD B2C 會自動填入登入名稱，而使用者只需提供密碼。

若要預先填入登入名稱，請執行下列動作：

1. 如果您使用自訂原則，請新增必要的輸入宣告，如設定直接登入中所述。
2. 尋找您的 Microsoft 驗證程式庫 (MSAL) 設定物件，然後使用登入提示來新增 withLoginHint() 方法。

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.loginHint = "bob@contoso.com"
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

預先選取識別提供者

如果您已將應用程式的登入旅程圖設定為包含社交帳戶 (例如 Facebook、LinkedIn 或 Google)，您可以指定 domain_hint 參數。 此查詢參數會向 Azure AD B2C 提供應該用於登入的社交識別提供者相關提示。 例如，如果應用程式指定 domain_hint=facebook.com，則登入流程會直接移至 Facebook 登入頁面。

若要將使用者重新導向至外部識別提供者，請執行下列動作：

1. 檢查外部識別提供者的網域名稱。 如需詳細資訊，請參閱將登入重新導向至社交提供者。
2. 建立或使用現有的清單物件來儲存額外的查詢參數。
3. 將具有對應網域名稱的 domain_hint 參數新增至清單 (例如 facebook.com)。
4. 將額外的查詢參數清單傳遞至 MSAL 設定物件的 extraQueryParameters 屬性。

let extraQueryParameters: [String: String] = ["domain_hint": "facebook.com"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

指定 UI 語言

Azure AD B2C 中的語言自訂，可讓您的使用者流程容納各種不同語言，以符合客戶的需求。 如需詳細資訊，請參閱語言自訂。

若要設定慣用語言，請執行下列動作：

1. 設定語言自訂。
2. 建立或使用現有的清單物件來儲存額外的查詢參數。
3. 將具有對應語言代碼的 ui_locales 參數新增至清單 (例如 en-us)。
4. 將額外的查詢參數清單傳遞至 MSAL 設定物件的 extraQueryParameters 屬性。

let extraQueryParameters: [String: String] = ["ui_locales": "en-us"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

傳遞自訂查詢字串參數

使用自訂原則，您可以傳遞自訂查詢字串參數。 想要以動態方式變更頁面內容，就是個良好的使用案例範例。

若要傳遞自訂查詢字串參數，請執行下列動作：

1. 設定 ContentDefinitionParameters 元素。
2. 建立或使用現有的清單物件來儲存額外的查詢參數。
3. 新增自訂查詢字串參數，例如 campaignId。 設定參數值 (例如 germany-promotion)。
4. 將額外的查詢參數清單傳遞至 MSAL 設定物件的 extraQueryParameters 屬性。

let extraQueryParameters: [String: String] = ["campaignId": "germany-promotion"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

傳遞識別碼權杖提示

信賴憑證者應用程式可以將輸入 JSON Web 權杖 (JWT) 放入 OAuth2 授權要求中傳送。 輸入權杖是關於使用者或授權要求的提示。 Azure AD B2C 會驗證權杖，然後擷取宣告。

若要在驗證要求中包含識別碼權杖提示，請執行下列動作：

1. 在您的自訂原則中，定義識別碼權杖提示技術設定檔。
2. 在您的程式碼中，產生或取得識別碼權杖，然後將權杖設定為變數 (例如 idToken)。
3. 建立或使用現有的清單物件來儲存額外的查詢參數。
4. 使用儲存識別碼權杖的對應變數來新增 id_token_hint 參數。
5. 將額外的查詢參數清單傳遞至 MSAL 設定物件的 extraQueryParameters 屬性。

let extraQueryParameters: [String: String] = ["id_token_hint": idToken]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

設定記錄

MSAL 程式庫會產生可協助診斷問題的記錄訊息。 應用程式可以設定記錄。 應用程式也可以讓您自訂對詳細資料層級的控制，以及是否記錄個人和組織資料。

建議您建立 MSAL 記錄回撥，並為使用者提供在遇到驗證問題時提交記錄的方法。 MSAL 提供下列層級的記錄詳細資料：

• 錯誤：已發生問題並產生錯誤。 此層級用於偵錯和識別問題。
• 警告：不一定已經發生錯誤或失敗，但該資訊可用來進行診斷並查明問題。
• 資訊：MSAL 會記錄用於資訊用途，而不一定用於偵錯的事件。
• 詳細資訊：這是預設層級。 MSAL 會記錄程式庫行為的完整詳細資料。

根據預設，MSAL 記錄器不會擷取任何個人或組織資料。 程式庫可讓您選擇在需要時啟用記錄個人和組織資料的功能。

在提出任何 MSAL 要求之前，應儘早在應用程式啟動順序中設定 MSAL 記錄器。 在 AppDelegate.swiftapplication 方法中，設定 MSAL 記錄。

下列程式碼片段示範如何設定 MSAL 記錄：

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        MSALGlobalConfig.loggerConfig.logLevel = .verbose
        MSALGlobalConfig.loggerConfig.setLogCallback { (logLevel, message, containsPII) in
            
            // If PiiLoggingEnabled is set YES, this block will potentially contain sensitive information (Personally Identifiable Information), but not all messages will contain it.
            // containsPII == YES indicates if a particular message contains PII.
            // You might want to capture PII only in debug builds, or only if you take necessary actions to handle PII properly according to legal requirements of the region
            if let displayableMessage = message {
                if (!containsPII) {
                    #if DEBUG
                    // NB! This sample uses print just for testing purposes
                    // You should only ever log to NSLog in debug mode to prevent leaking potentially sensitive information
                    print(displayableMessage)
                    #endif
                }
            }
        }
        return true
    }

內嵌的 Web 檢視體驗

互動式驗證一定會使用到網頁瀏覽器。 依預設，MSAL 程式庫會使用系統 Web 檢視。 在登入期間，MSAL 程式庫會以 Azure AD B2C 使用者介面來顯示 iOS 系統 Web 檢視。

如需詳細資訊，請參閱自訂 iOS/macOS 的瀏覽器和 WebView。

視您的需求而定，您可以使用內嵌的 Web 檢視。 內嵌的 Web 檢視與 MSAL 中的系統 Web 檢視之間有視覺效果和單一登入行為的差異。

重要

建議您使用平台預設值，這通常是系統瀏覽器。 系統瀏覽器更適合用來記住先前登入過的使用者。 某些身分識別提供者 (例如 Google) 不支援內嵌檢視體驗。

若要變更此行為，請將 MSALWebviewParameters 的 webviewType 屬性變更為 wkWebView。 下列範例示範如何將 Web 檢視類型變更為內嵌檢視：

func initWebViewParams() {
    self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
    
    // Use embedded view experience
    self.webViewParameters?.webviewType = .wkWebView
}

下一步

• 若要深入了解，請參閱適用於 iOS Swift 的MSAL 設定選項。