單一登入

一、先記下這條回呼位址

在身分提供者那裡建立應用程式時，一定會讓你填一個「回呼位址」（也可能叫重新導向 URI、Redirect URI、跳轉位址）。雲瞰的這一條長這樣：

https://<你存取雲瞰用的位址>/api/auth/oidc/callback

雲瞰的設定頁頂部已經按你目前存取的位址算好了完整的一條，還帶複製按鈕，照抄那一條最保險。

• 要用你實際存取的位址 —— 不是容器內部位址，也不是 127.0.0.1。
• 必須逐字一致 —— 通訊協定是 https 還是 http、連接埠號、大小寫，差一個字元就不通。
• 兩個入口就登記兩條 —— 在家用區域網路位址、在外面用公網網域的話，在提供者那裡把兩條都填上（絕大多數提供者都支援填多條）。

二、雲瞰這邊填什麼

「進階」裡還有兩項，預設值對絕大多數提供者都能用：「申請的權限範圍」保持預設即可；「使用者名稱取自」決定拿對方的哪個欄位當雲瞰使用者名稱，取不到或者不合規時雲瞰會自動產生一個。

三、群暉 SSO Server

NAS 使用者最順手的一條：不用另外裝什麼，DSM 自帶的套件就能當身分提供者，NAS 上已有的帳號直接拿來登入雲瞰。

1. 1

   裝套件並打開服務

   做什麼：套件中心裝 SSO Server，打開後在「服務」裡勾選 OIDC（這是單一登入的通用標準，各家介面裡都叫這個名字）。

2. 2

   新增應用程式

   做什麼：「應用程式 → 新增」，類型選 OIDC，名稱隨便取（比如「雲瞰」），「重新導向 URI」填第一節那條回呼位址。

3. 3

   抄兩個值回雲瞰

   做什麼：儲存後清單裡能看到應用程式 ID和應用程式密鑰，分別對應雲瞰的「用戶端 ID」和「用戶端密鑰」。

4. 4

   填服務位址

   做什麼：填 https://<你存取 DSM 用的位址>/webman/sso，例如 https://nas.example.com:5001/webman/sso。

群暉不單獨提供「使用者名稱」欄位，雲瞰會直接用 DSM 的登入名稱當雲瞰使用者名稱（DSM 上叫什麼，進來還叫什麼），顯示名取電子郵件。「使用者名稱取自」保持預設就好。

四、Authentik

1. 1

   新建 Provider

   去哪裡：左側 Applications → Providers → Create，選 OAuth2/OpenID Provider。

2. 2

   填關鍵幾項

   做什麼：授權流程選你現有的那條（帶確認頁或不帶都行）；Client type 選 Confidential；Redirect URIs 填第一節那條回呼位址（多個位址就填多行）；Signing Key 任選一個憑證。

3. 3

   抄憑據

   做什麼：儲存後在 Provider 詳情頁複製 Client ID 與 Client Secret，填進雲瞰。

4. 4

   建 Application 並設定可見範圍

   做什麼：Applications → Create 建一個應用程式綁定剛才的 Provider，順手設定好誰能用。

5. 5

   填服務位址

   做什麼：Provider 詳情頁裡的 OpenID Configuration Issuer 就是它，形如 https://auth.example.com/application/o/yunkan/，整條貼進雲瞰的「服務位址」。末尾的斜線加不加都行。

五、Microsoft Entra ID（原 Azure AD）

1. 1

   註冊應用程式

   去哪裡：Azure 入口網站 → Microsoft Entra ID → 應用程式註冊 → 新增註冊。「重新導向 URI」平台選 Web，填第一節那條回呼位址。

2. 2

   拿兩個識別碼

   做什麼：註冊完在「概觀」頁複製應用程式 (用戶端) 識別碼（→ 雲瞰的「用戶端 ID」）和目錄 (租用戶) 識別碼（下一步拼位址要用）。

3. 3

   建立用戶端密碼

   做什麼：「憑證和祕密（Certificates & secrets）→ 新增用戶端密碼」，建立後立刻複製「值」那一欄——離開這個頁面就再也看不到了。貼進雲瞰的「用戶端密鑰」。

4. 4

   填服務位址

   做什麼：填 https://login.microsoftonline.com/<租用戶 ID>/v2.0。

Entra 給出的使用者名稱通常是完整電子郵件，雲瞰會取 @ 前面那一段當使用者名稱，重名時自動加序號。「API 權限」裡保持預設的那幾項即可。

六、Google

1. 1

   建立憑證

   去哪裡：Google Cloud Console → API 和服務 → 憑證 → 建立憑證 → OAuth 用戶端 ID，類型選 網頁應用程式。

2. 2

   填回呼位址

   做什麼：在「已授權的重新導向 URI」裡填第一節那條回呼位址，然後建立，拿到用戶端 ID 與用戶端密鑰。

3. 3

   填服務位址

   做什麼：填 https://accounts.google.com。

4. 4

   調一下使用者名稱來源

   做什麼：Google 不給「使用者名稱」這個欄位，把「使用者名稱取自」改成 email，或者乾脆留預設讓雲瞰自動產生。

七、Keycloak

1. 1

   新建 Client

   去哪裡：選好 realm → Clients → Create client，Client type 選 OpenID Connect，Client ID 自己取一個（比如 yunkan）。

2. 2

   打開機密用戶端

   做什麼：下一步打開 Client authentication，Authentication flow 勾上 Standard flow。

3. 3

   填回呼位址

   做什麼：Valid redirect URIs 填第一節那條回呼位址。

4. 4

   抄密鑰並填服務位址

   做什麼：建好後在 Credentials 頁籤複製 Client secret；服務位址填 https://kc.example.com/realms/<realm 名稱>。

Keycloak 預設就提供使用者名稱欄位，「使用者名稱取自」保持預設即可。

八、第一次用它登入會發生什麼

1. 1

   跳過去登入

   做什麼：在雲瞰登入頁點「使用 XX 登入」，跳到提供者，用那邊的方式登入（含它自己的兩步驟驗證），然後自動跳回雲瞰。

2. 2

   雲瞰找有沒有對應的帳號

   做什麼：什麼都不用做，雲瞰按提供者給的使用者唯一識別碼去找。找到過關聯的，那就是你，直接進。

3. 3

   沒找到的兩種走向

   開著自動建立：當場建一個新的雲瞰帳號，角色按設定裡的預設值，並把這個外部帳號關聯上去。 關著自動建立：提示這個帳號還沒有和雲瞰的使用者關聯，需要先按下一節手動關聯，或者請管理員打開自動建立。

九、把外部帳號關聯到已有的雲瞰帳號

適合「我已經有一個雲瞰管理員帳號，想以後用 NAS 帳號登入它」這種情況。

1. 1

   先用雲瞰帳號正常登入

   做什麼：使用者名稱密碼照常登進去。

2. 2

   找到關聯入口

   去哪裡：我的帳號 → 登入安全 →「已關聯的帳號」。

3. 3

   點「關聯 XX 帳號」

   做什麼：跳到提供者登入一次，回來就完成了。 怎麼算成功：卡片裡列出這個帳號，下次登入頁上點那個按鈕直接進的就是這個雲瞰帳號。

一個雲瞰帳號可以關聯多個提供者帳號；反過來一個提供者帳號只能關聯到一個雲瞰帳號——否則「用它登入該進誰」就沒有確定答案了。解除關聯在同一張卡片上。

十、手機 App

Android 和 iOS 都支援：在登入頁把伺服器位址填好（位址旁邊的圓點變綠），按鈕就會自己出現。點它會打開系統瀏覽器完成登入，然後自動跳回 App。

• 手機瀏覽器要能打開同一個雲瞰位址 —— 人在外面時，伺服器位址那一欄就得填公網位址。
• 用不了「記住密碼」 —— 那一項記的是登入密碼，而這類帳號沒有密碼。想省事就讓提供者那邊保持登入狀態，瀏覽器會記住。

十一、常見問題

• 提示重新導向 URI 不符 —— 提供者那裡登記的位址和雲瞰實際發出的不一致。打開雲瞰設定頁頂部那條位址，和提供者後台裡逐字比：通訊協定、連接埠、末尾斜線、大小寫。區域網路和公網兩個入口要各登記一條。
• 提示位址與服務回傳的識別碼不一致 —— 「服務位址」填的不是提供者真正的 issuer（多半是從別的頁面複製來的）。回到提供者的應用程式詳情頁，找「Issuer / OpenID Configuration」那一條重新複製。結尾的 /.well-known/openid-configuration 與斜線都不影響。
• 跳回來說登入沒有完成 —— 最常見的兩類：一是雲瞰所在機器的時間不準（和提供者差出兩分鐘以上就會被拒，NAS 不開自動校時很常見）；二是用戶端密鑰不對，重新產生一個貼進來儲存——這一欄留空表示「保持不變」，所以必須真正貼上新值才會生效。
• 改了設定多久生效 —— 立刻。換了服務位址之後雲瞰會丟掉快取的提供者資訊，下一次點按鈕就走新位址。
• 關掉單一登入之後，自動建出來的帳號還在嗎 —— 在，關聯關係也在，只是登入頁不再顯示按鈕。要徹底清掉就在使用者管理裡刪帳號。
• 能不能只讓某幾個人用 —— 能，但要在提供者那邊管（Authentik 的策略、Google 的測試使用者清單、群暉的使用者群組）。雲瞰這邊的粗粒度開關是「首次登入自動建立帳號」，關掉之後只有你手動關聯過的人能進。

相關教學

• 使用者與權限——給新進來的人設定可見攝影機
• 登入兩步驟驗證——雲瞰自己的驗證碼，和單一登入二選一即可
• 外網存取——配網域和憑證