---
title: "Claims 与权限 - QiSSO"
description: "识别稳定用户身份、令牌 Claims 和业务权限，避免混用角色、scope 与资源授权。"
canonical_url: "https://docs.mcent.cn/qisso/claims-and-permissions"
---
# Claims 与权限 - QiSSO

> 识别稳定用户身份、令牌 Claims 和业务权限，避免混用角色、scope 与资源授权。

认证回答“用户是谁”，授权回答“当前能做什么”。接入 QiSSO 后，业务系统还需要自己的资源归属、租户隔离与接口权限检查。

## 标准身份字段

<table>
<thead>
  <tr>
    <th>
      Claim
    </th>
    
    <th>
      含义
    </th>
    
    <th>
      使用方式
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        iss
      </code>
    </td>
    
    <td>
      签发者
    </td>
    
    <td>
      与本环境完整 Issuer 精确匹配
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sub
      </code>
    </td>
    
    <td>
      此签发者下的用户标识
    </td>
    
    <td>
      使用 <code>
        (iss, sub)
      </code>
      
       关联本地账号
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        aud
      </code>
    </td>
    
    <td>
      令牌受众
    </td>
    
    <td>
      ID Token 包含本客户端 ID；Access Token 按资源契约校验
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        azp
      </code>
    </td>
    
    <td>
      获授权的客户端
    </td>
    
    <td>
      根据 OIDC 库执行多受众等校验
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        exp
      </code>
      
       / <code>
        iat
      </code>
    </td>
    
    <td>
      到期 / 签发时间
    </td>
    
    <td>
      由协议库验证，业务缓存不能超过有效期
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        nonce
      </code>
    </td>
    
    <td>
      绑定登录事务
    </td>
    
    <td>
      与 BFF 保存的本次随机值匹配
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sid
      </code>
    </td>
    
    <td>
      身份会话标识，可能存在
    </td>
    
    <td>
      不把它直接当作业务 Cookie 或用户 ID
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
      
       / <code>
        preferred_username
      </code>
    </td>
    
    <td>
      显示资料
    </td>
    
    <td>
      可变化，不能作为稳定外键
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        email
      </code>
      
       / <code>
        email_verified
      </code>
    </td>
    
    <td>
      邮箱及验证状态
    </td>
    
    <td>
      按返回值与业务策略使用，不因有邮箱就自动关联本地高权限账号
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        picture
      </code>
    </td>
    
    <td>
      头像地址，可能存在
    </td>
    
    <td>
      正常作为外部资源展示，允许缺失与加载失败
    </td>
  </tr>
</tbody>
</table>

Claims 的实际存在与 scope、账号资料、令牌类型及服务端配置有关。缺少可选资料时提供回退，不把示例中的所有字段设为必填。

## QiSSO 授权字段

当前用户授权上下文包括：

```json
{
  "roles": ["license-operator"],
  "permissions": ["license.licenses.read"],
  "authz_ver": 7
}
```

此处权限字符串是结构示意，业务接口应使用其正式定义的权限键。`roles` 为角色键数组，`permissions` 为权限键数组，`authz_ver` 为用户授权版本。版本用于识别授权上下文发生变化，不是某个用户的稳定 ID，也不是访问许可本身。

当前 `resource_access` 是既有 QiLicense 角色兼容字段，其对象键并不自动等于所有接入应用的 Client ID。新应用不要依赖这个兼容字段推断自己的角色；优先使用已约定的 `roles`、`permissions` 与本应用的服务端策略。

## 三类授权不能混用

<table>
<thead>
  <tr>
    <th>
      类型
    </th>
    
    <th>
      例子
    </th>
    
    <th>
      不代表什么
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      OAuth scope
    </td>
    
    <td>
      <code>
        openid
      </code>
      
      、<code>
        users:read
      </code>
    </td>
    
    <td>
      不代表用户拥有后台管理员权限
    </td>
  </tr>
  
  <tr>
    <td>
      用户角色/权限
    </td>
    
    <td>
      <code>
        roles
      </code>
      
      、<code>
        permissions
      </code>
    </td>
    
    <td>
      不代表某个资源属于用户当前租户
    </td>
  </tr>
  
  <tr>
    <td>
      业务资源规则
    </td>
    
    <td>
      当前租户、订单归属、对象可操作状态
    </td>
    
    <td>
      不能仅由统一身份令牌中的角色替代
    </td>
  </tr>
</tbody>
</table>

服务令牌中的 `permissions` 来源于获批的服务 scope，用户令牌的授权上下文来源于用户角色配置，两者的身份和用途不同。`client_credentials` 没有终端用户身份，不从它创建用户登录会话。

## 在业务端执行权限检查

前端可以根据权限控制菜单和按钮，服务端必须再次校验接口所需权限及资源归属。未知、格式错误或不属于本应用的权限键按本应用策略拒绝，不能默认为拥有全部权限。

在使用启承服务共享授权 SDK 的现有系统中，`@orangezh1/qisvc-authz` 提供 Claims 解析与权限检查，识别精确权限键及受控的 `*` 全权限标记。它不是面向任意业务系统的通用权限目录；新应用需要明确自己的权限命名和映射，不复制其他产品的权限键当作业务模型。

如果将 QiSSO 身份映射到本地角色，映射规则应由管理员或受信配置决定，不接受浏览器提交“我是管理员”。本地权限的变化与统一账号授权变化要分别处理。

## 处理权限变化

令牌是签发时刻的快照。账号禁用、角色修改、应用授权撤销后，旧 JWT 的签名仍可能验证成功，直到其自然过期。

需要实时控制的操作使用[服务端重新核验](https://docs.mcent.cn/qisso/server-integration)，结合 `authz_ver` 更新本地缓存。授权撤销或账号失效时终止本地会话；服务不可用时，对要求实时授权的操作拒绝放行，不把旧缓存无限延长。

完整退出与授权关系见[会话与退出](https://docs.mcent.cn/qisso/sessions-and-logout)。


## Sitemap

See the full [sitemap](https://docs.mcent.cn/sitemap.md) for all pages.