创建或更新角色映射 API
编辑创建或更新角色映射 API编辑
创建和更新角色映射。
先决条件编辑
- 要使用此 API，您必须至少具有
manage_security集群权限。
描述编辑
角色映射定义了分配给每个用户的角色。每个映射都有用于标识用户的*规则*以及授予这些用户的*角色*列表。
角色映射 API 通常是管理角色映射的首选方式，而不是使用 角色映射文件。创建或更新角色映射 API 无法更新在角色映射文件中定义的角色映射。
此 API 不会创建角色。而是将用户映射到现有角色。可以使用 创建或更新角色 API 或 角色文件 来创建角色。
有关更多信息，请参阅 将用户和组映射到角色。
角色模板编辑
角色映射最常见的用途是创建从用户上的已知值到固定角色名称的映射。例如，cn=admin,dc=example,dc=com LDAP 组中的所有用户都应在 Elasticsearch 中获得 superuser 角色。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”角色分配给所有用户
POST /_security/role_mapping/mapping1
{
"roles": [ "user"],
"enabled": true,
"rules": {
"field" : { "username" : "*" }
},
"metadata" : {
"version" : 1
}
}
成功的调用将返回一个 JSON 结构，该结构显示是创建还是更新了映射。
以下示例将“user”和“admin”角色分配给特定用户
POST /_security/role_mapping/mapping2
{
"roles": [ "user", "admin" ],
"enabled": true,
"rules": {
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
}
}
以下示例匹配针对特定领域进行身份验证的用户
POST /_security/role_mapping/mapping3
{
"roles": [ "ldap-user" ],
"enabled": true,
"rules": {
"field" : { "realm.name" : "ldap1" }
}
}
以下示例匹配用户名为 esadmin 或用户位于 cn=admin,dc=example,dc=com 组中的任何用户
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 字段使用数组语法。这将匹配任何组（而不是所有组）
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 身份提供程序包含其自己的“组映射”功能，并且可以配置为在用户的 SAML 属性中发布 Elasticsearch 角色名称时，可能会出现这种情况。
在这些情况下，可以使用将组名称视为角色名称的模板。
注意：仅当您打算为所有提供的组定义角色时，才应执行此操作。将用户映射到大量不必要的或未定义的角色效率低下，并且可能会对系统性能产生负面影响。如果您只需要映射组的子集，则应使用显式映射来执行此操作。
POST /_security/role_mapping/mapping5
{
"role_templates": [
{
"template": { "source": "{{#tojson}}groups{{/tojson}}" },
"format" : "json"
}
],
"rules": {
"field" : { "realm.name" : "saml1" }
},
"enabled": true
}
以下示例匹配特定 LDAP 子树中的用户
POST /_security/role_mapping/mapping6
{
"roles": [ "example-user" ],
"enabled": true,
"rules": {
"field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
}
}
以下示例匹配特定领域中特定 LDAP 子树中的用户
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
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 角色。