深入淺出digiRunner - OIDC 串接 Keycloak × digiRunner 取得 Token 並呼叫 API
前言
在現代微服務架構與 API 安全機制中，OAuth 2.0 與 OpenID Connect (OIDC) 已成為主流的授權與身份驗證解決方案。而作為企業內常見的身份平台，Keycloak 提供了彈性又標準化的 OIDC 支援，能夠方便地與各式應用串接。
本篇教學將實作將 Keycloak 串接至 digiRunner，並透過 Postman 驗證整體流程，從 Client 建立、Token 取得到 API 呼叫，一步步帶你完成整合過程。無論你是第一次接觸 OIDC，還是想更熟悉 digiRunner 串接流程，都能在這篇中找到實用的參考資訊。
如果想要複習API管理相關的朋友，也可以參考以下幾篇 :
深入淺出digiRunner - 依據指定時間預約啟用API並於需求結束時自動停用API
深入淺出digiRunner - 透過批次更新 API 標籤的方式，根據指定的標籤條件查詢並獲取 API 列表
內文
一、透過API 群組現況查詢來獲取X-API-KEY 授權相關的 API
-
登入至 Keycloak 後，從左側選單中點選 Clients，進入用戶端管理頁面，此處會列出目前管理中的所有 Client。
-
接下來，我們點選右上角的 [ Create Client ]，進入建立 Client 的畫面。
-
在 [ Client Type ] 的下拉選單中，選擇 OpenID Connect。
-
[ Client ID *]：輸入此 Client 的唯一名稱，這個值後續會用於串接設定，請務必記下。
-
[ Name ]：輸入一個便於辨識的名稱，讓使用者能快速了解這個 Client 的用途。
-
[ Description ] ：可選填欄位，輸入這個 Client 的簡要說明，方便後續維護與管理。
-
填寫完成後，點選 [ Capability config ] ，進入下一步的功能設定頁面。
-
在 Capability config 頁面中，請確認 [ Client authentication ] 為開啟
（On）狀態，這代表此 Client 為 confidential 類型。
接著，在 Authentication flow 區塊中： -
勾選 「Standard flow」，代表此 Client 將使用標準的授權碼流程
（Authorization Code Flow）。 -
取消勾選 「Direct access grants」，避免啟用密碼型登入
（Resource Owner Password Credentials Flow）。 -
完成上述設定後，點選 [ Login Settings ]，進入下一步的登入相關設定頁面。
-
在 [ Valid redirect URIs ] 欄位中，輸入：
「 https://oauth.pstmn.io/v1/callback」
這是 Postman 使用的預設 Callback URL，用於接收授權流程中的回傳資訊，因此若你要透過 Postman 來測試 OAuth 流程，這個 URL 是必填的。 -
確認設定無誤後，點選 [ Save ]，即完成在 Keycloak 中建立新的 Client。
-
為了支援 PKCE（Proof Key for Code Exchange），客戶端與認證伺服器需使用相同的雜湊函數，這裡我們使用的是 S256，也是最常見的選項。
-
在完成 Client 建立後，回到 Clients 列表頁，找到剛剛建立的那筆 Client 資訊，點選該項目進入更新設定頁面。
-
點選 [ Advanced ] 進入進階設定頁面後，接著點選右側的 [ Advanced Settings ]。
-
在 Proof Key for Code Exchange Code Challenge Method 欄位中，選擇 S256，這是為了啟用 PKCE 中的安全雜湊機制，確保授權過程更加安全。
-
接下來，點選 Credentials 進入該頁面，您將會看到 [ Client Secret ] 。點選欄位右側的 [ 眼睛圖示 ] 來解除密碼遮罩，並複製該密碼。
此密碼將用於後續的 digiRunner OAuth 2.0 設定中，請將其填入 [ IdP Client Secret ] 欄位，以完成與 Keycloak 的串接。 -
最後，我們需要建立一組 User，以便之後透過 Postman 導向 Keycloak 登入頁面時，能夠使用該組帳號與密碼來取得 Token。
-
首先，點選左側選單中的 [ Users ] ，您將會被導向至 User 管理頁面。接著，點選 [ Add user ] ，進入用戶建立頁面。
-
在建立頁面中，您只需填寫 [ Username* ]，這將是您為該用戶設定的帳號名稱。填寫完成後，點選 [ Create ] 來創建用戶。
-
用戶創建完成後，點選 [ Credentials ] 進入密碼設定頁面，然後點選 [ Set password ] 來設定該用戶的登入密碼。
-
在 Set password 頁面中，填寫 [ Password* ] 與 [ Password confirmation* ] 欄位，並將 [ Temporary ] 設定為「Off」，這樣密碼將不會在下一次登入時過期。完成後，點選 [ Save ]。
-
接著，會彈出一個確認視窗，請再次點選 [ Save password ] 來確認您的設定。回到 Credentials 頁面後，您就可以看到剛設置好的密碼。
二、建立Client並透過GTW OAuth 2.0 IdP來串接KeyCloak
-
我們需要在 digiRunner 中建立一個 Client，以便串接到 IDP。
首先登入至 digiRunner，然後點選左側選單中的 Client Management > API Client，進入 Client 管理頁面。 -
在這個頁面中，點選 [ Create ] 進入建立頁面，並依照以下欄位設定：
-
[ Client name* ] ：輸入一個便於辨識的名稱，這將是該 Client 的識別名稱。
-
[ Display name* ][ Client ID ]：建議與 Client name 保持一致，這樣更容易管理與識別。
-
[ Password* ][ Confirm password* ]：填入您為此 Client 設定的密碼，並在確認欄位中再次輸入相同的密碼以確認。
-
[ Note* ] ：這是一個可選欄位，您可以輸入一些有助於辨識的標記或說明。
-
[ Status* ] ：選擇 Active，使該 Client 處於啟用狀態。
-
[ API Audience* ] ：此欄位為 API 的內外部備註，您可以保留預設設定。
-
設定完成後，[ Create ] ，即可成功建立新的 Client。
-
完成建立 Client 之後，我們需要設定 Redirect URL，以便能夠串接至 Postman 進行測試。
-
首先，回到 Client List，找到剛才建立的 Client，然後點選 [ Security ] 進入安全設定頁面。
-
在安全設定頁面中，找到 [ Default Redirect URI ]，並輸入以下 URL：「https://oauth.pstmn.io/v1/callback」 , 這是 Postman 使用的預設 Callback URL，用於接收授權流程中的回傳資訊。
-
完成後，點選 [ Update ]，即可成功更新設定。
-
現在我們已經完成建立 Client，接下來需要在 IDP 頁面進行串接設定。
-
首先，點選左側選單中的 Client Management > GTW OAuth 2.0 IdP，進入 IDP 管理頁面。
-
在這裡，選擇您要串接的 Client，然後點選該 Client 的 [ Details ]，進入 IDP 串接設定列表。
-
接著，點選 [ Create ] 進入建立串接頁面的設定。
-
[ Enable* ]：將此欄位設為「Y」，啟用該 IDP 串接。
-
[ Type* ] ：在下拉選單中選擇「OIDC」。
-
[ IdP Client ID* ]：輸入在 Keycloak 中為此 Client 設定的 Client ID。
-
[ IdP Client Name* ]：可以設定一個便於辨識的名稱，讓您輕鬆識別此 Client。
-
[ IdP Client Secret* ]：輸入在 Keycloak 中為此 Client 設定的 Client Secret，即該 Client 的密碼。
-
[ dgR Callback URL* ]：填入以下 Callback URL，這是 digiRunner 接收授權結果的回調位置：
「https://{{ip}}:{{port}}/dgrv4/ssotoken/gtwidp/OIDC/gtwIdPCallback」 -
[ IdP Well Known URL* ]：填寫 Keycloak 的 Well-Known URL，這是用來自動發現 OpenID 配置的路徑：
「http://{{ip}}:{{port}}/realms/D5SIT/.well-known/openid-configuration」 -
[ IdP Scope ] ：在此欄位中輸入「openid email profile」，這是所需的授權範圍，用於獲取使用者的基本資訊。
-
完成所有設定後，點選 [ Create ]，即完成 IDP 串接設定。
三、透過PostMan OAuth2.0 登入來取得Token
-
進入 Authorization 頁面，並將 Auth Type 設定為 OAuth 2.0。
-
在 [ Grant Type ] 下拉選單中，選擇「Authorization Code (With PKCE)」，這是 OAuth 2.0 標準授權流程，並啟用 PKCE 增強安全性。
-
勾選「Authorize using browser」，這樣可以使用 Postman 預設的 Callback URL：「https://oauth.pstmn.io/v1/callback」
-
在 Auth URL 欄位中，填寫以下地址，用於引導使用者進行授權： 「https://localhost:18080/dgrv4/ssotoken/gtwidp/OIDC/authorization」
-
在 [ Access Token URL ] 欄位中，填寫以下 Token 請求地址： 「https://localhost:18080/oauth/token」
-
[ Client ID ] ：輸入在 digiRunner 中為該 Client 設定的 Client ID。
-
[ Client Secret ]：輸入在 digiRunner 中為該 Client 設定的 Client Secret。
-
-
在 [ Code Challenge Method ] ：選擇「SHA-256」，這是為了啟用 PKCE 中的安全加密方法。
-
在 [ Code Verifier ] ：根據 Keycloak 的標準，該值需要在 43 到 128 個字元之間。因此，您可以在 Postman 的變數中使用 「{{$guid}}{{$guid}}」，這樣就能生成符合長度要求的隨機值
（Postman 會生成兩個 GUID，合計長度為 72 字元）。 -
在 [ Scope ] ：輸入「openid email profile」，這是所需的授權範圍，用來取得使用者的基本資訊。
-
在 [ State ] ：輸入 「{{$guid}}」，這樣會生成一個隨機的 GUID，並保證每次請求的 State 值都是唯一的。
-
在 [ Client Authentication ] 欄位中，選擇「Send as Basic Auth header」，這是告訴服務器使用基本的身份驗證方式來傳遞 Client ID 和 Client Secret。
-
完成以上設定後，點選 [ Get New Access Token ] ，這樣會將您導向至 Keycloak 的登入頁面，並在授權完成後取得 Token。
-
完成設定後，您將會從瀏覽器轉導到 Keycloak 的登入頁面。此時，請輸入在 第一個區塊的第14 步驟中所設定好的 User 帳號與密碼，然後點選 [ Sign in ] 。
-
這樣就能完成登入並取得授權，接下來就能順利取得 Access Token。
-
當驗證成功後，瀏覽器將會回應您。
-
此時，Postman 會收到並帶回成功取得的 Access Token、Refresh Token 和 ID Token，接著，點選 Use Token，將這些 Token 自動帶入後，您就可以開始使用這些憑證來發送請求。
-
當您將 Token 自動帶入後，點選 [ Send ] 來發送請求並呼叫 API。如果此時您收到 403 HTTP 狀態碼，這表示目前 digiRunner 尚未授權該 Client 存取此 API。此時，請回頭檢查 Client 的授權設定是否正確。
-
參考 深入淺出digiRunner - 串接用戶端權控並授權API 的流程，完成串接後，再次取得一次 Token，即可成功呼叫 API。
-
以上便是完整的流程，從 digiRunner 串接 Keycloak，並透過 Postman 取得 Token，進而成功呼叫 API。
結語
透過本篇教學，相信你已能掌握如何將 Keycloak 與 digiRunner 串接，並成功使用 OAuth 2.0 的 Authorization Code with PKCE 流程來取得 Token 並呼叫 API。
這樣的整合不僅能提升系統安全性，也讓身份控管更集中一致。未來無論擴充應用或整合更多服務，都可以沿用這套架構做延伸。
若在實作過程中遇到任何授權錯誤（如 403），也可以回頭檢查 Client 的授權設定與 Token 權限，確保整體設定無誤。
希望這篇文章能作為你整合 OIDC 解法的實戰指南，為你的 API 安全管理打下堅實基礎。
