> 本文件說明如何在 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 login button 進行測試

#### 6) 疑難排解

(1) redirect_uri_mismatch → 只要有些微差異就會報錯 → 請確認 100% 一致

(2) invalid_client → Secret 輸入錯誤，或 Channel 尚未 Published

(3) email NULL → 電子郵件權限尚未核准，或使用者已拒絕

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

(5) Development mode 限制 → 僅測試帳號可登入

日誌：

- `/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。
- 收集電子郵件需要事先核准。