# 單一登入

跟完這篇，家裡人不用再記一個雲瞰專用的密碼——用群暉 NAS 上的帳號、公司帳號或者 Google 帳號點一下就進來了。

> **ℹ️ 開始之前**
>
> 只有管理員能設定，入口是**平台設定 → 單一登入**（桌面介面：控制面板 → 單一登入）。你還需要一個「保管帳號的那一方」：群暉 NAS 自帶的帳號服務、公司的帳號系統、Google 都算，下面統稱身分提供者。設定好之後登入頁會多一個「使用 XX 登入」的按鈕，網頁和手機 App 都有。

> **💡 對方那邊驗過的，雲瞰不再驗一遍**
>
> 身分提供者要求的簡訊、驗證器、企業政策照常生效，驗過之後雲瞰直接放行，不會再疊一層自己的驗證碼。所以「公司要求強制兩步驟驗證」這類需求，接過來就自動滿足了。

## 一、先記下這條回呼位址

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

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

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

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

## 二、雲瞰這邊填什麼

| 填的東西 | 說明 |
| --- | --- |
| 啟用單一登入 | 總開關。關掉之後登入頁不再顯示按鈕，已經關聯好的帳號不受影響 |
| 顯示名稱 | 按鈕上顯示的名字，比如「家裡的 NAS 帳號」「公司帳號」。留空就顯示 SSO |
| 服務位址 | 身分提供者給出的位址，直接貼上即可。結尾帶不帶 `/.well-known/openid-configuration` 或斜線都可以，雲瞰會自行收斂。必須是 https |
| 用戶端 ID | 在提供者那裡建立應用程式之後拿到 |
| 用戶端密鑰 | 同上。只在雲瞰和提供者兩台伺服器之間使用，不會下發到瀏覽器或手機 |
| 首次登入自動建立帳號 | 開著：沒見過的人第一次登入就自動開一個雲瞰帳號。關掉：必須先手動關聯，沒關聯過的人會被拒絕 |
| 自動建立時的角色 | 建議保持「訪客（唯讀）」。需要管理權限的人，事後在使用者管理裡單獨提升 |

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

> **⚠️ 別急著先打開總開關**
>
> 建議的順序是：填完服務位址、用戶端 ID、用戶端密鑰 → 儲存 → 再打開「啟用單一登入」→ 登出試一次。萬一哪裡填錯，登入頁上不會先擺出一個點了必然失敗的按鈕。

> **ℹ️ 這幾家我們完整跑過**
>
> 群暉、Authentik、Keycloak 三家是在真機上從頭設定到登入成功驗證過的。Microsoft Entra 與 Google 按各自官方後台的步驟設定，填法與前面幾家一致。

## 三、群暉 SSO Server

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

1. **裝套件並打開服務**

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

2. **新增應用程式**

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

3. **抄兩個值回雲瞰**

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

4. **填服務位址**

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

> **⚠️ DSM 這個位址必須是 https 且憑證有效**
>
> 瀏覽器打開 DSM 不跳憑證警告就算過關。自己簽的憑證雲瞰會拒絕——DSM 裡可以一鍵申請免費憑證，先把那步做了。

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

## 四、Authentik

1. **新建 Provider**

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

2. **填關鍵幾項**

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

3. **抄憑據**

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

4. **建 Application 並設定可見範圍**

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

5. **填服務位址**

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

## 五、Microsoft Entra ID（原 Azure AD）

1. **註冊應用程式**

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

2. **拿兩個識別碼**

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

3. **建立用戶端密碼**

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

4. **填服務位址**

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

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

## 六、Google

> **⚠️ Google 不接受區域網路位址**
>
> 它只認公網可解析的網域加 HTTPS，區域網路 IP 和明文 http 一律拒絕。也就是說要用 Google 登入，你的雲瞰得先有一個自己的網域和憑證——見〈[外網存取](/docs/remote-access)〉，憑證能在網頁裡自動申請。

1. **建立憑證**

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

2. **填回呼位址**

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

3. **填服務位址**

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

4. **調一下使用者名稱來源**

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

> **🛑 別讓全世界都能在你的雲瞰上開帳號**
>
> 誰能用 Google 登入由 Google 那邊的「OAuth 同意畫面」控制。個人帳號建議把發布狀態留在「測試」，並把允許的人加進測試使用者清單——否則在「首次登入自動建立帳號」開著的情況下，任何一個 Google 帳號都能在你的雲瞰上註冊出一個帳號來。

## 七、Keycloak

1. **新建 Client**

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

2. **打開機密用戶端**

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

3. **填回呼位址**

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

4. **抄密鑰並填服務位址**

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

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

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

1. **跳過去登入**

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

2. **雲瞰找有沒有對應的帳號**

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

3. **沒找到的兩種走向**

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

> **ℹ️ 自動建出來的帳號沒有登入密碼**
>
> 它只能用單一登入進。想讓它也能用密碼登入，管理員在**使用者管理**裡給它設一個密碼即可。另外記得去使用者管理裡給新人設定「可見攝影機」——預設角色是訪客，看得到哪幾台仍然由授權決定。

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

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

1. **先用雲瞰帳號正常登入**

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

2. **找到關聯入口**

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

3. **點「關聯 XX 帳號」**

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

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

> **⚠️ 沒有密碼的帳號不讓解除關聯**
>
> 自動建立出來的帳號本來就沒有登入密碼，解除關聯等於把自己鎖在門外，雲瞰會擋住並提示先讓管理員設一個密碼。

## 十、手機 App

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

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

## 十一、常見問題

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

## 相關教學

- [使用者與權限](/docs/users)——給新進來的人設定可見攝影機
- [登入兩步驟驗證](/docs/two-factor)——雲瞰自己的驗證碼，和單一登入二選一即可
- [外網存取](/docs/remote-access)——配網域和憑證

---

來源:https://yun-kan.com/zh-TW/docs/sso