企业官网建设流程全解析

Firebase Auth for iOS 集成指南：从多方式登录配置到源码级流程解析

【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk

Firebase Auth 为 Apple 平台应用提供了一整套开箱即用的用户认证能力，支持 Google、Apple、Twitter、Microsoft、GitHub、Yahoo、Facebook 等第三方身份提供商，以及邮箱密码、邮箱免密（Passwordless）、手机号、匿名、自定义认证系统等多种登录方式。本文以 firebase-ios-sdk 仓库中 FirebaseAuth/README.md 及其配套的 SampleSwift 示例工程 为核心骨架，结合仓库内真实源码与测试，完整讲解每种认证方式的启用步骤、关键配置项、Xcode 工程要求，并深入到 Passwordless 登录的完整调用链，帮助你在一小时内搭建一个可运行、可演示、可测试的 Firebase Auth 集成工程。

一、Firebase Auth 与仓库内的示例工程

1.1 Firebase Auth 是什么

根据 FirebaseAuth/README.md 的定位，Firebase Auth 是一套帮助 iOS/macOS 应用"轻松支持多种端用户认证选项"（easily support multiple authentication options for their end users）的认证框架。它把认证状态管理、ID Token 生命周期、多因素认证（MFA）、OAuth 凭据交换等复杂逻辑封装为稳定的公开 API，开发者只需关注"选择哪种认证方式、如何把第三方 SDK 的登录结果交给 Firebase"。

从仓库源码结构看，FirebaseAuth 的公开 API 集中在 FirebaseAuth/Sources/Public/FirebaseAuth 目录下，包括：

• FIRAuth.h：核心入口，负责登录、登出、监听认证状态与 ID Token 变化、发送验证邮件/密码重置邮件、处理 Action Code（OOB Code）等；
• FIRUser.h：当前用户对象，提供获取 ID Token、更新邮箱/密码、关联/解绑身份提供商、多因素管理、删除账户等能力；
• 各类 Provider 头文件：FIRGoogleAuthProvider.h、FIREmailAuthProvider.h、FIRPhoneAuthProvider.h、FIRFacebookAuthProvider.h、FIRGitHubAuthProvider.h、FIRTwitterAuthProvider.h、FIRFederatedAuthProvider.h、FIRGameCenterAuthProvider.h等，分别对应把第三方 SDK 的凭据转换为 FirebaseAuthCredential的工厂方法；
• FIRMultiFactor.h：多因素认证（MFA）的公开接口。

1.2 示例工程与测试的组织方式

FirebaseAuth/README.md 明确说明：

• 仓库内的Example/Auth目录包含一批与 FirebaseAuth 集成的样例与测试。在当前仓库中，这一目录即 FirebaseAuth/Tests/SampleSwift，其中包含了 Swift 示例应用AuthenticationExample（基于官方 quickstart-ios 的 authentication 示例实现）、AuthenticationExampleUITests、ObjCApiTests、SwiftApiTests，以及一个generate_refresh_token.sh脚本；
• 单元测试无需额外配置即可随 Firebase 整体测试一起运行；
• 示例工程的搭建、运行与测试说明集中在 Tests/SampleSwift/README.md。

打开示例工程的方式为：在 Xcode 中打开AuthenticationExample.xcodeproj。该工程是一个 Tab 双页应用：SceneDelegate.swift中创建了"Authentication"（认证入口页）与"Current User"（当前用户信息页）两个导航控制器并挂载到UITabBarController上，入口页由 AuthViewController.swift 驱动，通过DataSourceProvider渲染认证方式菜单。

二、连接 Firebase 控制台：把示例工程与你的 Firebase 项目绑定

在使用任何认证流程前，需要先把示例应用连接到 Firebase 控制台。步骤摘要如下：

1. 访问 Firebase 控制台，创建一个新应用（项目）；
2. 在项目中添加一个iOS App，填入的Bundle Identifier必须与示例工程的 Bundle Identifier 完全一致；
3. 按提示下载GoogleService-Info.plist；
4. 将下载的GoogleService-Info.plist拖入 Xcode 工程（或通过File→Add Files to 'AuthenticationExample'添加），并确保该文件被加入应用的主 Target；
5. 此时即可直接构建并运行示例应用。

从 AuthViewController.swift 的 Google 登录实现可以看到，示例应用通过FirebaseApp.app()?.options.clientID读取 Firebase 配置（即来自GoogleService-Info.plist的 CLIENT_ID），这正是"plist 必须加入主 Target"的原因——运行时的FirebaseApp配置依赖它。

三、通用前提：为 OAuth 流程添加自定义 URL Scheme

配置下面大部分身份提供商之前，都需要在 Xcode 工程中为每个身份提供商分别添加一个自定义 URL Scheme（不要互相覆盖替换），这样 Firebase Auth 才能正确接收身份提供商回调回应用的数据。操作路径为：选中应用 Target →Info标签页 → 展开URL Types区域 → 新增 URL Type。

• 对于 Google / Twitter / Microsoft / GitHub / Yahoo 等流程：URL Scheme 使用GoogleService-Info.plist中REVERSED_CLIENT_ID键对应的值；
• 对于 Facebook：URL Scheme 的格式为'fb' + Facebook App Id（例如fb1234567890）；
• 对于 Dynamic Links 免密登录：URL Scheme 使用应用的Bundle Identifier（详见本文第六节）。

此外，REVERSED_CLIENT_ID与 Facebook App Id 也可以在工程的Info.plist中配置（AuthViewController.swift的 Facebook 配置注释提到，Facebook 的kFacebookAppID与Info.plist配置二选一即可）。

四、启用身份提供商（Identity Providers）

示例应用对每一类第三方登录都实现了完整流程，全部在 AuthViewController.swift 中，入口集中在didSelectRowAt的switch provider分发逻辑。下面按登录方式逐一说明。

4.1 Google Sign In

Firebase 控制台侧：进入项目的Auth面板 →Sign In Method标签 → 点击Google→ 打开Enable开关 → 保存。

Xcode 工程侧：示例工程已经内置了GoogleSignIn包依赖；按第三节说明，把GoogleService-Info.plist中的REVERSED_CLIENT_ID添加为自定义 URL Scheme。

运行与代码路径：运行应用后，在Identity Providers下选择Google。源码实现见 AuthViewController.swift：

guard let clientID = FirebaseApp.app()?.options.clientID else { return } let config = GIDConfiguration(clientID: clientID) GIDSignIn.sharedInstance.configuration = config Task { do { let result = try await GIDSignIn.sharedInstance.signIn(withPresenting: self) let user = result.user guard let idToken = user.idToken?.tokenString else { ... } let credential = GoogleAuthProvider.credential(withIDToken: idToken, accessToken: user.accessToken.tokenString) try await signIn(with: credential) } catch { return displayError(error) } }

关键点：Google SDK 返回idToken与accessToken后，通过GoogleAuthProvider.credential(withIDToken:accessToken:)构造 Firebase 凭据，再调用AppManager.shared.auth().signIn(with: credential)完成 Firebase 侧登录。signIn(with:)方法还处理了多因素（second factor）场景：当返回的错误码为AuthErrorCode.secondFactorRequired时，从AuthErrorUserInfoMultiFactorResolverKey取出MultiFactorResolver并转入 MFA 登录流程。

4.2 Sign in with Apple

前提：需要在 Xcode 工程的Signing & Capabilities中启用Sign in with Apple能力（Capability）。

Firebase 控制台侧：Auth 面板 → Sign In Method → 点击Apple→ 打开Enable→ 保存。

运行：运行应用后选择Apple。示例代码位于 AuthViewController.swift，其做法是：

let nonce = try CryptoUtils.randomNonceString() currentNonce = nonce let appleIDProvider = ASAuthorizationAppleIDProvider() let request = appleIDProvider.createRequest() request.requestedScopes = [.fullName, .email] request.nonce = CryptoUtils.sha256(nonce) let authorizationController = ASAuthorizationController(authorizationRequests: [request]) authorizationController.delegate = self authorizationController.presentationContextProvider = self authorizationController.performRequests()

即：用CryptoKit生成随机 nonce 并对sha256(nonce)传入ASAuthorizationAppleIDRequest，随后在授权回调中把 Apple 凭据交给OAuthProvider.credential(withProviderID: "apple.com", idToken:rawNonce:)完成 Firebase 登录。nonce 机制用于防止重放攻击，是 Sign in with Apple 与 Firebase 集成的标准做法。

4.3 Twitter

1. Firebase 控制台：Auth → Sign In Method → 开启Twitter；
2. 在 Twitter 开发者门户注册应用，获取API Key与App Secret，填入 Firebase 控制台并保存；
3. 在 Twitter 应用配置页，把 Firebase OAuth 回调地址（形如my-app-12345.firebaseapp.com/__/auth/handler）设置为 Authorization callback URL；
4. 在 Xcode 中添加REVERSED_CLIENT_ID对应的自定义 URL Scheme（若之前已添加过可复用）；
5. 运行应用，在 Identity Providers 下选择Twitter。

4.4 Microsoft

1. Firebase 控制台：Auth → Sign In Method → 开启Microsoft；
2. 在 Microsoft（Azure AD）开发者门户注册应用，获取Application Id与Application Secret，填入 Firebase 控制台并保存；
3. 将 Firebase OAuth 回调地址（my-app-12345.firebaseapp.com/__/auth/handler）配置为应用的 Authorization callback URL；
4. Xcode 中添加REVERSED_CLIENT_IDURL Scheme；
5. 运行应用，选择Microsoft。

4.5 GitHub

1. Firebase 控制台：Auth → Sign In Method → 开启GitHub；
2. 在 GitHub 开发者门户构建 OAuth App，获取Client ID与Client Secret，填入 Firebase 控制台并保存；
3. 将 Firebase OAuth 回调地址配置为 Authorization callback URL；
4. Xcode 中添加REVERSED_CLIENT_IDURL Scheme；
5. 运行应用，选择GitHub。

4.6 Yahoo

1. Firebase 控制台：Auth → Sign In Method → 开启Yahoo；
2. 在 Yahoo 开发者门户创建应用，获取Client ID与Client Secret，填入 Firebase 控制台并保存；
3. 将 Firebase OAuth 回调地址配置为 Authorization callback URL；
4. Xcode 中添加REVERSED_CLIENT_IDURL Scheme；
5. 运行应用，选择Yahoo。

4.7 Facebook

1. 在 Facebook 开发者站点按指引创建 iOS 应用，Bundle ID 填写com.google.firebase.quickstart.AuthenticationExample（示例默认 Bundle Identifier；若修改过，需保证与 Facebook 开发者后台一致）；
2. 按 Facebook iOS 集成指南完成配置（示例工程已内置FBSDKLoginKit依赖与初始化代码，可跳过其指南中的步骤 1 与步骤 3）；
3. Firebase 控制台：Auth → Sign In Method → 开启Facebook，填入App Id与App Secret并保存；
4. 将AuthViewController.swift顶部常量kFacebookAppID的值替换为你的 Facebook App Id（也可在示例的Info.plist中配置）；
5. Xcode 中添加格式为'fb' + App Id的自定义 URL Scheme（如fb1234567890）；
6. 运行应用，选择Facebook。

对应实现见 AuthViewController.swift：使用LoginManager请求["email"]权限，拿到AccessToken.current后，通过FacebookAuthProvider.credential(withAccessToken:)构造凭据并signin(with:)。

五、邮箱密码认证（Email/Password）

配置：Firebase 控制台 → Auth → Sign In Method → 开启Email/Password→ 保存。

运行：运行应用后选择Email & Password。示例工程以 SwiftUI 形式呈现登录界面（AuthViewController通过UIHostingController(rootView: LoginView(delegate: self))展示），支持登录与创建账户两种操作，属于最基础的认证能力，也是后续验证邮件、密码重置等 Action Code 流程的载体。

六、其他认证方式

6.1 Email Link / Passwordless 免密登录

邮箱免密登录（Passwordless）通过向用户邮箱发送一封含特殊Dynamic Link的验证邮件完成认证，用户点击链接即可回到应用并自动登录。配置链路较长，按以下顺序操作：

1. 在 Firebase 控制台开启免密：Auth → Sign In Method → 确保Email/Password已开启 → 打开Email link (passwordless sign-in)→ 保存。

2. 配置 Dynamic Links：

• 在项目设置中启用 Dynamic Links，需要填写App Store ID（示例中可随意填写，如123456789）与Team ID（需与 Apple 开发者账号关联）；
• 在控制台Dynamic Links面板点击Get Started，输入一个域名，例如authenticationexample.page.link（该域名大概率已被占用，可调整为authenticationexample123之类，务必保留.page.link后缀）；
• 在 Xcode 中为应用主 Target 添加Associated Domains能力，并将上面复制的域名以applinks:[域名]格式填入（例如applinks: authenticationexample.page.link）。若工程开启了自动签名，可在 Signing & Capabilities 页直接点 "+" 添加；否则需在 Apple Developer 控制台配置并下载描述文件；
• 回到 Dynamic Links 面板创建New Dynamic Link：
  • Short URL：随意，如demo、login、passwordless；
  • Deep Link URL：形如https://[authorized domain]/login?email=email。其中授权域名取自 Firebase 控制台Authentication → Settings → Authorized domains中类似[app 名称].firebaseapp.com的域名（也可以把 Dynamic Links 前缀域名加入白名单后使用）；
  • Define link behavior for iOS：选择Open the deep link in your iOS App，并在下拉框中选中你的应用；
  • 其余步骤按需配置后点击Create；
• 由于 Dynamic Links 默认使用应用的 Bundle Identifier 作为 URL Scheme，需在 Xcode 中把Bundle Identifier添加为自定义 URL Scheme。

3. 修改示例代码：打开PasswordlessViewController.swift，找到sendSignInLink()方法，把其中的stringURL常量替换为你创建的 Dynamic Link 长链接对应的授权域名，形如：

let stringURL = "https://\(authorizedDomain)/login"

4. 运行验证：运行应用 → 选择Email Link/Passwordless→ 输入邮箱并点击Send Sign In Link→ 保持当前页面不退出，切到邮件应用等待验证邮件 → 点击邮件中的登录链接 → 应用被唤起并完成登录。

6.2 Phone Number 手机号认证

手机号认证的工作机制值得注意：Firebase Auth 会先尝试向设备发送一条静默的Apple Push Notification（APN），以确认该手机号与当前设备关联；如果 APNs 未启用或配置不正确，则会回退到带有 reCAPTCHA 验证的网页流程。因此 APNs（与 Sign in with Apple 一样，是可在 Xcode 或 Apple Developer 控制台开启的能力）对手机号认证的体验有直接影响。

配置与运行：Firebase 控制台 → Auth → Sign In Method → 开启Phone→ 保存 → 运行应用选择Phone Number→ 输入手机号后等待约 5 秒，让 Firebase Auth 呈现必要的验证流程。

对应实现位于 PhoneAuthViewController.swift，核心是PhoneAuthProvider.provider().verifyPhoneNumber(...)获取验证 ID 与发送验证码，再通过PhoneAuthProvider.provider().credential(withVerificationID:verificationCode:)完成登录。同时，SceneDelegate.swift 中实现了scene(_:openURLContexts:)，通过Auth.auth().canHandle(url)处理 reCAPTCHA 的回调 URL——注释特别说明，在关闭 swizzling 时该方法是必需的，否则 reCAPTCHA 的登录视图控制器无法正确关闭。

6.3 Anonymous Authentication 匿名认证

配置：Firebase 控制台 → Auth → Sign In Method → 开启Anonymous→ 保存。

运行：运行应用选择Anonymous Authentication。实现极简，见 AuthViewController.swift：

AppManager.shared.auth().signInAnonymously { result, error in guard error == nil else { return self.displayError(error) } self.transitionToUserViewController() }

匿名认证常作为"游客先用、之后再升级为正式账号"的产品方案起点——匿名用户后续可通过link(with:)关联邮箱/第三方凭据。

6.4 Custom Auth System 自定义认证系统

适用于已有自有账号体系、希望由 Firebase 托管会话与 Token 的场景。

1. 确保你的认证服务器能签发自定义签名 Token（custom signed tokens）；用户登录时，客户端向该服务器请求签名 Token；
2. 拿到 Token 后调用Auth.auth().signIn(withCustomToken:)完成 Firebase 认证。示例中的演示入口在 CustomAuthViewController.swift（粘贴 Token 后点击Login即可登录关联用户）。

本地生成测试 Token 的方法（示例文档给出的配置路径）：

• Firebase 控制台 →Project settings→Service accounts标签 → 在All service account区域点击对应链接进入 Google Cloud Console；
• 在 Google Cloud Console 选中正确的 Firebase 项目 → 左侧菜单进入API Manager→ 点击Credentials→New credentials→Service account key→ 新建服务账号，密钥类型选择JSON，点击Create，下载 JSON 密钥文件；
• 用浏览器打开示例目录LegacyAuthQuickstart子目录中的web/auth.html，点击Choose File上传刚下载的 JSON 文件，输入任意 User ID 并点击Generate，复制生成的 Token；
• 在示例应用中选择Custom Auth system，粘贴 Token 并登录。

七、源码级流程解析：Passwordless 免密登录完整调用链

示例文档专门用一节"So how does this work?"讲解免密登录的端到端机制，我们结合仓库源码把这条链路完整还原。

第一阶段：发送验证链接。用户输入邮箱并点击Send Sign In Link后，PasswordlessViewController.swift 构造ActionCodeSettings并调用sendSignInLink：

let actionCodeSettings = ActionCodeSettings() let stringURL = "https://\(authorizedDomain)/demo" actionCodeSettings.url = URL(string: stringURL) actionCodeSettings.handleCodeInApp = true actionCodeSettings.setIOSBundleID(Bundle.main.bundleIdentifier!) actionCodeSettings.linkDomain = customDomain AppManager.shared.auth() .sendSignInLink(toEmail: email, actionCodeSettings: actionCodeSettings) { error in ... }

三个关键配置的作用：url指向 Dynamic Link 的深链地址；handleCodeInApp = true表示登录操作必须在应用内完成（对应控制台"Email link"开关）；linkDomain用于指定自定义托管域名。发送成功后，示例把email暂存，等待后续完成登录时使用。

第二阶段：接收 Dynamic Link 回调。由于示例采用SceneDelegateAPI，Dynamic Link 的唤起由 SceneDelegate.swift 的scene(_:continue:)处理，其userActivity.webpageURL即为传入的链接：

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { if let incomingURL = userActivity.webpageURL { handleIncomingDynamicLink(incomingURL) } } private func handleIncomingDynamicLink(_ incomingURL: URL) { let link = incomingURL.absoluteString if AppManager.shared.auth().isSignIn(withEmailLink: link) { UserDefaults.standard.set(link, forKey: "Link") NotificationCenter.default .post(Notification(name: Notification.Name("PasswordlessEmailNotificationSuccess"))) } }

这里先用Auth.auth().isSignIn(withEmailLink:)判断链接是否为签名链接（而不是普通网页或广告链接），若是则将链接存入UserDefaults，并向PasswordlessViewController广播通知，示意"用户点开了我们发送的验证链接，可以完成认证了"。

第三阶段：完成登录。PasswordlessViewController在viewDidLoad中注册了同名通知（registerForLoginNotifications），收到通知后执行passwordlessSignIn()（PasswordlessViewController.swift）：

guard let link = UserDefaults.standard.value(forKey: "Link") as? String else { return } AppManager.shared.auth().signIn(withEmail: email, link: link) { result, error in ... }

Auth.auth().signIn(withEmail:link:)在后台会校验该链接确实是当初发送给对应邮箱的签名链接，校验通过即完成登录；随后示例通过currentUser.isEmailVerified确认验证状态并跳转到用户页。

这条链路完整展示了免密登录的三大要素：邮件里的签名链接（含邮箱信息）、Dynamic Links 将用户从邮件带回应用、signIn(withEmail:link:)的链接-邮箱关联校验。

八、进阶能力：Token、监听器与多因素认证

除了登录流程，示例工程还覆盖了 Firebase Auth 的高频进阶 API，同样可以在应用中逐项演示（入口均位于 AuthViewController.swift 的菜单分发）：

• Token 获取与强制刷新：currentUser.getIDTokenResult(forcingRefresh:completion:)，可查看 ID Token 中携带的 claims；
• 认证状态监听：Auth.auth().addStateDidChangeListener与removeStateDidChangeListener(handle)，用于驱动 UI 随登录态切换；示例维护了监听器句柄数组，可添加/移除多个监听器（addAuthStateListener/removeAuthStateListener）；
• ID Token 变化监听：addIDTokenDidChangeListener/removeIDTokenDidChangeListener；
• Action Code（OOB Code）全流程：sendEmailVerification、sendPasswordReset(withEmail:actionCodeSettings:)、confirmPasswordReset(withCode:newPassword:)、checkActionCode、applyActionCode、verifyPasswordResetCode。actionCodeSettings()通过ActionCodeSettings配置继续 URL、handleCodeInApp与linkDomain，并支持在.inApp/.continue/.email三种请求类型间切换（toggleActionCodeRequestType）；
• 多因素认证（MFA）：手机号因子注册（user.multiFactor.getSessionWithCompletion→PhoneAuthProvider.provider().verifyPhoneNumber(_:multiFactorSession:)→PhoneMultiFactorGenerator.assertion(with:)→enroll）与TOTP 因子注册（TOTPMultiFactorGenerator.generateSecret(with:)→ 生成二维码 URL 并唤起 OTP App →TOTPMultiFactorGenerator.assertionForEnrollment→enroll），以及按factorInfo.uid解绑因子（unenroll(withFactorUID:)）；
• 登录时的 MFA 二次校验：signIn(with:)捕获AuthErrorCode.secondFactorRequired错误，取出MultiFactorResolver后通过MFALoginView完成二次验证；
• reCAPTCHA 初始化：Auth.auth().initializeRecaptchaConfig()（performInitRecaptcha）与自定义认证域名Auth.auth().customAuthDomain = ...（performCustomAuthDomainFlow）；
• App 删除：FirebaseApp.delete。

九、开发与测试：如何运行与验证

FirebaseAuth/README.md 说明了两条测试路径：

1. 单元测试无需额外配置：FirebaseAuth/Tests/Unit下的 64 个测试文件（61 个 Swift、3 个 Objective-C）可随 Firebase 整体单元测试一起运行，覆盖 Auth 内核各模块（Token 管理、API 请求、用户状态机等）；
2. 示例工程测试：Tests/SampleSwift/README.md 中强调AuthenticationExample同时用于手动与自动化集成测试。工程内包含AuthenticationExampleUITests（UI 级自动化测试）、SwiftApiTests（Swift API 调用测试）与ObjCApiTests（Objective-C API 兼容性测试），可验证公开 API 在两种语言下的行为一致性。

由于AuthenticationExample依赖真实 Firebase 后端，UI/集成测试需要先完成第二节的 Firebase 控制台接入；而纯单元测试则完全离线可跑。这种"单元测试零配置 + 集成测试按需配置"的分层，正是大型 SDK 工程中可借鉴的测试组织方式。

十、小结

围绕 FirebaseAuth/README.md 定位的"多认证方式支持"能力，本文完整继承了 SampleSwift 示例文档 的全部配置步骤，并结合仓库源码补充了底层实现：

• 从Firebase 控制台 + Xcode 双端配置（URL Scheme、Associated Domains、APNs）到运行时 API 调用（GoogleAuthProvider.credential、sendSignInLink、signIn(with:link:)等），每一步都有明确的仓库内实现可供对照；
• 第三方 OAuth 类流程统一走"Provider SDK 取凭据 →AuthCredential转换 →signIn(with:)"模式；免密登录则额外依赖 Dynamic Links 与SceneDelegate回调；
• 手机号认证的 APN/APNs 回退 reCAPTCHA 机制、Google 登录的REVERSED_CLIENT_IDURL Scheme、Facebook 的fb + AppIdScheme 等易错细节，均已给出明确结论。

如果你需要把某一种登录方式接入自己的应用，推荐直接以 AuthViewController.swift 中对应的方法为蓝本，保留 Provider SDK 部分、替换为自己的 UI 逻辑即可。

【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk