# 单点登录

跟完这篇，家里人不用再记一个云瞰专用的密码——用群晖 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 三家是在真机上从头配到登录成功验证过的。微软 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/`，整条粘进云瞰的「服务地址」。末尾的斜杠加不加都行。

## 五、微软 Entra ID（原 Azure AD）

1. **注册应用**

   **去哪里**：Azure 门户 → **Microsoft Entra ID → 应用注册 → 新注册**。「重定向 URI」平台选 **Web**，填第一节那条回调地址。

2. **拿两个 ID**

   **做什么**：注册完在「概述」页复制**应用程序(客户端) ID**（→ 云瞰的「客户端 ID」）和**目录(租户) ID**（下一步拼地址要用）。

3. **建客户端密码**

   **做什么**：「证书和密码 → 新客户端密码」，创建后**立刻复制「值」那一列**——离开这个页面就再也看不到了。粘进云瞰的「客户端密钥」。

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**，类型选 **Web 应用**。

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-CN/docs/sso