本参考文档解释了 LangSmith 的基于属性的访问控制 (ABAC) 系统，该系统支持基于资源属性的细粒度访问控制，是对 RBAC的补充。关于自动将用户分配到角色，请参阅 SCIM.

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

准备工作

• * 设置资源标签 在您的工作区中。
• * ABAC 当前仅支持 resource_tag_key as an attribute_name 在策略中用于针对资源标签进行评估。目前不支持其他属性。

为自托管部署启用 ABAC

1. ABAC 需要一个 self-hosted 运行 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;
        

• 为所有组织启用： 将以下环境变量添加到 commonEnv 中 values.yaml:

        DEFAULT_ORG_FEATURE_CAN_USE_ABAC: "true"
        

1. 设置身份验证。要通过 API 管理访问策略，您需要从 组织管理员 用户获取个人访问令牌 (PAT)，或使用具有组织管理员权限的组织范围服务密钥。在运行任何脚本之前，请设置以下环境变量：

    # 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** - 条件匹配时阻止访问

条件组

该 condition_groups 数组包含一个或多个条件组。多个条件组使用 **OR 逻辑** - 如果任何组匹配，则应用该策略。

每个条件组指定： - **permission** - 此组应用的权限 - **resource_type** - 要匹配的资源类型 - **conditions** - 条件数组（使用 **AND 逻辑** 在组内求值）

资源类型和权限

条件

每个条件在 conditions 数组中指定： - **attribute_name** - 当前仅支持 resource_tag_key ，且仅支持 - **attribute_key** - 要匹配的标签键（例如 Environment, Team) - **operator** - 比较运算符 - **attribute_value** - 要比较的值

运算符

_if_exists 变体

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

角色

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

策略可以在创建时附加到角色，也可以稍后通过 API 附加。

管理访问策略

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

ABAC 与 RBAC 的协同工作方式

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

• - ABAC **拒绝** 策略优先于 RBAC 权限
• - ABAC **允许** 策略可以在没有 RBAC 权限的情况下授予访问权限
• - 如果没有 ABAC 策略匹配，系统回退到 RBAC

策略评估结果

功能组合：

当 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 的数据集。由于拒绝策略优先于允许策略，这会阻止即使拥有 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 模式访问"聊天机器人"系列中任何应用程序的项目：

{
  "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. 客户端数据及没有 Client 标签的资源，使用 _if_exists

顾问没有 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"
    }]
  }]
}

故障排除

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

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

策略未生效？ - 确认策略已附加到正确的角色 - 验证用户在工作区中拥有该角色 - 检查 resource_type 和 permission 与被访问的资源相匹配