IFS Cloud 25R2：为 HCM 创建带 IAM Client、Service User 和 Person 的 API 账户

在 IFS Cloud 中创建 OAuth2 技术账户看起来很简单：生成 Client ID 和 Client Secret，分配几个 Permission Sets，似乎就完成了。实际上，只要该账户需要访问 HCM 数据，多个身份层就会叠加在一起：IAM Client、Service Account、IFS Service User 和 Person。我们的 UAT 环境刷新之后，这条身份链变得不一致，IFS 甚至在评估权限之前就拒绝了该账户。下面是最终在我的 IFS Cloud 25R2 环境中成功运行的配置。

01真正的问题：多条身份链同时存在

我的需求其实非常常见：创建一个可供中间件使用的技术账户，获取 Client ID 和 Client Secret，通过 OAuth2 Client Credentials 流程申请 token，然后调用 HCM 模块所需的 IFS REST API。

真正的陷阱，是以为一个“API 账户”对象能够承担所有这些职责。实际上，IFS 将它们拆分为多个层级：

外部应用
        │
        ▼
IAM Client
        │
        ▼
IAM Service Account
        │
        ▼
IFS Service User
        │
        ├── Companies
        ├── Permission Sets
        │
        ▼
Person
        │
        ▼
HCM 数据范围

每一层回答的问题都不同：

• 谁来申请 token？ IAM Client。
• 哪一个技术身份承载 token？ IAM Service Account。
• 哪一个 IFS 用户执行 API 调用？ IFS Service User。
• 允许调用哪些功能和 projection？ Permission Sets。
• 可以看到哪些 Companies 和人力资源数据？ Company 访问权限以及与 Person 关联的 HCM 数据范围。

02为什么 UAT 刷新让问题变得更复杂

在我的场景中，问题出现在 UAT 环境从生产环境刷新之后。该 API 账户之前存在于 UAT，但在作为克隆源的生产环境中并不存在。

刷新完成后，一些组件仍然存在，另一些组件只被部分重建，而 IAM 与 IFS 用户之间的关联已经不再一致。

IAM Client 存在
+
IFS 用户存在或只被部分重建
+
Directory ID 缺失、错误或关联到错误对象
=
无法获取 token 或无法运行应用

API 返回的是一个由通用代码 DB_ACCESS_ERROR 包装的错误，其中包含以下详细信息：

ORA-20105: Login.FUSRNULL:
The directory id SERVICE-ACCOUNT-... is not allowed to run the application.

很多人的第一反应是继续添加 Permission Sets。但在这个具体场景中，这样做没有任何作用：IFS 还没有进入功能权限评估阶段。它首先就无法把 IAM 身份正确解析为 IFS 应用用户。

03必须区分的四个对象

04两个创建向导带来的陷阱

IFS 提供两条创建路径，而每一条单独看起来都几乎够用。

从 Users 创建
→ IFS Service User + Person
→ 没有 Client ID / Client Secret

从 IAM Client 自动创建
→ IAM Client + Service Account + IFS Service User
→ 在我的场景中没有 Person

因此，最终采用的方法是有意将这两个操作拆开：

05能够正常工作的目标架构

IAM Client: IFS_BLUEWAY
        │
        ├── Client ID
        ├── Client Secret
        └── Service Accounts = Yes
        │
        ▼
IAM Service Account
service-account-ifs_blueway
        │
        │ 将该值复制到 Directory ID
        ▼
IFS Service User: IFS_BLUEWAY
        │
        ├── User Type = Service User
        ├── Companies
        ├── Permission Sets
        └── Create Person = Yes
        │
        ▼
Person: IFS_BLUEWAY
        │
        ▼
HCM Organization Access

06步骤 1：创建 IAM Client

在 IFS Cloud 25R2 中打开：

Solution Manager
→ Users and Permissions
→ Identity and Access Manager
→ IAM Clients

创建一个专用于该集成的客户端，例如：

IFS_BLUEWAY

对于服务器到服务器的场景，我使用的配置如下：

IFS 随后会创建一个类似以下内容的 Service Account 身份：

service-account-ifs_blueway

需要保存三项信息：Client ID、Client Secret，以及准确的 Service Account User 值。

07步骤 2：创建 IFS Service User 及其 Person

然后打开：

Solution Manager
→ Users and Permissions
→ Users

手动创建技术用户。例如：

Identity      : IFS_BLUEWAY
User Type     : Service User
Directory ID  : service-account-ifs_blueway
Create Person : Yes

最关键的字段是 Directory ID。它必须包含 IAM Client 创建的准确 Service Account User 值。

IFS Identity 的名称可以保持便于管理员阅读，但真正建立技术关联的是 Directory ID：

OAuth2 token
     │
     ▼
IAM Service Account
     │
     │ 通过 Directory ID 解析
     ▼
IFS Service User
     │
     ▼
允许的权限与数据

还需要确认该用户处于启用状态、被允许运行应用，并且类型确实为 Service User。

08为什么 HCM 可能需要 Person

中间件当然不是真实的人。但在 IFS 中，一些 HCM 授权机制依赖 Person 对象以及它与组织范围之间的关联。

因此必须区分两类控制：

因此，即使账户拥有所需的 Permission Sets，如果关联 Person 没有正确的数据范围，某些 HCM API 仍可能返回错误或空结果。

09步骤 3：分配 Companies

根据环境配置，Company 访问权限可以从以下位置管理：

Accounting Rules
→ User Related Data
→ Users per Company

将技术账户添加到中间件需要读取或处理数据的每一个 Company。不要默认授予所有 Companies，仍然应该遵循最小权限原则。

10步骤 4：分配 Permission Sets

接下来，为中间件实际使用的 REST projections 和功能分配所需的 Permission Sets。

为了更容易诊断问题，应从测试 projection 所需的最小 Permission Sets 开始，然后按功能逐步添加权限。直接分配一个非常宽泛的权限配置会掩盖真正的问题，并增加安全风险。

11步骤 5：分配 HCM 数据范围

组织结构可以从以下位置访问：

Human Capital Management
→ HCM Services
→ Organization Management
→ Graphical Organization Structure

检查技术账户对应的 Person 必须访问哪些范围。正确的设置取决于实际需求：整个组织、部分组织单元，或更受限制的范围。

完整链条如下：

IAM Client
     │
     ▼
IAM Service Account
     │
     ▼
IFS Service User
     ├── Companies
     ├── Permission Sets
     │
     ▼
Person
     │
     ▼
HCM Organization Access

12逐层测试 OAuth2 和 API

完成配置后，中间件即可使用 OAuth2 Client Credentials 流程。

Client ID + Client Secret
          │
          ▼
IFS OAuth2 endpoint
          │
          ▼
Access Token
          │
          ▼
Authorization: Bearer <token>
          │
          ▼
IFS REST projection

为了避免把多个问题混在一起，建议按照以下顺序测试：

1. 使用 Client ID 和 Client Secret 获取 token。
2. 调用一个简单 projection，该 projection 只需要少量权限。
3. 使用非 HCM 数据测试 Company 访问权限。
4. 测试目标 HCM projection。
5. 将预期结果与 Person 的数据范围进行比较。

以下是通用示例，需要替换为当前环境真实的 OAuth2 endpoint：

curl -X POST "<IFS_TOKEN_ENDPOINT>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>"

13错误诊断矩阵

下表是一套实用诊断方法，并不是 IFS 官方提供的完整错误列表。

FUSRNULL 错误：优先检查项

IAM Service Account User
            =
IFS Service User 的 Directory ID

然后继续确认：

• Service User 处于启用状态。
• 其类型为 Service User。
• 该用户被允许运行 IFS 应用。
• Directory ID 与 IAM 身份完全一致。
• 没有其他用户使用相同的 Directory ID。
• 测试使用的是正确环境以及正确的 Client ID。

14环境克隆后的检查清单

无论是从 PROD 克隆到 UAT、刷新 TEST，还是执行其他环境替换操作，用户在界面中仍然可见，都不能证明整条身份链仍然一致。

• IAM Client：它是否存在于目标环境中，并处于启用状态？
• Client ID：中间件使用的是否是目标环境对应的 Client ID？
• Client Secret：它是否仍然有效，并保存在正确位置？
• Service Account User：IAM 实际创建的准确值是什么？
• IFS Service User：它是否存在、处于启用状态，并且类型正确？
• Directory ID：它是否与 Service Account User 完全一致？
• Person：它是否存在，并关联到正确用户？
• Companies：是否已分配所需 Companies？
• Permission Sets：目标 projections 是否已授权？
• HCM Access：组织范围是否仍然存在？

15技术账户的安全与运维

还应补充以下通用最佳实践：

• 每个集成、每个环境使用独立客户端：不要让多个中间件共用同一个 Client ID，也不要让 PROD 与 UAT 共用。
• 最小权限：只分配必要的 Companies、projections 和 HCM 数据范围。
• Secret 轮换：记录凭据更新流程以及中间件更新步骤。
• 可追溯性：使用可以在日志和审计中明确识别的技术名称。
• 健康检查：定期验证 token 获取，并调用一个无破坏性的 projection。
• 禁止交互式登录：用于集成的 Service User 不应变成通用人工账户。
• 可控撤销：在停用客户端或 Service User 之前，先明确哪些数据流会受到影响。

16最终配置与快速检查清单

在我的环境中，最终可用的配置如下：

IAM Client: IFS_BLUEWAY
     ├── Enabled = Yes
     ├── Public Client = No
     ├── Service Accounts = Yes
     ├── Create IFS Service User = No
     ├── Client ID
     └── Client Secret
             │
             ▼
IAM Service Account User
service-account-ifs_blueway
             │
             │ Directory ID
             ▼
IFS Service User: IFS_BLUEWAY
     ├── User Type = Service User
     ├── Active
     ├── Companies
     ├── Permission Sets
     └── Person 已创建
             │
             ▼
Person: IFS_BLUEWAY
     └── HCM 授权

需要记住的创建顺序：

1. 创建 IAM Client。
2. 启用 Service Accounts。
3. 不要让系统自动创建 Service User。
4. 复制准确的 Service Account User 值。
5. 手动创建 IFS Service User。
6. 将 Service Account User 用作 Directory ID。
7. 创建关联的 Person。
8. 分配 Companies。
9. 分配 Permission Sets。
10. 分配 HCM 数据范围。
11. 先测试 token，再逐层测试 API。