---
title: "服务端调用 - QiSSO"
description: "区分用户身份与服务身份，配置客户端凭据、接口权限和授权重新核验。"
canonical_url: "https://docs.mcent.cn/qisso/server-integration"
---
# 服务端调用 - QiSSO

> 区分用户身份与服务身份，配置客户端凭据、接口权限和授权重新核验。

`client_credentials` 用于受信系统代表自身调用接口，不代表某个用户已经登录。它不能生成用户授权关系，也不能替代授权码登录。

## 申请服务权限

管理员为机密客户端开启 `client_credentials`，只授予实际需要的服务 scope，并在资源服务登记允许的调用方。仅拿到令牌不代表可以访问所有 QiSSO 或业务接口。

当前服务 scope 包括：

<table>
<thead>
  <tr>
    <th>
      Scope
    </th>
    
    <th>
      能力归属
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        users:read
      </code>
    </td>
    
    <td>
      QiSSO 用户目录及受信应用的用户授权重新核验
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        users:create
      </code>
    </td>
    
    <td>
      QiSSO 受信用户创建能力
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        account.profile.read
      </code>
    </td>
    
    <td>
      QiSSO 受信账号资料读取
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        account.profile.write
      </code>
    </td>
    
    <td>
      QiSSO 受信账号资料更新
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        license.account.read
      </code>
    </td>
    
    <td>
      QiLicense 账号许可证查询
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        license.account.rebind
      </code>
    </td>
    
    <td>
      QiLicense 账号许可证换绑
    </td>
  </tr>
</tbody>
</table>

服务 scope 是现有能力的目录，不是对所有新应用的默认授权。许可证权限由 QiLicense 的资源接口继续校验；面向账号的调用还需要用户与应用之间的有效授权关系。

QiSSO 自身的受信服务接口通过 `QISSO_SERVICE_CLIENT_IDS` 维护调用方允许名单。新客户端的 scope、允许名单和资源接口配置需要同时匹配。

## 获取服务令牌

使用 Discovery 提供的 `token_endpoint` 和应用登记的认证方式：

```http
POST <token_endpoint>
Authorization: Basic <service_client_credentials>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=users%3Aread
```

这里只请求本次任务需要的服务 scope，不附带用户登录用的 `openid` 或 `offline_access`。令牌在服务端内存或受控存储中缓存，按响应中的 `expires_in` 提前少量刷新；`client_credentials` 不使用用户 Refresh Token。

服务凭据、令牌和调用头不得下发浏览器，也不写入日志。不要假设所有 Access Token 都是 JWT；受信服务接口可能要求 QiSSO 签发的不透明服务令牌，不能用 ID Token 或自行构造的 JWT 替代。

## 重新核验用户授权

已获 `users:read` 并进入允许名单的业务服务端，可通过以下接口重新核验当前业务用户：

```http
GET /api/v1/service/authorization/users/<url_encoded_sub>
Authorization: Bearer <service_access_token>
```

返回当前授权上下文：

```json
{
  "sub": "example-user-id",
  "roles": [],
  "permissions": [],
  "authz_ver": 1,
  "checked_at": "2026-01-01T00:00:00.000Z"
}
```

`sub` 必须来自本地已验证的登录会话。接口核验账号状态，以及用户是否仍授权给当前服务令牌所属的客户端；不会因为持有服务令牌而创建授权关系。

<table>
<thead>
  <tr>
    <th>
      结果
    </th>
    
    <th>
      业务端处理
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      按返回的当前授权上下文更新本地状态，再执行业务权限判断
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        401
      </code>
    </td>
    
    <td>
      检查服务令牌与服务身份；不要继续使用未经核验的权限
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        403 APPLICATION_AUTHORIZATION_REVOKED
      </code>
    </td>
    
    <td>
      清理该用户的本地业务会话，重新发起授权
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        403 ACCOUNT_NOT_ACTIVE
      </code>
      
       / <code>
        404 USER_NOT_FOUND
      </code>
    </td>
    
    <td>
      终止受影响的本地会话与访问
    </td>
  </tr>
  
  <tr>
    <td>
      超时或服务不可用
    </td>
    
    <td>
      需要实时授权的操作拒绝放行，展示可重试的失败状态
    </td>
  </tr>
</tbody>
</table>

JWT 中的角色与权限反映签发时刻，不能单靠它们保证账号禁用、应用撤销或权限变更即时生效。需要及时收回访问的系统应设计明确的重新核验时机与缓存上限。

## 受信账号接口

当前资料接口包括 `GET /api/v1/service/account/summary` 与 `PATCH /api/v1/service/account/profile`，分别需要 `account.profile.read` 与 `account.profile.write`。调用时还需 `X-QiSvc-User-Id`，由受信 BFF 从本地会话中的已验证 `sub` 设置，并要求该用户仍授权给当前客户端。更新接口当前仅接受 `name` 字段。

这些接口面向受信服务，不能直接转发浏览器提交的用户 ID、服务认证头或任意资料字段。需要展示当前会话时，可传 `X-QiSvc-Session-Id`；QiSSO 只接受属于该用户且仍有效的会话标识。

## 资源服务令牌内省

`/api/v1/service/tokens/introspect` 是现有 QiLicense 资源服务专用的服务令牌内省接口，使用规定的资源服务客户端身份与独立的 `QISSO_INTROSPECTION_TARGET_CLIENT_IDS`。它只识别符合策略的机器 Access Token，不是任意应用或浏览器可用的通用用户会话验证接口。

新增资源服务应先明确身份、受众、令牌类型和权限契约，不能直接套用该专用接口。普通用户登录接入继续按 [OIDC 登录](https://docs.mcent.cn/qisso/oidc-login)实施。


## Sitemap

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