单点登录

一、先记下这条回调地址

在身份提供方那里创建应用时，一定会让你填一个「回调地址」（也可能叫重定向 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/，整条粘进云瞰的「服务地址」。末尾的斜杠加不加都行。

五、微软 Entra ID（原 Azure AD）

1. 1

   注册应用

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

2. 2

   拿两个 ID

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

3. 3

   建客户端密码

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

4. 4

   填服务地址

   做什么：填 https://login.microsoftonline.com/<租户 ID>/v2.0。

Entra 给出的用户名通常是完整邮箱，云瞰会取 @ 前面那一段当用户名，重名时自动加序号。「API 权限」里保持默认的那几项即可。

六、Google

1. 1

   创建凭据

   去哪里：Google Cloud Console → API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID，类型选 Web 应用。

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 的测试用户列表、群晖的用户组）。云瞰这边的粗粒度开关是「首次登录自动创建账号」，关掉之后只有你手动关联过的人能进。

相关教程

• 用户与权限——给新进来的人配可见摄像头
• 登录二次验证——云瞰自己的验证码，和单点登录二选一即可
• 外网访问——配域名和证书