History 073 Administrator guide

历史文档：保留迁移前已公开内容，适用其正文声明的版本。当前候选说明见 Administrator-guide。

SandIAM 手把手使用说明

适用于 SandIAM 0.7.3 源码候选；安装兼容性与真实操作结果须在自己的隔离环境确认。当前候选尚未形成正式发行，发行状态见版本与兼容性。

写给第一次接触 SandIAM 的人。本文只讲“在后台哪里点、填什么、保存后看什么、出问题怎么办”。SandIAM 是通用的身份与访问管理工具：它把客户主体、接入应用、环境、应用用户、权限、系统调用和审计记录放在清楚的范围里，帮助你回答三件事：谁可以进入、谁可以做什么、出了问题如何查到并撤销。

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

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

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

后台能做的事：

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

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

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

十分钟快速体验

下面的名字只是演示记录值，不是产品要求。你可以替换成自己的名称：

项目	演示填写值
客户主体名称	示例客户主体
接入应用名称	订单中心
应用用户或测试对象	示例用户
系统代码	demo-org、demo-app、test

1. 登录 SandAdmin，打开 SandIAM 身份与访问，再打开 第一次使用。
2. 依次创建“客户主体”“接入应用”“应用环境”。名称按上表填写；系统代码使用小写字母、数字和短横线，保存后不要随意改动。
3. 回到页面确认三项都显示为已设置，并点开记录核对所属关系：客户主体 → 接入应用 → 应用环境。
4. 打开 应用用户与权限，选择“订单中心”（演示值），创建一个应用用户、一个用户组、一个角色和一个业务资源。
5. 在策略页建立一条允许策略，再建立一条明确的拒绝场景；发布后进入 策略模拟，分别查看允许与拒绝的后端结果。
6. 打开 访问审计，按应用和时间筛选，确认创建和发布记录可查。策略模拟是只读解释，不写审计；再从接入应用发起一次真实允许和一次真实拒绝请求，按各自的 request ID 核对授权审计。
7. 撤销刚才的策略或停用演示用户，再次模拟，确认结果改变；最后按“清理演示数据”删除或停用本次记录。

若页面、菜单或保存结果与本文不同，先看故障排查。 若入口缺失、页面报错或步骤无法继续，请记录版本、页面地址、操作时间和脱敏错误信息，不要手动拼地址或绕过权限。

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

1. 创建客户主体

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

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

2. 创建接入应用

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

3. 创建应用环境

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

七条完整操作链

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

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

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

第二条：身份源、用户、组、角色、资源、策略

1. 去 应用用户与权限 → 身份源，选择应用，填写身份源名称、范围和必要标识。密钥只在保存时提交，页面只显示“已配置”。
2. 去 应用用户 创建或绑定一个应用用户；批量导入时先到 用户导入导出 预检，确认没有错误行后再确认导入。
3. 去 用户组 创建组，在成员页添加用户；需要邀请时去 用户邀请，填写接收地址，保存后列表只显示脱敏目标。
4. 去 角色 创建角色；去 业务资源 登记应用真正要保护的资源。
5. 去 身份角色 给用户或组授予角色；去 策略 选择主体、资源、动作和允许/拒绝效果，保存后点击“发布”。
6. 打开 策略模拟，选应用用户、资源和动作。分别准备一个允许条件和一个不满足条件，查看页面返回的允许/拒绝结果及原因。
7. 在 访问审计 确认用户创建、组关系和策略发布记录。策略模拟本身不写审计；从接入应用发起真实调用后，再按 request ID 核对允许或拒绝审计。撤销角色或策略后重新模拟，确认结果已变为拒绝。
8. 清理时按反向顺序撤销策略、角色关系、组成员、邀请和身份；保留审计记录。导出完整联系方式需要单独权限和二次确认。

若应用启用了目录同步，在 用户同步 → 目录同步连接 查看运行记录和出站记录。出站事件达到最大尝试次数后显示为 failed；先修复对端、连接配置或限流，再只对该条事件点击“重新排队”。系统会拒绝跨应用事件、非 failed 事件及与正在运行的同步任务并发的重试，并在审计中记录 sync.outbox_retry。不要直接修改 outbox 表、尝试次数或密文载荷。

当前版本暂不可用/尚未完成： 外部目录真实同步、真实邮件或短信发送、批量导入的真实宿主页面和浏览器验收尚未完成。页面若显示“进入页面确认”或“暂时无法读取”，请不要据此判断同步已经成功。

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

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

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

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

1. 去 客户与应用接入 → 服务调用身份，选择应用环境，填写后端服务名称。它代表机器或后端程序，不代表员工。
2. 去 服务与动作 查看服务提供方发布的服务和动作；只选择实际需要的动作、服务受众、有效期、数据等级和网络限制。
3. 去 服务授权 将动作授给调用身份，保存后核对环境、动作和约束。
4. 去 调用凭证 点击“签发”。明文只显示一次，应立即交给应用负责人放入受控密钥库，不要写入聊天、截图、工单或代码仓库。
5. 由接入应用发起一次正确调用，再发起一次无授权或错误受众调用。正确调用应允许，错误调用应拒绝；两次结果都要能在审计中对应。
6. 回到 调用凭证 撤销凭证，再次调用确认旧凭证失效；需要继续调用时重新签发，不要恢复已撤销的凭证。
7. 清理时先撤销凭证，再撤销服务授权，最后停用调用身份；审计记录保留。

当前版本暂不可用/尚未完成： 真实业务服务、真实服务提供方、宿主 HTTP 和外部调用的完整验收尚未完成。仅看到凭证已签发，不能证明调用成功。

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

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。

---

文档首页 · 排障