跳转至

Client credentials applications（客户端凭证应用）

Client credentials applications are externally hosted OAuth or OSDK applications that use client credentials for authentication. These applications are ideal for pro-code solutions that require maximum user scale and allow customer-defined authentication and authorization logic outside of Foundry.

Client credentials applications are ideal for the following use cases:

  • Server-to-server integrations that do not require user login.
  • Automated systems that need to access Foundry data programmatically.
  • Backend services that process data or trigger workflows.
  • API integrations with external platforms.
  • Public-facing applications that need to serve many users without individual authentication.

Architecture

Client credentials applications authenticate using a client ID and client secret. They then receive an access token tied to a service user and use that token to make API calls to Foundry through the service user's permissions.

External application → OAuth Client Credentials → Service user → Foundry APIs

Prerequisites

Before setting up a client credentials application, ensure that you have the following:

  • Third-party application management permissions on your organization in Control Panel.
  • An external hosting environment for your application.

Setup

Step 1: Create an OAuth client application

OAuth clients are now created in Developer Console. Refer to the comprehensive OAuth client guide for more information.

  1. Navigate to Developer Console > OAuth clients.
  2. Select Create OAuth client.
  3. Choose the Backend service application type.
  4. Configure the application settings and note the generated credentials.

Step 2: Understand service user implications

For client credentials applications, Foundry creates a service user that acts on behalf of your application. This offers the following benefits:

  • No user login required: Since your application displays information that is not scoped to individual users, the service user handles all operations.
  • Service user permissions: By default, the service account does not have access to any resources. A Foundry administrator must assign the desired roles and permissions to the service user account for the client to perform actions in Foundry.
  • Authorization responsibility: You must implement authorization logic in your application since users cannot log in individually. Your application receives a single token for all operations.
  • Permission management: Grant the service user access to specific projects, object types, and datasets required by your application.

Step 3: Configure service user permissions

After creating the OAuth client, configure the following permissions for the service user:

  • Project access: Grant the service user access to projects containing required resources.
  • Ontology type access: Grant access to the necessary ontology types. Ensure that the service user can submit actions.
  • Dataset access: Grant access to required datasets.
  • Role assignments: Assign appropriate roles that provide necessary API operations.

Step 4: OSDK application implementation

For TypeScript applications, use the OSDK to generate a custom SDK library for your application. Refer to the bootstrapping server-side TypeScript applications guide for more information.

The OSDK bootstrapping process consists of the following steps:

  1. Create an OSDK package: Use Developer Console to generate an OSDK package.
  2. Add Ontology resources to the SDK: Add the entities that your application needs to access to the OSDK resources.
  3. Install the OSDK: Install the generated OSDK package in your application.
  4. Configure authentication: Use the OSDK authentication client with your OAuth client credentials to access Foundry.
  5. Query data: Query ontology data with the service user's permissions using the OSDK client.

The OSDK client provides type safety, automatic serialization, and simplified API interactions compared to raw REST API calls.

Step 5: Verify application access

  1. Verify authentication: Ensure that your application can successfully obtain access tokens.
  2. Test API calls: Confirm that your application can access the required Foundry resources.

:::callout{theme="warning"} When using a client credentials grant, remember to keep the OAuth2 client secret secure. Never store secrets in public code repositories, or within publicly accessible code in an application.

If a secret is exposed, rotate the secret immediately. :::

Troubleshooting

Authentication issues

  • Invalid client credentials: Verify that the client ID and secret are correct. Regenerate if necessary to confirm the secret is correct.
  • Scope errors: Ensure requested scopes are granted to the OSDK client application.
  • Network connectivity: Check firewall and network policies to ensure your requests are making it to Foundry.

Permission errors

  • 403 Forbidden: Review application permissions in Developer Console. A 403 error means a user does not have permission to see the application.
  • Resource not found: If the user does not have access to resources that you expect them to see, verify that the application service user has access to those resources and they have been added to the application's ontology resources.

You now have a working client credentials application with the power of the Ontology at your fingertips. Your external application can securely access Foundry data and functionality through the service user's permissions, enabling you to build scalable consumer-facing applications with robust backend integration.

中文翻译

客户端凭证应用

客户端凭证应用（Client credentials applications）是外部托管的 OAuth 或 OSDK 应用，使用客户端凭证进行身份验证。这类应用非常适合需要最大用户规模、允许在 Foundry 外部自定义身份验证和授权逻辑的专业代码解决方案。

客户端凭证应用适用于以下场景：

  • 无需用户登录的服务器到服务器集成
  • 需要以编程方式访问 Foundry 数据的自动化系统
  • 处理数据或触发工作流的后端服务
  • 与外部平台的 API 集成
  • 需要服务大量用户且无需单独身份验证的面向公众应用

架构

客户端凭证应用使用客户端 ID（client ID）和客户端密钥（client secret）进行身份验证。随后，它们会获取一个绑定到服务用户（service user）的访问令牌，并利用该令牌通过服务用户的权限向 Foundry 发起 API 调用。

外部应用 → OAuth 客户端凭证 → 服务用户 → Foundry API

前提条件

在设置客户端凭证应用之前，请确保您具备以下条件：

  • 在 Control Panel 中拥有组织的第三方应用管理权限
  • 为您的应用准备的外部托管环境

设置

步骤 1：创建 OAuth 客户端应用

OAuth 客户端现在在 Developer Console 中创建。有关更多信息，请参阅全面的 OAuth 客户端 指南。

  1. 导航至 Developer Console > OAuth clients
  2. 选择 Create OAuth client
  3. 选择 Backend service 应用类型
  4. 配置应用设置并记录生成的凭证

步骤 2：了解服务用户的影响

对于客户端凭证应用，Foundry 会创建一个代表您的应用执行操作的服务用户。这具有以下优势：

  • 无需用户登录： 由于您的应用显示的信息不针对单个用户，因此所有操作均由服务用户处理
  • 服务用户权限： 默认情况下，服务账户无权访问任何资源。Foundry 管理员必须为服务用户账户分配所需的角色和权限，客户端才能在 Foundry 中执行操作
  • 授权责任： 由于用户无法单独登录，您必须在应用中实现授权逻辑。您的应用将获得一个用于所有操作的单一令牌
  • 权限管理： 授予服务用户访问应用所需的特定项目、对象类型和数据集的权限

步骤 3：配置服务用户权限

创建 OAuth 客户端后，为服务用户配置以下权限：

  • 项目访问权限： 授予服务用户访问包含所需资源的项目的权限
  • 本体类型访问权限： 授予对必要本体类型的访问权限。确保服务用户能够提交操作
  • 数据集访问权限： 授予对所需数据集的访问权限
  • 角色分配： 分配提供必要 API 操作的适当角色

步骤 4：OSDK 应用实现

对于 TypeScript 应用，使用 OSDK 为您的应用生成自定义 SDK 库。有关更多信息，请参阅 引导服务器端 TypeScript 应用 指南。

OSDK 引导过程包括以下步骤：

  1. 创建 OSDK 包： 使用 Developer Console 生成 OSDK 包
  2. 向 SDK 添加本体资源： 将您的应用需要访问的实体添加到 OSDK 资源中
  3. 安装 OSDK： 在您的应用中安装生成的 OSDK 包
  4. 配置身份验证： 使用 OSDK 身份验证客户端配合您的 OAuth 客户端凭证访问 Foundry
  5. 查询数据： 使用 OSDK 客户端以服务用户的权限查询本体数据

与原始 REST API 调用相比，OSDK 客户端提供了类型安全、自动序列化和简化的 API 交互。

步骤 5：验证应用访问权限

  1. 验证身份验证： 确保您的应用能够成功获取访问令牌
  2. 测试 API 调用： 确认您的应用能够访问所需的 Foundry 资源

:::callout{theme="warning"} 使用客户端凭证授权时，请务必确保 OAuth2 客户端密钥的安全。切勿将密钥存储在公共代码仓库或应用中可公开访问的代码中。

如果密钥泄露，请立即轮换密钥。 :::

故障排除

身份验证问题

  • 无效的客户端凭证： 验证客户端 ID 和密钥是否正确。如有必要，重新生成以确认密钥正确
  • 作用域错误： 确保请求的作用域已授予 OSDK 客户端应用
  • 网络连接： 检查防火墙和网络策略，确保您的请求能够到达 Foundry

权限错误

  • 403 禁止访问： 在 Developer Console 中检查应用权限。403 错误表示用户没有查看应用的权限
  • 资源未找到： 如果用户无法访问您期望他们看到的资源，请验证应用服务用户是否具有这些资源的访问权限，并且这些资源已添加到应用的本体资源中

现在，您已拥有一个功能完善的客户端凭证应用，可以充分利用 Ontology 的强大功能。您的外部应用可以通过服务用户的权限安全地访问 Foundry 数据和功能，使您能够构建具有强大后端集成的可扩展消费者应用。