OAuth2 / OIDC——将服务连接到Omniscol

Omniscol作为OAuth2服务器的作用

外部服务——AI智能体、连接器、仪表盘——会成为您账户中声明的客户端；学校的某位用户通过授权页面批准其访问；服务随后获得一个有效期较短的访问令牌，其范围受限于已授予的 scope 和该用户的权限。

该机制不同于OIDC / SSO中介绍的用户SSO：在后者中，Omniscol是您的身份提供方的客户端，用于让您的用户登录。而在这里，Omniscol位于服务器一侧：由各种服务来连接它。

Omniscol有两项集成使用该服务器：

• MCP——AI智能体的标准认证经由该OAuth2服务器完成（参见MCP——连接外部AI智能体）；
• OneRoster——OneRoster生产方使用该服务器签发的机器对机器OAuth2令牌进行认证（参见OneRoster）。

任何其他符合OAuth2 / OIDC的服务都可以用同样的方式连接。

发现机制与协议接口

Omniscol在标准的 .well-known 地址发布其发现元数据，这些地址位于您账户域名的根路径下（例如 https://your-school.omniscol.com）。符合规范的客户端能自行找到所有接口，无需手动配置：

• /.well-known/oauth-authorization-server——授权服务器元数据（RFC 8414）；
• /.well-known/openid-configuration——OpenID Connect元数据（内容与上一项相同）；
• /.well-known/jwks.json——用于验证的公钥（JWKS），可用来校验 id_token 的签名；
• /.well-known/oauth-protected-resource——受保护资源元数据（RFC 9728）。

这些元数据会公布协议接口：

• /oauth/authorize——授权请求（先登录，再进入授权页面）；
• /oauth/token——用授权码换取令牌，以及刷新令牌；
• /oauth/register——动态客户端注册（RFC 7591）；
• /oidc/userinfo——已登录用户的信息（OIDC）；
• /oauth/revoke——撤销令牌（RFC 7009）。

这些协议接口是公开的：不限于Premium账户，也无需手动开放。只有下文介绍的客户端管理界面属于Premium。

授权流程

Omniscol支持三种OAuth2流程：

• 带PKCE的授权码模式——服务代表用户操作时的默认流程。服务将用户重定向到 /oauth/authorize；用户登录并授权后，Omniscol返回一个授权码（有效期5分钟），服务再到 /oauth/token 兑换。采用的PKCE方法为 S256，唯一接受的 response_type 是 code。
• 刷新（refresh_token）——用于延长委托访问，无需再次经过授权。
• Client credentials——机器对机器流程，没有用户参与，主要供 OneRoster 的使用方采用。客户端直接认证并获得访问令牌。

兑换时，服务器会签发一个访问令牌（Bearer，有效期1小时）；对于用户流程，还会签发一个刷新令牌（有效期30天）。当请求了 openid scope时，还会签发已签名的OIDC id_token，其签名可通过 /.well-known/jwks.json 验证。client_credentials 流程只签发访问令牌，没有刷新令牌，也没有 id_token。

访问令牌随后放在HTTP请求头 Authorization: Bearer <令牌> 中提交。每次调用时，Omniscol都会验证其签名，检查客户端是否仍处于**活跃**状态、用户是否仍然存在并具备所需角色，以及令牌的 scope 是否覆盖所调用的接口——否则调用会被拒绝。

scope与授权

您可以在客户端上管理的scope有：

• read:basic——读取课表、仪表盘和各类查询（主页、课表、仪表盘、课表管理模块）；
• read:user——读取用户列表；
• write:data——写入上述查询类模块；
• admin——管理访问（管理、缺勤管理、课表管理模块）。

服务器还支持OIDC scope（openid、email、profile）以及只读的 OneRoster scope（前缀为 imsglobal.org）。后者属于特权 scope：客户端不能通过动态注册为自己授予；它们必须由管理员在该客户端上预置。

实际授予的scope是客户端所请求的与其已注册的交集：客户端获得的权限不会超出其已注册的范围。在用户流程中，授权页面（/oauth/consent）会显示请求方服务的名称和徽标，以及所请求scope的易读列表，并提供**接受和拒绝**按钮。批准后会签发授权码，并将用户送回服务；拒绝则带着 access_denied 错误将其送回。

动态客户端注册

/oauth/register 接口实现了动态注册（Dynamic Client Registration，RFC 7591）：符合规范的服务可以自行声明为客户端，无需事先人工干预。这使MCP智能体仅凭服务器URL就能完成自身配置。

动态注册不能为自己授予特权scope（OneRoster scope）：这些scope会被静默剔除，如果没有剩下任何有效scope，则默认授予 read:basic。特权scope仍只能由管理员预置。

OAuth2客户端管理界面

在 Premium账户中，您可以在管理 → 导入/导出的 OAuth2 部分，通过按钮OAuth2管理客户端。进入前会先要求输入管理员密码——打开界面前的一道额外确认。

界面列出已注册的客户端，并显示每个客户端的状态（活跃 / 停用）、名称、scope、联系人和 URI（网站、徽标、重定向URI）。您可以：

• 注册客户端——填写名称、可选的 software_id、scope、联系人、网站、徽标和重定向URI。创建时，Omniscol会仅显示一次 client_id 和 client_secret。
• 修改客户端——只能修改安全的字段：名称、scope、联系人、网站和徽标。重定向URI、software_id 和密钥不能在此修改。
• 启用或停用客户端——客户端被停用后，其令牌在下一次调用时即被拒绝。
• 删除客户端——删除是永久性的。

客户端密钥

client_secret 在注册时只显示一次。Omniscol只保存该密钥的指纹，从不保存明文密钥：之后无法再次显示或找回。请立即将其复制到密钥管理工具中。

client_id 则是确定性的：由账户名称、客户端名称以及其技术元数据的指纹生成。因此，两次完全相同的注册会得到同一个标识。

更新密钥（轮换）

密钥轮换是支持的：它会签发新密钥，只保存新密钥的指纹，并且仅返回一次新密钥。轮换通过动态注册的管理接口（/oauth/register/<client_id>/rotation）进行，需要出示客户端动态注册时交给它的注册令牌。因此它不是从上述管理界面触发的，该界面不处理此令牌。

OAuth2还是API密钥：如何选择

Omniscol提供两种机器访问机制，信任模型各不相同：

• OAuth2（本页）——已注册的第三方在用户授权后，获得一个有效期较短（1小时）、限定于已授予scope、可刷新、可撤销（通过停用客户端）的令牌。client_credentials 流程还支持没有用户参与的机器对机器场景。它适用于已识别的第三方服务、MCP和OneRoster。
• API密钥（参见Omniscol API）——由服务器签名的独立令牌，内含一份被授权的接口列表，由您自己交给外部系统：没有已注册的第三方，没有授权页面，也没有刷新。这相当于管理员把自己的权限委托给他所掌控的系统。

总之：当您亲自把访问权限交给自己控制的系统时，适合使用 API密钥；当已识别的第三方服务需要获得受限于scope、可撤销的委托访问，或协议本身要求时（MCP、OneRoster），适合使用 OAuth2。