src/lib/plugins/auth/apple.ts

src/lib/plugins/auth/apple.ts

Apple Sign In 认证插件，支持通过 Apple ID 登录。

概述

该插件基于 NextAuth.js 的 Apple Provider，集成 Apple 的 Sign In with Apple 认证流程。

主要导出

applePlugin

认证插件实例，实现了 AuthPlugin 接口。

import { applePlugin } from "@/lib/plugins/auth/apple";

功能特性

用户信息映射

从 Apple 的用户资料中提取以下信息：

Apple 字段映射字段说明
subidApple 用户唯一标识
name.firstName + name.lastNamename用户姓名（仅首次登录提供）
emailemail用户邮箱（仅首次登录提供）
-image始终为 null（Apple 不提供头像）

姓名处理

由于 Apple 只在首次登录时提供姓名信息：

  • 使用 name.firstName 和 name.lastName 组合
  • 如果姓名不可用，使用邮箱前缀
  • 如果邮箱不可用，使用 "User"

环境变量

需要配置以下环境变量：

# Apple Sign In 配置
AUTH_APPLE_ID=your_client_id
AUTH_APPLE_SECRET=your_client_secret

获取方式

  1. 进入 Apple Developer Portal
  2. 选择 Certificates, Identifiers & Profiles
  3. 创建 App ID，启用 Sign In with Apple
  4. 创建 Services ID 作为 Client ID
  5. 配置回调域名（需要 HTTPS）
  6. 创建 Private Key 用于生成 Client Secret
  7. 使用 Apple 提供的密钥生成 Client Secret（JWT）

Client Secret 生成

Apple 的 Client Secret 是一个 JWT，需要：

  • 使用 Private Key 签名
  • 包含特定的 claims（iss, iat, exp, aud, sub）
  • 定期刷新（最长 6 个月有效期）

使用方式

前端登录调用

import { signIn } from "next-auth/react";

await signIn("apple");

配置启用

在 prompts.config.ts 中启用：

export default defineConfig({
  auth: {
    providers: ["apple", "credentials"],
    allowRegistration: true,
  },
  // ...
});

特殊注意事项

首次登录 vs 后续登录

Apple 只在首次登录时提供用户的姓名和邮箱：

  • 首次登录：可以获取姓名和邮箱
  • 后续登录：只能获取 sub（用户 ID）

因此，必须在首次登录时保存用户信息。

邮箱隐私保护

用户可以选择隐藏真实邮箱：

  • Apple 会生成一个代理邮箱地址
  • 发送到该地址的邮件会转发到用户真实邮箱
  • 在应用中看到的可能是类似 xyz@privaterelay.appleid.com 的地址

平台要求

  • 必须使用 HTTPS
  • 需要在 Apple Developer 中验证域名
  • 仅在 iOS、macOS 或 Web 上可用

注意事项

  1. 首次登录时必须保存用户姓名，后续登录不再提供
  2. 用户可能使用隐藏邮箱地址
  3. 不支持头像，始终返回 null
  4. Client Secret 需要定期更新
  5. 需要 Apple Developer 账号（付费）
  6. 必须在 Apple Developer 中配置并验证回调域名
← 返回目录