基于属性的访问控制

本参考文档介绍 LangSmith 的基于属性的访问控制（ABAC）系统，它支持基于资源属性进行细粒度访问控制，是对 RBAC 的补充。有关将用户自动预配到角色的信息，请参阅 SCIM。

NOTE

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

ABAC 通过在访问决策中加入基于标签的条件，对基于角色的访问控制（RBAC）形成补充。RBAC 基于用户角色授予一揽子权限（例如“可以读取所有项目”），而 ABAC 允许你基于资源标签来限制或授予访问权限（例如“只能读取带有 Environment=Development 标签的项目”）。

NOTE

角色和资源标签可以通过 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：
  sql
```
UPDATE organizations SET config = config || '{"can_use_abac": true}' WHERE id = '<organization_id>' AND NOT is_personal;
```
  1
- 为所有组织启用： 将以下环境变量添加到你的 values.yaml 中的 commonEnv：
  yaml
```
DEFAULT_ORG_FEATURE_CAN_USE_ABAC: "true"
```
  1

NOTE

 此环境变量对个人组织没有影响，因为个人组织未启用 [RBAC](/langsmith/rbac)。

设置身份认证。要通过 API 管理访问策略，你需要来自组织管理员用户的个人访问令牌（PAT），或具有组织管理员权限的组织级服务密钥。在运行任何脚本之前设置以下环境变量：

bash

export LANGSMITH_API_KEY="your_admin_api_key"
# Required for self-hosted or regional SaaS deployments:
# export LANGCHAIN_ENDPOINT="https://eu.api.smith.langchain.com"
# export LANGCHAIN_ENDPOINT="https://aws.api.smith.langchain.com"
# export LANGCHAIN_ENDPOINT="https://apac.api.smith.langchain.com"
# export LANGCHAIN_ENDPOINT="https://langsmith.yourdomain.com/api"

访问策略结构

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

json

{
  "name": "Policy Name",
  "description": "Optional 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 - 条件匹配时阻止访问

NOTE

拒绝（deny）策略始终优先。如果允许（allow）策略和拒绝（deny）策略同时匹配，则拒绝访问。

条件组

condition_groups 数组包含一个或多个条件组。多个条件组按 OR 逻辑评估 - 只要任一条件组匹配，策略即生效。

每个条件组指定：

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

资源类型和权限

资源类型	支持的权限
`project`	`projects:read`, `projects:update`, `projects:delete`, `runs:read`, `runs:read-inputs`, `runs:read-outputs`, `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`, `datasets:download`, `datasets:clone`
`deployment`	`deployments:read`, `deployments:update`, `deployments:delete`
`queues`	`annotation-queues:create`, `annotation-queues:delete`, `annotation-queues:read`, `annotation-queues:update`
`mcp_server`	`mcp-servers:read`, `mcp-servers:invoke`, `mcp-servers:update`, `mcp-servers:delete`. See Fleet tool access control.
`fleet_integration`	`mcp-servers:read`, `mcp-servers:invoke`. See Fleet tool access control.

NOTE

运行没有自己的标签。运行权限（runs:read、runs:read-inputs、runs:read-outputs、runs:create、runs:share、runs:delete）是针对父项目的标签进行评估的。关于输入和输出权限如何影响响应，请参阅控制对运行输入和输出的访问。

NOTE

克隆会将示例从源数据集复制到目标数据集。datasets:clone 权限会针对两个数据集分别检查：一次使用源数据集的标签，一次使用目标数据集的标签。要成功克隆，策略必须授予对两个数据集的 datasets:clone 访问权限。

条件

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 模式时匹配，或标签键不存在

TIP

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

角色

role_ids 数组指定策略适用于哪些工作区角色。当具有该角色的用户访问资源时，会评估策略条件。

策略可以在创建时附加到工作区角色（内置或自定义），也可以在之后通过 API 附加。

管理访问策略

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

ABAC 如何与 RBAC 协同工作

在确定对资源的访问权限时，RBAC 权限和 ABAC 策略都会被纳入考虑：

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

策略评估结果

功能组合：

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

当 RBAC 和 ABAC 都启用时：

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

控制对运行输入和输出的访问

runs:read 控制用户能否看到某个运行。runs:read-inputs 和 runs:read-outputs 控制他们能否看到该运行的输入和输出。这些权限的访问策略使用 resource_type: "project"，并针对每个运行的父项目进行评估，因此你可以在某些项目中隐藏输入、输出或两者，而保持工作区中的其他项目不变。对于这些权限，RBAC 与 ABAC 的组合方式与其他任何权限相同。更多详情，请参阅 ABAC 如何与 RBAC 协同工作。

示例场景

1. 标注员团队分配

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

json

{
  "name": "Annotator Team A Access",
  "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 的数据集的访问。由于 deny 策略会覆盖 allow 策略，因此这会阻止访问，即使对于拥有 RBAC 权限的用户也是如此：

json

{
  "name": "Block PII Datasets",
  "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" 系列中任意应用的项目：

json

{
  "name": "Chatbot Apps Access",
  "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 逻辑）

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

json

{
  "name": "Client Training Data Access",
  "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. 使用 `_if_exists` 处理客户端数据以及没有 `Client` 标签的资源

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

json

{
  "name": "Acme Consultant Access",
  "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"
    }]
  }]
}

6. 在敏感项目中隐藏运行输入和输出

让用户仍能浏览包含 PII 的项目中的运行，但隐藏这些运行的输入和输出。每个权限都有各自的条件组，各条件组按 OR 逻辑评估。用户仍需拥有 runs:read 才能看到这些运行：

json

{
  "name": "Hide PII Run Payloads",
  "effect": "deny",
  "condition_groups": [
    {
      "permission": "runs:read-inputs",
      "resource_type": "project",
      "conditions": [{
        "attribute_name": "resource_tag_key",
        "attribute_key": "Contains-PII",
        "operator": "equals",
        "attribute_value": "true"
      }]
    },
    {
      "permission": "runs:read-outputs",
      "resource_type": "project",
      "conditions": [{
        "attribute_name": "resource_tag_key",
        "attribute_key": "Contains-PII",
        "operator": "equals",
        "attribute_value": "true"
      }]
    }
  ]
}

在创建时标记资源

当 ABAC 策略生效时，资源会基于其标签进行访问控制。为确保资源一创建就受到保护，你可以在创建请求中使用 tag_value_ids 参数直接提供标签。

这在项目、数据集和提示词的创建端点（包括 fork 和克隆操作）上受支持。标签会与资源创建在同一个数据库事务中以原子方式应用。

有关完整详情和示例，请参阅资源标签指南中的在创建时标记资源。

NOTE

如果你依赖 LangSmith SDK 在追踪摄取期间自动创建追踪项目，则该自动创建路径上不提供 tag_value_ids 参数。为确保 ABAC 策略从一开始就生效，请在启动追踪会话之前，通过 POST /api/v1/sessions 并使用所需的 tag_value_ids 预先创建项目。

故障排查

访问意外被拒绝？

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

访问意外被授予？

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

运行输入或输出缺失？

检查用户角色是否授予了 runs:read-inputs 和 runs:read-outputs，或者是否有 allow 策略为该运行所在项目授予了这些权限
检查是否存在针对 runs:read-inputs 或 runs:read-outputs 且匹配项目标签的 deny 策略
除非两个权限都被授予，否则消息和轨迹视图会返回 403 Forbidden

策略未生效？

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

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织