› › ›

Определение ролей

Роль определяется следующей JSON-структурой:

{
  "run_as": [ ... ], 
  "cluster": [ ... ], 
  "global": { ... }, 
  "indices": [ ... ], 
  "applications": [ ... ], 
  "remote_indices": [ ... ], 
  "remote_cluster": [ ... ], 
  "metadata": { ... }, 
  "description": "..." 
}

	Список имён пользователей, от имени которых владельцы этой роли могут выступать.
	Список привилегий кластера. Эти привилегии определяют действия на уровне кластера, которые пользователи с этой ролью могут выполнять. Это поле необязательно (отсутствие `cluster` привилегий фактически означает отсутствие разрешений на уровне кластера).
	Объект, определяющий глобальные привилегии. Глобальная привилегия — это тип привилегии кластера, чувствительный к запросу. Стандартная привилегия кластера принимает решения об авторизации, основываясь только на выполняемом действии. Глобальная привилегия также учитывает параметры, включенные в запрос. Поддержка глобальных привилегий в настоящее время ограничена управлением привилегиями приложений. Это поле необязательно.
	Список записей разрешений индексов. Это поле необязательно (отсутствие `indices` привилегий фактически означает отсутствие разрешений на уровне индексов).
	Список записей привилегий приложений. Это поле необязательно.
	Список записей разрешений индексов для удаленных кластеров, настроенных с использованием модели на основе API-ключа. Это поле необязательно (отсутствие `remote_indices` привилегий фактически означает отсутствие разрешений на уровне индексов для любых удалённых кластеров на основе API-ключа).
	Список записей разрешений кластера для удаленных кластеров, настроенных с использованием модели на основе API-ключа. Это поле необязательно (отсутствие `remote_cluster` привилегий фактически означает отсутствие дополнительных разрешений кластера для любых удалённых кластеров на основе API-ключа).
	Поле метаданных, связанное с ролью, например, `metadata.app_tag`. Метаданные индексируются внутри как поля flattened. Это означает, что все подполя ведут себя как `keyword` поля при запросах и сортировке. Значения метаданных могут быть простыми значениями, а также списками и картами. Это поле необязательно.
	Строковое значение с текстовым описанием роли. Максимальная длина — `1000` символов. Поле индексируется внутри как текстовое поле (с значениями по умолчанию для всех параметров). Это поле необязательно.

Имена ролей должны содержать от 1 до 507 символов. Они могут содержать буквенно-цифровые символы (a-z, A-Z, 0-9), пробелы, знаки препинания и печатные символы из блока Basic Latin (ASCII). Пробелы в начале или конце не допускаются.

Привилегии индексов

Ниже описана структура записи разрешений индексов:

{
  "names": [ ... ], 
  "privileges": [ ... ], 
  "field_security" : { ... }, 
  "query": "...", 
  "allow_restricted_indices": false 
}

	Список потоков данных, индексов и алиасов, к которым применяются разрешения в этой записи. Поддерживаются подстановочные знаки (`*`).
	Разрешения на уровне индекса, которыми владельцы роли обладают для связанных потоков данных и индексов, указанных в аргументе `names`.
	Описание полей документов, к которым владельцы роли имеют доступ для чтения. Подробности см. в Настройка безопасности на уровне полей и документов.
	Запрос поиска, который определяет документы, к которым владельцы роли имеют доступ для чтения. Документ внутри связанных потоков данных и индексов должен соответствовать этому запросу, чтобы к нему могли получить доступ владельцы роли.
	Ограниченные индексы — это специальная категория индексов, используемых внутри для хранения конфигурационных данных, к которым не следует напрямую обращаться. Только внутренние системные роли обычно должны предоставлять разрешения на ограниченные индексы. Настройка этого флага крайне не рекомендуется, поскольку это может предоставить неограниченные операции с критическими данными, сделав всю систему нестабильной или утекая конфиденциальную информацию. Однако, если для административных целей вам необходимо создать роль с разрешениями, охватывающими ограниченные индексы, необходимо установить это поле в `true` (по умолчанию `false`), а затем поле `names` будет охватывать и ограниченные индексы.

Параметр names принимает подстановочные знаки и регулярные выражения, которые могут ссылаться на несколько потоков данных, индексов и алиасов.

Подстановочные знаки (по умолчанию) — простое сопоставление подстановочных знаков, где * — заполнитель для нуля или более символов, ? — заполнитель для одного символа, и \ может использоваться в качестве символа экранирования.
Регулярные выражения — более мощная синтаксическая конструкция для сопоставления более сложных шаблонов. Это регулярное выражение основано на синтаксисе автомата регулярных выражений Lucene. Для включения этого синтаксиса он должен быть заключён в пару прямых слэшей (/). Любой шаблон, начинающийся с / и не заканчивающийся /, считается некорректным.

Примеры регулярных выражений.

"foo-bar":               # match the literal `foo-bar`
"foo-*":                 # match anything beginning with "foo-"
"logstash-201?-*":       # ? matches any one character
"/.*-201[0-9]-.*/":      # use a regex to match anything containing 2010-2019
"/foo":                  # syntax error - missing final /

Глобальные привилегии

Ниже описана структура записи глобальных привилегий:

{
  "application": {
    "manage": {    
      "applications": [ ... ] 
    }
  },
  "profile": {
    "write": { 
      "applications": [ ... ] 
    }
  }
}

	Привилегия для управления привилегиями приложений
	Список имён приложений, которые можно управлять. Этот список поддерживает подстановочные знаки (например, `"myapp-"`) и регулярные выражения (например, `"/app[0-9]/"`).
	Привилегия для возможности записи `access` и `data` любого профиля пользователя
	Список имён, подстановочных знаков и регулярных выражений, к которым ограничено право записи

Привилегии приложений

Ниже описана структура записи привилегий приложений:

{
  "application": "my_app", 
  "privileges": [ ... ],   
  "resources": [ ... ]     
}

	Имя приложения.
	Список имён привилегий приложения, которые необходимо предоставить этой роли.
	Ресурсы, к которым применяются эти привилегии. Они обрабатываются так же, как и шаблоны имён индексов в разрешениях `indices`. Эти ресурсы не имеют специального значения для функций безопасности Elasticsearch.

Подробные сведения о правилах проверки для этих полей см. в API добавления привилегий приложений.

Роль может ссылаться на привилегии приложений, которых не существует — то есть они ещё не были определены с помощью API добавления привилегий приложений (или они были определены, но с тех пор были удалены). В этом случае привилегия не оказывает никакого действия и не предоставит никаких действий в API проверки наличия привилегий.

Привилегии удаленных индексов

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

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

Запись привилегий удаленных индексов имеет дополнительное обязательное поле clusters по сравнению с записью привилегий индексов. В остальном, структура двух записей идентична. Ниже приведена структура записи разрешений удаленных индексов:

{
  "clusters": [ ... ], 
  "names": [ ... ], 
  "privileges": [ ... ], 
  "field_security" : { ... }, 
  "query": "...", 
  "allow_restricted_indices": false 
}

	Список псевдонимов удаленных кластеров. Поддерживаются строковые значения, а также маски и регулярные выражения. Это поле обязательно.
	Список потоков данных, индексов и псевдонимов, к которым применяются разрешения в этой записи. Поддерживаются маски (`*`).
	Привилегии уровня индекса, которые владельцы роли имеют на соответствующие потоки данных и индексы, указанные в аргументе `names`.
	Указание полей документов, к которым владельцы роли имеют доступ для чтения. Подробности см. в разделе Настройка безопасности на уровне полей и документов.
	Запрос поиска, определяющий документы, к которым владельцы роли имеют доступ для чтения. Документ в соответствующих потоках данных и индексах должен соответствовать этому запросу, чтобы он был доступен владельцам роли.
	Ограниченные индексы — это специальная категория индексов, используемых для хранения конфигурационных данных и к которым не следует напрямую обращаться. Обычно только внутренние системные роли должны предоставлять разрешения на ограниченные индексы. Категорически не рекомендуется изменять этот флаг, так как это может предоставить неограниченные операции с критическими данными, сделав всю систему неустойчивой или раскрывая конфиденциальную информацию. Однако, если в административных целях вам необходимо создать роль с привилегиями, охватывающими ограниченные индексы, необходимо установить это поле в значение `true` (по умолчанию `false`), а затем поле `names` будет охватывать также и ограниченные индексы.

Привилегии удаленного кластера

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

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

Ниже приведена структура записи разрешений удаленного кластера:

{
  "clusters": [ ... ], 
  "privileges": [ ... ] 
}

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

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

Пример

Следующий фрагмент показывает пример определения роли clicks_admin:

resp = client.security.put_role(
    name="clicks_admin",
    run_as=[
        "clicks_watcher_1"
    ],
    cluster=[
        "monitor"
    ],
    indices=[
        {
            "names": [
                "events-*"
            ],
            "privileges": [
                "read"
            ],
            "field_security": {
                "grant": [
                    "category",
                    "@timestamp",
                    "message"
                ]
            },
            "query": "{\"match\": {\"category\": \"click\"}}"
        }
    ],
)
print(resp)

const response = await client.security.putRole({
  name: "clicks_admin",
  run_as: ["clicks_watcher_1"],
  cluster: ["monitor"],
  indices: [
    {
      names: ["events-*"],
      privileges: ["read"],
      field_security: {
        grant: ["category", "@timestamp", "message"],
      },
      query: '{"match": {"category": "click"}}',
    },
  ],
});
console.log(response);

POST /_security/role/clicks_admin
{
  "run_as": [ "clicks_watcher_1" ],
  "cluster": [ "monitor" ],
  "indices": [
    {
      "names": [ "events-*" ],
      "privileges": [ "read" ],
      "field_security" : {
        "grant" : [ "category", "@timestamp", "message" ]
      },
      "query": "{\"match\": {\"category\": \"click\"}}"
    }
  ]
}

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

Имитировать пользователя clicks_watcher_1 и выполнять запросы от его имени.
Мониторить кластер Elasticsearch
Читать данные из всех индексов, начинающихся с events-
В этих индексах читать только события категории click
В этих документах читать только поля category, @timestamp и message.

Полный список доступных привилегий кластера и индексов

Существует два способа определения ролей: с помощью API управления ролями или в локальных файлах на узлах Elasticsearch. Вы также можете реализовать пользовательские провайдеры ролей. Если вам необходимо интегрировать с другой системой для получения ролей пользователей, вы можете создать пользовательский плагин провайдера ролей. Дополнительная информация в разделе Настройка ролей и авторизации.

Пользовательский интерфейс управления ролями

Вы можете легко управлять пользователями и ролями в Kibana. Для управления ролями войдите в Kibana и перейдите в раздел Управление / Безопасность / Роли.

API управления ролями

API управления ролями позволяют динамически добавлять, обновлять, удалять и получать роли. При использовании API для управления ролями в области native роли хранятся во внутреннем индексе Elasticsearch. Более подробная информация и примеры в разделе Роли.

Управление ролями в файлах

Помимо API управления ролями, роли также можно определить в локальном файле roles.yml, расположенном в ES_PATH_CONF. Это YAML-файл, где каждая роль определяется по имени.

Если одно и то же имя роли используется в файле roles.yml и через API управления ролями, будет использоваться роль из файла.

Хотя API управления ролями является предпочтительным способом определения ролей, использование файла roles.yml становится полезным, если вы хотите определить фиксированные роли, которые никто (кроме администратора с физическим доступом к узлам Elasticsearch) не сможет изменить. Однако обратите внимание, что файл roles.yml предоставлен в качестве минимальной административной функции и не предназначен для охвата и использования для определения ролей во всех сценариях.

Вы не можете просматривать, редактировать или удалять роли, определенные в файле roles.yml, используя пользовательский интерфейс управления ролями или API управления ролями.

Файл roles.yml управляется локально узлом и не является глобальным для кластера. Это означает, что с типичным многоузловым кластером необходимо применять те же изменения на каждом узле кластера.

Более безопасный подход — применить изменение на одном из узлов и распределить/скопировать roles.yml на все остальные узлы кластера (как вручную, так и с помощью системы управления конфигурацией, такой как Puppet или Chef).

Следующий фрагмент показывает пример конфигурации файла roles.yml:

click_admins:
  run_as: [ 'clicks_watcher_1' ]
  cluster: [ 'monitor' ]
  indices:
    - names: [ 'events-*' ]
      privileges: [ 'read' ]
      field_security:
        grant: ['category', '@timestamp', 'message' ]
      query: '{"match": {"category": "click"}}'

Elasticsearch непрерывно отслеживает файл roles.yml и автоматически подбирает и применяет любые изменения в нём.

© 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/defining-roles.html