---
url: https://qiwuadmin.com/features/oauth.md
description: 把栖梧用作 OAuth2 授权服务器：登记客户端与密钥、授权同意页、记住授权、第三方会话和令牌有效期，以及 PKCE、不支持 OIDC 等接入限制。
---

# 单点登录（OAuth2）

栖梧可以当作一个 **OAuth2 授权服务器**，让别的系统接入：

* **第三方网站或应用**可以在登录页放一个"用栖梧账号登录"的按钮。用户点击后来到栖梧的授权页，同意以后，第三方就能读取这个用户的基本资料（用户名、姓名、头像、界面语言），用来登录或关联自己的账号；
* **机器客户端**（比如另一个系统的后台服务）可以用客户端标识和密钥直接申请令牌，不代表任何用户。

用户在栖梧已经登录时，授权只需要点一次"同意授权"；记住授权以后，连这一步也会跳过，第三方的登录几乎是无感的。

::: tip 给第三方开发者
完整的接入步骤、请求和响应示例见 [OAuth2 接入指南](/reference/oauth2)。这一页只讲管理员和用户能看到的部分。
:::

## 客户端管理

每个要接入的系统都要先登记成一个**客户端**。在 **系统管理 → 客户端管理** 中新增，主要填写：

* **客户端标识**：第三方接入时用的 ID，比如 `crm`。由管理员填写，只能用小写字母、数字和 `.` `_` `-`，3 到 64 个字符，**创建后不能修改**。`console` 和 `mobile` 是本系统自己保留的，不能使用；
* **客户端名称**和**图标**：显示在授权页上，让用户知道是谁在申请；
* **授权方式**：授权码（让用户授权）、刷新令牌（访问令牌到期后换一对新令牌，用户不用再授权）、客户端凭证（机器客户端），至少选一项；选刷新令牌必须同时选授权码；
* **回调地址**：用户同意或拒绝后回到第三方的地址，最多 10 个。必须是 `https://`，本机调试可以用 `http://localhost` 或 `http://127.0.0.1`；
* **授权范围**和**自动授权范围**：`user.read`（读取基本资料）；另有 `mcp`、`mcp.write` 两个范围，只用于登记智能体客户端，默认不勾选，见[MCP 智能体接入 · OAuth2](/features/mcp#oauth2)。放进"自动授权范围"的不用问用户，授权页上也不出现；
* **访问令牌有效期**和**刷新令牌有效期**：每个客户端单独设置，见[会话和令牌](#会话和令牌)。

![新增客户端表单](/screenshots/zh-oauth-form.webp)

字段的详细规则和列表上的操作见[系统管理 · 客户端管理](/features/system#客户端管理)。这里只说几条要特别注意的：

* **密钥只显示一次**。保存新客户端后，弹窗"保存客户端密钥"里显示密钥，复制保存后点"我已保存"。之后在页面、接口和日志里都看不到它。丢了只能点"重置密钥"，重置后旧密钥立即失效，已经签发的令牌不受影响；
* **内置客户端 `console`**（管理后台自己）在列表里只读，不能编辑、停用、重置密钥或删除；
* **停用或删除客户端**（包括批量删除），它的所有会话立即结束，用户授权的和客户端凭证的都算在内。删除以后，同一个客户端标识可以重新登记，但它是一个新的客户端：旧会话、没兑换的授权码和用户记住的授权都不会转到新客户端上。

![保存客户端密钥弹窗](/screenshots/zh-oauth-secret.webp)

权限：`oauth.client.browse`（浏览）、`oauth.client.view`（查看）、`oauth.client.create`（新增）、`oauth.client.modify`（修改）、`oauth.client.remove`（删除）、`oauth.client.reset-secret`（重置密钥）。

::: info 开启多租户时
[多租户](/features/multi-tenancy)打开后，有几点不同：

* **客户端管理**只有平台（默认租户）的人员能用，登记的客户端所有租户共用；
* **客户端凭证**签出的令牌属于平台，只用于平台自身的系统集成，读不到其他租户的数据。租户的应用请用授权码接入；
* 用户先在自己的租户里登录（租户绑定的域名，或者主域名加租户编码），再打开同意页；
* 不同租户可以有同名用户，第三方要用用户信息里的 `sub` 关联账号，不要用 `username`。

细节见仓库的 [OAuth2 文档 · client_credentials](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/oauth2.md#3-client_credentials机器令牌)和[令牌隔离与会话](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/oauth2.md#7-令牌隔离与会话)。
:::

## 授权同意页

第三方把用户的浏览器带到本站的 `/sso` 页面（地址里带着授权请求的参数），用户在这里决定是否授权：

* 标题是"授权登录"，下面一行"以 （你的显示名） 的身份继续"，显示的是当前登录用户的显示名；
* 显示客户端的图标（没有图标时显示客户端名称的首字）、名称和标识，然后是"（客户端名称） 请求访问你的账号："和申请的权限列表，比如"读取你的基本资料（用户名、姓名、头像）"；
* 下面一行"授权后将跳转到 ……"，显示回调地址的主机名。用户可以借此认出冒充的应用；
* 三个按钮：**同意授权**、**拒绝**、**切换账号**。同意后回到第三方并带上授权码；拒绝后也回到第三方，但只带一个"用户拒绝"的结果；切换账号会先退出当前账号，换一个账号登录后回到这个授权页。

几种特殊情况：

* **还没登录**：先跳到登录页，登录后自动回到同一个授权页。授权过程中登录过期了也一样；
* **请求无效**：客户端不存在或已停用、回调地址没有登记、缺少 PKCE 参数、申请的范围超出登记的范围等。页面停在 `/sso`，显示服务端给出的原因和"返回首页"，**不会跳转**到任何地址，以免把用户送到没有核实过的网站；
* **不需要询问**：申请的范围都是自动授权的，或者都已经[记住授权](#记住授权)，页面显示"正在跳转…"后直接回到第三方。

同意和拒绝都会记入操作日志，日志里不会出现授权码。

## 记住授权

用户同意一次以后，在一段时间内再授权同一个客户端，就不会再看到同意页。

* 天数由参数 `oauth.consent_ttl_days`（"记住授权天数（0 = 每次询问）"）决定，默认 **30** 天，在 **系统管理 → 参数设置** 中修改，可以填 0 到 3650，填错时按 30 天处理；
* 设为 **0** 时不再记住，已经记住的也不再生效，每次都要用户点同意；
* 同意页上**没有**"记住授权"的勾选框，同意时这次申请的所有范围一起记住。每次同意都把有效期重新算满；每个客户端分开记；
* 自动授权范围本来就不需要用户同意，所以不用记，授权页也不会出现。

目前还没有让用户自己撤回授权的页面。需要撤回时，管理员可以停用或删除这个客户端，或者把参数设为 0。删除用户或删除客户端时，相关的授权记录一起作废。

## 会话和令牌

第三方拿到的令牌，在本系统里是一个普通的会话，只是用途受限：

* **在线用户里能看到**：在 **系统监控 → 在线用户** 中，第三方会话的"客户端"一列显示它的客户端标识，筛选时也可以直接输入客户端标识。强退后令牌立即失效。客户端凭证申请的会话不属于任何用户，只有超级管理员能看到和强退；
* **不能调用后台接口**：第三方令牌只能读取用户信息，调用后台的其他接口一律返回 401，也不能替用户在同意页上点同意；
* **账号变化时一起失效**：用户修改密码、更换手机号、被管理员重置密码或用短信找回密码、被停用、被删除、被管理员"强退该用户"，或者在锁屏、改密码、换手机号时连续输错当前密码，他在所有第三方的会话，以及还没兑换的授权码，都会一起失效。只强退某一个会话时，只结束那一个；
* **有效期按客户端设置**：访问令牌有效期 300 到 86400 秒，默认 1800 秒（30 分钟），到期不会自动续期，要用刷新令牌换新的；刷新令牌有效期 3600 到 2592000 秒，默认 604800 秒（7 天），同时也是**这次授权的最长时间**，从第三方应用用授权码换到令牌时算起，刷新不会延长。到期后用户要重新授权（记住授权期间只是一次跳转）。

## 限制

* **只支持机密客户端**：申请、校验、撤销令牌时都必须带客户端密钥，所以接入方必须有自己的后端。纯前端的网页应用和手机 App 要通过自己的后端接入，不能把密钥放进浏览器或安装包；
* **授权码方式必须用 PKCE**，而且只接受 `S256`。授权码 300 秒内有效，只能用一次；
* **不支持 OIDC**：没有 `id_token`，没有自动发现地址（discovery）和公钥地址（JWKS）。用户信息从专门的用户信息接口读取；
* **不支持**密码授权（`password`）和隐式授权（`implicit`）；
* **给第三方读用户信息的授权范围只有 `user.read`**（`mcp`、`mcp.write` 只用于[智能体接入](/features/mcp)），用户信息只有用户 ID、用户名、姓名、头像和界面语言，不含手机号、邮箱、部门和角色；
* **按 IP 限流**：授权页每个 IP 每分钟 120 次，令牌接口 600 次，校验和撤销接口各 1200 次，超出返回 429。计数存在 Redis 里，部署多个服务实例时共用同一份额度（见[部署 · 多实例部署](/guide/deploy#多实例部署)）；
* **演示模式下不能用**：开启演示模式（`APP_DEMO_MODE=true`）时，同意授权、申请令牌、校验和撤销令牌都会被拒绝（返回 403）。要体验单点登录，请用没有开启演示模式的安装。

## 开发指南

* [OAuth2 接入指南](/reference/oauth2)：给第三方开发者的完整流程（curl 示例）、接口、错误码和接入清单
* [部署 · OAuth2 与单点登录](/guide/deploy#oauth2-与单点登录)：反向代理和 `TRUST_PROXY` 的要求

相关功能：[系统管理 · 客户端管理](/features/system#客户端管理)、[登录与账号 · 在线用户与强制下线](/features/login#在线用户与强制下线)、[安全基线](/features/security#单点登录-oauth2)。
