› › ›

API создания или обновления ролей

Добавляет и обновляет роли в родном домене.

Запрос

POST /_security/role/<name>

PUT /_security/role/<name>

Предварительные условия

Для использования этого API у вас должен быть хотя бы manage_security привилегий кластера.

Описание

API управления ролями, как правило, предпочтительнее, чем использование управления ролями на основе файлов. API создания или обновления ролей не может обновлять роли, определённые в файлах ролей.

Параметры пути

name: (строка) Название роли.

Тело запроса

В теле запроса PUT или POST можно указать следующие параметры, относящиеся к добавлению роли:

applications

(список) Список записей привилегий приложения.

application (обязательно): (строка) Название приложения, к которому относится эта запись
privileges: (список) Список строк, где каждый элемент — имя привилегии или действия приложения.
resources: (список) Список ресурсов, к которым применяются привилегии.

cluster

(список) Список привилегий кластера. Эти привилегии определяют действия на уровне кластера, которые пользователи с этой ролью могут выполнять.

description

(строка) Описание роли. Максимальная длина — 1000 символов.

global

(объект) Объект, определяющий глобальные привилегии. Глобальная привилегия — это форма привилегии кластера, которая учитывает запрос. Поддержка глобальных привилегий в настоящее время ограничена управлением привилегиями приложения. Это поле необязательно.

indices

(список) Список записей разрешений индексов.

field_security: (объект) Поля документов, к которым владельцы роли имеют доступ для чтения. Дополнительная информация в разделе настройки безопасности на уровне полей и документов.
names (обязательно): (список) Список индексов (или шаблонов имён индексов), к которым применяются разрешения в этой записи.
privileges (обязательно): (список) Разрешения на уровне индекса, которыми владельцы роли обладают для указанных индексов.
query: Запрос поиска, определяющий документы, к которым владельцы роли имеют доступ для чтения. Документ в указанных индексах должен соответствовать этому запросу, чтобы он был доступен владельцам роли.

metadata

(объект) Необязательные метаданные. Внутри объекта metadata ключи, начинающиеся с _, зарезервированы для использования системой.

run_as

(список) Список пользователей, от имени которых владельцы этой роли могут действовать. Дополнительная информация в разделе выполнения запросов от имени других пользователей.

remote_indices

(список) Список записей разрешений удалённых индексов.

Удалённые индексы эффективны для удаленных кластеров, настроенных по модели API-ключей. Они не влияют на удалённые кластеры, настроенные по модели сертификатов.

clusters (обязательно): (список) Список псевдонимов кластеров, к которым применяются разрешения в этой записи.
field_security: (объект) Поля документов, к которым владельцы роли имеют доступ для чтения. Дополнительная информация в разделе настройки безопасности на уровне полей и документов.
names (обязательно): (список) Список индексов (или шаблонов имён индексов) в удалённых кластерах (указанных с clusters), к которым применяются разрешения в этой записи.
privileges (обязательно): (список) Разрешения на уровне индекса, которыми владельцы роли обладают для указанных индексов.
query: Запрос поиска, определяющий документы, к которым владельцы роли имеют доступ для чтения. Документ в указанных индексах должен соответствовать этому запросу, чтобы он был доступен владельцам роли.

remote_cluster

(список) Список записей разрешений удалённых кластеров.

Разрешения удалённых кластеров эффективны для удаленных кластеров, настроенных по модели API-ключей. Они не влияют на удалённые кластеры, настроенные по модели сертификатов.

clusters (обязательно): (список) Список псевдонимов кластеров, к которым применяются разрешения в этой записи.
privileges (обязательно): (список) Разрешения на уровне кластера, которыми владельцы роли обладают в указанных кластерах. Примечание — для удалённых кластеров поддерживается только подмножество привилегий кластера. API встроенных привилегий можно использовать для определения разрешённых привилегий по версии.

Дополнительная информация в разделе определения ролей.

Примеры

В следующем примере добавляется роль под названием my_admin_role:

resp = client.security.put_role(
    name="my_admin_role",
    description="Grants full access to all management features within the cluster.",
    cluster=[
        "all"
    ],
    indices=[
        {
            "names": [
                "index1",
                "index2"
            ],
            "privileges": [
                "all"
            ],
            "field_security": {
                "grant": [
                    "title",
                    "body"
                ]
            },
            "query": "{\"match\": {\"title\": \"foo\"}}"
        }
    ],
    applications=[
        {
            "application": "myapp",
            "privileges": [
                "admin",
                "read"
            ],
            "resources": [
                "*"
            ]
        }
    ],
    run_as=[
        "other_user"
    ],
    metadata={
        "version": 1
    },
)
print(resp)

const response = await client.security.putRole({
  name: "my_admin_role",
  description:
    "Grants full access to all management features within the cluster.",
  cluster: ["all"],
  indices: [
    {
      names: ["index1", "index2"],
      privileges: ["all"],
      field_security: {
        grant: ["title", "body"],
      },
      query: '{"match": {"title": "foo"}}',
    },
  ],
  applications: [
    {
      application: "myapp",
      privileges: ["admin", "read"],
      resources: ["*"],
    },
  ],
  run_as: ["other_user"],
  metadata: {
    version: 1,
  },
});
console.log(response);

POST /_security/role/my_admin_role
{
  "description": "Grants full access to all management features within the cluster.",
  "cluster": ["all"],
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": ["all"],
      "field_security" : { // optional
        "grant" : [ "title", "body" ]
      },
      "query": "{\"match\": {\"title\": \"foo\"}}" // optional
    }
  ],
  "applications": [
    {
      "application": "myapp",
      "privileges": [ "admin", "read" ],
      "resources": [ "*" ]
    }
  ],
  "run_as": [ "other_user" ], // optional
  "metadata" : { // optional
    "version" : 1
  }
}

Успешный вызов возвращает JSON-структуру, показывающую, была ли роль создана или обновлена.

{
  "role": {
    "created": true 
  }
}

При обновлении существующей роли created устанавливается в false.

Следующий пример настраивает роль, которая может запускать SQL в JDBC:

resp = client.security.put_role(
    name="cli_or_drivers_minimal",
    cluster=[
        "cluster:monitor/main"
    ],
    indices=[
        {
            "names": [
                "test"
            ],
            "privileges": [
                "read",
                "indices:admin/get"
            ]
        }
    ],
)
print(resp)

const response = await client.security.putRole({
  name: "cli_or_drivers_minimal",
  cluster: ["cluster:monitor/main"],
  indices: [
    {
      names: ["test"],
      privileges: ["read", "indices:admin/get"],
    },
  ],
});
console.log(response);

POST /_security/role/cli_or_drivers_minimal
{
  "cluster": ["cluster:monitor/main"],
  "indices": [
    {
      "names": ["test"],
      "privileges": ["read", "indices:admin/get"]
    }
  ]
}

Следующий пример настраивает роль с разрешениями на удалённые индексы и удалённый кластер для удалённого кластера:

resp = client.security.put_role(
    name="only_remote_access_role",
    remote_indices=[
        {
            "clusters": [
                "my_remote"
            ],
            "names": [
                "logs*"
            ],
            "privileges": [
                "read",
                "read_cross_cluster",
                "view_index_metadata"
            ]
        }
    ],
    remote_cluster=[
        {
            "clusters": [
                "my_remote"
            ],
            "privileges": [
                "monitor_stats"
            ]
        }
    ],
)
print(resp)

const response = await client.security.putRole({
  name: "only_remote_access_role",
  remote_indices: [
    {
      clusters: ["my_remote"],
      names: ["logs*"],
      privileges: ["read", "read_cross_cluster", "view_index_metadata"],
    },
  ],
  remote_cluster: [
    {
      clusters: ["my_remote"],
      privileges: ["monitor_stats"],
    },
  ],
});
console.log(response);

POST /_security/role/only_remote_access_role
{
  "remote_indices": [
    {
      "clusters": ["my_remote"], 
      "names": ["logs*"], 
      "privileges": ["read", "read_cross_cluster", "view_index_metadata"] 
    }
  ],
  "remote_cluster": [
    {
      "clusters": ["my_remote"], 
      "privileges": ["monitor_stats"]  
    }
  ]
}

	Удалённые индексы и разрешения удалённого кластера применяются к удалённому кластеру с псевдонимом `my_remote`.
	Разрешения предоставляются для индексов, соответствующих шаблону `logs*` в удалённом кластере (`my_remote`).
	Фактические разрешения на индексы, предоставленные для `logs*` в `my_remote`.
	Фактические разрешения на кластер, предоставленные для `my_remote`. Примечание — для удалённых кластеров поддерживается только подмножество привилегий кластера.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-put-role.html