使用 Azure AD B2C 在 iOS Swift 应用中启用身份验证选项

2025-05-06

重要

自 2025 年 5 月 1 日起，Azure AD B2C 将不再可供新客户购买。在我们的常见问题解答中了解详细信息。

本文介绍为 iOS Swift 应用程序启用、自定义和增强 Azure Active Directory B2C （Azure AD B2C）身份验证体验的方法。

在开始之前，请熟悉以下文章：

使用自定义域

通过使用自定义域，可以完全打造身份验证 URL 的品牌。从用户的角度来看，用户在身份验证过程中会留在您的域名中，而无需重定向到 Azure AD B2C 的 b2clogin.com 域名。

若要删除对 URL 中“b2c”的所有引用，还可以将身份验证请求 URL 中的 B2C 租户名称 (contoso.onmicrosoft.com) 替换为你的租户 ID GUID。例如，可以更改为 https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/https://account.contosobank.co.uk/<tenant ID GUID>/.

若要在身份验证 URL 中使用自定义域和租户 ID，请执行以下作：

按照 “启用自定义域”中的指南进行操作。
用您的自定义域更新 kAuthorityHostName 类的成员。
将 kTenantName 类成员更新为你的租户 ID。

以下 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 会自动填充登录名称，用户只需提供密码。

若要预填充登录名称，请执行以下作：

如果使用自定义策略，请添加所需的输入声明，如设置直接登录中所述。
查找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 登录页。

若要将用户重定向到外部标识提供者，请执行以下作：

检查外部标识提供者的域名。有关详细信息，请参阅将登录重定向到社交服务提供商。
创建或使用现有列表对象来存储额外的查询参数。
将 domain_hint 具有相应域名的参数添加到列表（例如， facebook.com）。
将额外的查询参数列表传递到 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 中的语言自定义使用户流能够适应各种语言以满足客户的需求。有关详细信息，请参阅语言自定义。

若要设置首选语言，请执行以下作：

配置语言自定义。
创建或使用现有列表对象来存储额外的查询参数。
将 ui_locales 具有相应语言代码的参数添加到列表中（例如 en-us，）。
将额外的查询参数列表传递到 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
...

传递自定义查询字符串参数

使用自定义策略，可以传递自定义查询字符串参数。良好的用例示例是想要动态更改页面内容。

若要传递自定义查询字符串参数，请执行以下作：

配置 ContentDefinitionParameters 元素。
创建或使用现有列表对象来存储额外的查询参数。
添加自定义查询字符串参数，例如 campaignId。设置参数值（例如，germany-promotion）。
将额外的查询参数列表传递到 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
...

传递 ID 令牌提示

信赖方应用程序可以将入站 JSON Web 令牌（JWT）作为 OAuth2 授权请求的一部分发送。入站令牌是有关用户或授权请求的提示。 Azure AD B2C 验证令牌，然后提取声明。

若要在身份验证请求中包含 ID 令牌提示，请执行以下作：

在自定义策略中，定义 ID 令牌提示技术配置文件。
在代码中，生成或获取 ID 令牌，然后将令牌设置为变量（例如，idToken）。
创建或使用现有列表对象来存储额外的查询参数。
使用存储 ID 令牌的相应变量添加 id_token_hint 参数。
将额外的查询参数列表传递到 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 视图体验

交互式身份验证需要 Web 浏览器。默认情况下，MSAL 库使用系统 Web 视图。登录期间，MSAL 库会弹出带有 Azure AD B2C 用户界面的 iOS 系统 Web 视图。

有关详细信息，请参阅适用于 iOS/macOS 的自定义浏览器和 WebViews 一文。

根据你的要求，可以使用嵌入的 Web 视图。嵌入式 Web 视图与 MSAL 中的系统 Web 视图之间存在可视和单一登录行为差异。

显示系统 Web 视图体验与嵌入式 Web 视图体验之间的差异的屏幕截图。

重要

建议使用平台默认值（通常是系统浏览器）。系统浏览器更擅长记住之前登录过的用户。某些标识提供者（如 Google）不支持嵌入式视图体验。

若要更改此行为，请将 webviewType 其 MSALWebviewParameters 属性更改为 wkWebView。以下示例演示如何将 Web 视图类型更改为嵌入视图：

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

后续步骤

若要了解详细信息，请参阅适用于 iOS Swift 的 MSAL 配置选项。

通过