Foundry third-party application & API guidance（Foundry 第三方应用与 API 指南）¶

Foundry’s third-party application authentication and authorization features enable non-Foundry applications and scripts to interact securely with Foundry’s APIs. The core of these features is OAuth2 support for external applications. This document provides guidance of how Palantir recommends these features to be used, as well as examples of potentially inappropriate uses.

:::callout{theme="warning"} By authorizing third-party applications and APIs, users agree to follow the appropriate use terms as mutually agreed to in writing between Palantir and the customer. Contact your Palantir representative if you have any questions regarding your intended use or if you are unsure whether your plans are appropriate, safe, or secure. :::

Appropriate uses¶

Replacing service user accounts
The OAuth2 Authorization Code Flow allows external applications to act on behalf of an individual Foundry user. This ensures that permissions are correct and that there is a clear audit path. Using the OAuth2 flow also ensures that the user has explicitly granted the application access to take actions on their behalf, again providing a clear audit path.
We strongly recommend that existing applications that use a service account to perform actions in Foundry move to the OAuth2 Authorization flow where possible.
Interfacing with external systems
Example: An application that watches for changes in an internal customer system and performs actions in the Foundry Ontology.
Custom applications for specific user workflows
Example: A mobile phone application that interacts with Foundry’s Ontology and Actions APIs to provide a streamlined UX for a critical workflow.
Monitoring or control of Foundry pipelines or workflows
Example: An application which connects to Foundry’s monitoring and data health APIs to assess the state of critical pipelines and allows its users to trigger builds where needed.

Inappropriate uses¶

The integration of third-party applications and the use of Foundry APIs presents risks to data security and should only be undertaken with a clear understanding of the technical and contractual considerations. When scoping a development project that accesses data or undertakes actions on behalf of a user, contact your system administrator to determine if your plans are appropriate, safe, and secure and in compliance with the Foundry appropriate use terms.

The examples below outline representative scenarios where the inappropriate usage of APIs to access data or perform actions can compromise the integrity or security of data managed in Foundry.

Circumventing data controls
Example: Reading data with one user’s token and writing back with another.
Foundry has advanced and fine-grained user authorization features. Sharing data between user accounts in your application could circumvent these controls.
It is important you keep the use of individual Foundry accounts fully isolated. You must not access data with one user's tokens and allow another user to read, discover, write, or in any way interact with that data. If you wish to allow users to share data, this should be done in Foundry, not in the third-party application.
Performing actions without user understanding and consent.
Your application must not deceive your users. Your application must clearly and accurately describe what actions it is performing when using a Foundry user’s account.
Your application must request the minimum set of roles and permissions it needs to perform its function, and no more. It must also make it clear to your users when actions will be performed in Foundry, and what those actions will do.
Any unclear, unexpected, malicious or damaging application behavior is forbidden.
Retrieving or storing of data outside of Foundry without consideration for access control.
Foundry’s customers rely on Foundry to safely store critical data; your application must respect the sensitivity and value of this data and retrieve the minimum set of data that it needs to perform its function.
Your application should also avoid storing or caching data retrieved from Foundry if possible. One potential exception to this could be offline caching, but care should be taken and clear user consent received.
If Foundry data is moved into another data storage system, acknowledge that it will no longer be access controlled or audited in accordance to your organization's configurations for data protection within Foundry.

中文翻译¶

Foundry 第三方应用与 API 指南¶

Foundry 的第三方应用认证与授权功能使非 Foundry 应用和脚本能够安全地与 Foundry 的 API 进行交互。这些功能的核心是支持外部应用的 OAuth2 协议。本文档将介绍 Palantir 推荐的使用方式，并举例说明可能的不当使用场景。

:::callout{theme="warning"} 通过授权第三方应用和 API，用户同意遵守 Palantir 与客户之间书面约定的适当使用条款。如果您对预期用途有任何疑问，或不确定您的计划是否适当、安全或可靠，请联系您的 Palantir 代表。 :::

适当使用场景¶

替代服务用户账户
OAuth2 授权码流程（Authorization Code Flow）允许外部应用代表单个 Foundry 用户执行操作。这确保了权限的正确性，并提供了清晰的审计路径。使用 OAuth2 流程还能确保用户已明确授予应用代表其执行操作的权限，同样提供了清晰的审计路径。
我们强烈建议当前使用服务账户在 Foundry 中执行操作的现有应用尽可能迁移至 OAuth2 授权流程。
与外部系统对接
示例：一个监控内部客户系统变更并在 Foundry 本体（Ontology）中执行操作的应用。
针对特定用户工作流的自定义应用
示例：一款与 Foundry 本体和操作 API（Actions APIs）交互的移动应用，为关键工作流提供简化的用户体验。
监控或控制 Foundry 管道或工作流
示例：一个连接到 Foundry 监控和数据健康 API（monitoring and data health APIs）的应用，用于评估关键管道的状态，并允许用户在需要时触发构建。

不当使用场景¶

集成第三方应用和使用 Foundry API 会带来数据安全风险，只有在充分理解技术和合同考量后方可进行。在规划代表用户访问数据或执行操作的开发项目时，请联系您的系统管理员，以确定您的计划是否适当、安全、可靠，并符合 Foundry 的适当使用条款。

以下示例概述了不当使用 API 访问数据或执行操作可能危及 Foundry 管理数据完整性或安全性的典型场景。

规避数据控制
示例：使用一个用户的令牌读取数据，再使用另一个用户的令牌写入数据。
Foundry 具有先进且细粒度的用户授权功能。在您的应用中共享用户账户之间的数据可能会规避这些控制措施。
务必确保各个 Foundry 账户的使用完全隔离。您不得使用一个用户的令牌访问数据，而允许另一个用户读取、发现、写入或以任何方式与该数据交互。如果您希望允许用户共享数据，应在 Foundry 内部而非第三方应用中实现。
在用户不知情或未同意的情况下执行操作
您的应用不得欺骗用户。当使用 Foundry 用户账户时，您的应用必须清晰准确地描述其正在执行的操作。
您的应用应仅请求执行其功能所需的最少角色和权限，不得多要。同时，必须向用户明确说明何时将在 Foundry 中执行操作，以及这些操作将产生什么影响。
任何不清晰、意外、恶意或具有破坏性的应用行为均被禁止。
未考虑访问控制而在 Foundry 外部检索或存储数据
Foundry 的客户依赖 Foundry 安全存储关键数据；您的应用必须尊重这些数据的敏感性和价值，仅检索执行其功能所需的最少数据。
您的应用应尽可能避免存储或缓存从 Foundry 检索的数据。一个可能的例外是离线缓存，但需谨慎处理并获得用户的明确同意。
如果将 Foundry 数据迁移至其他数据存储系统，请注意这些数据将不再按照您组织在 Foundry 内的数据保护配置进行访问控制或审计。