自定义范围
Custom scopes 允许Agent应用程序定义通过OAuth公开的权限或功能。 它们被添加到应用的OIDC发现中，并与标准OIDC作用域一起使用。
何时使用自定义范围
适用于类别为 Agent 的应用程序。 适用于：
- 需要为不同资源定义细粒度权限的MCP服务器
- 希望控制对特定端点或功能访问的API服务
- 实现细粒度授权模型的应用程序
默认（非Agent）应用程序仅使用标准OIDC作用域，无需自定义作用域。
配置范围
在应用程序编辑页面上，添加作用域。 每个都有：
- Name — OAuth中的作用域标识符（例如
files:read、messages:write）。 - Display name — 在用户同意期间向用户显示（例如：“读取文件”）。
- Description — 范围允许的内容（例如：“允许读取您的文件”）。
作用域的工作原理
当你配置自定义 scopes 用于一个 Agent 应用程序：
- 作用域与应用程序配置一起存储
- 它们与发现端点中的标准OIDC作用域合并
- 客户端应用程序可在 OAuth 流程中请求这些范围
- 这些范围会显示在 OIDC 发现文档的
/.well-known/openid-configuration中
标准OIDC范围始终可用，不受您的自定义范围配置影响。 您的自定义范围是扩展而非替换默认范围。
示例
以下是用于管理文件和数据库的MCP服务器的实际示例：
| 名称 | 显示名称 | 描述 |
|---|---|---|
files:read | 读取文件 | 查看和下载存储中的文件 |
files:write | 写文件 | 在您的存储中创建、修改和删除文件 |
db:query | 查询数据库 | 执行只读数据库查询 |
db:modify | 修改数据库 | 创建、更新和删除数据库记录 |
当客户端连接到此MCP服务器时，它们可以根据所需执行的操作，按照最小权限原则请求特定范围。
添加范围
从该应用程序编辑页面：
- 确保您的应用程序类别设置为“Agent”
- 滚动到“作用域”部分
- Click "添加" 以创建一个 new 作用域
- 填写名称、显示名称和描述
- 使用向上/向下箭头重新排序范围
- 单击删除按钮以移除不需要的作用域
- 保存你的应用程序
保存后，这些作用域立即可用，并将显示在您的OIDC发现端点中。
作用域强制执行
当应用程序至少配置了一个自定义作用域时，Casdoor 会针对每个令牌请求，按照该列表验证 scope 参数。 如果客户端请求的作用域不在应用程序的作用域列表中，Casdoor将返回invalid_scope错误（根据RFC 6749）：
{
"error": "invalid_scope",
"error_description": "the requested scope is invalid, unknown, or malformed"
}
应用程序使用 no scopes configured 接受任何scope 价值, 保留向后兼容性。 一旦您定义了至少一个作用域，系统将仅接受您所列出的作用域。
正则表达式和通配符范围
当客户端的范围字符串包含正则表达式元字符（.、*、+、?、^、$、{、}、(、)、|、[、]、\）时，可使用正则表达式模式请求范围。
当检测到模式时，Casdoor会通过与所有已配置的作用域名称进行匹配来扩展该模式。 所有匹配的作用域名称将替换最终授予作用域中的模式。 字面范围名称（无元字符）仍按以前的精确匹配方式进行验证。
例如，如果一个应用程序定义了“files:read”、“files:write”和“db:query”，则请求“scope=files:.*”的客户端将同时获得“files:read”和“files:write”。
如果模式匹配不到任何内容，则请求将被拒绝，并返回invalid_scope。