› › ›

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

Создаёт и обновляет сопоставления ролей.

Запрос

POST /_security/role_mapping/<name>

PUT /_security/role_mapping/<name>

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

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

Описание

Сопоставления ролей определяют, какие роли назначаются каждому пользователю. Каждое сопоставление имеет правила, определяющие пользователей, и список ролей, предоставляемых этим пользователям.

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

Это API не создаёт роли. Вместо этого оно сопоставляет пользователей с существующими ролями. Роли можно создавать с помощью API создания или обновления ролей или файлов управления ролями.

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

Шаблоны ролей

Наиболее распространённое использование сопоставлений ролей — создание сопоставления из известного значения пользователя с фиксированным именем роли. Например, все пользователи в группе cn=admin,dc=example,dc=com LDAP должны получить роль superuser в Elasticsearch. Для этой цели используется поле roles.

Для более сложных задач можно использовать шаблоны Mustache для динамического определения имён ролей, которые должны быть предоставлены пользователю. Для этой цели используется поле role_templates.

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

Все доступные поля пользователей в сопоставлении ролей rules также доступны в шаблонах ролей. Таким образом, можно назначить пользователю роль, отражающую их username, их groups или имя realm, с которым они авторизовались.

По умолчанию шаблон оценивается для создания одной строки, представляющей имя роли, которое должно быть назначено пользователю. Если format шаблона установлено в значение "json", ожидается, что шаблон выведет строку JSON или массив строк JSON для имён ролей.

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

name: (строка) Уникальное имя, идентифицирующее сопоставление ролей. Имя используется только для идентификации при взаимодействии через API; оно никак не влияет на поведение сопоставления.

Тело запроса

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

enabled: (Обязательно, логическое значение) Сопоставления, у которых enabled установлено в значение false, игнорируются при выполнении сопоставления ролей.
metadata: (объект) Дополнительные метаданные, которые помогают определить, какие роли назначаются каждому пользователю. В объекте metadata ключи, начинающиеся с _, зарезервированы для использования системой.
roles: (список строк) Список имён ролей, которые предоставляются пользователям, соответствующим правилам сопоставления ролей. Необходимо указать точно один из параметров roles или role_templates.
role_templates: (список объектов) Список шаблонов Mustache, которые будут вычисляться для определения имён ролей, которые должны предоставляться пользователям, соответствующим правилам сопоставления ролей. Формат этих объектов определён ниже. Необходимо указать точно один из параметров roles или role_templates.
rules: (Обязательно, объект) Правила, определяющие, какие пользователи должны быть сопоставлены с помощью сопоставления. Правило — логическое условие, выраженное с использованием JSON DSL. См. ресурсы сопоставления ролей.

Примеры

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

resp = client.security.put_role_mapping(
    name="mapping1",
    roles=[
        "user"
    ],
    enabled=True,
    rules={
        "field": {
            "username": "*"
        }
    },
    metadata={
        "version": 1
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping1",
  roles: ["user"],
  enabled: true,
  rules: {
    field: {
      username: "*",
    },
  },
  metadata: {
    version: 1,
  },
});
console.log(response);

POST /_security/role_mapping/mapping1
{
  "roles": [ "user"],
  "enabled": true, 
  "rules": {
    "field" : { "username" : "*" }
  },
  "metadata" : { 
    "version" : 1
  }
}

	Сопоставления, у которых `enabled` установлено в `false`, игнорируются при выполнении сопоставления ролей.
	Метаданные необязательны.

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

{
  "role_mapping" : {
    "created" : true 
  }
}

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

В следующем примере пользователям назначаются роли "user" и "admin":

resp = client.security.put_role_mapping(
    name="mapping2",
    roles=[
        "user",
        "admin"
    ],
    enabled=True,
    rules={
        "field": {
            "username": [
                "esadmin01",
                "esadmin02"
            ]
        }
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping2",
  roles: ["user", "admin"],
  enabled: true,
  rules: {
    field: {
      username: ["esadmin01", "esadmin02"],
    },
  },
});
console.log(response);

POST /_security/role_mapping/mapping2
{
  "roles": [ "user", "admin" ],
  "enabled": true,
  "rules": {
     "field" : { "username" : [ "esadmin01", "esadmin02" ] }
  }
}

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

resp = client.security.put_role_mapping(
    name="mapping3",
    roles=[
        "ldap-user"
    ],
    enabled=True,
    rules={
        "field": {
            "realm.name": "ldap1"
        }
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping3",
  roles: ["ldap-user"],
  enabled: true,
  rules: {
    field: {
      "realm.name": "ldap1",
    },
  },
});
console.log(response);

POST /_security/role_mapping/mapping3
{
  "roles": [ "ldap-user" ],
  "enabled": true,
  "rules": {
    "field" : { "realm.name" : "ldap1" }
  }
}

В следующем примере подбираются пользователи, у которых либо имя пользователя равно esadmin, либо пользователь входит в группу cn=admin,dc=example,dc=com:

resp = client.security.put_role_mapping(
    name="mapping4",
    roles=[
        "superuser"
    ],
    enabled=True,
    rules={
        "any": [
            {
                "field": {
                    "username": "esadmin"
                }
            },
            {
                "field": {
                    "groups": "cn=admins,dc=example,dc=com"
                }
            }
        ]
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping4",
  roles: ["superuser"],
  enabled: true,
  rules: {
    any: [
      {
        field: {
          username: "esadmin",
        },
      },
      {
        field: {
          groups: "cn=admins,dc=example,dc=com",
        },
      },
    ],
  },
});
console.log(response);

POST /_security/role_mapping/mapping4
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "any": [
      {
        "field": {
          "username": "esadmin"
        }
      },
      {
        "field": {
          "groups": "cn=admins,dc=example,dc=com"
        }
      }
    ]
  }
}

Приведённый выше пример полезен, когда имена групп в вашей системе управления идентификацией (например, Active Directory или поставщик SAML-идентификации) не имеют взаимно однозначного соответствия с именами ролей в Elasticsearch. Сопоставление ролей служит для связи имени группы с именем роли.

Если есть несколько групп, можно использовать синтаксис массива для поля groups. Это соответствует любой из групп (а не всем группам):

resp = client.security.put_role_mapping(
    name="mapping4",
    roles=[
        "superuser"
    ],
    enabled=True,
    rules={
        "any": [
            {
                "field": {
                    "username": "esadmin"
                }
            },
            {
                "field": {
                    "groups": [
                        "cn=admins,dc=example,dc=com",
                        "cn=other,dc=example,dc=com"
                    ]
                }
            }
        ]
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping4",
  roles: ["superuser"],
  enabled: true,
  rules: {
    any: [
      {
        field: {
          username: "esadmin",
        },
      },
      {
        field: {
          groups: ["cn=admins,dc=example,dc=com", "cn=other,dc=example,dc=com"],
        },
      },
    ],
  },
});
console.log(response);

POST /_security/role_mapping/mapping4
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "any": [
      {
        "field": {
          "username": "esadmin"
        }
      },
      {
        "field": {
          "groups": [
               "cn=admins,dc=example,dc=com",
               "cn=other,dc=example,dc=com"
            ]
        }
      }
    ]
  }
}

Однако в редких случаях имена ваших групп могут точно совпадать с именами ролей Elasticsearch. Такое может происходить, когда ваш поставщик SAML-идентификации включает в себя собственную функцию "сопоставления групп" и может быть настроен на предоставление имён ролей Elasticsearch в атрибутах пользователя SAML.

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

Примечание

: Это следует делать только в случае, если вы намерены определить роли для всех предоставленных групп. Сопоставление пользователя с большим количеством ненужных или неопределённых ролей неэффективно и может негативно сказаться на производительности системы. Если вам нужно сопоставить только подмножество групп, следует использовать явные сопоставления.

resp = client.security.put_role_mapping(
    name="mapping5",
    role_templates=[
        {
            "template": {
                "source": "{{#tojson}}groups{{/tojson}}"
            },
            "format": "json"
        }
    ],
    rules={
        "field": {
            "realm.name": "saml1"
        }
    },
    enabled=True,
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping5",
  role_templates: [
    {
      template: {
        source: "{{#tojson}}groups{{/tojson}}",
      },
      format: "json",
    },
  ],
  rules: {
    field: {
      "realm.name": "saml1",
    },
  },
  enabled: true,
});
console.log(response);

POST /_security/role_mapping/mapping5
{
  "role_templates": [
    {
      "template": { "source": "{{#tojson}}groups{{/tojson}}" }, 
      "format" : "json" 
    }
  ],
  "rules": {
    "field" : { "realm.name" : "saml1" }
  },
  "enabled": true
}

	Функция `tojson` mustache используется для преобразования списка имён групп в допустимый JSON-массив.
	Поскольку шаблон генерирует JSON-массив, формат должен быть установлен на `json`.

Следующий пример подбирает пользователей внутри определённого поддерева LDAP:

resp = client.security.put_role_mapping(
    name="mapping6",
    roles=[
        "example-user"
    ],
    enabled=True,
    rules={
        "field": {
            "dn": "*,ou=subtree,dc=example,dc=com"
        }
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping6",
  roles: ["example-user"],
  enabled: true,
  rules: {
    field: {
      dn: "*,ou=subtree,dc=example,dc=com",
    },
  },
});
console.log(response);

POST /_security/role_mapping/mapping6
{
  "roles": [ "example-user" ],
  "enabled": true,
  "rules": {
    "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
  }
}

Следующий пример подбирает пользователей внутри определённого поддерева LDAP в определённом домене:

resp = client.security.put_role_mapping(
    name="mapping7",
    roles=[
        "ldap-example-user"
    ],
    enabled=True,
    rules={
        "all": [
            {
                "field": {
                    "dn": "*,ou=subtree,dc=example,dc=com"
                }
            },
            {
                "field": {
                    "realm.name": "ldap1"
                }
            }
        ]
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping7",
  roles: ["ldap-example-user"],
  enabled: true,
  rules: {
    all: [
      {
        field: {
          dn: "*,ou=subtree,dc=example,dc=com",
        },
      },
      {
        field: {
          "realm.name": "ldap1",
        },
      },
    ],
  },
});
console.log(response);

POST /_security/role_mapping/mapping7
{
  "roles": [ "ldap-example-user" ],
  "enabled": true,
  "rules": {
    "all": [
      { "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
      { "field" : { "realm.name" : "ldap1" } }
    ]
  }
}

Правила могут быть более сложными и включать подстановку шаблонов. Например, следующее сопоставление подбирает любого пользователя, где выполнены все эти условия:

Полное имя соответствует шаблону *,ou=admin,dc=example,dc=com, или имя пользователя равно es-admin, или имя пользователя равно es-system
пользователь входит в группу cn=people,dc=example,dc=com
у пользователя нет terminated_date

resp = client.security.put_role_mapping(
    name="mapping8",
    roles=[
        "superuser"
    ],
    enabled=True,
    rules={
        "all": [
            {
                "any": [
                    {
                        "field": {
                            "dn": "*,ou=admin,dc=example,dc=com"
                        }
                    },
                    {
                        "field": {
                            "username": [
                                "es-admin",
                                "es-system"
                            ]
                        }
                    }
                ]
            },
            {
                "field": {
                    "groups": "cn=people,dc=example,dc=com"
                }
            },
            {
                "except": {
                    "field": {
                        "metadata.terminated_date": None
                    }
                }
            }
        ]
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping8",
  roles: ["superuser"],
  enabled: true,
  rules: {
    all: [
      {
        any: [
          {
            field: {
              dn: "*,ou=admin,dc=example,dc=com",
            },
          },
          {
            field: {
              username: ["es-admin", "es-system"],
            },
          },
        ],
      },
      {
        field: {
          groups: "cn=people,dc=example,dc=com",
        },
      },
      {
        except: {
          field: {
            "metadata.terminated_date": null,
          },
        },
      },
    ],
  },
});
console.log(response);

POST /_security/role_mapping/mapping8
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "all": [
      {
        "any": [
          {
            "field": {
              "dn": "*,ou=admin,dc=example,dc=com"
            }
          },
          {
            "field": {
              "username": [ "es-admin", "es-system" ]
            }
          }
        ]
      },
      {
        "field": {
          "groups": "cn=people,dc=example,dc=com"
        }
      },
      {
        "except": {
          "field": {
            "metadata.terminated_date": null
          }
        }
      }
    ]
  }
}

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

В данном примере каждый пользователь, который авторизуется с помощью домена "cloud-saml", будет автоматически сопоставлен с двумя ролями — ролью "saml_user" и ролью, которая представляет собой имя пользователя, префикс которого равен _user_. Например, пользователю nwong будут назначены роли saml_user и _user_nwong.

resp = client.security.put_role_mapping(
    name="mapping9",
    rules={
        "field": {
            "realm.name": "cloud-saml"
        }
    },
    role_templates=[
        {
            "template": {
                "source": "saml_user"
            }
        },
        {
            "template": {
                "source": "_user_{{username}}"
            }
        }
    ],
    enabled=True,
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "mapping9",
  rules: {
    field: {
      "realm.name": "cloud-saml",
    },
  },
  role_templates: [
    {
      template: {
        source: "saml_user",
      },
    },
    {
      template: {
        source: "_user_{{username}}",
      },
    },
  ],
  enabled: true,
});
console.log(response);

POST /_security/role_mapping/mapping9
{
  "rules": { "field": { "realm.name": "cloud-saml" } },
  "role_templates": [
    { "template": { "source" : "saml_user" } }, 
    { "template": { "source" : "_user_{{username}}" } }
  ],
  "enabled": true
}

Поскольку невозможно указать roles и role_templates в одном сопоставлении ролей, мы можем применить роль с "фиксированным именем", используя шаблон без подстановок.

© 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-mapping.html