authentication

用途

Authentication 技能用于在 iOS 应用中实现认证流程，主要依托 Apple 的 AuthenticationServices 框架。资料中列出的适用范围包括：通过 Apple 登录（Sign in with Apple）、OAuth 与第三方 Web 认证、密码自动填充（Password AutoFill）以及生物识别认证。

主要能力

资料按以下小节组织内容：

• Sign in with Apple
• Credential Handling（凭据处理）
• Credential State Checking（凭据状态检查）
• Token Validation（令牌校验）
• Existing Account Setup Flows（已有账户初始化流程）
• ASWebAuthenticationSession（OAuth）
• Password AutoFill Credentials（密码自动填充凭据）
• Biometric Authentication（生物识别认证）
• SwiftUI SignInWithAppleButton
• Common Mistakes（常见错误）
• Review Checklist（评审清单）
• References（参考资料）

Sign in with Apple

使用前需在 Xcode 中添加 “Sign in with Apple” capability。UIKit 侧通过 ASAuthorizationAppleIDProvider 创建请求、设置 requestedScopes 为 [.fullName, .email]，再由 ASAuthorizationController 执行请求，并设置 delegate 与 presentationContextProvider。

委托回调 didCompleteWithAuthorization 中，可从 ASAuthorizationAppleIDCredential 取出 user（稳定的团队唯一标识）、email（首次授权后为 nil）、fullName（首次授权后为 nil）、identityToken（用于服务端校验的 JWT）与 authorizationCode（用于服务端交换的短期有效码）。资料给出的示例将 userID 保存到 Keychain，并将 identityToken 与 authorizationCode 发送到服务端。错误回调中按 ASAuthorizationError 的 code 分支处理 .canceled、.failed、.invalidResponse、.notHandled、.notInteractive 等情况。

Credential Handling

资料以表格列出 ASAuthorizationAppleIDCredential 各属性在首次授权与后续授权时的行为：user 始终提供；email 与 fullName 仅首次授权且请求时提供，后续为 nil；identityToken 与 authorizationCode 在两种情况下均提供；realUserStatus 首次可能为 .likelyReal / .unknown，后续为 .unknown。资料强调 email 与 fullName 仅在首次授权时提供，必须在初次注册流程中立即缓存；若用户删除并重新添加应用，这些值不会再次返回。示例代码在 handleCredential 中始终持久化 userID，并在 fullName、email 非空时立即保存。

Credential State Checking

资料要求在每次应用启动时检查凭据状态，因为用户可能随时通过“设置 > Apple 账户 > 登录与安全”撤销访问。示例使用 provider.credentialState(forUserID:)，按 .authorized、.revoked、.notFound、.transferred 与 @unknown default 分支处理；网络错误时允许离线访问或重试。此外，通过 NotificationCenter 注册 ASAuthorizationAppleIDProvider.credentialRevokedNotification 观察者，收到通知后立即登出。

Token Validation

identityToken 是 JWT，需发送到服务端校验，不应仅在客户端信任。示例代码将 identityToken 与 authorizationCode 以 JSON POST 到服务端接口，成功后将返回的会话 accessToken 存入 Keychain。服务端需使用 Apple 公钥（JWKS，地址为 https://appleid.apple.com/auth/keys）验证 JWT：iss 为 https://appleid.apple.com、aud 匹配自身 bundle ID、exp 未过期。

Existing Account Setup Flows

在展示登录界面之前，应静默检查是否已存在 Sign in with Apple 与密码凭据。示例同时创建 ASAuthorizationAppleIDProvider 与 ASAuthorizationPasswordProvider 的请求，调用 performRequests(options: .preferImmediatelyAvailableCredentials)。若未找到已有凭据，委托会收到 .notInteractive 错误，应静默处理并展示常规登录 UI。

ASWebAuthenticationSession（OAuth）

OAuth 与第三方认证（Google、GitHub 等）应使用 ASWebAuthenticationSession，资料明确不应使用 WKWebView 做认证流程。示例从授权 URL 启动会话，回调中使用 .customScheme("myapp") 获取 code，再在任务中交换令牌；设置 session.presentationContextProvider 与 session.prefersEphemeralWebBrowserSession = true 以避免共享 Cookie。SwiftUI 侧可使用 @Environment(.webAuthenticationSession) 与 authenticate(using:callback:) 完成流程。资料说明回调类型：.customScheme("myapp") 用于 URL scheme 重定向，.https(host:path:) 用于通用链接重定向（推荐）。

Password AutoFill Credentials

通过 ASAuthorizationPasswordProvider 在 Sign in with Apple 之外提供已保存的钥匙串凭据。示例在同一 ASAuthorizationController 中同时传入 Apple ID 请求与密码请求；委托中按 ASAuthorizationAppleIDCredential 与 ASPasswordCredential 分支处理，后者用 passwordCredential.user 与 passwordCredential.password 登录。为使自动填充生效，需在文本框上设置 textContentType 为 .username 与 .password。

Biometric Authentication

使用 LocalAuthentication 的 LAContext 实现 Face ID / Touch ID 登录或再次认证。示例先以 canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics) 检查可用性，再调用 evaluatePolicy 并传入 localizedReason。资料要求在 Info.plist 中添加 NSFaceIDUsageDescription，缺少该键会在 Face ID 设备上崩溃；同时提示若要用生物识别保护 Keychain 条目（SecAccessControl、.biometryCurrentSet），应参考 ios-security 技能。

SwiftUI SignInWithAppleButton

示例使用 SignInWithAppleButton(.signIn)，在请求闭包中设置 requestedScopes = [.fullName, .email]，在完成闭包中按 .success / .failure 处理，并通过 .signInWithAppleButtonStyle 依据 colorScheme 切换黑白样式。

使用方式

资料以代码示例形式给出各流程的实现方式，未提供安装命令或包管理方式。使用 Sign in with Apple 前需在 Xcode 中启用对应 capability；生物识别需在 Info.plist 添加 NSFaceIDUsageDescription；自动填充需设置 textContentType。

适用场景

适用于需要在 iOS 应用中集成登录与认证能力的开发场景，包括 Apple 登录、第三方 OAuth 登录、钥匙串密码快速登录以及 Face ID / Touch ID 生物识别认证。

限制

资料未提供安装命令、收费信息、价格、平台范围与效果数据。评审清单中列出的要点包括：Xcode 项目中已添加 Sign in with Apple capability；已实现 ASAuthorizationControllerPresentationContextProviding；每次启动检查凭据状态；注册 credentialRevokedNotification 观察者并处理登出；首次授权时缓存 email 与 fullName；identityToken 送服务端校验；令牌存入 Keychain 而非 UserDefaults 或文件；展示登录 UI 前调用 performExistingAccountSetupFlows；处理 .canceled、.failed、.notInteractive 错误；Info.plist 含 NSFaceIDUsageDescription；OAuth 使用 ASWebAuthenticationSession 而非 WKWebView；适当设置 prefersEphemeralWebBrowserSession；为用户名/密码字段设置 textContentType。常见错误部分还指出：不应假设用户仍处于授权状态、不应总是直接展示完整登录界面、不应强制解包 email 或 fullName、不应省略 presentation context provider、不应把 identityToken 存入 UserDefaults。