基于属性的访问控制 - Docs by LangChain

本参考文档解释了 LangSmith 的基于属性的访问控制（ABAC）系统，该系统支持基于资源属性的细粒度访问控制，作为 RBAC 的补充。有关将用户自动配置到角色的信息，请参阅 SCIM。

ABAC（基于属性的访问控制）是一项用于管理细粒度访问控制的企业功能。如果您对此功能感兴趣，请联系我们的销售团队。其他计划默认对所有用户使用管理员角色。

ABAC 通过向访问决策添加基于标签的条件来补充基于角色的访问控制（RBAC）。RBAC 根据用户的角色授予宽泛的权限（例如，“可以读取所有项目”），而 ABAC 允许您根据资源标签限制或授予访问权限（例如，“只能读取标记为 Environment=Development 的项目”）。

角色和资源标签可以通过 UI 或 API 进行管理。ABAC 策略可通过 API 进行配置。配置后，策略会在 API 和 UI 中自动强制执行。

开始之前

在您的工作区中设置资源标签。
ABAC 目前仅支持 resource_tag_key 作为策略中的 attribute_name，用于根据资源标签进行评估。尚不支持其他属性。

为自托管部署启用 ABAC

ABAC 需要运行 Helm chart 0.11.28 或更高版本（应用程序版本 0.12.1）的自托管 LangSmith 部署。升级后，使用以下选项之一启用 ABAC：
- 为特定组织启用： 针对您的 LangSmith PostgreSQL 数据库运行以下命令，将 <organization_id> 替换为从 UI 组织设置页面复制的 ID：
  UPDATE organizations SET config = config || '{"can_use_abac": true}' WHERE id = '<organization_id>' AND NOT is_personal;
- 为所有组织启用： 在您的 values.yaml 中的 commonEnv 添加以下环境变量：
  DEFAULT_ORG_FEATURE_CAN_USE_ABAC: "true"
  此环境变量对个人组织无效，因为个人组织未启用 RBAC。
设置身份验证。要通过 API 管理访问策略，您需要来自组织管理员用户的个人访问令牌（PAT），或具有组织管理员权限的组织范围服务密钥。在运行任何脚本之前设置以下环境变量：
```
export LANGSMITH_API_KEY="your_admin_api_key"
# 自托管或欧盟部署所需：
# export LANGCHAIN_ENDPOINT="https://eu.api.smith.langchain.com"
# export LANGCHAIN_ENDPOINT="https://langsmith.yourdomain.com/api"
```

访问策略结构

访问策略定义了授予或拒绝访问的条件。其结构如下：

{
  "name": "策略名称",
  "description": "可选描述",
  "effect": "allow | deny",
  "condition_groups": [
    {
      "permission": "projects:read",
      "resource_type": "project",
      "conditions": [
        {
          "attribute_name": "resource_tag_key",
          "attribute_key": "Environment",
          "operator": "equals",
          "attribute_value": "Production"
        }
      ]
    }
  ],
  "role_ids": ["<role-uuid>"]
}

效果

effect 决定条件匹配时发生的情况：

allow - 条件匹配时授予访问权限
deny - 条件匹配时阻止访问

拒绝策略始终优先。如果允许策略和拒绝策略都匹配，则拒绝访问。

条件组

condition_groups 数组包含一个或多个条件组。多个条件组使用 OR 逻辑 进行评估 - 如果任何组匹配，则应用该策略。每个条件组指定：

permission - 此组适用的权限
resource_type - 要匹配的资源类型
conditions - 条件数组（组内使用 AND 逻辑 进行评估）

资源类型和权限

资源类型	支持的权限
`project`	`projects:read`, `projects:update`, `projects:delete`, `runs:read`, `runs:share`, `runs:delete`, `projects:increase-trace-tier`, `projects:decrease-trace-tier`
`prompt`	`prompts:read`, `prompts:update`, `prompts:delete`, `prompts:share`, `prompts:tag`
`dataset`	`datasets:read`, `datasets:update`, `datasets:delete`, `datasets:share`
`deployment`	`deployments:read`, `deployments:update`, `deployments:delete`
`mcp_server`	`mcp-servers:read`, `mcp-servers:invoke`, `mcp-servers:update`, `mcp-servers:delete`。参见 Fleet 工具访问控制。
`fleet_integration`	`mcp-servers:read`, `mcp-servers:invoke`。参见 Fleet 工具访问控制。

运行（Runs）没有自己的标签。运行权限（runs:read, runs:create, runs:share, runs:delete）根据其父项目的标签进行评估。

条件

conditions 数组中的每个条件指定：

attribute_name - 目前仅支持 resource_tag_key
attribute_key - 要匹配的标签键（例如，Environment、Team）
operator - 比较运算符
attribute_value - 要比较的值

运算符

运算符	描述
`equals`	精确匹配（区分大小写）
`not_equals`	值不同（区分大小写）
`equals_ignore_case`	精确匹配（不区分大小写）
`not_equals_ignore_case`	值不同（不区分大小写）
`matches`	使用 `*` 和 `?` 通配符的 Glob 模式匹配
`not_matches`	当值不匹配 Glob 模式时匹配

`_if_exists` 变体

每个运算符都有一个 _if_exists 变体，当标签键不存在时默认匹配，或者当标签存在时正常评估条件：

运算符	描述
`equals_if_exists`	精确匹配（区分大小写），或标签键不存在时
`not_equals_if_exists`	值不同（区分大小写），或标签键不存在时
`equals_ignore_case_if_exists`	精确匹配（不区分大小写），或标签键不存在时
`not_equals_ignore_case_if_exists`	值不同（不区分大小写），或标签键不存在时
`matches_if_exists`	Glob 模式匹配，或标签键不存在时
`not_matches_if_exists`	当值不匹配 Glob 模式时匹配，或标签键不存在时

在 allow 策略中，_if_exists 变体授予对匹配条件或没有指定标签键的资源的访问权限。在 deny 策略中，它们阻止匹配条件或没有该标签键的资源。

角色

role_ids 数组指定策略适用的工作区角色。当具有该角色的用户访问资源时，将评估策略条件。策略可以在创建策略时附加到角色，也可以稍后通过 API 附加。

管理访问策略

访问策略由组织管理员通过 LangSmith API 管理。在创建策略之前，请在您的工作区中设置资源标签。

ABAC 如何与 RBAC 协同工作

在确定资源访问权限时，会同时考虑 RBAC 权限和 ABAC 策略：

ABAC deny 策略覆盖 RBAC 权限
ABAC allow 策略即使没有 RBAC 权限也可以授予访问权限
如果没有 ABAC 策略匹配，系统将回退到 RBAC

策略评估结果

功能组合：

RBAC 已启用	ABAC 已启用	行为
✗	✗	所有工作区成员都具有管理员级别的访问权限
✓	✗	标准 RBAC - 基于角色权限的访问
✓	✓	RBAC + ABAC - 基于标签的细粒度访问控制

当 RBAC 和 ABAC 都启用时：

RBAC 允许	Allow 策略匹配	Deny 策略匹配	结果
✓	✓	✗	允许
✓	✗	✗	允许（RBAC 回退）
✓	✓	✓	拒绝（拒绝优先）
✓	✗	✓	拒绝（拒绝优先）
✗	✓	✗	允许（ABAC 授予访问权限）
✗	✗	✗	拒绝
✗	✓	✓	拒绝（拒绝优先）

示例场景

1. 标注团队分配

允许标注员仅访问为其团队标记的数据集：

{
  "name": "标注员团队 A 访问",
  "effect": "allow",
  "condition_groups": [{
    "permission": "datasets:read",
    "resource_type": "dataset",
    "conditions": [{
      "attribute_name": "resource_tag_key",
      "attribute_key": "Annotation-Team",
      "operator": "equals",
      "attribute_value": "Team-A"
    }]
  }]
}

2. 阻止敏感数据

拒绝访问包含 PII 的数据集。由于拒绝策略覆盖允许策略，即使对于具有 RBAC 权限的用户，这也会阻止访问：

{
  "name": "阻止 PII 数据集",
  "effect": "deny",
  "condition_groups": [{
    "permission": "datasets:read",
    "resource_type": "dataset",
    "conditions": [{
      "attribute_name": "resource_tag_key",
      "attribute_key": "Contains-PII",
      "operator": "equals",
      "attribute_value": "true"
    }]
  }]
}

3. 基于应用程序的访问（使用通配符）

允许工程师使用 Glob 模式访问 “chatbot” 系列中任何应用程序的项目：

{
  "name": "聊天机器人应用访问",
  "effect": "allow",
  "condition_groups": [{
    "permission": "projects:read",
    "resource_type": "project",
    "conditions": [{
      "attribute_name": "resource_tag_key",
      "attribute_key": "Application",
      "operator": "matches",
      "attribute_value": "chatbot-*"
    }]
  }]
}

4. 客户和用途隔离（AND 逻辑）

仅当两个条件都满足时才授予访问权限 - 数据集用于训练且属于特定客户：

{
  "name": "客户训练数据访问",
  "effect": "allow",
  "condition_groups": [{
    "permission": "datasets:read",
    "resource_type": "dataset",
    "conditions": [
      {
        "attribute_name": "resource_tag_key",
        "attribute_key": "Purpose",
        "operator": "equals",
        "attribute_value": "Training"
      },
      {
        "attribute_name": "resource_tag_key",
        "attribute_key": "Client",
        "operator": "equals",
        "attribute_value": "Acme-Corp"
      }
    ]
  }]
}

5. 客户数据加上没有 `Client` 标签的资源（使用 `_if_exists`）

顾问没有 RBAC datasets:read 权限，但此策略授予他们访问标记为 Client=Acme-Corp 的数据集，以及根本没有 Client 标签的数据集的权限。标记为其他客户（例如 Client=Other-Corp）的数据集仍被阻止：

{
  "name": "Acme 顾问访问",
  "effect": "allow",
  "condition_groups": [{
    "permission": "datasets:read",
    "resource_type": "dataset",
    "conditions": [{
      "attribute_name": "resource_tag_key",
      "attribute_key": "Client",
      "operator": "equals_if_exists",
      "attribute_value": "Acme-Corp"
    }]
  }]
}

故障排除

访问意外被拒绝？

检查是否有拒绝策略匹配（拒绝始终优先）
检查用户是否具有 RBAC 权限或匹配的允许策略
验证资源是否具有预期的标签和值
带有 _if_exists 运算符的拒绝策略会阻止缺少该标签键的资源
对于区分大小写的运算符（equals、not_equals），检查大小写是否不匹配
当组中有多个条件时，所有条件都必须匹配（AND 逻辑）

访问意外被授予？

审查 RBAC 权限（用户可能通过其角色获得访问权限）
检查允许策略是否过于宽泛（例如，使用通配符）
_if_exists 运算符匹配缺少该标签键的资源

策略未生效？

确认策略已附加到正确的角色
验证用户在工作区中具有该角色
检查 resource_type 和 permission 是否与正在访问的资源匹配

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​开始之前

​为自托管部署启用 ABAC

​访问策略结构

​效果

​条件组

​资源类型和权限

​条件

运算符

_if_exists 变体

​角色

​管理访问策略

​ABAC 如何与 RBAC 协同工作

​策略评估结果

​示例场景

​1. 标注团队分配

​2. 阻止敏感数据

​3. 基于应用程序的访问（使用通配符）

​4. 客户和用途隔离（AND 逻辑）

​5. 客户数据加上没有 Client 标签的资源（使用 _if_exists）

​故障排除

开始之前

为自托管部署启用 ABAC

访问策略结构

效果

条件组

资源类型和权限

条件

`_if_exists` 变体

角色

管理访问策略

ABAC 如何与 RBAC 协同工作

策略评估结果

示例场景

1. 标注团队分配

2. 阻止敏感数据

3. 基于应用程序的访问（使用通配符）

4. 客户和用途隔离（AND 逻辑）

5. 客户数据加上没有 `Client` 标签的资源（使用 `_if_exists`）

故障排除