如何用 OAuth 串接 OOOPEN Lab 專案登入驗證？

如果你希望讓玩家在開始填答心理測驗或互動專案前，必須先登入自家會員系統（品牌官網或會員中心），OOOPEN Lab 的「串接自家會員登入」進階功能提供了兩種 OAuth 登入流程，無論是想透過現有的 SSO 機制導入用戶資料，或者控制填答權限讓僅限會員參與，這篇文章將詳細說明如何設定 OAuth 登入流程與回傳範例！

要怎麼啟用 OAuth？有回傳的資料範例嗎？

付費前，你可以先前往專案後台，點擊「填答登入/權限設定」
在跳窗中，選擇啟用「自訂 OAuth 登入」就能根據欄位設定相關資訊囉！
組合「你的平台名稱」與「登入按鈕顏色」設定，即可調整登入按鈕樣式（如下方附圖）
正式上線記得要成為付費用戶，並加購「串連自家會員登入」進階功能就能啟用囉（我該怎麼挑選方案？）

各個欄位要怎麼設定？以下一一說明並提供範例！

OAuth 登入網址

用戶點擊「使用（你的平台）登入」後開啟的網址，其中會自動帶入 redirect_uri 網址參數（URLSearchParams），請在用戶登入後，將用戶重新導向該網址。
- 若你設定的登入網址是

`https://mycoolapp.com/oauth/login?param1=value1&param2=value2`

當用戶從 OOOPEN Lab 點擊登入按鈕時，會開啟的網址會像這樣：

`https://mycoolapp.com/oauth/login?param1=value1&param2=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]", 

...

}