속성 기반 접근 제어

속성 기반 접근 제어 (ABAC)

이 레퍼런스는 리소스 속성에 기반한 세밀한 접근 제어를 가능하게 하는 LangSmith의 속성 기반 접근 제어(ABAC) 시스템을 설명해요. RBAC를 보완합니다. 역할에 사용자를 자동 프로비저닝하려면 SCIM을 참고하세요.

출처: 문서

참고: ABAC(속성 기반 접근 제어)는 세밀한 접근 제어를 관리하는 Enterprise 기능입니다. 이 기능에 관심이 있다면 영업팀에 문의하세요. 다른 요금제는 기본적으로 모든 사용자에게 Admin 역할을 사용합니다.

본문

ABAC는 접근 결정에 태그 기반 조건을 추가하여 역할 기반 접근 제어 (RBAC)를 보완합니다. RBAC가 사용자 역할에 기반한 포괄적 권한을 부여하는 반면(예: "모든 프로젝트 읽기 가능"), ABAC는 리소스 태그에 기반해 접근을 제한하거나 허용하게 합니다(예: Environment=Development로 태그된 프로젝트만 읽을 수 있음).

참고: 역할과 리소스 태그는 UI 또는 API를 통해 관리할 수 있습니다. ABAC 정책은 API로 구성할 수 있습니다. 구성되면 정책이 API와 UI 모두에서 자동으로 적용됩니다.

시작하기 전에

워크스페이스에 리소스 태그를 설정하세요.
ABAC는 현재 정책에서 attribute_name으로 resource_tag_key만 지원하며, 리소스 태그에 대해 평가합니다. 다른 속성은 아직 지원되지 않습니다.

자체 호스팅 배포에서 ABAC 활성화

ABAC는 Helm 차트 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를 통해 접근 정책을 관리하려면 Organization Admin 사용자의 Personal Access Token(PAT) 또는 Organization Admin 권한이 있는 조직 범위 서비스 키가 필요합니다. 스크립트를 실행하기 전에 다음 환경 변수를 설정하세요:

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

effect는 조건이 일치할 때 발생하는 일을 결정합니다:

allow - 조건이 일치하면 접근 허용
deny - 조건이 일치하면 접근 차단

참고: 거부(deny) 정책은 항상 우선합니다. allow와 deny 정책이 모두 일치하면 접근이 거부됩니다.

Condition groups

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`, `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`. Fleet 도구 접근 제어 참고.
`fleet_integration`	`mcp-servers:read`, `mcp-servers:invoke`. Fleet 도구 접근 제어 참고.

참고: 런에는 자체 태그가 없습니다. 런 권한(runs:read, runs:create, runs:share, runs:delete)은 상위 프로젝트의 태그에 대해 평가됩니다.

참고: 클론은 소스 데이터셋에서 대상 데이터셋으로 예제를 복사합니다. 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 패턴과 일치하지 않을 때 일치, 또는 태그 키가 없으면 일치

팁: allow 정책에서 _if_exists 변형은 조건과 일치하거나 지정된 태그 키가 없는 리소스에 접근을 허용합니다. deny 정책에서는 조건과 일치하거나 태그 키가 없는 리소스를 차단합니다.

Roles

role_ids 배열은 정책이 적용되는 워크스페이스 역할을 지정합니다. 해당 역할의 사용자가 리소스에 접근하면 정책 조건이 평가됩니다.

정책은 생성 시 워크스페이스 역할(기본 제공 또는 커스텀)에 연결하거나, 나중에 API로 연결할 수 있습니다.

접근 정책 관리

접근 정책은 Organization Admins이 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 승리)

예시 시나리오

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 논리)

두 조건이 모두 충족될 때만 접근을 허용합니다 - 데이터셋이 훈련용 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 매개변수를 사용해 태그를 직접 제공할 수 있습니다.

이는 프로젝트, 데이터셋, 프롬프트 생성 엔드포인트(fork 및 clone 작업 포함)에서 지원됩니다. 태그는 리소스 생성과 동일한 데이터베이스 트랜잭션에서 원자적으로 적용됩니다.

전체 내용과 예시는 리소스 태그 가이드의 생성 시 리소스 태그 지정을 참고하세요.

참고: 트레이스 수집 중 LangSmith SDK가 트레이싱 프로젝트를 자동 생성하는 데 의존한다면, 해당 자동 생성 경로에서는 tag_value_ids 매개변수를 사용할 수 없습니다. ABAC 정책이 처음부터 적용되도록 하려면, 트레이스 세션을 시작하기 전에 원하는 tag_value_ids로 POST /api/v1/sessions를 통해 프로젝트를 미리 생성하세요.

문제 해결

예상치 못한 접근 거부?

deny 정책이 일치하는지 확인하세요 (deny는 항상 우선).
사용자가 RBAC 권한 또는 일치하는 allow 정책이 있는지 확인하세요.
리소스에 예상된 태그와 값이 있는지 확인하세요.
_if_exists 연산자를 가진 deny 정책은 해당 태그 키가 없는 리소스를 차단합니다.
대소문자 구분 연산자(equals, not_equals)의 경우 대소문자 불일치를 확인하세요.
그룹에 여러 조건이 있으면 모두 일치해야 합니다 (AND 논리).

예상치 못한 접근 허용?

RBAC 권한을 검토하세요 (사용자가 자신의 역할로 접근권을 가질 수 있음).
allow 정책이 너무 광범위한지 확인하세요 (예: 와일드카드 사용).
_if_exists 연산자는 해당 태그 키가 없는 리소스를 일치시킵니다.

정책이 적용되지 않습니까?

정책이 올바른 역할에 연결되어 있는지 확인하세요.
사용자가 워크스페이스에서 해당 역할을 가졌는지 확인하세요.
resource_type과 permission이 접근하는 리소스와 일치하는지 확인하세요.

더 알아보기

RBAC 개념은 Role-based access control 문서를 참고하세요.
리소스 태그 설정은 Set up resource tags 문서를 확인해 보세요.

속성 기반 접근 제어