uipath-admin

UiPath Admin

通过 uip admin 执行 Identity Server、Authorization、OMS、IP Restriction 和 Audit 管理操作。

适用场景

• **Identity：**用户、群组和成员关系、机器人帐户、外部应用和凭据、PAT、SMTP、OAuth2 作用域发现，以及人员或机器人的入职。
• **Authz：**自定义角色、分配、权限目录、有效访问权限和临时授权。角色作用域为 Organization、TenantGlobal、Tenant 和 Project；分配也可以使用 Folder 或 App。
• **OMS：**当前组织、租户生命周期、服务预配、操作轮询和区域发现。CLI 无法创建或删除组织。
• **IP Restriction：**允许列表条目、强制执行、绕过规则，以及用于查询公网 IP 和安全检查的 ip-restriction my-ip。
• **Audit：**组织或租户审计事件、来源、目标、类型、查询、登录历史、成员关系/许可证活动、租户活动、调查和导出，请使用 uip admin audit，不要使用 uip or audit-logs。uip or audit-logs 用于 Orchestrator 运维审计，属于 uipath-platform。
• **Audit exclusions：**对于阻止审计跟踪记录匹配事件的规则，请使用 uip admin audit org exclusions——例如“停止/抑制/静默记录这些事件”、“我们的审计跟踪噪声太多”、“我们没有记录哪些事件”，或任何列出/获取/创建/更新/删除排除规则的请求。仅限组织作用域。每次写入都会抑制证据，因此请遵循 audit-exclusions-guide.md 和规则 30b–30e。
• **故障排查：**针对访问、身份验证、身份、租户操作、预配、机器人身份验证、SMTP、PAT、外部应用或 IP 锁定问题，请使用诊断能力索引和身份故障排查指南。

要查看审计是否可用，请运行 uip admin audit <scope> sources；应发现实时目录，而不是依赖记忆。请通过 audit-workflow-guide.md → 审计作用域判定 和规则 23，在 org 与 tenant 之间选择作用域。自然语言调查可以涵盖资源变更/删除、登录、租户变更、合规时间窗口和跨作用域请求；对每个请求的作用域分别运行一次，然后合并结果。

故障排查路径：拒绝访问 — 403、“角色未生效”和跨服务角色混淆属于同一场景 → 解析主体、检查有效访问权限、查找所需权限，然后根据权限缺失还是授权作用域错误进行后续处理（操作手册 1，故障模式 → 拒绝访问）；可疑登录 → 组织审计（操作手册 2）；IP 锁定 → my-ip、范围和强制执行（操作手册 3）；PAT/外部应用故障 → 过期、作用域和撤销审计（操作手册 4）。SMTP 使用 smtp get 和 smtp test；轮询卡住的租户操作；对于预配无操作，请检查平台固定的服务；区分机器人身份问题与凭据模型问题。

关键规则

每条规则都是 Agent 合约的一部分。

通用

1. 正确路由： Orchestrator 特定的角色／权限请求应发送至 uip or roles（uipath-platform），而非 uip admin authorization。组织／租户审计始终使用 uip admin audit <scope>（sources、events 或 export），绝不使用 uip or audit-logs，包括审计历史记录、导出、登录历史记录、合规性数据转储，以及“谁在何处做了什么”。
2. 先验证登录状态： 运行 uip login status --output json。如果未通过身份验证，请停止并让用户运行 uip login；该命令会打开交互式浏览器流程，不得在自动化／非交互式会话中运行。通过环境进行身份验证的会话已处于登录状态。根据活动会话确定组织。
3. 每条命令都使用 --output json。 以编程方式解析，并以对话方式呈现。
4. 遇到错误时停止并原样显示。 绝不重试身份验证失败；请让用户运行 uip login。
5. 执行高风险操作前解析具名主体： 用户、组、机器人账户和外部应用，包括创建／删除分配、删除用户／组、更改成员资格、删除机器人、删除外部应用以及生成密钥。先搜索并回显 Principal: <displayName> (<userName>) — <id>。匹配数为零：停止并询问用户。存在多个匹配项：显示编号列表并等待用户输入数字。绝不使用当前登录用户代替。请参阅解析主体 ID。

身份

6. 创建前先发现： 先列出机器人账户、组和外部应用；用户邀请除外。
7. 外部应用创建和 generate-secret 只显示一次密钥，并告知用户立即保存。
8. 外部应用需要创建作用域： --app-scope 或 --user-scope，例如 --app-scope "OR.Folders"。
9. 组成员资格使用用户 ID： 按规则 5 解析用户，然后使用 groups members add/revoke。
10. 在解析目标后确认删除用户、组、机器人账户和外部应用。内置组（type: "BuiltIn"）无法删除；只有 Custom 组可以删除。

Authz

11. 内置角色为只读。 只能创建、更新和删除 Custom 角色。CLI 会拒绝服务管理或平台级角色的编写操作；请参阅 管理自身角色的服务。
12. roles create/update 是 PUT 式 upsert。 根据标志和 --file ./actions.json 构建请求正文；更新前务必先执行 roles get，因为未指定的标志会覆盖相应字段。
13. --service 会推断范围（例如，studio → Tenant，apps → Organization）；仅在需要覆盖时使用 --scope。切勿猜测 serviceName——有效值及重新推导命令见：permission-catalog.md → serviceNames。
14. 列表支持所有服务；角色编写操作不支持。 roles list --service <svc> 和 roles assignments list --service <svc> 接受所有服务。使用 check-access 检查有效访问权限。
15. 范围词汇各不相同： roles create --scope = Organization|TenantGlobal|Tenant|Project；创建分配时还支持 Folder|App；列出分配时不包括 TenantGlobal；check-access --scope 仅支持 Tenant|Folder。
16. 创建/删除分配需要根据规则 5 解析主体；--identity-id 是未经检查的原始 UUID。
17. 分配的所有权必须与范围路径一致： 路径中的服务段为 lowercase(ownerServiceName)，须逐字取自该角色自身的 roles get——DocumentUnderstanding → /tenant/<tid>/documentunderstanding。CentralizedAccess 没有服务段（/ 或 /tenant/<tid>）。切勿用同级服务的段替代，也切勿从其他角色的授权中复制服务段：Reinfer（显示名称为 IXP）不是 Document Understanding。显示名称映射仅适用于面向用户的文本，不适用于路径。若不匹配，请使用 --service <slug> 或 --scope-path "/tenant/<tid>/<slug>" 重新创建分配；Tenant 范围的角色不带项目段。请参阅验证角色的所属服务。 17b. 范围错误的授权不会显示在默认列表中——使用 --scope-path 检索。 roles assignments list 会根据标志同时固定范围路径和 serviceName，因此，在裸 /tenant/<tid> 路径上授予的 <svc> 所有角色不会匹配任何默认形态：它不会出现在裸路径列表中，也不会出现在 --identity-id、--scope Tenant（无论是否带 --include-inherited）或 --service <svc> 的结果中。请使用 roles assignments list --scope-path "/tenant/<TENANT_ID>" --output json 检索，不要指定 --service。切勿把空列表当作授权不存在的证明，也不要据此重新创建分配——那会重现原始不匹配。请参阅访问被拒绝 → 原因 B。

OMS

18. 异步生命周期：自动轮询，然后移交处理。 租户创建/更新/删除/启用/禁用操作会返回 operationId；每隔五秒轮询一次 organizations operation get <OP_ID>，共轮询三次，遇到终态即停止；如果仍在进行中，则显示一个编号菜单。切勿无限循环。Organizations 创建/删除操作无法通过 CLI 执行，需使用 Portal/联系支持。请参阅轮询流程。
19. tenants delete 仅执行软删除。 恢复需要联系支持；不存在硬删除标志。
20. 租户命令默认针对登录租户。 对于租户删除/禁用和 tenants services remove，始终显式提供 <TENANT_ID>。
21. 创建租户前先确定区域： 先运行 organizations regions list，因为 --region 为必填项且与区域相关。
22. 禁用/移除服务可能会错误地报告 Success。 之后务必重新列出。请参阅租户概念。

Audit

23. 查询前先区分 org 和 tenant。 如果范围含糊，且之前的对话没有明确范围，请先提出一个澄清问题；如有 AskUserQuestion，则使用它；不要默认选择某个范围。如果无法进行交互式澄清，则查询两者并合并结果。范围由位置决定：uip admin audit org sources 或 uip admin audit tenant events；--scope 无效。请参阅 审计范围消歧。
24. 事件返回 {auditEvents, next, previous}，而不是纯数组。读取 Data.auditEvents[]；next 表示更新的事件，previous 表示更早的事件，按从最新往回遍历时应沿着 previous 继续。
25. --limit 会在内部进行分页。 不要通过循环日期来分页。每次服务端请求的数量会限制在 [10, 200]；CLI 限制最高为 10000。--limit 必须在 [1, 10000] 范围内；超过 10000 时会返回 Result: "ValidationError"。若要获取“全部”结果，请省略此参数或将其设为范围内的值。
26. 先运行 audit <scope> sources。 切勿臆造来源、目标或类型 GUID；请使用实时目录中的 GUID。响应也可用于回答可用性问题。
27. 使用 UTC ISO 8601 格式限定事件时间范围。 查询嘈杂的租户时，必须指定 --from-date 和 --to-date。可接受仅日期或时间戳格式，例如 2026-04-01T14:30:00Z。--to-date 包含该精确时刻；若要覆盖完整的最后一天，请使用次日零点或 T23:59:59.999Z。使用实际 UTC 时间（date -u）计算相对日期，切勿猜测，并回显时间范围。 27b. 针对目标的查询结果为空，即表示查询已完成。 请说明未找到匹配事件，并列出范围、筛选条件和时间范围；同时可提出扩大范围、查询另一种范围或检查资源是否存在。切勿根据相邻资源、事件类型或宽泛搜索推断操作者，也切勿仅为找到责任人而放宽筛选条件。只有匹配事件同时支持所请求的资源和操作时，才可指出操作者；请引用 createdOn 和用于识别的 eventDetails。请参阅 步骤 5。
28. 对 org 审计，--tenant-id 会被忽略。 请改用 audit tenant。
29. 审计返回 401 时，不要重试。 令牌缺少 Audit.Read；请告知用户运行 uip logout && uip login。 29b. 审计出现暂时性 5xx 错误时（ErrorCode: server_error / Retry: RetryLater，例如 503/504），请使用完全相同的查询，间隔数秒后最多再重试两次。不要更改限制或时间范围。切勿将错误信封作为数据呈现或保存；请报告检索失败。
30. 导出需指定基础目录和完整 UTC 日期。 必须提供 --from-date、--to-date 和 --output-path。日期是包含首尾的日历日期；不要使用事件查询的次日技巧。--output-path 是目录，不是文件名或扩展名；CLI 会在其中创建 audit_<from>_<to>_<generated-at>。默认 JSON 格式会按天创建 <YYYY-MM-DD>.json；--file-format csv 会创建一个合并后的 CSV。平面表格请使用 CSV，按天存储的文件请使用 JSON。对于用户指定的目标路径，请原样传入，无需确认；仅当选择默认路径（例如 ./audit-exports）时才需确认。请报告 Path 和 GeneratedAt。 30b. 排除规则的作用范围是组织，且规则必须有所约束。 使用 uip admin audit org exclusions <list|get|create|update|delete>；没有 audit tenant exclusions——要将规则限定到租户，请改用 --exclude-tenant 选择器。每个维度只能使用一个选择器：--exclude-tenant、--source、--target、--type（均可重复）以及 --status（单值，为 Success 或 Failure）。租户选择器是 --exclude-tenant，绝不能用 --tenant-id——在读取命令中，该标志表示“针对此租户运行”，此处不适用。同一选择器中的值按 OR 关系组合，多个选择器按 AND 关系组合。至少需要一个选择器，因为不约束任何内容的规则会排除组织中的所有事件；绝不要通过创建此类规则来满足含糊的“消除审计噪声”要求。使用 audit org sources 查找选择器 GUID，绝不要自行编造（规则 26）。enforcement 不是标志——唯一可用的值是 Exclude。规则名称不能是纯 GUID。请参阅 audit-exclusions-guide.md。

30c. 每次写入排除规则都会抑制证据——请先说明影响并取得明确确认。 在执行 create、update 或 delete 之前，请将规则的选择器映射为 audit org sources 中的名称（绝不能只显示 GUID），并说明：规则生效后即开始排除，且不会追溯生效；已记录的事件不受影响；此后被抑制的事件无法恢复，因为删除规则只会恢复记录，不会补回这段空缺。等待用户确认。绝不要将规则的范围扩大到超出用户要求；绝不要为了绕过 RuleLimitExceeded 或 OverlappingRuleExists 而删除并非由你创建的规则；也绝不要连续执行写入——创建一条规则，用 exclusions get 验证，报告 PolicyId 和 ActivatedOn，然后停止。

30d. exclusions update 是完整替换，而非增量修改——并且会重新激活规则。 get、update 和 delete 接受一个 <rule> 位置参数，可使用规则的名称或其策略 ID；优先使用用户提供的名称，并将 <rule> 放在选择器标志之前，因为这些标志可接受多个值，否则会将 <rule> 解析为另一个值。先运行 exclusions get "<RULE>" --output json，然后重新传入规则应保留的所有选择器——省略的字段会被删除，因此仅使用 --name 重命名会移除规则的选择器。**激活状态也是替换内容的一部分：**不加 --inactive 时，规则会恢复为启用状态，因此替换原本刻意设为待启用的规则会开始抑制事件——请检查 get 返回的 IsActive；如果其值为 false，也要再次传入 --inactive。--file 会提供整个请求体，不能与任何内联标志组合使用；请求体只能包含 camelCase 字段 name、enforcement、isActive 和 selectors（省略 isActive 时默认为 true），因此直接提交 get 响应会被拒绝：其字段使用 PascalCase，且包含由服务端管理的 policyId 和时间戳，不能通过删减响应字段来提交。若要在不中断记录的情况下替换规则，请先使用 --inactive 暂存替代规则，删除旧规则，然后激活新规则。 30e. 排除规则失败时会说明自身原因——根据 Instructions 采取行动，不要自行猜测。 拒绝信息会在 Message 中包含服务给出的原因，并在 Context.errorCode 中包含机器可读的代码（OverlappingRuleExists、UnknownSelectorValue、SelectorValueNotPermitted、DuplicateRuleName，等等）；本地 Result: ValidationError（退出码 3）表示请求从未发送到网络，因此应修正命令，而不是重试。当 <rule> 名称同时匹配一条启用规则和一条未启用规则时，CLI 会拒绝猜测——它会返回列出两个策略 ID 的 ValidationError；请询问用户要选哪一条，或传入 ID，绝不要默认选择启用的规则，因为另一条规则正是处于暂存状态的替代规则。SelectorValueNotPermitted 是有意如此——UiPath 监控事件和审计配置更改（包括对规则本身的更改）永远不能被排除；应说明拒绝原因，不要改写目标名称。unknown command 'exclusions' 表示已安装的 CLI 版本早于此功能（告知用户升级 @uipath/cli）；对 list 执行时出现 HTTP 404，表示此组织的审计服务尚未提供规则 API。这两种情况都不能通过重试解决，也都不能作为回退到 uip or audit-logs 的理由。启用的规则也会从 events 和 export 中隐藏其事件，且不会标记数据缺口——如果针对特定事件的调查没有结果，在断定该操作从未发生前，先运行 exclusions list（这能解释为何没有结果；但绝不能据此指认某位行为者，规则 27b）。

IP 限制

31. **启用强制执行前，必须进行安全检查并确认：**运行 ip-restriction my-ip，确认调用方 IP 包含在 ip-ranges list 中，然后说明：“启用 IP 限制后，源 IP 不在 ip-ranges list 中的任何调用方（Portal、CLI、机器人、外部应用）都将被阻止访问此组织。配置错误会导致你无法访问，且需要通过平台端恢复。是否继续？” 必须使用 --confirm。强制执行启用时，删除范围也需要使用 --confirm。请参阅强制执行管理。
32. **IP 锁定后只能通过平台端恢复：**使用已加入允许列表的 IP 来停用强制执行，或通过 Portal 恢复；CLI 没有绕过方式。
33. 切勿向用户展示“APMS”。 面向用户的输出中请使用“IP 限制”。

不要做的事

1. 绝不要将资源 ID 作为标志传入。 ID 和名称应作为位置参数，例如 groups members add <GROUP_ID> --user-ids ...；获取、更新、删除和创建命令也同样如此。
2. **绝不要在不注明来源的情况下展示授权结果：**角色名称、scopeType、ownerServiceName，以及使用名称而非 UUID 的租户绑定。请参阅来源信息规范。

其余规则与关键规则相反——绝不要：

• 将 uip or audit-logs 用于组织/租户审计（R1），或在范围不明确时默认审计范围（R23）；
• 将 audit events 当作普通数组处理（R24），手动循环日期来翻页（R25），臆造来源/目标/类型 GUID（R26），或在嘈杂的租户上查询不设范围的事件（R27）；
• 指定查询未返回的操作者（R27b），向 org 审计传入 --tenant-id（R28），重试 401（R29），或将错误信封保存/报告为数据（R29b）；
• 在 export 中使用次日 --to-date 技巧（R30），或使用仅包含已更改标志的 roles update（R12）；
• 使用 audit tenant exclusions，创建不含选择器的排除规则，或臆造选择器 GUID（R30b）；
• 在不说明影响并获得确认的情况下编写排除规则，或将其描述为追溯生效（R30c）；
• 向排除命令传入 --tenant-id，或重复传入 --status（R30b）；
• 使用仅包含已更改标志的 exclusions update，替换已暂存规则时省略 --inactive，将 --file 与内联标志混用，或将 get 响应重新传给 --file（R30d）；
• 重试 SelectorValueNotPermitted 拒绝，或对 exclusions 的 unknown command / 404 重试；如果 <rule> 名称含糊不清，也绝不要自行选择规则（R30e）；
• 将已配置的 services list 与 list-available 目录混淆（R22），或在运行 OMS 变更操作时未回显已解析的目标（输出规范）。

快速入门

目标	入口
邀请用户并分配组	user-management.md、group-management.md
创建自定义角色	uip admin authorization roles create --scope <Organization|TenantGlobal|Tenant|Project> --name "<NAME>" --file ./actions.json --output json
授予权限	grant-permissions.md
分配角色	解析主体；运行 roles get；验证所有者服务/路径；创建分配
检查有效访问权限	uip admin authorization check-access <USER_GUID_OR_EMAIL> --scope <Tenant|Folder> --output json
创建租户	tenant-management.md
添加租户服务	tenants services list-available --region <R>；添加；验证后置状态
查找公共 IP	ip-restriction my-ip --output json；返回 Data.ipAddress
启用 IP 强制执行	my-ip → 验证范围 → enforcement enable --confirm
查询/导出审计	audit-workflow-guide.md
停止记录嘈杂的审计事件	audit org sources → 提议并确认 → uip admin audit org exclusions create --name "<RULE_NAME>" --type <EVENT_TYPE_ID> --status Success --output json → 使用 exclusions get "<RULE_NAME>" 验证（规则 30b–30e，audit-exclusions-guide.md）
查看哪些审计事件已被抑制	uip admin audit org exclusions list --output json

核心概念

有关组织层级结构，以及用户、组、机器人账户、机器人凭据和外部应用之间的区别，请参阅 key-concepts.md。

输出规范与报告约定

区域	必需输出
身份变更	结果和新资源 ID；突出显示仅可查看一次的外部应用密钥，提醒用户保存，并提供相关的后续步骤。
授权读取/变更	响应中的角色名称、scopeType、ownerServiceName，适用时提供译名，并将租户绑定解析为名称。对于 check-access，使用嵌套的 roleAssignments[].securityPrincipalType，为每行标注 direct 或 inherited from <Group name>。请参阅来源信息约定。
OMS 读取	以 Organization: <ORG_NAME> 开头；将已预配服务及其状态与不带状态的可用目录分开列出。租户读取还应显示名称、UUID 和生命周期状态。
OMS 变更	回显已解析的目标；对异步操作自动轮询三次，间隔五秒，然后提供编号菜单；重新列出同步服务以验证状态。
审计查询/导出	说明范围、数量、已解析的 UTC 时间窗口、筛选条件和游标状态；遵守规则 23、26 和 27。报告后，等待用户选择下一步，不要串联变更操作。对于导出，报告 Path 和 GeneratedAt。请参阅审计输出规范。
审计排除项读取	规则数量和启用的规则数量；使用 audit org sources 将每条规则的选择器译为名称，绝不只显示 GUID；每条规则均显示 IsActive 和 ActivatedOn。
审计排除项写入	写入前，说明影响并获得明确确认（规则 30c）。写入后，报告 PolicyId、IsActive、ActivatedOn、停止记录的事件及生效时间；删除时，还需说明记录现在已恢复，但现有记录空缺仍会保留。提供一个后续步骤并等待；绝不串联另一次写入操作。请参阅 audit-exclusions-guide.md。
IP 限制变更	启用前，说明影响并获得明确确认；启用后，重新运行 my-ip 和 ip-ranges list，以确认覆盖范围；绝不提及 APMS。

Task Navigation

Need	Reference
Identity CLI	identity-commands.md
Users	user-management.md
Groups and membership	group-management.md
Robot accounts	robot-account-management.md
External apps	external-app-management.md
PATs	pat-management.md
SMTP	smtp-management.md
Authorization CLI	authorization-commands.md
Custom roles	role-management.md
Grant permissions	grant-permissions.md
Role assignments	role-assignment-management.md
Permission catalog	permission-catalog.md
Effective access	check-access.md
Organizations	organizations-commands.md, organization-management.md
Tenants and services	tenants-commands.md, tenant-management.md
IP Restriction CLI	ip-restriction-commands.md
IP ranges	ip-range-management.md
Enforcement	enforcement-management.md
Bypass rules	bypass-rule-management.md
Audit CLI	audit-commands.md
Audit investigations	audit-workflow-guide.md
Audit exclusion rules (stop recording events)	audit-exclusions-guide.md, surface in audit-commands.md
Audit pagination	audit-commands.md plus Rule 25
Troubleshooting	identity-troubleshoot-guide.md
Diagnostic capability index	diagnose/CAPABILITY.md
Failure modes	failure-modes.md
Diagnostic priority ladder	troubleshooting-guide.md