firebase-auth-basics

用途

Firebase Authentication 提供后端服务、易用的 SDK 和现成的 UI 库，用于对应用用户进行身份验证。当用户的应用需要用户登录、用户管理或使用 Firebase 服务进行安全数据访问时，可使用本技能。

前置条件

Firebase 项目：通过 npx -y firebase-tools@latest projects:create 创建（参见 firebase-basics）。
Firebase CLI：已安装并登录（参见 firebase-basics）。

核心概念

用户

用户是可以登录应用的实体。每个用户由唯一 ID（uid）标识，该 ID 在所有提供方中保证唯一。用户属性包括：

uid：唯一标识符。
email：用户邮箱地址（如可用）。
displayName：用户显示名称（如可用）。
photoURL：用户照片 URL（如可用）。
emailVerified：表示邮箱是否已验证的布尔值。

身份提供方

Firebase Auth 支持多种登录方式：

邮箱/密码：基本的邮箱和密码认证。
联合身份提供方：Google、Facebook、Twitter、GitHub、Microsoft、Apple 等。
电话号码：基于短信的认证。
匿名：临时访客账户，之后可关联到永久账户。
自定义认证：与现有认证系统集成。

推荐将 Google 登录作为良好且安全的默认提供方。

令牌

用户登录后会收到 ID Token（JWT）。该令牌用于在向 Firebase 服务（Realtime Database、Cloud Storage、Firestore）或自有后端发起请求时标识用户。

ID Token：短期有效（1 小时），用于验证身份。
刷新令牌：长期有效，用于获取新的 ID Token。

工作流程

1. 配置

方式一：通过 CLI 启用认证

只有 Google 登录、匿名认证和邮箱/密码认证可以通过 CLI 启用。其他提供方请使用 Firebase 控制台。

在 firebase.json 中添加 'auth' 块来配置 Firebase Authentication：

{
  "auth": {
    "providers": {
      "anonymous": true,
      "emailPassword": true,
      "googleSignIn": {
        "oAuthBrandDisplayName": "Your Brand Name",
        "supportEmail": "support@example.com",
        "authorizedRedirectUris": [
          "https://my-project-id.firebaseapp.com/__/auth/handler",
          "http://localhost"
        ]
      }
    }
  }
}

注意：如果 Google 登录弹窗打开后立即关闭并报错 [firebase_auth/unauthorized-domain]，说明该域名未授权。本地开发时，在 firebase.json 的 authorizedRedirectUris 中添加 http://localhost（或确保 localhost 已包含在 Firebase 控制台 Authentication > Settings > Authorized domains 的授权域名列表中）。关键：不要在 authorizedRedirectUris 中包含端口号（例如使用 http://localhost，而不是 http://localhost:9090 或 http://localhost:4000），也不要在控制台授权域名列表中包含协议或端口号（使用 localhost）。在 authorizedRedirectUris 中包含端口号会导致 firebase deploy --only auth 失败并报 INVALID_AUTHORIZED_DOMAIN。

关键：配置 firebase.json 后，必须将认证配置部署到 Firebase 后端才能使更改生效。这对于 Google 登录、邮箱/密码等认证提供方为应用平台自动生成必要的 OAuth 客户端至关重要。运行：

npx -y firebase-tools@latest deploy --only auth

方式二：在控制台启用认证

在 Firebase 控制台启用其他提供方：

访问 https://console.firebase.google.com/project/_/authentication/providers
选择你的项目。
启用所需的登录提供方（例如邮箱/密码、Google）。

2. 客户端设置与使用

Web：参见 references/client_sdk_web.md。
Flutter：参见 references/flutter_setup.md。
Android（Kotlin）：参见 references/client_sdk_android.md。
iOS（Swift）：参见 references/ios_setup.md。

3. 安全规则

在 Firestore/Storage 规则中使用 request.auth 保护数据。参见 references/security_rules.md。