Create or Update Role API

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

역할 생성 또는 업데이트 API

1.0에 도입됨 {: .label .label-purple }

지정된 역할을 생성하거나 대체해요.

엔드포인트

PUT /_plugins/_security/api/roles/{role}

요청 본문 필드

요청 본문은 필수예요. 다음 필드를 포함하는 JSON 객체예요.

필드	데이터 타입	설명	필수
`cluster_permissions`	Array of strings	역할이 허용하는 클러스터 수준 작업이에요. `indices:admin/create`와 같은 개별 작업 또는 `cluster_composite_ops`와 같은 작업 그룹을 지정해요.	아니요
`index_permissions`	Array of objects	역할이 부여하는 인덱스 수준 권한이에요. 각 객체는 `index_patterns`, `allowed_actions`, 그리고 선택적으로 `dls`, `fls`, `masked_fields`를 포함해요.	아니요
`tenant_permissions`	Array of objects	역할이 부여하는 테넌트 수준 권한이에요. 각 객체는 `tenant_patterns`와 `allowed_actions`를 포함해요.	아니요
`description`	String	역할에 대한 설명이에요.	아니요
`hidden`	Boolean	역할이 API 및 OpenSearch Dashboards에서 숨겨지는지 여부예요. 기본값은 `false`예요.	아니요
`reserved`	Boolean	역할이 읽기 전용이고 수정할 수 없는지 여부예요. 기본값은 `false`예요.	아니요

index_permissions 객체는 다음 필드를 포함해요.

필드	데이터 타입	설명	필수
`index_patterns`	Array of strings	권한이 적용되는 인덱스예요. `movies*`와 같은 와일드카드 패턴을 지원해요.	예
`allowed_actions`	Array of strings	역할이 허용하는 인덱스 수준 작업이에요. `indices:data/read/search`와 같은 개별 작업 또는 `read`와 같은 작업 그룹을 지정해요.	예
`dls`	String	역할이 읽을 수 있는 문서를 제한하는 쿼리(문자열)예요. 자세한 내용은 문서 수준 보안을 참조해요.	아니요
`fls`	Array of strings	역할이 읽을 수 있는 문서 필드예요. 필드 앞에 `~`를 붙이면 제외해요. 자세한 내용은 필드 수준 보안을 참조해요.	아니요
`masked_fields`	Array of strings	익명화할 문서 필드예요. 자세한 내용은 필드 마스킹을 참조해요.	아니요

tenant_permissions 객체는 다음 필드를 포함해요.

필드	데이터 타입	설명	필수
`tenant_patterns`	Array of strings	권한이 적용되는 테넌트예요. 와일드카드 패턴을 지원해요.	예
`allowed_actions`	Array of strings	역할이 허용하는 테넌트 수준 작업이에요. 유효한 값은 `kibana_all_read`와 `kibana_all_write`예요.	예

문서 수준 또는 필드 수준 보안 규칙이 text 필드를 대상으로 하면 표준 분석기가 유니코드 특수 문자에서 필드 값을 분할해요. 그래서 특수 문자를 포함하는 값이 여러 토큰으로 인덱싱돼요.

예를 들어, "user.id": "User-1"과 "user.id": "User-2" 값은 모두 하이픈을 포함해요. 그래서 분석기가 두 사용자를 구분할 수 없고 동일한 값으로 처리해요. 이로 인해 의도치 않게 문서가 필터링되어 규칙이 숨기려고 했던 문서에 접근을 허용할 수 있어요.

이를 방지하려면 사용자 지정 분석기를 사용하거나 필드를 keyword로 매핑하여 정확히 일치하는 검색을 수행해요. text 필드에서 피해야 할 문자 목록은 Word boundaries를 참조해요. {: .warning}

요청 예시

PUT _plugins/_security/api/roles/test-role
{
  "cluster_permissions": [
    "cluster_composite_ops",
    "indices_monitor"
  ],
  "index_permissions": [
    {
      "index_patterns": [
        "movies*"
      ],
      "dls": "",
      "fls": [],
      "masked_fields": [],
      "allowed_actions": [
        "read"
      ]
    }
  ],
  "tenant_permissions": [
    {
      "tenant_patterns": [
        "human_resources"
      ],
      "allowed_actions": [
        "kibana_all_read"
      ]
    }
  ]
}

{% include copy-curl.html security=true %}

응답 예시

{
  "status": "CREATED",
  "message": "'test-role' created."
}

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/security/api/roles/create-role/