Administrator guide

本页由独立源码仓的详细指南迁入 Wiki。当前已公开版本为 0.8.3；正文中的候选或历史验收描述保留各自适用范围，不作为本轮运行证明。发行状态和真实验收范围见 版本与兼容性。

SandIAM 手把手使用说明

写给应用管理员。本文说明后台的填写步骤、员工开通与技术负责人的交接点。SandIAM 是通用的身份与访问管理工具：它把客户主体、接入应用、环境、应用用户、权限、系统调用和审计记录放在清楚的范围里，帮助你回答三件事：谁可以进入、谁可以做什么、出了问题如何查到并撤销。

先说清楚：哪些事情由谁负责

SandAdmin 后台账号是管理后台的账号；接入应用里的最终用户账号、登录页面、会话和安全设置属于应用用户入口。后台管理员不能把自己的后台会话当成应用用户会话使用。

SandIAM 可以登记和管理通用身份、角色、资源、策略、服务调用身份、服务授权、凭证、管理范围和审计。应用本身仍负责自己的业务对象、业务状态和业务规则。

后台能做的事：

• 创建客户主体、接入应用和应用环境，并查看、修改、停用或恢复；
• 配置身份源、应用用户、用户组、角色、资源和策略；
• 配置服务调用身份、服务授权和凭证，查看调用审计并撤销凭证；
• 配置接口目录、路由绑定、策略模拟、管理委派和事件通知；
• 查询审计、查看投递失败并按规则重试。

后台不能替应用完成的事：

• 不能代替接入应用定义业务对象及其业务规则；
• 不能代替应用用户登录、保持会话、设置 MFA 或通行密钥；
• 不能在没有真实外部服务、接收地址或应用配合的情况下证明登录、调用或通知已经成功；
• 不能把没有权限的页面显示成可用。本文标为“当前版本暂不可用/尚未完成”的内容，请不要拿来做正式业务。

开始前：后台配置与业务接入

从第一次使用登记“示例公司（example-company）→ 工作项系统（work-items）→ 测试环境（test）”。这些名称是演示值，已有记录时先核对再选用。

只有后台时，可以登记对象、发送已配置的邀请、保存和模拟权限。要验证员工访问真实工作项，需要应用开发者提供已接入的业务地址和两条测试数据；要验证机器调用，需要服务提供方部署服务。不要把策略模拟或一条保存提示当作业务访问已经接通。

客户主体用于独立公司或客户隔离，不是公司部门。应用用户按应用隔离，测试/生产环境主要用于区分后端调用身份等接入配置，不承诺同一应用的账号按环境建立两个目录。

给两名员工开通账号并分配工作项权限

下面使用现有独立工作项示例。管理员、员工和开发者各完成自己的步骤：

1. 运维准备入口。 提供工作项系统的账户门户和业务地址，确认认证部署配置可用。邀请方式还需配置邀请 HTTPS 入口和消息发送；开放注册则由应用负责人决定是否启用。准备缺失时先交给运维，管理员不填密钥。
2. 管理员开通账号。 在 用户邀请 选择工作项系统，填写小林实际邮箱，接收方式选邮箱，有效小时填 24，初始用户组可留空，发送邀请。小周也发送一份独立邀请。未配置邀请时，可在获准的测试应用开放注册，让两人从门户注册；不能靠后台新建身份得到密码登录账号。
3. 员工设置密码并登录。 小林从自己的邀请设置账号 xiaolin、显示名称“小林”和符合密码要求的新密码；小周使用 xiaozhou。联系方式填写两人的实际地址，不复制演示地址。两人登录各自应用门户，确认工作项系统名称。密码不交给管理员。
4. 开发者给管理员配置单。 业务资源名称“工作项”、代码 standalone_work_item；所有者字段 owner_identity_id、组织字段 organization_id；动作 work_item.read（查看）和 work_item.close（关闭）。这些字段来自示例的实际业务表，其他应用须由开发者提供，不能照抄。
5. 管理员登记权限。 在 角色 新建“工作项操作员”，代码 operator；在 身份角色 为小林授予此角色，小周不授予。在 业务资源 按上一步配置单登记工作项，随后在 业务动作 登记并发布查看、关闭两个动作。
6. 管理员发布两条允许策略。 每条选择工作项系统、工作项资源、角色“工作项操作员”，授权效果“允许”；业务动作分别填 work_item.read 和 work_item.close。生效条件留空表示不额外限制请求条件。数据范围按下一段填写，分别保存并点击“发布”。不需要专门建立拒绝策略来证明小周无权：没有有效允许策略时默认拒绝。
7. 开发者登记业务接口。 按独立示例的接入登记表登记 API、动作和路由，接通登录令牌与真实对象授权，并提供两条工作项地址。后台管理员无需编写 SDK。
8. 员工验证。 小林查看自己的工作项应成功；查看另一个所有者的工作项应被拒绝。小周查看同一工作项应被拒绝。若业务示例只有 HTTP 入口，由开发者用两人授权的测试登录执行请求并展示结果；不得声称已有员工可点的业务列表。
9. 管理员撤权并复查。 撤销小林的角色关系或策略，重新访问刚才的工作项应被拒绝；在访问审计按应用、操作时间核对，详细请求编号由开发者关联。需要恢复时重新授予角色或发布策略，再验证访问；旧会话失效时须重新登录。

静态所有者范围怎么填： 由开发者确认此公司实际组织编号和小林实际身份编号；后者可从小林授权的测试登录结果 identity.id 取得。两条策略的数据范围都添加“等于”条件：字段 organization_id，类型选数字，值为实际组织编号；字段 owner_identity_id，类型选数字，值为小林实际身份编号。例如仅当实际编号确认为 42、101 时才填这两个数字。不要把“示例公司”的名称、用户名 xiaolin、字符串 "101" 或文档演示编号替代真实数值。

这是给小林本人固定范围的例子；同一角色的其他成员会受到相同范围限制，不是“自动按当前用户”计算的规则。为多人配置各自范围时，可按已确认身份分别设置直接身份策略，避免把一人的编号授给整个角色。

只看本部门怎么办： 本示例没有部门表或部门字段，也没有动态“当前用户部门”的替换规则。业务系统必须先维护可信的员工/工作项部门关系，向 SandIAM 提交相应事实，并实现列表查询、分页与直接访问的一致范围控制。由开发者确认支持方式后再提供管理员配置单；不能把客户主体当部门，也不能只在表单里编一个 department_id 就认为已生效。

第一次使用：客户主体 → 应用 → 环境

1. 创建客户主体

去 客户与应用接入 → 客户主体，点击“新建”。填写名称、系统代码和状态。系统代码是给系统稳定引用的短代码，创建后通常不能修改。

点击保存后，列表中应出现名称、状态和系统代码。打开详情确认没有选错归属。停用前先处理下属应用和授权；恢复时从同一条记录启用，不要重复新建。

2. 创建接入应用

去 客户与应用接入 → 接入应用，点击“新建”。选择刚才的客户主体，填写应用名称、系统代码和状态。保存后确认所属客户主体正确。应用代表一个产品或系统，不代表某个员工。

3. 创建应用环境

去 客户与应用接入 → 应用环境，选择接入应用，填写“开发”“测试”或“生产”等环境名称和系统代码。保存后应能从应用详情进入该环境。测试环境的用户、凭证和授权不要直接复制到生产环境。

七条完整操作链

每条链都按“设置 → 保存确认 → 允许/拒绝验证 → 查看审计 → 撤销或恢复 → 清理演示数据”完成。源码和页面名称已经按下面的路径组织；标注“尚未完成”的部分不要当作正式可用功能。

第一条：客户主体、应用、环境

1. 在 客户与应用接入 中按上节顺序创建三层记录。
2. 保存后分别打开详情，确认名称、系统代码、所属关系和状态。
3. 修改名称或状态后刷新列表，确认新值仍在；停用后尝试新建下属授权，结果应被拒绝。
4. 重新启用记录，再确认可以继续管理。
5. 在 访问审计 中按对象和时间查看创建、修改、停用、恢复记录。
6. 清理演示数据时，先撤销下属授权和凭证，再停用或删除最下层记录，最后处理应用和客户主体；不要删除审计记录。

第二条：用户、角色、资源与策略

先按上面的工作项例子选择邀请或注册，开通可登录账号；已有企业账号才配置身份源与协议。后台新增身份仅建档，本地密码需员工在邀请或注册过程中设置。

1. 在 应用用户 按应用查看已开通员工，核对名称与状态。人员多时可建用户组，邀请时选初始组，或从组成员页加入已有用户；组不是公司部门的自动数据权限。
2. 在 角色 定义业务职能，再从 身份角色 授予用户或组。角色与业务资源的代码由应用负责人和开发者约定。
3. 在 业务资源、业务动作 使用开发者提供的配置单；动作发布后与业务 API 保持一致。不要用菜单名称、HTTP 方法或自行编写的字段代替。
4. 在 策略 选择角色或指定应用用户，两者二选一；选择资源、动作及允许/拒绝效果。按技术负责人提供的字段和值设置条件及范围，数值字段选择数字类型；保存后发布并确认已启用。空数据范围不添加额外记录过滤，不能代表“本部门”。
5. 在 策略模拟 用同一应用的身份、资源、动作和可信测试属性查看结果。模拟用于解释配置，不会登录用户、执行业务请求或产生调用审计。
6. 从实际业务系统用允许用户和无权用户访问，由开发者关联业务结果与访问审计。移除角色/组关系后若仍允许，核对直接身份策略、其他角色和用户组来源，再撤销确需收回的授权。

用户导入、导出和目录同步是批量/外部目录场景的可选流程，不是开通两名本地员工的前置条件。目录同步问题见排障指南，外部目录、邮件/短信及真实页面是否可用须以当前部署验证。

第三条：认证、登录、会话、MFA 或通行密钥

1. 后台去 认证与会话 → 认证设置，选择应用，设置注册开关、密码要求、失败锁定和验证码开关，保存后刷新查看当前值。
2. 应用用户必须从接入应用自己的登录入口注册或登录；后台只负责设置和查看可管理的安全信息。
3. 用户登录后，在应用用户入口查看自己的会话；撤销指定会话后再次访问，应该重新登录。
4. MFA/TOTP、恢复码和通行密钥由应用用户在应用入口完成绑定、验证和撤销。恢复码、种子和密钥只显示一次。
5. 后台可查看应用级设置和审计；不能代替用户点击登录、读取用户密码、读取恢复码或伪造通行密钥。
6. 在 访问审计 核对登录、失败锁定、MFA 绑定、会话撤销等记录。清理时先撤销会话和认证器，再停用演示用户。

当前版本暂不可用/尚未完成： 真实宿主 HTTP、浏览器 Cookie/会话、验证码供应商和标准客户端互操作尚未完成验收。源码有相应后台和应用入口，不等于当前部署已经可用。

第四条：调用身份、服务授权、凭证和调用

先取得服务提供方的配置单。下面对应现有文档处理服务与调用方，它不是 SandAI；这些值只有在该示例已部署并登记服务目录后才可用于调用：

配置项	本例填写值	来源/填写位置
公司、应用、环境	示例公司 / 工作项系统 / 测试环境	选择实际已登记记录
调用身份名称 / 代码	工作项系统测试后端 / backend	应用技术负责人约定，在服务调用身份页填写
受众	provider-b	服务提供方给出，在调用身份和服务授权两处保持一致
服务代码 / 服务动作	provider-b-document / document.process	服务提供方登记目录，管理员按服务/动作名称选择
目标服务地址	已部署 Provider 的 HTTPS 地址	服务提供方提供；不是受众
凭证名称	工作项系统测试调用	管理员约定，便于识别归属
文档编号	该公司的一条实际测试文档编号	服务提供方从业务数据确认，不猜文档 ID

1. 去 客户与应用接入 → 服务调用身份，选择环境，填名称、代码和受众。
2. 去 服务授权，重新核对当前公司、应用、环境和调用身份，选择上述已登记服务动作，受众填 provider-b。未看到服务或动作时让服务提供方检查目录，不用其他相似动作代替。有效期按测试需要设定；数据等级、额度和网络限制由服务提供方说明，不能猜格式。
3. 去 调用凭证 为该身份签发，核对凭证名称与过期时间。一次性明文仅交给该应用测试环境的技术负责人保存到受控密钥库，交接时同时说明公司、应用、环境、身份、受众、服务动作和目标地址；普通员工不使用这个凭证。
4. 技术负责人按照Provider 调用步骤注入配置并处理一条实际测试文档。成功须能看到业务处理结果；再用没有该动作授权的测试身份或错误受众请求确认拒绝。
5. 管理员撤销刚签发的凭证，技术负责人再次请求，应被拒绝且不新增处理结果。双方在访问审计和业务服务记录中核对同次操作；仅验证短期上下文并不证明业务处理成功。
6. 需要继续调用时重新签发并更新应用运行配置。旧凭证永久失效，不能恢复。撤销服务授权后须按需要重建授权；恢复用户或身份不自动恢复凭证、授权或旧会话。

如果签发或轮换结果不确定，先核对凭证列表与密钥库，不反复点击。明文已丢失时由有权管理员轮换或重新签发，并完成新凭证交付和调用复查，不要求页面回显旧值。

第五条：业务动作、接口目录、路由清单和策略模拟

1. 去 接口与访问控制 → 业务动作，为应用登记稳定的业务资源和语义动作。代码发布后不能改；需要改时新建并停用旧动作。
2. 少量接口可去 接口目录 手工登记名称、应用、资源、动作、操作类型、版本、受众和风险。已有 OpenAPI 3.0/3.1 JSON 时，在 路由清单 → 导入 OpenAPI 接口目录 选择导入包；每个接口都要明确映射到现有资源和已发布动作。页面的“填入完整示例”可生成字段齐全的导入包；字段表、可复制 JSON 和三套 SDK 调用方式见OpenAPI 接口目录导入。
3. 手工登记时去 路由绑定 绑定请求方法和路由模板。OpenAPI 导入会同时维护来源为 openapi 的绑定。变更方法或模板时重新预检，不要把 URL 本身当成权限名称。
4. 在 路由清单 先做变更预检，确认新增、修改、停用项，再点击确认保存或确认导入。存在未映射接口、资源/动作缺失或归属冲突时不能继续。
5. 去 策略模拟 查看后端给出的允许/拒绝及原因，再由应用发起实际调用，核对调用结果与审计是否一致。
6. 清理时先撤销策略，再停用接口、路由绑定和业务动作；不要删除原审计。

OpenAPI 原始文档不会保存。导入包不要包含密码、令牌、客户端密钥或真实凭证。预检页面显示“已保存”或“已导入”前，不要对外宣称规则已生效。

第六条：管理委派和越权检查

1. 平台管理员去 管理范围 → 客户主体管理委派，选择后台管理员和客户主体，保存后查看状态。
2. 客户主体管理员去 管理范围 → 应用管理员委派，选择后台管理员和接入应用，保存后查看所属应用。
3. 让被委派管理员重新登录，只打开自己被授予的范围，创建或修改一条允许范围内的记录。
4. 再让其打开另一个未授权客户主体或应用，确认页面不显示或操作被拒绝；把拒绝时间和对象记下。
5. 平台管理员在 访问审计 中查看委派、允许操作和越权拒绝记录，撤销委派后再次验证该授权来源已失效。客户主体委派和独立应用委派可以同时存在：撤销前者不会移除后者；要收回某应用的全部委派管理范围，需核对两种来源。
6. 清理时先撤销应用委派，再撤销客户主体委派；保留审计记录。

委派创建、更新和停用与成功审计一起提交，审计失败会回滚该次变更。请求超时后先重新查询委派状态并核对请求号审计。后台菜单是否可见还受宿主角色权限控制，菜单显示与 SandIAM 管理范围应分别检查；越权拒绝测试应使用被委派的普通管理员账号。

当前版本暂不可用/尚未完成： 三类真实后台角色、宿主登录和浏览器越权验证尚未完成，不能把静态页面或单次接口返回当成委派闭环通过。

第七条：事件订阅、成功投递、失败重试和审计

1. 去 事件通知 → 事件订阅，选择应用，填写通知名称、HTTPS 接收地址和事件范围。密钥只显示一次。
2. 保存后回到列表，确认应用、地址摘要、事件摘要、密钥状态和启用状态。
3. 触发一次受控的用户或权限变化，去 投递记录 按应用和状态查看结果、尝试次数和错误码。详情显示接收端 HTTP 状态；没有响应状态时先排查连接或签名准备阶段。查看投递记录不要求同时拥有通知配置列表权限；通知名称不可用时保留编号供定位。
4. 使用受控接收端制造一次失败；仅对等待或最终失败记录点击“重试”。“已重新排队”只确认重试任务已保存，不表示接收方已经收到消息；重新加载确认最终结果和尝试次数。若排队成功但刷新失败，先重新加载列表，不要反复点击重试。
5. 在 访问审计 对照订阅保存、触发、投递、失败、重试和最终结果。

OIDC 后通道登出投递达到五次失败后会进入 dead，不能继续发送原令牌，因为它可能已经过期。修复 RP 接收端后，应用管理员先用 GET /app/sand-iam/admin/oauth-client/logout-delivery/index?id=<oauth_client_id>&state=dead 核对失败记录，再以新的 X-Request-Id 调用 POST /app/sand-iam/admin/oauth-client/logout-delivery/reissue，提交 id=<oauth_client_id> 与 delivery_id=<dead_delivery_id>。SandIAM 保留原 dead 记录，签发带新 jti 和有效期的 logout token，并创建一条 pending 后继任务；同一原记录的并发或重复恢复只会得到同一后继。客户端、所属应用或主体已停用、后通道地址已移除，或原会话并非已撤销状态时，接口关闭失败。列表与审计不会返回登出令牌或其密文。 6. 清理时停用订阅；当前管理接口不提供独立的通知密钥撤销操作。不要把接收地址或密钥写入公开记录。

当前版本暂不可用/尚未完成： 真实 HTTPS 接收端、并发投递 worker、真实事件生产者和宿主页面验收尚未完成。保存通知配置不等于接收方已经收到消息。

看审计、撤销和清理演示数据

审计怎么查

打开 审计与排错 → 访问审计，先按客户主体、应用、动作和时间缩小范围，再打开详情。列表没有记录只表示当前筛选范围为空，不代表系统没有记录。详情、导出和归档入口需要对应权限；没有权限时不要通过其他页面猜测结果。

通用撤销顺序

遇到人员离职、凭证泄露、应用停用或测试结束，按以下顺序处理：

1. 撤销会话、MFA/通行密钥或调用凭证；
2. 撤销策略、角色关系、服务授权或管理委派；
3. 停用用户、调用身份、环境、应用或客户主体；
4. 刷新页面并再次做一次访问或调用验证；
5. 在审计中确认撤销及后续拒绝记录。

清理演示数据

演示记录可沿用本页的“示例公司”“工作项系统”“小林/小周”，只处理本次实际创建的记录。清理时只处理带有明确演示标记、系统代码或本次操作时间的记录：

1. 先撤销凭证、服务授权、策略、角色关系、管理委派和通知；
2. 再移除组成员、撤销邀请、停用演示用户和调用身份；
3. 按环境 → 应用 → 客户主体的顺序停用或删除演示对象；
4. 回到审计确认撤销和清理动作，审计证据不要删除；
5. 看到无法确认归属的记录先停下，不要批量删除。

故障排查：看到什么—可能原因—怎么处理

看到什么	可能原因	怎么处理
页面显示 404	菜单、动态路由、权限或页面版本不同步；也可能当前版本尚未发布该页面	先刷新并重新登录；从 SandIAM 总览进入；仍是 404 就记录页面地址和账号范围，交给平台管理员，不要手动拼地址
页面底部内容看不到、按钮被挡住	窗口太矮或页面滚动区域没有正确展开	使用浏览器整页滚动，缩小到 90% 临时查看；仍不能到达时记录窗口尺寸和页面名称
点击保存后刷新又恢复旧值	没有保存权限、请求失败、选项属于其他应用，或页面没有重新读取成功	查看页面提示，重新打开详情确认；不要连续重复点击；记录对象名称、时间和提示
看到“没有权限”或操作被拒绝	账号没有该菜单权限，或超出客户主体/应用管理范围	联系平台管理员确认角色和管理范围；不要借用他人账号，也不要把拒绝当成系统故障
列表为空	当前筛选范围没有数据，或账号没有读取范围	清除筛选并确认应用、环境、状态；仍为空时请管理员核对管理范围
保存提示与现有记录冲突	系统代码重复、归属不一致或已有同名配置	打开已有记录核对名称、代码和归属；修正表单，不要重复创建
凭证、恢复码或密钥找不到	这类敏感内容只显示一次	立即轮换或重新签发，旧值按泄露处理；不要要求系统回显旧明文
保存通知后没有收到消息	接收地址不可达、事件没有触发、订阅停用或投递失败	打开投递记录看错误码和尝试次数；修正接收端后只重试允许重试的记录
登录/MFA 页面打不开或登录后又退出	应用入口、会话、验证码或外部身份源未完成配置	先确认应用侧登录入口和应用状态；后台只能检查设置和审计，不能代替应用侧登录

当前版本的验收清单

逐项打勾；没有真实证据就留空：

• 客户主体、应用、环境已创建，并验证过修改、停用和恢复。
• 用户、组、角色、资源、策略各有一条允许和一条拒绝验证。
• 会话撤销后再次访问被拒绝；MFA/通行密钥在应用入口完成验证。
• 正确调用成功、无权调用被拒绝、凭证撤销后旧凭证失效。
• 接口目录和路由清单经过预检，实际调用结果与审计一致。
• 被委派管理员只能操作授权范围，越权操作被拒绝并留下审计。
• 通知成功投递、失败重试和最终记录均可查。
• 演示数据已按反向顺序清理，审计记录仍保留。
• 以上结果在真实宿主和实际浏览器中复核过，而不是只看构建、静态页面或单次保存提示。

本文中的检查项只有在目标环境取得真实结果后才能勾选。静态检查、构建成功或页面存在都不能替代安装、浏览器、协议和业务调用证据。

相关入口：第一次使用 SandIAM。

文档首页 · 迁移前历史说明