› › ›

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

Массовое добавление и обновление ролей в родном домене.

Запрос

POST /_security/role/

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

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

Описание

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

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

refresh: Необязательная настройка политики обновления для запроса записи. По умолчанию — Немедленно.

Тело запроса

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

roles: (объект) Роли для добавления в качестве имени роли к карте ролей.

<role_name> (обязательно)

(строка) Имя роли.

applications

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

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

cluster

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

global

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

indices

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

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

metadata

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

run_as

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

remote_indices

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

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

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

remote_cluster

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

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

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

Дополнительную информацию см. в разделе об определении ролей.

Примеры

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

resp = client.security.bulk_put_role(
    roles={
        "my_admin_role": {
            "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
            }
        },
        "my_user_role": {
            "cluster": [
                "all"
            ],
            "indices": [
                {
                    "names": [
                        "index1"
                    ],
                    "privileges": [
                        "read"
                    ],
                    "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.bulkPutRole({
  roles: {
    my_admin_role: {
      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,
      },
    },
    my_user_role: {
      cluster: ["all"],
      indices: [
        {
          names: ["index1"],
          privileges: ["read"],
          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
{
    "roles": {
        "my_admin_role": {
            "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
            }
        },
        "my_user_role": {
            "cluster": [
                "all"
            ],
            "indices": [
                {
                    "names": [
                        "index1"
                    ],
                    "privileges": [
                        "read"
                    ],
                    "field_security": {
                        "grant": [
                            "title",
                            "body"
                        ]
                    },
                    "query": "{\"match\": {\"title\": \"foo\"}}"
                }
            ],
            "applications": [
                {
                    "application": "myapp",
                    "privileges": [
                        "admin",
                        "read"
                    ],
                    "resources": [
                        "*"
                    ]
                }
            ],
            "run_as": [
                "other_user"
            ],
            "metadata": {
                "version": 1
            }
        }
    }
}

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

{
    "created": [ 
        "my_admin_role", 
        "my_user_role"
    ]
}

	Тип результата, один из `created`, `updated`, `noop`, `errors`.
	Список ролей, которые были созданы.

Поскольку ошибки обрабатываются индивидуально для каждого создания или обновления роли, API позволяет частичный успех.

Следующий запрос вызовет ошибку для my_admin_role, потому что привилегия bad_cluster_privilege не существует, но будет успешен для my_user_role.

resp = client.security.bulk_put_role(
    roles={
        "my_admin_role": {
            "cluster": [
                "bad_cluster_privilege"
            ],
            "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
            }
        },
        "my_user_role": {
            "cluster": [
                "all"
            ],
            "indices": [
                {
                    "names": [
                        "index1"
                    ],
                    "privileges": [
                        "read"
                    ],
                    "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.bulkPutRole({
  roles: {
    my_admin_role: {
      cluster: ["bad_cluster_privilege"],
      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,
      },
    },
    my_user_role: {
      cluster: ["all"],
      indices: [
        {
          names: ["index1"],
          privileges: ["read"],
          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
{
    "roles": {
        "my_admin_role": {
            "cluster": [
                "bad_cluster_privilege"
            ],
            "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
            }
        },
        "my_user_role": {
            "cluster": [
                "all"
            ],
            "indices": [
                {
                    "names": [
                        "index1"
                    ],
                    "privileges": [
                        "read"
                    ],
                    "field_security": {
                        "grant": [
                            "title",
                            "body"
                        ]
                    },
                    "query": "{\"match\": {\"title\": \"foo\"}}"
                }
            ],
            "applications": [
                {
                    "application": "myapp",
                    "privileges": [
                        "admin",
                        "read"
                    ],
                    "resources": [
                        "*"
                    ]
                }
            ],
            "run_as": [
                "other_user"
            ],
            "metadata": {
                "version": 1
            }
        }
    }
}

Результат будет иметь поле errors со значением true и содержать ошибку для обновления my_admin_role.

{
    "created": [
        "my_user_role" 
    ],
    "errors": { 
        "count": 1, 
        "details": {
            "my_admin_role": { 
                "type": "action_request_validation_exception",
                "reason": "Validation Failed: 1: unknown cluster privilege [bad_cluster_privilege]. a privilege must be either one of the predefined cluster privilege names [manage_own_api_key,manage_data_stream_global_retention,monitor_data_stream_global_retention,none,cancel_task,cross_cluster_replication,cross_cluster_search,delegate_pki,grant_api_key,manage_autoscaling,manage_index_templates,manage_logstash_pipelines,manage_oidc,manage_saml,manage_search_application,manage_search_query_rules,manage_search_synonyms,manage_service_account,manage_token,manage_user_profile,monitor_connector,monitor_enrich,monitor_inference,monitor_ml,monitor_rollup,monitor_snapshot,monitor_stats,monitor_text_structure,monitor_watcher,post_behavioral_analytics_event,read_ccr,read_connector_secrets,read_fleet_secrets,read_ilm,read_pipeline,read_security,read_slm,transport_client,write_connector_secrets,write_fleet_secrets,create_snapshot,manage_behavioral_analytics,manage_ccr,manage_connector,manage_enrich,manage_ilm,manage_inference,manage_ml,manage_rollup,manage_slm,manage_watcher,monitor_data_frame_transforms,monitor_transform,manage_api_key,manage_ingest_pipelines,manage_pipeline,manage_data_frame_transforms,manage_transform,manage_security,monitor,manage,all] or a pattern over one of the available cluster actions;"
            }
        }
    }
}

	Успешно созданная роль.
	Встреченные ошибки.
	Количество запросов на размещение роли, которые завершились ошибкой.
	Ошибка, связанная с именем роли.

© 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-bulk-put-role.html