> 本文件说明如何在 Simple Easy Social Login（SESLP） 插件中， 配置各个社交登录服务提供商（Google、Facebook、LinkedIn、Naver、Kakao、LINE）。

> 所有登录均基于 OAuth 2.0 / OpenID Connect（OIDC）。
> 您必须在各提供商的开发者控制台中创建应用（Client）， 并将 Client ID / Client Secret 填写到 SESLP 中。

## 🔧 通用设置指南

#### 1) Redirect URI 规则：

`https://{your-domain}/?social_login={provider}`

示例：

- Google → `https://example.com/?social_login=google`
- Facebook → `https://example.com/?social_login=facebook`
- LinkedIn → `https://example.com/?social_login=linkedin`
- Naver → `https://example.com/?social_login=naver`
- Kakao → `https://example.com/?social_login=kakao`
- LINE → `https://example.com/?social_login=line`

#### 2) 必须使用 HTTPS。

大多数提供商要求使用 HTTPS，并会拒绝 `http://` 的重定向请求。

#### 3) 完全一致匹配

控制台中设置的 Redirect URI 必须与 SESLP 发送的 URI 100% 完全一致 （包括协议、子域名、路径、末尾斜杠和查询参数）。

#### 4) Email 可能不可用

部分提供商允许用户拒绝共享电子邮箱。SESLP 可以使用稳定的提供商 ID 来进行账号关联。

#### 5) 日志查看位置

- `/wp-content/SESLP-debug.log`
- `/wp-content/debug.log`（`WP_DEBUG_LOG = true`）

## 🐞 调试日志与故障排查

如何阅读 SESLP 调试日志

#### 日志文件位置

- `/wp-content/SESLP-debug.log`（SESLP 调试日志）
- `/wp-content/debug.log`（`WP_DEBUG_LOG = true`）

#### 日志格式

    [YYYY-MM-DD HH:MM:SS Z] [LEVEL] 消息 {"key":"value",...}

- `Z`：UTC 或 WordPress 本地时间（例如 KST）— 可在 SESLP 设置中选择
- 隐私：电子邮箱 / Token / Secret 会自动脱敏 （例如：`r********@g****.com`）

#### OAuth 流程日志（常见）

1) OAuth 开始

    [DEBUG] State created {"provider":"google","state":"906****23","ttl":"10min"}

说明：创建用于 CSRF 防护的 state token。`ttl` 有效期为 10 分钟。

2) Callback 触发

    [DEBUG] Auth route triggered {"provider":"google","has_code":1}

说明：已进入回调。`has_code:1` → 已获取 OAuth `code`。

3) State 验证

成功：

    [DEBUG] State validated {"provider":"google","state":"906****23"}

失败：

    [WARNING] State validation failed: not found/expired {"provider":"google","state":"906****23"}

4) Token 交换

    [DEBUG] Token response (google) {"has_access_token":1}

说明：成功获取 Token。

失败：

    [ERROR] Token request failed (google) {"error":"..."}

5) 用户信息请求

    [ERROR] Userinfo request failed (google)
      [WARNING] Invalid userinfo (google)

6) 用户关联

    [DEBUG] Linker: signing in user {"user_id":45,"provider":"google","created":0}
      [INFO]  Login success (google) {"user_id":45,"email":"r********@g****.com"}

7) 重定向

    [DEBUG] Redirect decision {"mode":"profile","user_id":45,"url":"https://example.com/wp-admin/profile.php"}

#### 快速参考表

日志信息（简述） | 可能原因 | 处理方式
--- | --- | ---
State validation failed | 超时、切换标签页、重复请求 | 快速重试或使用无痕模式
Token request failed | Client ID/Secret/Redirect 错误或请求被阻止 | 检查开发者控制台、防火墙、服务器时间
Userinfo invalid | 缺少 scope 或 email 为私密 | 添加 `email, profile` scope，并获取用户同意
User create failed | 账号冲突或 WordPress 限制 | 检查已有用户、多站点设置
Redirect missing | 代码过早 return | 确保 Redirect 类在 callback 后执行

#### 提交问题时建议提供的信息

- 相关日志内容（已脱敏）
- 使用的提供商（Google / Naver 等）
- Redirect 模式 / 自定义 URL
- 是否开启调试日志
- WordPress 环境（单站 / 多站 / 缓存插件等）

## 🌍 提供商指南

请展开下方各个提供商，并粘贴您为该提供商准备的英文指南内容。

Google

- 推荐权限范围： `openid email profile`
- Redirect URI 规则： `https://{domain}/?social_login=google`

#### 1) 准备工作（必备检查清单）

(1) 建议/必须使用 HTTPS（本地环境请使用可信的开发证书）。

(2) Redirect URI 必须与控制台中注册的值100% 完全一致。例如：`https://example.com/?social_login=google`

(3) 在测试模式下，仅测试用户可以登录（最多 100 个用户）。

(4) 使用应用主页/隐私政策/服务条款 URL 时，可能需要进行应用域名（Authorized domains）注册及域名所有权验证。

#### 2) 项目 / 同意屏幕设置

(1) 访问 Google Cloud Console。
https://console.cloud.google.com/apis/credentials

(2) 顶部选择项目 → 创建新项目（如有需要）。

(3) 侧边栏：进入 APIs & Services → OAuth consent screen。

(4) 选择 User Type：通常为 External。

(5) 填写 应用信息：应用名称、用户支持邮箱、（可选）Logo。

(6) 应用域名 部分

- 填写应用主页 URL、隐私政策 URL、服务条款 URL
- 将根域名（例如 example.com）添加到 Authorized domains → 保存
- 如有需要，通过 Search Console 完成域名所有权验证

(7) 配置 Scopes

- 推荐： `openid`、`email`、`profile`
- 敏感/受限权限在上线前可能需要审核

(8) 添加测试用户（测试模式下允许登录的邮箱）。

(9) 保存。

注意：仅使用基础权限（`openid email profile`）通常可以无需审核即可发布使用。

#### 3) 创建 OAuth 客户端（Web 应用）

(1) 侧边栏：APIs & Services → Credentials。

(2) 顶部：+ Create Credentials → OAuth client ID。

(3) 应用类型：`Web application`。

(4) 输入一个易于区分的名称（例如：`SESLP – Front`）。

(5) 添加Authorized redirect URIs

- `https://{domain}/?social_login=google`

(6) 点击 Create，然后复制生成的 Client ID / Client Secret。

（可选）本插件使用授权码模式，一般不需要配置 Authorized JavaScript origins。

#### 4) WordPress（插件）设置

(1) WP 后台 → SESLP Settings → Google 标签页。

(2) 粘贴 Client ID / Client Secret → 保存。

(3) 在网站前端点击Google 登录按钮进行测试。

#### 5) 从测试切换到正式环境

(1) 查看 OAuth consent screen → Publishing status。

(2) 切换到正式环境前：

- 确认应用信息（Logo/域名/隐私政策/条款）填写完整且正确
- 移除不必要的权限，仅保留必需权限
- 如使用敏感权限，提交审核申请

(3) 切换后，所有 Google 账户均可登录。

#### 6) 常见错误与解决方案

(1) redirect_uri_mismatch

→ 当控制台中注册的 Redirect URI 与实际请求 URI 有任何差异（协议、子域、路径、参数等）时会发生。请确保完全一致。

(2) access_denied / disallowed_useragent

→ 浏览器或内嵌环境限制。请使用普通浏览器重试。

(3) invalid_client / unauthorized_client

→ Client ID/Secret 输入错误或应用状态异常（被删除/禁用）。请重新检查或生成。

(4) Email 为空

→ 检查是否包含 `email` 权限、同意屏幕展示情况以及账户邮箱可见性设置。请在同意页面中明确说明邮箱用途。

日志查看：

- `wp-content/SESLP-debug.log`（插件调试开启）
- `wp-content/debug.log`（`WP_DEBUG`, `WP_DEBUG_LOG = true`）

#### 7) 总结检查清单

- OAuth 同意屏幕：配置应用信息/域名/政策/条款/权限/测试用户
- Credentials：创建 Web Application 客户端
- 注册 Redirect URI：`https://{domain}/?social_login=google`
- SESLP：保存 Client ID/Secret 并测试登录
- 上线前切换发布状态（必要时提交审核）

Facebook

- Redirect URI： `https://{domain}/?social_login=facebook`
- 请求权限（推荐）： `public_profile`、`email`
- Facebook 不使用 `openid`。

#### 1) 创建应用并添加产品

(1) 前往 Meta for Developers → 登录
https://developers.facebook.com/

(2) 点击 Create App → 选择一般类型（例如 Consumer）→ 创建应用

(3) 在左侧菜单中，从 Products 添加 Facebook Login

(4) 前往 Settings → 确认以下项目：

- Client OAuth Login： 开启（ON）
- Web OAuth Login： 开启（ON）
- Valid OAuth Redirect URIs：
- 新增 `https://{domain}/?social_login=facebook`
- （选填）Enforce HTTPS： 默认建议启用

#### 2) 基本应用设置（App Settings → Basic）

(1) App Domains： `example.com`（应用政策/条款/主页所属域名）

(2) Privacy Policy URL： 可公开访问的隐私政策页面

(3) Terms of Service URL： 可公开访问的服务条款页面

(4) User Data Deletion： 提供说明页面或数据删除端点

(5) Category / App Icon： 设置完成后点击 Save

#### 3) 权限（Scopes）与应用审核

(1) 一般登录所需的基本权限为 `public_profile`；可选电子邮箱为 `email`

(2) 大多数情况下，`email` 可在无需审核的情况下使用，但可能因地区/账号不同而有所差异

(3) 高级权限（如 pages/ads）需通过 App Review 与 Business Verification

#### 4) 切换模式（Development → Live）

在应用顶部或设置区域，将 App Mode：Development → Live

#### 5) 切换为 Live 前检查清单

- 准备隐私政策 / 条款 / 数据删除页面
- 正确填写 Valid OAuth Redirect URIs
- 移除不必要权限，仅保留必要项目
- （如需要）完成 App Review / Business Verification

#### 6) WordPress 设置（SESLP）

(1) WP 后台 → SESLP Settings → Facebook

(2) 输入 App ID / App Secret → 保存

(3) 在前端使用 Facebook 登录按钮 进行测试

#### 7) 故障排查

(1) Can't Load URL / redirect_uri error

→ 请确认在 Valid OAuth Redirect URIs 中注册的 URI 与实际请求完全一致（包括协议、子域名、斜杠与查询参数）

(2) email 为 null

→ 用户未在 Facebook 注册电子邮箱或设为私密。请准备基于 ID 的账号绑定逻辑，并在同意页面中清楚说明电子邮箱用途

(3) 权限相关错误

→ 若请求权限超出基本范围，则需进行 App Review / Business Verification

(4) 无法切换为 Live

→ 若隐私政策 / 条款 / 数据删除页面未提供或不可公开访问，则无法切换，需提供公开网址

LinkedIn

- Redirect URI： `https://{domain}/?social_login=linkedin`
- 必要设置： 启用 OpenID Connect（OIDC）
- 推荐权限范围： `openid`、`profile`、`email`
- LinkedIn 正在逐步淘汰旧版权限（`r_liteprofile`、`r_emailaddress`）。
- 新应用必须使用 OIDC 标准权限。

#### 1) 创建应用

(1) 前往 LinkedIn Developers Console

→ https://www.linkedin.com/developers/apps

(2) 使用 LinkedIn 账号登录

(3) 点击 Create app

(4) 填写必要信息：

- 应用名称：例如 `MySite LinkedIn Login`
- LinkedIn 页面：选择或“None”
- 应用图标：100×100 以上 PNG/JPG
- 隐私政策 URL / 商业邮箱：必须有效且可公开访问

(5) 点击 Create app

默认处于开发模式 → 可立即测试 `openid`、`profile`、`email` 登录，无需发布

#### 2) 启用 OpenID Connect（OIDC）

(1) 前往 Products 页面

(2) 找到 Sign In with LinkedIn using OpenID Connect

(3) 点击 Add product → 即时批准

(4) OIDC 设置会显示在 Auth 页面中

OIDC 必要权限

- `openid` → 返回 ID Token
- `profile` → 姓名、头像、标题等
- `email` → 电子邮箱地址

#### 3) OAuth 2.0 设置（Auth 页面）

(1) 前往 Auth → OAuth 2.0 settings

(2) 在 Redirect URLs 中添加：

→ `https://{domain}/?social_login=linkedin`

(3) 必须完全一致（协议、子域名、斜杠、查询参数）

(4) 如有需要，可注册多个：

- 本地：`https://localhost:3000/?social_login=linkedin`
- 测试环境：`https://staging.example.com/?social_login=linkedin`
- 生产环境：`https://example.com/?social_login=linkedin`

(5) 点击 Save

#### 4) 获取 Client ID / Client Secret

(1) 在 Auth 页面中找到：

- Client ID
- Client Secret

(2) WordPress 后台 → SESLP Settings → LinkedIn

(3) 粘贴后 → 保存

(4) 在前端测试 LinkedIn 登录按钮

安全性：

- 切勿公开 Client Secret
- 如已泄露，请使用 Regenerate secret

#### 5) 权限说明

权限 | 说明 | 备注
--- | --- | ---
`openid` | 返回 OIDC 标准 ID Token | 必需
`profile` | 姓名、头像、标题等 | 必需
`email` | 电子邮箱地址 | 必需

旧版权限（`r_liteprofile`、`r_emailaddress`）

- 已于 2024 年后废弃
- 新应用无法使用

#### 6) 故障排查

(1) redirect_uri_mismatch

→ URI 有任何差异都会导致错误 → 请确保 100% 完全一致

(2) invalid_client

→ ID/Secret 错误或应用未启用 → 请重新检查或重新生成

(3) email 为 NULL

→ 用户拒绝或未包含 `email` 权限 → 请在同意页面说明用途

(4) insufficient_scope

→ 请求的权限未获批准 → 请确认已启用 OIDC

(5) 未启用 OIDC

→ Products 中缺少 Sign In with LinkedIn using OpenID Connect

日志：

- `/wp-content/SESLP-debug.log`
- `/wp-content/debug.log`

#### 7) 总结检查清单

- 已创建应用
- 已添加 OpenID Connect 产品
- 已正确注册 Redirect URI
- 已在 SESLP 保存 Client ID/Secret
- 权限：`openid profile email`（不使用旧版权限）
- 已在 HTTPS 前端测试

注意：

- SESLP 完全支持 OIDC 流程。
- 旧版 OAuth 2.0 已不再支持。
- 新集成请务必使用 OpenID Connect。

Naver

- Redirect URI： `https://{domain}/?social_login=naver`
- 推荐权限范围： 基本信息（`name`）、电子邮箱（`email`）
- Naver 使用 Naver Login（네아로） API，必须使用 HTTPS

#### 1) 应用注册

(1) 前往 Naver Developer Center

→ https://developers.naver.com/apps/

(2) 使用 Naver 账号登录

(3) 点击 Application → Register Application

(4) 填写必要信息：

- 应用名称：例如 `MySite Naver Login`
- API 使用：选择 `Naver Login（네아로）`
- 添加环境 → Web
- 服务 URL： `https://example.com`
- Callback URL： `https://example.com/?social_login=naver`

(5) 同意条款 → Register

注意：

- 必须使用 HTTPS → 不允许 HTTP
- 子域名需分别注册

#### 2) 获取 Client ID / Client Secret

(1) 前往 My Applications

(2) 点击应用 → 复制 Client ID 和 Client Secret

#### 3) WordPress（插件）设置

(1) WP 后台 → SESLP Settings → Naver

(2) 粘贴 Client ID / Client Secret

(3) 确认 Redirect URI 完全一致：`https://{domain}/?social_login=naver`

(4) Save → 在前端使用 Naver 登录按钮测试

#### 4) 权限与数据提供

数据 | 权限 | 备注
--- | --- | ---
姓名 | `name` | 默认
电子邮箱 | `email` | 默认
性别、生日 | 附加项目 | 需要审核

- 用户可在授权页面同意或拒绝
- 若拒绝 email → `email = null` → 请使用基于 ID 的账号绑定
- 敏感数据需通过 Naver 应用审核

#### 5) 故障排查

(1) Redirect URI 不匹配

→ 只要有细微差异都会报错 → 请确保 100% 完全一致

(2) HTTP 错误

→ 必须使用 HTTPS

(3) 子域名错误

→ 每个子域名需分别注册

(4) email 为 NULL

→ 用户拒绝或设为私密 → 请准备 ID 绑定逻辑

(5) 需要审核

→ 基础登录：无需审核
→ 附加数据：需要审核

日志：

- `/wp-content/SESLP-debug.log`
- `/wp-content/debug.log`

#### 6) 总结检查清单

- 已在 Naver Developer Center 注册应用
- Callback URL 已正确注册
- 已使用 HTTPS
- 子域名已分别注册（如需要）
- Client ID/Secret 已保存至 SESLP
- 已测试 email 同意/拒绝行为
- 前端登录测试完成

注意：

- SESLP 完全支持 Naver Login（네아로）。
- 基础登录（`name`、`email`）无需审核即可使用。

Kakao

- Redirect URI： `https://{domain}/?social_login=kakao`
- 推荐权限范围： `profile_nickname`、`profile_image`、`account_email`
- `account_email` 仅在完成身份验证或企业验证后可用
- 必须使用 HTTPS，且必须启用 Client Secret

#### 1) 创建应用

(1) 前往 Kakao Developers

→ https://developers.kakao.com/

(2) 登录 → My Applications → Add New App

(3) 输入：

- App Name、Company Name
- Category
- 同意 Operation Policy

(4) Save

#### 2) 启用 Kakao Login

(1) Product Settings > Kakao Login

(2) 将 Enable Kakao Login 切换为 ON

(3) 注册 Redirect URI

- `https://{domain}/?social_login=kakao`
- Save

(4) 域名必须与 Platform site domain 一致

#### 3) 同意项（Scopes）

(1) Consent Items

(2) 添加并设置：

Scope | 说明 | 同意类型 | 备注
--- | --- | --- | ---
`profile_nickname` | 昵称 | 必选 / 可选 | 基本信息
`profile_image` | 头像 | 必选 / 可选 | 基本信息
`account_email` | 电子邮箱 | 可选 | 需要验证

(3) 为每一项清楚说明其用途

(4) Save

注意：敏感权限需要验证

#### 4) 注册 Web 平台

(1) App Settings > Platform

(2) Register Web Platform

(3) 网站域名：`https://{domain}`

(4) Save → 必须与 Redirect URI 的域名一致

#### 5) 安全性 – 生成并启用 Client Secret

(1) Product Settings > Security

(2) Use Client Secret → ON

(3) Generate Secret → 复制其值

(4) Activation Status → Active

(5) Save

重要：生成后必须启用

#### 6) 获取 REST API Key（Client ID）

(1) App Keys

(2) 复制 REST API Key → 作为 Client ID 使用

#### 7) WordPress 设置

(1) WP 后台 → SESLP Settings → Kakao

(2) Client ID = REST API Key
Client Secret = 生成的 Secret

(3) Save

(4) 使用 Kakao Login Button 进行测试

#### 8) 故障排查

(1) redirect_uri_mismatch → 必须 100% 完全一致

(2) invalid_client → Secret 未启用或输入错误

(3) email empty → 用户拒绝提供或尚未验证

(4) Domain mismatch → Platform 与 Redirect URI 域名不一致

(5) HTTP forbidden → 仅支持 HTTPS

日志：

- `/wp-content/SESLP-debug.log`
- `/wp-content/debug.log`

#### 9) 总结检查清单

- 已启用 Kakao Login
- 已注册 Redirect URI
- 已注册 Web 平台域名
- 已配置同意项
- 已生成并启用 Client Secret
- 已将 REST API Key / Secret 保存到 SESLP
- 已在 HTTPS 前端完成测试

LINE

- Redirect URI： `https://{domain}/?social_login=line`
- 必要条件：启用 OpenID Connect，并申请并获得电子邮箱权限批准
- 推荐权限范围： `openid`、`profile`、`email`
- 必须使用 HTTPS，且电子邮箱权限需要审批

#### 1) 创建 Provider 与 Channel

(1) 前往 LINE Developers Console

→ https://developers.line.biz/console/

(2) 使用 LINE Business Account 登录（不允许个人账号）

(3) 点击 Create a new provider → 输入名称 → Create

(4) 在该 Provider 下 → Channels 标签页

(5) 选择 Create a LINE Login channel

(6) 配置内容：

- Channel type： `LINE Login`
- Provider： 选择已创建的 Provider
- Region： 目标国家（例如 `South Korea`、`Japan`）
- Name / description / icon： 显示在授权页面

(7) 同意条款 → Create

#### 2) 启用 OpenID Connect 并申请电子邮箱权限

(1) 前往左侧菜单中的 OpenID Connect

(2) 在 Email address permission 旁点击 Apply

(3) 填写申请信息：

- 隐私政策 URL（必须可公开访问）
- 上传隐私政策截图
- 提交

(4) `email` 权限仅在审批通过后可用
→ 审批通常需要 1～3 个工作日

#### 3) 注册 Callback URL 并发布 Channel

(1) 前往左侧菜单中的 LINE Login

(2) 输入 Callback URL：

→ `https://{domain}/?social_login=line`

(3) 必须完全一致：

- 协议：`https://`（不允许 HTTP）
- 域名、路径、查询参数必须 100% 完全一致

(4) 点击 Save

(5) 将 Channel 状态设置为 Published

- Development mode： 仅用于测试
- Published： 正式上线服务

#### 4) 获取 Channel ID / Secret

(1) 在 Channel 页面顶部或 Basic settings

(2) Channel ID → SESLP 的 Client ID
Channel Secret → SESLP 的 Client Secret

#### 5) WordPress 设置

(1) WP 后台 → SESLP Settings → LINE

(2) Client ID ← Channel ID
Client Secret ← Channel Secret

(3) Save

(4) 在前端使用 LINE 登录按钮 进行测试

#### 6) 故障排查

(1) redirect_uri_mismatch → 只要有细微差异就会报错 → 请确保 100% 完全一致

(2) invalid_client → Secret 输入错误，或 Channel 尚未发布（Published）

(3) email 为 NULL → 电子邮箱权限尚未批准，或用户已拒绝

(4) 不允许 HTTP → 必须使用 HTTPS（localhost 的 HTTPS 可接受）

(5) 开发模式限制 → 仅测试账号可登录

日志：

- `/wp-content/SESLP-debug.log`
- `/wp-content/debug.log`

#### 7) 总结检查清单

- 已使用 Business Account 创建 Provider + LINE Login channel
- 电子邮箱权限已申请并获得批准
- Callback URL 已正确注册
- 已使用 HTTPS，且状态为 Published
- Channel ID / Secret 已保存至 SESLP
- 前端登录测试完成

注意：SESLP 完整支持

- LINE Login v2.1 + OpenID Connect。
- 收集电子邮箱需要事先审批。