OIDC 單一登入（SSO）驗證功能

一、什麼是 OIDC 驗證

OIDC（OpenID Connect）是建立在 OAuth 2.0 之上的「身分驗證標準協定」。它讓使用者用一個集中帳號，就能登入多個應用系統，達成單一登入（SSO）。

核心概念：應用系統本身不儲存、也不比對使用者密碼，而是把「驗證身分」這件事委託給一個受信任的「身分提供者（IdP，Identity Provider）」。

典型登入流程：

•　使用者在應用系統點擊「使用 OIDC 登入」。

•　應用系統將使用者導向 IdP 的登入頁。

•　使用者在 IdP 完成登入，IdP 簽發「身分權杖（ID Token）」。

•　應用系統驗證權杖無誤後，即完成登入。

※ 好處：帳號密碼集中由 IdP 管理，應用系統不接觸密碼；可統一停用/啟用帳號、套用 MFA 等安全政策。

二、本次示範說明

本次以 Authentik 作為身分提供者（IdP）來示範。MAVIS 採用 Authentik 作為「內部的身分驗證平台」，所有使用者的登入驗證統一交由 Authentik 處理。

• Authentik 上設定 Mavis 的 callback url 範例

https://{mavis-fqdn}/sso/oidc

架構：

使用者 → MAVIS（https://shun.mavisdemo.com）→ 導向 Authentik 登入 → 驗證通過導回 MAVIS

※ 本手冊聚焦「MAVIS 端如何串接」與「使用者/權限流程」；Authentik 上建立應用的細部步驟不在本手冊範圍。

三、Authentik 產生的三個值

在 Authentik 建立好對應的 OIDC 應用後，系統會產生以下「三個關鍵值」。這三個值稍後要填入 MAVIS，是串接的核心：

四、在 MAVIS 設定（連線設置）

步驟 1

使用管理員身份 進入 MAVIS 平台：管理介面 → 系統管理→ 登入驗證→ 驗證來源(編輯）→驗證來源選擇OIDC

步驟 2 

依下表填入各欄位（欄位值取自 Authentik，可對照設定畫面）：

　把 Authentik 的三個值填入對應欄位：

步驟 2　設定授權範圍與 claim 對應：

※ 使用者名稱欄位必須填 preferred_username，這是 Authentik 送出的標準 claim（等於 Authentik 的使用者名稱）；若填 username 會對不到、名稱帶不出來。

步驟 3　按「儲存」完成設定。

五、使用者首次登入

串接完成後，使用者依下列流程登入：

步驟 1　開啟 MAVIS 登入頁。

步驟 2　點「使用 OIDC 進行登入」。

步驟 3　頁面導向 Authentik → 輸入帳號密碼登入。

步驟 4　驗證通過後自動導回 MAVIS，完成登入。

步驟 5　首次登入 Mavis 後，系統會顯示「無權限」狀態，需由管理員指派相應權限後方可使用

※ 重要：使用者「必須先成功登入一次」，該帳號才會被自動建立並出現在 MAVIS 的「使用者管理」清單中。登入之前，管理員在使用者管理是看不到這個帳號的。

六、指派權限（管理員）

使用者首次登入後雖已出現在使用者管理，但預設「沒有任何權限」，無法進行任何操作。

步驟 1　管理員登入 MAVIS，進入使用者管理，找到該首次登入的使用者。

步驟 2　為該使用者指派對應的「專案權限」。

步驟 3　指派完成後，使用者重新整理／重新登入，即可存取並操作被授權的專案。

※ 流程重點：先登入（帳號才會出現）→ 管理員給專案權限 → 才能操作。權限一律由管理員在 MAVIS 端控管。