ロールマッピングの作成または更新（Create or update role mappings）

役割マッピング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グループのすべてのユーザーには、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」役割を割り当てます:

Python

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

Js

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
  }
}

成功した呼び出しは、マッピングが作成または更新されたかどうかを示すJSON構造を返します。

コンソール-結果

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

次の例では、「user」と「admin」役割を特定のユーザーに割り当てます:

Python

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

Js

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" ] }
  }
}

次の例では、特定のレルムに対して認証されたユーザーを一致させます:

Python

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

Js

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グループに属する任意のユーザーを一致させます:

Python

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)

Js

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の役割名と1対1の対応を持たない場合に便利です。役割マッピングは、グループ名を役割名にリンクする手段です。

複数のグループがある場合、グループフィールドに配列構文を使用できます。これにより、すべてのグループではなく、任意のグループに一致します:

Python

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)

Js

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アイデンティティプロバイダーが独自の「グループマッピング」機能を含み、ユーザーのSAML属性にElasticsearch役割名をリリースするように構成できる場合に発生します。

この場合、グループ名を役割名として扱うテンプレートを使用することが可能です。

注意：これは、提供されたすべてのグループに対して役割を定義するつもりである場合にのみ行うべきです。不要または未定義の役割にユーザーをマッピングすることは非効率的であり、システムのパフォーマンスに悪影響を及ぼす可能性があります。グループのサブセットのみをマッピングする必要がある場合は、明示的なマッピングを使用してこれを行うべきです。

Python

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)

Js

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
}

次の例では、特定のLDAPサブツリー内のユーザーを一致させます:

Python

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

Js

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サブツリー内のユーザーを一致させます:

Python

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)

Js

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" } }
   ]
  }
}

ルールはより複雑で、ワイルドカードマッチングを含むことができます。たとえば、次のマッピングは、すべての条件が満たされる任意のユーザーに一致します：

• Distinguished Nameがパターン*,ou=admin,dc=example,dc=comに一致するか、ユーザー名がes-adminであるか、ユーザー名がes-systemである
• cn=people,dc=example,dc=comグループのユーザー
• ユーザーがterminated_dateを持たない

Python

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)

Js

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役割が割り当てられます。

Python

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)

Js

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
}