跳转至

Permissions reference（权限参考）

All major concepts in Data Connection — agents, sources, and syncs — are managed in Foundry as resources. This enables flexibly organizing these resources across Projects and folders, and allows security primitives such as markings to be applied to Data Connection resources.

Platform owners should be careful to not over-share Data Connection resources. Users with view and edit permissions on sources and agents should be trusted pipeline developers. The datasets produced by the syncs can be imported to downstream Transforms projects as necessary, thereby granting access to the data without sharing access to the agents or sources.

This page documents how permissions work for all Data Connection resources, including:

Resource permissions

:::callout{theme="neutral"} The permissions listed below are defaults. In some environments, the default permission behavior may have been changed using custom roles. :::

Agents

Owner

An owner of an agent is usually its creator and gets the following permissions:

  • Re-download the agent or regenerate the token for that agent
  • Inherits permissions of Editor

Editor

An editor of an agent can:

  • Deploy a source to that agent.
  • Configure an agent using the Agent Manager (change the plugins and configs, and restart the agent).
  • Share the agent with other users.
  • Inherit Viewer permissions.
  • Delete the agent.

:::callout{theme="neutral"} A user must be the editor of a Project to create an agent in that Project, but must be an owner of the Project to administer the agents within that Project. That means that a user may create an agent and then be unable to generate download links or perform other administrative tasks on the agent. :::

Viewer

A Viewer of an agent can:

  • See the agent configuration and status.

Sources

Owner

By default, the source owner inherits Editor permissions.

A source owner can also:

  • Modify export configurations if the user configuring exportable Markings has permission to remove Markings from any Organization or security Markings they add as safe to export to the selected source.
  • Allow a source to be imported into code resources.

Editor

An editor of a source can:

  • Delete the source.
  • Change the assigned agents of the source (additionally requires Edit on every agent being added).
  • Update the source configuration (additionally requires Edit on the agents assigned to the source).
  • Rename the source.
  • Create, edit, and delete syncs for that source.
  • Run SQL queries on database sources.
  • Share the source with other users.
  • Explore and preview sources that support these operations, such as JDBC and Directory sources.
  • Inherit Viewer permissions.
  • Import a source to a code resource

:::callout{theme="warning" title="Warning"} Keep in mind that syncs can change the source system if the source credentials allow it (e.g. delete files from a directory or S3 source, or drop data from a database via arbitrary SQL). You should only grant Edit access to the source (or the Project containing it) to users whom you would also grant full access to the account the source uses to access the data. :::

Viewer

  • A viewer of a source can view source configuration, including assigned agents.

Syncs

Sync permissions are derived from the relevant source and output dataset.

  • Viewing a sync requires View on the source and dataset.
  • Editing a sync requires Edit on the source and dataset.
  • Deleting a sync requires Edit on the source and dataset.
  • Running a sync requires Edit on the dataset.

Plugins and JDBC Drivers

Owner

  • Inherits Editor permissions.

Editor

  • Delete the plugin / driver (the plugin / driver must not be assigned to any agents to successfully delete it).
  • Inherits Viewer permissions.

Viewer

  • View the plugin / driver.
  • Download the plugin / driver.
  • Add the plugin to an agent (also requires Editor on the agent).

Webhooks

A Webhook’s permissions are inherited entirely from the source with which it is associated.

  • Viewing a Webhook configuration requires View on the source.
  • Creating a Webhook requires Edit on the source.
  • Editing a Webhook configuration requires Edit on the source.
  • Deleting a Webhook requires Edit on the source.
  • Configuring an Action to use a Webhook requires Edit on the source.
  • Executing a Webhook requires Edit on the source. Note that executing a Webhook permission is not required when executing a Webhook through an Action.

By default, only the user who executes a Webhook may view the response using the history tab in the Data Connection application. The webhooks:read-privileged-data permission may be added to a custom or default role to allow users with that role to view the full request and response history for all webhooks that they can access. The standard recommended setup is to add a new role called "Webhook Privileged Data Viewer" with this permission, and ensure that users who need to view full Webhook history have this role on the relevant sources.

External connections from code

External transforms, pipelines, and compute modules

:::callout{theme="warning"} When a source is imported into a code resource, users with edit access on the repository can write custom code using the connection details configured for that source, including accessing secret values.

This means that the ability to import sources into code and granting Editor access to the source should be carefully managed, with only trusted users given access to the source and repository. :::

  • Importing a source in a code resource (transform, pipeline or compute module) requires Editor permission on the source.
  • Triggering a build that imports a source requires Editor on the code resource (nothing on the source itself).
  • Removing an imported source from a code resource requires Editor on the source or the code resource.

External functions

Refer to the documentation on external functions permissions for detailed information regarding permission of using webhooks in a functions repository.

Marking propagation

As noted above, resources can have Organizations and Markings applied as an additional level of access control. Organizations and Markings are applied to the source will propagate to the datasets produced from syncs on that source. This means users will not be able to view data in any of the datasets produced from a source, unless they have access to all of the Organizations and Markings applied to that source.

:::callout{theme="warning" title="Foundry-to-Foundry sync exception"} When syncing data between Foundry instances using the Foundry connector, Markings and column-based access control (CBAC) policies are not automatically propagated to the destination stack. While CBAC is respected on the source stack — users can only sync data they are permitted to view — these security configurations are not transferred during the sync. You must manually configure appropriate permissions and Markings on the destination stack after the data arrives. :::

Since it is likely for sources to contain data of varying levels of sensitivity, we recommend that you mark the source with all of the Organizations and Markings that apply to the data available in that source, and then use transforms to clean and unmark the data using the stop_propagating and/or stop_requiring functionality. To learn more about unmarking, see the guides on removing Markings and removing inherited Markings.

Note that applying Organizations and Markings to the data after it has been synced should not be considered sufficient; as access to the source is effectively access to the data, the source should be marked with the Organizations and Markings that apply to anything it contains.

Best practices

As a quick reminder, the primary Data Connection resources are agents and sources. Plugins and drivers are deployed to agents to expand functionality.

Agent best practices

There are two recommended permission setups for agents: all agents in a single Project per Organization, or each agent in its own Project. The diagram above illustrates the former option; the guidance below describes why you might choose each option.

Option 1: Place all agents in a single Project per Organization.

Placing all agents in a single Project is the cleanest approach, and is recommended if there is one group of users managing all agents. This allows you to control access to the agents at the Project level, and to permission sources and syncs separately, downstream from the agent.

Choose this option only if it is acceptable for every Agent Manager and every source editor to have access to all agents. Remember that to deploy a source on an agent, a user must have Editor permission on that agent.

Option 2: Place each agent in its own Project.

This approach allows for full granularity of agent permissions. It also guarantees that the structure will never drift from the “groupings” at any time during the evolution of the source management. For example, you can safely assign / unassign agents from a source without needing to grant users access to an entire group of agents, and there would be no need to restructure Projects to account for group permission changes in the future.

This approach is recommended if you have multiple groups managing agents, and you would like to permission their access to agents separately.

:::callout{theme="warning" title="Warning"} Editors of the Project containing the agent will be able to create new sources and syncs that run on that agent. Make sure you do not grant Editor role on the Project to users who should not be able to do this. :::

Source best practices

Each source should be in its own Project in the datasource layer. Each sync defined on a source should output to a dataset within the same Project as the source. If the source contains sensitive data such as PII, you can apply a Marking to the source which will propagate to the output datasets.

:::callout{theme="warning" title="Warning"} Editors of the Project containing the source will be able to create new syncs and edit existing syncs for that source, as well as create Webhooks and configure them for use elsewhere in Foundry.

Keep in mind that syncs can change the source system if the source credentials allow it; for instance, deleting files from a Directory or S3 source, or dropping data from a database via arbitrary SQL.

You should only grant Edit access to the source (or the Project containing it) to users whom you would also grant full access to the account the source uses to access the data. :::

Plugins and JDBC drivers

There are two recommended permission setups for plugins and JDBC drivers: all resources in a single Project per Organization, or each JDBC / driver in a Project with one or more agents that require it.

Option 1: Place all plugins and drivers in a single Project per Organization.

This is recommended if there is one group of users managing all agents. This allows Agent Managers to have access to all plugins and drivers that have been uploaded. This approach should only be chosen if there should be equal access to plugins and drivers among all Agent Managers.

The recommended process for implementing this approach is:

  1. Create one folder per agent.
  2. Migrate the current plugin and driver to the appropriate agent folder.
  3. Choose one copy of each plugin and driver to be the authoritative copy of each asset and move it to the Project root.
  4. Migrate each agent to use the root copy of the required plugin and driver.
  5. Deprecate the individual agent folders.

Option 2: Place each plugin and driver type in its own Project.

This approach allows for certain "sensitive" plugins or drivers to be permissioned separately from others. If this approach is taken, you must ensure to give the required agent owners adequate permissions on each project so they can use them on agents.

中文翻译

权限参考

Data Connection 中的所有主要概念——代理(Agent)、数据源(Source)和同步(Sync)——在 Foundry 中均作为资源(Resource)进行管理。这使得这些资源可以在项目和文件夹之间灵活组织，并允许将标记(Marking)等安全原语应用于 Data Connection 资源。

平台所有者应注意不要过度共享 Data Connection 资源。拥有数据源和代理查看及编辑权限的用户应是受信任的流水线开发者。同步生成的数据集可以根据需要导入到下游的 Transforms 项目中，从而在不共享代理或数据源访问权限的情况下授予数据访问权限。

本文档说明了所有 Data Connection 资源的权限工作方式，包括：

资源权限

:::callout{theme="neutral"} 以下列出的权限为默认设置。在某些环境中，默认权限行为可能已通过自定义角色(Custom Role)进行了更改。 :::

代理(Agent)

所有者(Owner)

代理的所有者通常是其创建者，拥有以下权限：

  • 重新下载代理或重新生成该代理的令牌
  • 继承编辑者(Editor)权限

编辑者(Editor)

代理的编辑者可以：

  • 将数据源部署到该代理。
  • 使用代理管理器(Agent Manager)配置代理（更改插件和配置，并重启代理）。
  • 与其他用户共享代理。
  • 继承查看者(Viewer)权限。
  • 删除代理。

:::callout{theme="neutral"} 用户必须是项目的编辑者才能在该项目中创建代理，但必须是项目的所有者才能管理该项目内的代理。这意味着用户可能创建了代理，但随后无法生成下载链接或对该代理执行其他管理任务。 :::

查看者(Viewer)

代理的查看者可以：

  • 查看代理配置和状态。

数据源(Source)

所有者(Owner)

默认情况下，数据源所有者继承编辑者(Editor)权限。

数据源所有者还可以：

  • 修改导出配置，前提是配置可导出标记的用户有权从他们添加为可安全导出到所选数据源的任何组织或安全标记中移除标记(Marking)。
  • 允许将数据源导入到代码资源中。

编辑者(Editor)

数据源的编辑者可以：

  • 删除数据源。
  • 更改数据源的已分配代理（还需要对每个添加的代理具有编辑权限）。
  • 更新数据源配置（还需要对分配给数据源的代理具有编辑权限）。
  • 重命名数据源。
  • 为该数据源创建、编辑和删除同步。
  • 对数据库数据源运行 SQL 查询。
  • 与其他用户共享数据源。
  • 浏览和预览支持这些操作的数据源，例如 JDBC 和目录(Directory)数据源。
  • 继承查看者(Viewer)权限。
  • 将数据源导入到代码资源中。

:::callout{theme="warning" title="警告"} 请记住，如果数据源凭据允许，同步可能会更改源系统（例如，从目录或 S3 数据源删除文件，或通过任意 SQL 从数据库中删除数据）。您只应将数据源（或其所在项目）的编辑访问权限授予那些您也会授予其完全访问该数据源用于访问数据的账户的用户。 :::

查看者(Viewer)

  • 数据源的查看者可以查看数据源配置，包括已分配的代理。

同步(Sync)

同步权限源自相关的数据源和输出数据集。

  • 查看同步需要对数据源和数据集具有查看权限。
  • 编辑同步需要对数据源和数据集具有编辑权限。
  • 删除同步需要对数据源和数据集具有编辑权限。
  • 运行同步需要对数据集具有编辑权限。

插件(Plugin)和 JDBC 驱动(JDBC Driver)

所有者(Owner)

  • 继承编辑者(Editor)权限。

编辑者(Editor)

  • 删除插件/驱动（要成功删除，插件/驱动不得分配给任何代理）。
  • 继承查看者(Viewer)权限。

查看者(Viewer)

  • 查看插件/驱动。
  • 下载插件/驱动。
  • 将插件添加到代理（还需要对代理具有编辑权限）。

Webhook

Webhook 的权限完全继承自与其关联的数据源。

  • 查看 Webhook 配置需要对数据源具有查看权限。
  • 创建 Webhook需要对数据源具有编辑权限。
  • 编辑 Webhook 配置需要对数据源具有编辑权限。
  • 删除 Webhook需要对数据源具有编辑权限。
  • 配置操作(Action)以使用 Webhook需要对数据源具有编辑权限。
  • 执行 Webhook需要对数据源具有编辑权限。请注意，通过操作执行 Webhook 时，不需要执行 Webhook 的权限。

默认情况下，只有执行 Webhook 的用户才能使用 Data Connection 应用程序中的历史记录(History)选项卡查看响应。可以将 webhooks:read-privileged-data 权限添加到自定义或默认角色(Role)，以允许拥有该角色的用户查看他们可以访问的所有 Webhook 的完整请求和响应历史记录。标准的推荐设置是创建一个名为"Webhook 特权数据查看者(Webhook Privileged Data Viewer)"的新角色并赋予此权限，并确保需要查看完整 Webhook 历史记录的用户在相关数据源上拥有此角色。

代码外部连接(External Connections from Code)

外部转换(External Transform)、流水线(Pipeline)和计算模块(Compute Module)

:::callout{theme="warning"} 当数据源被导入到代码资源中时，对仓库具有编辑访问权限的用户可以使用为该数据源配置的连接详细信息编写自定义代码，包括访问密钥值。

这意味着，应谨慎管理将数据源导入代码以及授予数据源编辑者(Editor)访问权限的能力，只应授予受信任的用户对数据源和仓库的访问权限。 :::

  • 在代码资源（转换(Transform)、流水线(Pipeline)或计算模块(Compute Module)）中导入数据源需要对数据源具有编辑者(Editor)权限。
  • 触发导入数据源的构建需要对代码资源具有编辑者(Editor)权限（对数据源本身无要求）。
  • 从代码资源中移除已导入的数据源需要对数据源或代码资源具有编辑者(Editor)权限。

外部函数(External Function)

有关在函数仓库中使用 Webhook 的权限详细信息，请参阅外部函数权限文档。

标记传播(Marking Propagation)

如上所述，资源可以应用组织(Organization)和标记(Marking)作为额外的访问控制层级。应用于数据源的组织和标记将传播到从该数据源同步生成的数据集。这意味着，除非用户拥有应用于该数据源的所有组织和标记的访问权限，否则他们将无法查看从该数据源生成的任何数据集中的数据。

:::callout{theme="warning" title="Foundry 到 Foundry 同步例外情况"} 在使用 Foundry 连接器在 Foundry 实例之间同步数据时，标记和基于列的访问控制(CBAC)策略不会自动传播到目标堆栈。虽然 CBAC 在源堆栈上得到遵守——用户只能同步他们被允许查看的数据——但这些安全配置在同步过程中不会转移。数据到达后，您必须在目标堆栈上手动配置适当的权限和标记。 :::

由于数据源很可能包含不同敏感级别的数据，我们建议您使用适用于该数据源中可用数据的所有组织和标记来标记该数据源，然后使用转换通过 stop_propagating 和/或 stop_requiring 功能来清理和取消标记数据。要了解有关取消标记的更多信息，请参阅移除标记(Marking)和移除继承标记的指南。

请注意，在数据同步后对其应用组织和标记不应被视为足够；因为对数据源的访问实际上就是对数据的访问，所以数据源应使用适用于其包含的任何内容的组织和标记进行标记。

最佳实践

快速提醒一下，主要的 Data Connection 资源是代理和数据源。插件和驱动部署到代理以扩展功能。

代理最佳实践

代理有两种推荐的权限设置：每个组织的所有代理放在一个项目中，或者每个代理放在自己的项目中。上图说明了前一种方案；以下指南描述了为何选择每种方案。

方案 1：将每个组织的所有代理放在一个项目中。

将所有代理放在一个项目中最简洁，如果有一组用户管理所有代理，则推荐此方案。这允许您在项目级别控制对代理的访问，并在下游独立于代理对数据源和同步进行权限设置。

仅当每个代理管理器和每个数据源编辑者都可以访问所有代理时，才选择此方案。请记住，要将数据源部署到代理上，用户必须对该代理具有编辑者权限。

方案 2：将每个代理放在自己的项目中。

此方法允许完全精细化的代理权限。它还保证了在数据源管理的演变过程中，结构永远不会偏离"分组"。例如，您可以安全地分配/取消分配代理与数据源的关联，而无需授予用户对整个代理组的访问权限，并且将来也无需重组项目以适应组权限变更。

如果有多个组管理代理，并且您希望分别授予他们对代理的访问权限，则推荐此方案。

:::callout{theme="warning" title="警告"} 包含代理的项目的编辑者将能够创建在该代理上运行的新数据源和同步。确保不要将项目编辑者角色授予那些不应能够执行此操作的用户。 :::

数据源最佳实践

每个数据源应位于数据源(datasource)层中自己的项目中。在数据源上定义的每个同步应输出到与数据源相同项目内的数据集(Dataset)。如果数据源包含敏感数据（如 PII），您可以对数据源应用标记(Marking)，该标记将传播到输出数据集。

:::callout{theme="warning" title="警告"} 包含数据源的项目的编辑者将能够为该数据源创建新的同步和编辑现有同步，以及创建 Webhook 并将其配置为在 Foundry 的其他地方使用。

请记住，如果数据源凭据允许，同步可能会更改源系统；例如，从目录或 S3 数据源删除文件，或通过任意 SQL 从数据库中删除数据。

您只应将数据源（或其所在项目）的编辑访问权限授予那些您也会授予其完全访问该数据源用于访问数据的账户的用户。 :::

插件和 JDBC 驱动

插件和 JDBC 驱动有两种推荐的权限设置：每个组织的所有资源放在一个项目中，或者每个 JDBC/驱动与一个或多个需要它的代理放在一个项目中。

方案 1：将每个组织的所有插件和驱动放在一个项目中。

如果有一组用户管理所有代理，则推荐此方案。这允许代理管理器访问所有已上传的插件和驱动。仅当所有代理管理器之间应平等访问插件和驱动时，才应选择此方法。

实施此方法的推荐流程是：

  1. 为每个代理创建一个文件夹。
  2. 将当前的插件和驱动迁移到相应的代理文件夹。
  3. 选择每个插件和驱动的一个副本作为每个资产的权威副本，并将其移动到项目根目录。
  4. 将每个代理迁移为使用所需插件和驱动的根目录副本。
  5. 弃用各个代理文件夹。

方案 2：将每种插件和驱动类型放在自己的项目中。

此方法允许某些"敏感"插件或驱动与其他插件或驱动分开进行权限设置。如果采用此方法，必须确保为所需的代理所有者授予每个项目足够的权限，以便他们可以在代理上使用这些插件和驱动。