如果你希望讓玩家在開始填答心理測驗或互動專案前，必須先登入自家會員系統（品牌官網或會員中心），OOOPEN Lab 的「串接自家會員登入」進階功能提供了兩種 OAuth 登入流程，無論是想透過現有的 SSO 機制導入用戶資料，或者控制填答權限讓僅限會員參與，這篇文章將詳細說明如何設定 OAuth 登入流程與回傳範例！
目錄
要怎麼啟用 OAuth？有回傳的資料範例嗎？
- 付費前，你可以先前往專案後台，點擊「填答登入/權限設定」
- 在跳窗中，選擇啟用「自訂 OAuth 登入」就能根據欄位設定相關資訊囉！
- 組合「你的平台名稱」與「登入按鈕顏色」設定，即可調整登入按鈕樣式（如下方附圖）
- 正式上線記得要成為付費用戶，並加購「串連自家會員登入」進階功能就能啟用囉（我該怎麼挑選方案？）
各個欄位要怎麼設定？以下一一說明並提供範例！
OAuth 登入網址
- 用戶點擊「使用（你的平台） 登入」後開啟的網址，其中會自動帶入 redirect_uri 網址參數（URLSearchParams），請在用戶登入後，將用戶重新導向該網址。
- 若你設定的登入網址是
`https://mycoolapp.com/oauth/login?param1=value1¶m2=value2`- 當用戶從 OOOPEN Lab 點擊登入按鈕時，會開啟的網址會像這樣：
`https://mycoolapp.com/oauth/login?param1=value1¶m2=value2&state=random_hash&redirect_uri =https://ooopenlab.cc/auth/0123456789abcdef/callback`＊提醒：OOOPEN Lab 會自動追加兩個參數 redirect_uri 及 state
- 當用戶在你的登入介面完成登入後，就可以將用戶重新導向回 redirect_uri，也可以一併帶入 state 這個安全性參數
- 每個模組會有專屬該模組的 redirect_uri ，若你使用的 OAuth 提供商，需要針對 redirect_uri 做白名單的設定的話，你可以下圖處複製網址
回傳授權類型（Grant Type）
用戶登入後，重新導向時採用的授權類型，請依指示正確帶入該方式所需之參數；我們建議選用安全性較高的 Authorization Code 方式
- 若你選用 Authorization Code 方式，請在回傳到 redirect_uri 時，在網址內帶入 ?code={code} 參數；此參數為你所發行的 Authorization Code，會在下一步 Token 交換傳遞時使用到。
- 若你選用 Implicit Flow 方式，請在回傳到 redirect_uri 時，在網址內帶入 ?access_token={access_token} 參數；此參數即為後續 API 呼叫流程中會用到的access_token
（視條件出現）Token 交換網址
- 若在上一步選用了Authorization Code方式，用戶被導回 OOOPEN Lab 時，就會利用你填入的 Token 交換網址來取得 access_token 或 id_token
- 請求將會以 `x-www-form-urlencoded` POST 方式送出，且帶入上一步的 code 跟 redirect_uri 為 body 參數
用戶資料取得方式
請選擇要用 OpenID Connect 協定或是一般 API 方式來取得用戶資料，根據選項，會需要設定對應的串接網址
（視條件出現）OpenID Connect (OIDC) 網址
若設定 OpenID Connect 方式串接，OOOPEN Lab 即會自動利用前一步設定的 Token 進行連線，連線時會優先使用 access_token 連線，若有收到 id_token，也會使用 id_token 連線
- 請求將會以 `x-www-form-urlencoded` POST 方式送出
- access_token 連線方式，會同時將 access_token 帶入 Bearer Header 跟 `x-www-form-urlencoded` 的 body，你可視需求擇一驗證
- id_token 連線方式，會將 id_token 帶入 `x-www-form-urlencoded` 的 body
- OIDC 回傳即為標準格式，sub 欄位即為用來辨別用戶的唯一識別碼，若同時有回傳 Email 欄位，也會一併記錄到填答紀錄中
以下有簡單範例：
{
"sub": "10769150350006150715113082367",
"email": "[email protected]",
...
}（視條件出現）用戶資訊 API 網址
請求將會以 GET 方式送出
- access_token 連線方式，會同時將 access_token 帶入 Bearer Header 跟網址的 query，你可視需求擇一驗證
- API 需回傳單一 JSON 物件，且一定要包含 id 這個欄位，這個 id 即為用來辨別用戶的唯一識別碼，若同時有回傳 Email 欄位，也會一併記錄到填答紀錄中
以下為簡易 JSON 範例：
{
"id": "user_id",
"email": "[email protected]",
...
}實戰範例：用 LINE Login 串接，會員 ID 對得上你的 LINE 官方帳號好友
OOOPEN Lab 也有內建的「社群會員登入 → LINE」，但它走的是平台共用的 LINE Channel，拿到的 LINE userId 跟你自家 LINE 官方帳號好友 ID 不一樣。如果你想把填答者跟你自家 LINE 官方帳號好友比對（在 MA／CRM 裡找出「這位填答者就是這位好友」），就要走「自訂 OAuth 登入」、串到你自己申請的 LINE Login Channel。
建議使用 OpenID Connect 模式，OOOPEN Lab 編輯器各欄位填法如下（{Channel ID} 與 {Channel secret} 請替換為你在 LINE Developers 該 Channel 取得的值）：
⚠️ 填寫時請注意：表格中的 {Channel ID}、{Channel secret} 是 placeholder（佔位符號），實際貼到 OOOPEN Lab 欄位時要連同大括號 { } 整段一起換掉，只留下你從 LINE Developers 取得的純值。例如 Channel ID 是 1234567890，請填 client_id=1234567890，不是 client_id={1234567890}。
| OAuth 登入網址 | https://access.line.me/oauth2/v2.1/authorize?response_type=code&client_id={Channel ID}&scope=profile%20openid%20email |
| 回傳授權類型 | Authorization Code |
| Token 交換網址 | https://api.line.me/oauth2/v2.1/token?grant_type=authorization_code&client_id={Channel ID}&client_secret={Channel secret} |
| 用戶資料取得方式 | OpenID Connect |
| OIDC 網址 | https://api.line.me/oauth2/v2.1/verify?client_id={Channel ID} |
＊進階選項（依需求加在「OAuth 登入網址」欄位）：
- 若同時想拿到 Email：scope 保留
email，且需向 LINE Developers 申請 email 權限通過審核 - 若想讓玩家登入後自動加為官方帳號好友：在 OAuth 登入網址加上
bot_prompt=normal參數
⚠️ 別忘了：把 OOOPEN Lab 的 redirect_uri 設定到 LINE Channel
LINE Login 預設只允許白名單內的 Callback URL，沒設定的話玩家登入後會被 LINE 擋下、看到錯誤頁。請務必到 LINE Developers Console 把 OOOPEN Lab 給你的 redirect_uri 加上去：
- 在 OOOPEN Lab 的 OAuth 設定畫面，複製模組專屬的
redirect_uri（格式為https://ooopenlab.cc/auth/{quizId}/callback，其中{quizId}會由系統自動帶入該模組對應的 ID，不需要替換） - 到 LINE Developers Console → 選擇對應的 Provider → 進入該 LINE Login Channel
- 切到「LINE Login」分頁 → 找到「Callback URL」欄位 → 點「Edit」 → 把 redirect_uri 貼上去 → 存檔
- 若同一個 LINE Login Channel 同時服務多個測驗模組，每個模組的 redirect_uri 都要分別加進 Callback URL 清單（一行一個）
串接完成後，OOOPEN Lab 收到的會員 ID 格式是 custom:{quizId}-{LINE userId}，把 custom:{quizId}- 前綴切掉，剩下的就是你 LINE 官方帳號 webhook 收到的同一個 userId — 這樣就能跟你現有的會員資料（LINE 好友清單、MA／CRM）直接比對歸戶。前提是這個 LINE Login Channel 與你的官方帳號 Messaging API Channel 要屬於同一個 LINE Developers Provider，跨 Provider 拿到的 userId 並不相同。
