Session

用途說明

為經過 GOC API Gateway 代理的 APIs 管理瀏覽器之工作階段 (Session)。

欄位配置說明

變數	類型	預設值	說明	必填
secret	string	random number generated from utils.random_string	查詢字串的列表， GOC API Gateway 會審查並從中取得 JWTs。
cookie_names	string	session	cookie 的名稱。
cookie_lifetime	number	3600	session 會保持暢通的時間區間(單位為秒)。
cookie_idletime	number		cookie 閒置時間(單位為秒)。在這段期間，session 是無效的。
cookie_renew	number	600	session 在多久之後即被更新(單位為秒)。
cookie_path	string	/	cookie 在主機的所在位置。
cookie_domain	string		準備交換 cookie 的域口。
cookie_samesite	string	Strict	決定在跨網站請求中，cookie 如何被傳送。有以下三種方式： 1. Strict： 完全禁止第三方 Cookies，只有當前網頁的 URL 與請求目標一致，才會送出 Cookie。 2. Lax：大多數情況也是不發送 Cookie 到第三方，但是 Get 請求除外。例如，從一個連結跳轉到原始的網頁。 3. None 或 off： 容許所有網站對 Cookie 的存取。在新版的瀏覽器中，使用這個方式時，必須加上 Secure 參數。 詳請請參考 SameSite cookies docs。 此欄位接受輸入的值為以下其一： Strict、 Lax、None 以及 off 。
cookie_httponly	boolean	true	提供 HttpOnly 標籤，因此 cookie 會直接送至伺服器。請參考 Restrict access to cookies docs。
cookie_secure	boolean	true	探供 Secure 標籤，因此 cookie 會在加密的請求中使用 HTTPS 協定直接傳送至伺服器。請參考 Restrict access to cookies docs。
cookie_discard	number	10	在舊有的 session 存活時間更新後，決定多少時間(單位為秒)後將捨棄這個舊有的 session。
storage	string	cookie	Session 資訊儲存的地方。 kong：儲存加密的 session 資訊在現有 database 策略，cookie 不會包含任何 session 資料。 cookie：儲存加密的 session 資訊在 cookie 本身。 此欄位接受輸入的值為以下其一： kong、cookie。
logout_methods	array of string	["POST", "DELETE"]	可以結束 session 的方法。 此欄位接受輸入的值為以下其一： POST 、 DELETE 以及 GET 。
logout_query_arg	string	session_logout	會夾帶在登出請求的查詢字串。
logout_post_arg	string	session_logout	POST 引數會夾帶在登出請求中。不要修改這項屬性。

用法示例

在全局啟用插件

1. 從網站左邊 Menu 中 外掛插件 頁面中，點選右上角的 新增外掛插件 ：

2. 點選後，選擇 認證 頁籤，並啟用 Session，填寫內容參考欄位配置說明，設定成功後，任何請求(不分服務、路由、用戶)皆需經過認證才能通過。

在服務端上啟用插件

1. 從網站左邊 Menu 中 服務 > 服務列表 頁面中，選擇要啟用此插件的服務，假設為 google，點選對應的編輯按鈕：

2. 在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

點選後，選擇 認證 頁籤，並啟用 Session，填寫內容參考欄位配置說明，設定成功後，僅有此服務(範例為google)請求需經過認證才能通過。

在路由端上啟用插件

可以由兩種方式來選擇路由，並啟用插件：

方式一：路由列表

1. 從網站左邊 Menu 中 服務 > 路由列表 頁面中，選擇要啟用此插件的路由，假設為 google，點選對應的編輯按鈕：

方式二：服務 > 服務列表 > 路由列表

1. 從網站左邊 Menu 中 服務 > 服務列表 頁面中，選擇要啟用此插件的路由 所屬之服務(假設為 google)，點選對應的編輯按鈕。

在編輯畫面中，點選上方的 路由 頁籤，選擇要啟用此插件的路由(假設為 google)，點選對應的編輯按鈕：

---

2. 承第1步，點擊上述兩種方式之一的編輯按鈕後，在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

點選新增外掛插件 按鈕後，選擇 認證 頁籤，並啟用 Session，填寫內容參考欄位配置說明，設定成功後，僅有此路由(範例為google)請求需經過認證才能通過。

驗證

Session 插件必須與其它的驗證插件一起使用。當有其它驗證插件開啟時，如果沒有找到任何的 session，則會維持原本的插件邏輯。
為了讓匿名用戶的存取被阻擋，因此需要開啟 Request Termination 的插件在匿名用戶身上。如果沒有做這個動作，則所有請求都會通過。

設立驗證環境

1. 創立測試的服務及路由。

2. 在服務開啟 Key Auth 之插件。

3. 此時在 console 上送出以下指令：

$ curl <GOC API Gateway protocol>://<GOC API Gateway ip>:<GOC API Gateway proxy port>/session-test -i

會得到以下回應：

HTTP/1.1 401 Unauthorized

代表插件正常運作，並阻擋未通過驗證之請求。

4. 創立匿名用戶以及測試用戶，並在測試用戶建立 Key Auth 的憑證。

5. 將匿名用戶之 ID 加入服務底下已開啟之 Key Auth 插件。

6. 在服務底下開啟 Session 插件，將 cookie_secure 設為 關閉 以及將 storage 改成 kong 。

7. 在匿名用戶底下開啟流量控管分類下的 Request Termination 插件。

驗證

1. 此時在 console 上送出以下指令：

$ curl <GOC API Gateway protocol>://<GOC API Gateway ip>:<GOC API Gateway proxy port>/session-test -i

會得到 403 以及剛剛設定的訊息。

2. 使用剛剛建立的 Key Auth 憑證送出以下指令：

$ curl "<GOC API Gateway protocol>://<GOC API Gateway ip>:<GOC API Gateway proxy port>/session-test?apikey=keKCvnHMdv80NzRTHAZTm62p7MdAT0dC" -i

會得到回應，其中會有標頭 Set-Cookie ，大概會像下列的樣子：

Set-Cookie: session=r7N6BD_KXFKqR4pJQPHomQ|1669200614|9lQB7DbAyP7flzeVSfIQ0lCOwFU; Path=/; SameSite=Strict; HttpOnly

則可以將其值加入標頭中：

$ curl -H "cookie:session=r7N6BD_KXFKqR4pJQPHomQ|1669200614|9lQB7DbAyP7flzeVSfIQ0lCOwFU" <GOC API Gateway protocol>://<GOC API Gateway ip>:<GOC API Gateway proxy port>/session-test -i

也可以得到正常的回應，而且 Set-Cookie 回應的標頭直到更新前不會再出現。