Path parameters

  • namestring Required

    The distinct name that identifies the role mapping. The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way.

Query parameters

  • refreshstring

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

application/json

BodyRequired

  • enabledboolean

    Mappings that have enabled set to false are ignored when role mapping is performed.

  • metadataobject
    Hide metadata attribute Show metadata attribute object
  • rolesarray[string]

    A list of role names that are granted to the users that match the role mapping rules. Exactly one of roles or role_templates must be specified.

  • role_templatesarray[object]

    A list of Mustache templates that will be evaluated to determine the roles names that should granted to the users that match the role mapping rules. Exactly one of roles or role_templates must be specified.

    Hide role_templates attributes Show role_templates attributes object
    • formatstring

      Values are string or json.

    • templateobject Required
      Hide template attributes Show template attributes object

      • sourcestring | object

        One of:
        ScriptSourcestringSearchRequestBodyobject
      • idstring
      • paramsobject

        Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

        Hide params attribute Show params attribute object
        • *object Additional properties

      • langstring

        Any of:
        ScriptLanguagestringScriptLanguagestring

        Values are painless, expression, mustache, or java.

      • optionsobject
        Hide options attribute Show options attribute object
        • *string Additional properties
  • rulesobject
    Hide rules attributes Show rules attributes object
  • run_asarray[string]

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
PUT /_security/role_mapping/{name}
POST /_security/role_mapping/mapping1
{
  "roles": [ "user"],
  "enabled": true, 
  "rules": {
    "field" : { "username" : "*" }
  },
  "metadata" : { 
    "version" : 1
  }
}
curl \
 --request PUT 'http://api.example.com/_security/role_mapping/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"roles\": [ \"user\"],\n  \"enabled\": true, \n  \"rules\": {\n    \"field\" : { \"username\" : \"*\" }\n  },\n  \"metadata\" : { \n    \"version\" : 1\n  }\n}"'
Request examples
Run `POST /_security/role_mapping/mapping1` to assign the `user` role to all users.
{
  "roles": [ "user"],
  "enabled": true, 
  "rules": {
    "field" : { "username" : "*" }
  },
  "metadata" : { 
    "version" : 1
  }
}
Run `POST /_security/role_mapping/mapping2` to assign the "user" and "admin" roles to specific users.
{
  "roles": [ "user", "admin" ],
  "enabled": true,
  "rules": {
    "field" : { "username" : [ "esadmin01", "esadmin02" ] }
  }
}
Run `POST /_security/role_mapping/mapping3` to match users who authenticated against a specific realm.
{
  "roles": [ "ldap-user" ],
  "enabled": true,
  "rules": {
    "field" : { "realm.name" : "ldap1" }
  }
}
Run `POST /_security/role_mapping/mapping4` to match any user where either the username is `esadmin` or the user is in the `cn=admin,dc=example,dc=com group`. This example is useful when the group names in your identity management system (such as Active Directory, or a SAML Identity Provider) do not have a one-to-one correspondence with the names of roles in Elasticsearch. The role mapping is the means by which you link a group name with a role name.
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "any": [
      {
        "field": {
          "username": "esadmin"
        }
      },
      {
        "field": {
          "groups": "cn=admins,dc=example,dc=com"
        }
      }
    ]
  }
}
Run `POST /_security/role_mapping/mapping5` to use an array syntax for the groups field when there are multiple groups. This pattern matches any of the groups (rather than all of the groups).
{
  "role_templates": [
    {
      "template": { "source": "{{#tojson}}groups{{/tojson}}" }, 
      "format" : "json" 
    }
  ],
  "rules": {
    "field" : { "realm.name" : "saml1" }
  },
  "enabled": true
}
Run `POST /_security/role_mapping/mapping6` for rare cases when the names of your groups may be an exact match for the names of your Elasticsearch roles. This can be the case when your SAML Identity Provider includes its own "group mapping" feature and can be configured to release Elasticsearch role names in the user's SAML attributes. In these cases it is possible to use a template that treats the group names as role names. NOTE: This should only be done if you intend to define roles for all of the provided groups. Mapping a user to a large number of unnecessary or undefined roles is inefficient and can have a negative effect on system performance. If you only need to map a subset of the groups, you should do it by using explicit mappings. The `tojson` mustache function is used to convert the list of group names into a valid JSON array. Because the template produces a JSON array, the `format` must be set to `json`.
{
  "role_templates": [
    {
      "template": { "source": "{{#tojson}}groups{{/tojson}}" }, 
      "format" : "json" 
    }
  ],
  "rules": {
    "field" : { "realm.name" : "saml1" }
  },
  "enabled": true
}
Run `POST /_security/role_mapping/mapping7` to match users within a particular LDAP sub-tree in a specific realm.
{
  "roles": [ "ldap-example-user" ],
  "enabled": true,
  "rules": {
    "all": [
      { "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
      { "field" : { "realm.name" : "ldap1" } }
    ]
  }
}
Run `POST /_security/role_mapping/mapping8` to assign rules that are complex and include wildcard matching. For example, this mapping matches any user where all of these conditions are met: the Distinguished Name matches the pattern `*,ou=admin,dc=example,dc=com`, or the `username` is `es-admin`, or the `username` is `es-system`; the user is in the `cn=people,dc=example,dc=com` group; the user does not have a `terminated_date`.
{
  "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
          }
        }
      }
    ]
  }
}
Run `POST /_security/role_mapping/mapping9` to use templated roles to automatically map every user to their own custom role. In this example every user who authenticates using the `cloud-saml` realm will be automatically mapped to two roles: the `saml_user` role and a role that is their username prefixed with `_user_`. For example, the user `nwong` would be assigned the `saml_user` and `_user_nwong` roles.
{
  "rules": { "field": { "realm.name": "cloud-saml" } },
  "role_templates": [
    { "template": { "source" : "saml_user" } }, 
    { "template": { "source" : "_user_{{username}}" } }
  ],
  "enabled": true
}
Response examples (200)
A successful response from `POST /_security/role_mapping/mapping1`.
{
  "role_mapping" : {
    "created" : true 
  }
}