WKWebView 在企业内部应用或混合开发中经常需要加载受保护资源，当服务端返回 401 Unauthorized 状态码时，WebKit 不会自动弹出标准的系统登录框，而是触发导航代理的认证挑战回调。如果开发者漏掉这个回调，页面可能表现为空白、重复弹窗，或者 WebView 直接取消加载。对 NTLM 认证来说，情况更为复杂，因为 NTLM 属于基于连接的多轮质询协议，普通的一次性用户名密码输入很难满足要求。
本文先从 WKURLAuthenticationChallenge 的对象结构说起，说明 401 与保护空间之间的关系；然后给出 NTLM 认证的可行方案，借助 URLSession 预先获取凭据；最后讨论缓存、错误码和常见问题，帮助你在 iOS 端稳定接管 401 认证流程。
一、理解 WKURLAuthenticationChallenge 与保护空间
当 WKWebView 发起请求后，如果服务端响应 401 或 407，WebKit 会生成一个 WKURLAuthenticationChallenge 对象传递给导航代理。这个对象中包含 protectionSpace，也就是保护空间，描述需要认证的服务器信息。protectionSpace 的 authenticationMethod 属性决定了认证协议类型，常见值包括 NSURLAuthenticationMethodHTTPBasic、NSURLAuthenticationMethodHTTPDigest、NSURLAuthenticationMethodNTLM 以及 NSURLAuthenticationMethodNegotiate。
开发者容易忽略的一点是，同一个保护空间下的认证信息并不是全部相同。Basic 和 Digest 可以直接通过用户名密码生成 URLCredential 交给 completionHandler；但 NTLM 和 Negotiate 通常需要多次握手，并且与 TCP 连接、域信息、代理配置关系密切。如果只是把认证方法当成同一个分支处理，很可能导致认证失败或 WebView 卡住。
另一个关键属性是 previousFailureCount，它表示该保护空间之前尝试失败的次数。很多应用在用户密码错误后没有清空凭据存储，导致 WebKit 一直复用旧的错误凭据，用户无论怎样输入都会重复失败。因此，在挑战回调中判断 previousFailureCount，并主动调用 URLCredentialStorage.shared.removeCredential 清除缓存，是稳定处理 401 的前提。
二、NTLM 认证为什么不能直接弹出系统登录框
NTLM 是微软提出的一套挑战/响应认证协议，报文在 HTTP 头中以 Authorization: NTLM 和 WWW-Authenticate: NTLM 进行交换。协议大致分为三步：客户端先发送一条协商消息，服务端返回 401 并附带挑战信息，客户端再根据用户密码计算响应并重新请求。问题在于，WKWebView 的认证挑战回调是单次回调，只适合处理 Basic 这类一问一答的认证，而 NTLM 的多个步骤需要保持连接状态或重复触发挑战。
在 iOS 中，Safari 和 WKWebView 对 NTLM 的支持并不相同。Safari 可以弹出系统认证框并完成 NTLM 握手，但 WKWebView 不会自动弹出这样的系统框，或者说弹出的只是基础的 HTTP 认证框，无法持续处理 NTLM 的多次质询。如果你在 webView(_:didReceive:completionHandler:) 中直接构造一个 URLCredential 并调用 completionHandler(.useCredential, credential)，很可能会发现第一次请求成功返回 200，紧接着后续资源请求再次失败。
更稳定的做法是先使用独立的 URLSession 请求同一保护空间，利用 URLSessionDelegate 完成 NTLM 的多轮质询，拿到有效的 URLCredential 后再回传给 WKWebView。这样做的好处是，URLSession 的认证委托会多次回调 urlSession(_:didReceive:completionHandler:)，能够按顺序完成协商、挑战和响应，最终获得可复用的凭据。下面代码展示了这一过程。
import Foundation
final class NTLMAuthenticationHandler: NSObject, URLSessionDelegate {
private var session: URLSession?
private var credential: URLCredential?
private let username: String
private let password: String
init(username: String, password: String) {
self.username = username
self.password = password
super.init()
}
func fetchCredential(for protectionSpace: URLProtectionSpace, completion: @escaping (URLCredential?) -> Void) {
let config = URLSessionConfiguration.ephemeral
config.urlCredentialStorage = nil
config.requestCachePolicy = .reloadIgnoringLocalCacheData
session = URLSession(configuration: config, delegate: self, delegateQueue: nil)
let host = protectionSpace.host
let port = protectionSpace.port
let scheme = protectionSpace.protocol ?? "http"
let urlString = "\(scheme)://\(host):\(port)/"
guard let url = URL(string: urlString) else {
completion(nil)
return
}
let request = URLRequest(url: url)
let task = session?.dataTask(with: request) { [weak self] _, _, _ in
completion(self?.credential)
self?.session?.invalidateAndCancel()
self?.session = nil
}
task?.resume()
}
func urlSession(_ session: URLSession, didReceive challenge: URLAuthenticationChallenge, completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
if challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodNTLM {
let credential = URLCredential(user: username, password: password, persistence: .forSession)
completionHandler(.useCredential, credential)
} else {
completionHandler(.performDefaultHandling, nil)
}
}
}
需要注意，URLSession 实例必须被强引用，否则任务尚未完成时对象被释放，delegate 回调不会执行。这里使用类属性持有 session，任务结束后再调用 invalidateAndCancel 释放资源。同时设置 urlCredentialStorage = nil 是为了避免系统缓存旧的错误凭据干扰本次认证。
如果企业服务器使用域账户，用户名需要写成 DOMAIN\username 形式。这里的反斜杠是 Windows 域账户分隔符，Objective-C 和 Swift 字符串中都要注意转义。例如 Swift 中应写 "DOMAIN\\username"，而 Objective-C 中写 @"DOMAIN\\username"。如果少了反斜杠，服务端可能返回 401 且没有明确错误。
三、在 WKNavigationDelegate 中统一处理 401 挑战
WKWebView 的认证挑战回调方法为 webView(_:didReceive:completionHandler:)，它属于 WKNavigationDelegate 协议。无论是首次加载还是 iframe 中的子资源请求，只要服务端要求认证，都会走到这里。开发者应该在该方法中先读取 challenge.protectionSpace.authenticationMethod，再决定使用哪种凭据策略。
extension ViewController: WKNavigationDelegate {
func webView(_ webView: WKWebView, didReceive challenge: URLAuthenticationChallenge, completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
let method = challenge.protectionSpace.authenticationMethod
if method == NSURLAuthenticationMethodHTTPBasic {
let credential = URLCredential(user: "your_user", password: "your_password", persistence: .forSession)
completionHandler(.useCredential, credential)
} else if method == NSURLAuthenticationMethodNTLM {
let handler = NTLMAuthenticationHandler(username: "DOMAIN\\username", password: "your_password")
handler.fetchCredential(for: challenge.protectionSpace) { credential in
if let credential = credential {
completionHandler(.useCredential, credential)
} else {
completionHandler(.cancelAuthenticationChallenge, nil)
}
}
} else {
completionHandler(.performDefaultHandling, nil)
}
}
}
调用 completionHandler 时必须保证只触发一次，并且要在主线程中处理。实际开发中 NTLM 凭据获取是异步完成的，如果服务端在超时时间内没有返回，可以在 fetchCredential 的闭包中增加超时控制，避免页面一直等待。还应考虑 previousFailureCount，如果该值大于 2，说明凭据已多次失败，应当提示用户重新输入账号密码，而不是继续使用缓存的错误凭据。
Basic 认证虽然简单，但同样存在缓存问题。默认情况下 URLCredential 会写入共享的 URLCredentialStorage，下一次请求会自动带上旧凭据。若用户修改了密码，需要先调用 URLCredentialStorage.shared.removeCredential 删除旧项，否则仍然会使用过期凭据。对于 NTLM 认证，建议把 persistence 设为 forSession 或 none，降低跨页面串扰的风险。
四、错误排查与优化建议
在实际项目中，处理 401 与 NTLM 常见的问题集中在三个方面：认证方法判断遗漏、URLSession 配置不当、以及 WebView 的回调链条被打断。第一个问题很容易出现在使用 Kerberos 或 Negotiate 的企业环境，此时 authenticationMethod 会显示为 NSURLAuthenticationMethodNegotiate，如果只处理 NTLM 分支，页面会一直卡在认证状态。建议将 NTLM 和 Negotiate 都交给 URLSession 辅助完成。
另一个容易忽视的点是 ATS 与本地网络。企业内网地址常常使用 HTTP 而不是 HTTPS，iOS 默认的 ATS 会拦截明文请求。需要在 Info.plist 中为相关域名添加 NSExceptionDomains，或临时允许 Arbitrary Loads。证书校验失败时，URLSession 的认证挑战也会触发 NSURLAuthenticationMethodServerTrust，此时不要与 401 混淆。若服务端证书不受信任，应该在 URLSession 的 delegate 中单独处理信任挑战，而不是在 WKWebView 的 401 分支中处理。
如果页面在认证成功后依然无法加载，可以检查 WKWebView 的 customUserAgent 是否被修改。部分企业网关会根据 User-Agent 判断是否允许 NTLM 认证，缺失或错误的 UA 可能造成认证通过但后续资源仍然 403。还可以打开 Safari 开发者工具查看网络请求，确认 Authorization 头是否只出现在第一个请求中，以及后续请求是否带有 Cookie 或认证头。逐一排查请求头与响应状态码，能更快定位认证链路中的断点。
最后，考虑到安全风险，不建议把明文用户名密码硬编码在客户端代码中。可以通过 Keychain 保存，或者由登录页让用户输入后通过 JavaScript 与原生层通信，再传递给认证处理类。使用 Keychain 时注意不要使用 kSecAttrAccessibleAlways 这类过于宽松的可访问性，避免设备锁屏时凭据被读取。