Abac

---
title: 基于属性的访问控制
sidebarTitle: 基于属性的访问控制
---

本参考文档介绍了 LangSmith 的基于属性的访问控制（ABAC）系统，该系统可根据资源属性实现细粒度的访问控制，是对 [RBAC](/langsmith/rbac) 的补充。如需将用户自动分配到角色，请参阅 [SCIM](/langsmith/user-management#set-up-scim-for-your-organization)。

<Note>
ABAC（基于属性的访问控制）是一项用于管理细粒度访问控制的企业版功能。如果您对此功能感兴趣，[请联系我们的销售团队](https://www.langchain.com/contact-sales)。其他套餐默认所有用户均使用 Admin 角色。
</Note>

ABAC 通过在访问决策中添加基于标签的条件来补充[基于角色的访问控制（RBAC）](/langsmith/rbac)。RBAC 会根据用户角色授予整体权限（例如“可以读取所有项目”），而 ABAC 允许您根据资源标签来限制或授予访问权限（例如“只能读取带有 Environment=Development 标签的项目”）。

<Note>
角色和资源标签可以通过 UI 或 API 进行管理。ABAC 策略可通过 [API](https://api.smith.langchain.com/docs#/access_policies) 进行配置。配置完成后，这些策略会在 API 和 UI 中自动强制执行。
</Note>

## 开始之前

* 在工作区中[设置资源标签](/langsmith/set-up-resource-tags)。
* ABAC 目前仅在策略中将 `resource_tag_key` 支持为 `attribute_name`，用于评估资源标签。暂不支持其他属性。

## 为自托管部署启用 ABAC

1. ABAC 需要运行 Helm chart 0.11.28 或更高版本（应用版本 0.12.1）的[自托管](/langsmith/self-hosted) 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;

为所有组织启用： 在 values.yaml 的 commonEnv 中添加以下环境变量：
DEFAULT_ORG_FEATURE_CAN_USE_ABAC: "true"
该环境变量对个人组织没有影响，因为个人组织未启用 RBAC。

设置身份验证。要通过 API 管理访问策略，您需要拥有 Organization Admin 用户签发的个人访问令牌（PAT），或具有 Organization Admin 权限的、组织范围的 service key。在运行任何脚本之前，请设置以下环境变量：

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"

访问策略结构

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

{
  "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 — 条件匹配时阻止访问

拒绝策略始终具有优先权。如果同时有 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`, `datasets:download`
`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`。参见 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 附加。

管理访问策略

访问策略由 Organization Admin 通过 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 回退）
✓	✓	✓	拒绝（拒绝优先）
✓	✗	✓	拒绝（拒绝优先）
✗	✓	✗	允许（ABAC 授予访问权限）
✗	✗	✗	拒绝
✗	✓	✓	拒绝（拒绝优先）

示例场景

1. 标注者团队分配

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

{
  "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 权限的用户也会被阻止访问：

{
  "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”系列的任何应用项目：

{
  "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 逻辑）

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

{
  "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）的数据集仍会被阻止：

{
  "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"
    }]
  }]
}

在创建时为资源打标签

当 ABAC 策略生效时，资源会根据其标签受到访问控制。为了确保资源在创建时立即受到保护，您可以使用 tag_value_ids 参数在创建请求中直接提供标签。这适用于项目、数据集和 Prompt 的创建端点（包括 fork 和 clone 操作）。标签会在与资源创建相同的数据库事务中原子地应用。有关完整细节和示例，请参阅资源标签指南中的创建时为资源打标签。

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

故障排查

访问意外被拒绝？

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

访问意外被授予？

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

策略未生效？

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

---

<div className="source-links">
<Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
</Callout>
<Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/abac.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
</Callout>
</div>

Organization

Users & access control

Tools

Auditing

Data & compliance

Additional resources

访问策略结构

效果

条件组

资源类型与权限

条件

运算符

`_if_exists` 变体

角色

管理访问策略

ABAC 与 RBAC 的协同工作

策略评估结果

示例场景

1. 标注者团队分配

2. 阻止敏感数据

3. 使用通配符的基于应用的访问

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

5. 使用 `_if_exists` 访问客户端数据以及没有 `Client` 标签的资源

在创建时为资源打标签

故障排查

​访问策略结构

​效果

​条件组

​资源类型与权限

​条件

运算符

_if_exists 变体

​角色

​管理访问策略

​ABAC 与 RBAC 的协同工作

​策略评估结果

​示例场景

​1. 标注者团队分配

​2. 阻止敏感数据

​3. 使用通配符的基于应用的访问

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

​5. 使用 _if_exists 访问客户端数据以及没有 Client 标签的资源

​在创建时为资源打标签

​故障排查

访问策略结构

效果

条件组

资源类型与权限

条件

`_if_exists` 变体

角色

管理访问策略

ABAC 与 RBAC 的协同工作

策略评估结果

示例场景

1. 标注者团队分配

2. 阻止敏感数据

3. 使用通配符的基于应用的访问

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

5. 使用 `_if_exists` 访问客户端数据以及没有 `Client` 标签的资源

在创建时为资源打标签

故障排查