Find roles with a query Generally available; Added in 8.15.0

GET /_security/_query/role

Get roles in a paginated manner. The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The query roles API does not retrieve roles that are defined in roles files, nor built-in ones. You can optionally filter the results with a query. Also, the results can be paginated and sorted.

Required authorization

  • Cluster privileges: read_security
application/json

Body

  • query object

    A query to filter which roles to return. If the query parameter is missing, it is equivalent to a match_all query. The query supports a subset of query types, including match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range, and simple_query_string. You can query the following information associated with roles: name, description, metadata, applications.application, applications.privileges, and applications.resources.

    Hide query attributes Show query attributes object
    • bool object

      matches roles matching boolean combinations of other queries.

      Hide bool attributes Show bool attributes object
      • boost number

        Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

        Default value is 1.0.

      • _name string

      • filter object | array[object]

        The clause (query) must appear in matching documents. However, unlike must, the score of the query will be ignored.

        One of:
        QueryContainer object array-2 array[object]

        An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

      • minimum_should_match

      • must object | array[object]

        The clause (query) must appear in matching documents and will contribute to the score.

        One of:
        QueryContainer object array-2 array[object]

        An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

      • must_not object | array[object]

        The clause (query) must not appear in the matching documents. Because scoring is ignored, a score of 0 is returned for all documents.

        One of:
        QueryContainer object array-2 array[object]

        An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

      • should object | array[object]

        The clause (query) should appear in the matching document.

        One of:
        QueryContainer object array-2 array[object]

        An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

    • exists object

      Returns roles that contain an indexed value for a field.

      Hide exists attributes Show exists attributes object
      • boost number

        Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

        Default value is 1.0.

      • _name string
      • field string Required

        Name of the field you wish to search.

    • ids object

      Returns roles based on their IDs. This query uses role document IDs stored in the _id field.

      Hide ids attributes Show ids attributes object
      • boost number

        Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

        Default value is 1.0.

      • _name string
      • values
    • match object

      Returns roles that match a provided text, number, date or boolean value. The provided text is analyzed before matching.

    • match_all object

      Matches all roles, giving them all a _score of 1.0.

      Hide match_all attributes Show match_all attributes object
      • boost number

        Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

        Default value is 1.0.

      • _name string
    • prefix object

      Returns roles that contain a specific prefix in a provided field.

    • range object

      Returns roles that contain terms within a provided range.

    • simple_query_string object

      Returns roles based on a provided query string, using a parser with a limited but fault-tolerant syntax.

      Hide simple_query_string attributes Show simple_query_string attributes object
      • boost number

        Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

        Default value is 1.0.

      • _name string
      • analyzer string

        Analyzer used to convert text in the query string into tokens.

      • analyze_wildcard boolean

        If true, the query attempts to analyze wildcard terms in the query string.

        Default value is false.

      • auto_generate_synonyms_phrase_query boolean

        If true, the parser creates a match_phrase query for each multi-position token.

        Default value is true.

      • default_operator string

        Default boolean logic used to interpret text in the query string if no operators are specified.

        Values are and, AND, or, or OR.

      • fields array[string]

        Array of fields you wish to search. Accepts wildcard expressions. You also can boost relevance scores for matches to particular fields using a caret (^) notation. Defaults to the index.query.default_field index setting, which has a default value of *.

      • fuzzy_max_expansions number

        Maximum number of terms to which the query expands for fuzzy matching.

        Default value is 50.0.

      • fuzzy_prefix_length number

        Number of beginning characters left unchanged for fuzzy matching.

        Default value is 0.0.

      • fuzzy_transpositions boolean

        If true, edits for fuzzy matching include transpositions of two adjacent characters (for example, ab to ba).

      • lenient boolean

        If true, format-based errors, such as providing a text value for a numeric field, are ignored.

        Default value is false.

      • minimum_should_match
      • query string Required

        Query string in the simple query string syntax you wish to parse and use for search.

      • quote_field_suffix string

        Suffix appended to quoted text in the query string.

    • term object

      Returns roles that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.

    • terms object

      Returns roles that contain one or more exact terms in a provided field. To return a document, one or more terms must exactly match a field value, including whitespace and capitalization.

      Hide terms attributes Show terms attributes object
      • boost number

        Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.

        Default value is 1.0.

      • _name string
    • wildcard object

      Returns roles that contain terms matching a wildcard pattern.

  • from number

    The starting document offset. It must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

    Default value is 0.0.

  • sort string | object | array[string | object]

    The sort definition. You can sort on name, description, metadata, applications.application, applications.privileges, and applications.resources. In addition, sort can also be applied to the _doc field to sort by index order.

    One of:
    Field string SortOptions object array-2 array[string | object]

    Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

  • size number

    The number of hits to return. It must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

    Default value is 10.0.

  • search_after array[number | string | boolean | null]

    The search after definition.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • total number Required

      The total number of roles found.

    • count number Required

      The number of roles returned in the response.

    • roles array[object] Required

      A list of roles that match the query. The returned role format is an extension of the role definition format. It adds the transient_metadata.enabled and the _sort fields. transient_metadata.enabled is set to false in case the role is automatically disabled, for example when the role grants privileges that are not allowed by the installed license. _sort is present when the search query sorts on some field. It contains the array of values that have been used for sorting.

      Hide roles attributes Show roles attributes object
      • cluster array[string]

        A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

      • indices array[object]

        A list of indices permissions entries.

        Hide indices attributes Show indices attributes object
        • field_security
        • names
        • privileges array[string] Required

          The index level privileges that owners of the role have on the specified indices.

        • query
        • allow_restricted_indices boolean Generally available

          Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

          Default value is false.

      • remote_indices array[object] Generally available; Added in 8.14.0

        A list of indices permissions for remote clusters.

        Hide remote_indices attributes Show remote_indices attributes object

        The subset of index level privileges that can be defined for remote clusters.

        • clusters
        • field_security
        • names
        • privileges array[string] Required

          The index level privileges that owners of the role have on the specified indices.

        • query
        • allow_restricted_indices boolean Generally available

          Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

          Default value is false.

      • remote_cluster array[object] Generally available; Added in 8.15.0

        A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.

        Hide remote_cluster attributes Show remote_cluster attributes object

        The subset of cluster level privileges that can be defined for remote clusters.

        • clusters
        • privileges array[string] Required

          The cluster level privileges that owners of the role have on the remote cluster.

          Values are monitor_enrich or monitor_stats.

      • global array[object] | object Generally available

        An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.

        One of:
        array-1 array[object] GlobalPrivilege object
      • applications array[object]

        A list of application privilege entries

        Hide applications attributes Show applications attributes object
        • application string Required

          The name of the application to which this entry applies.

        • privileges array[string] Required

          A list of strings, where each element is the name of an application privilege or action.

        • resources array[string] Required

          A list resources to which the privileges are applied.

      • metadata object

        Optional meta-data. Within the metadata object, keys that begin with _ are reserved for system usage.

        Hide metadata attribute Show metadata attribute object
        • * object Additional properties
      • run_as array[string]

        A list of users that the API keys can impersonate. NOTE: In Elastic Cloud Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.

      • description string

        Optional description of the role descriptor

      • restriction object

        Restriction for when the role descriptor is allowed to be effective.

        Hide restriction attribute Show restriction attribute object
        • workflows array[string] Required

          A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.

      • transient_metadata object
        Hide transient_metadata attribute Show transient_metadata attribute object
        • * object Additional properties
      • _sort array[number | string | boolean | null]

        A field value.

      • name string Required

        Name of the role.
GET /_security/_query/role 
curl \
 --request GET 'http://api.example.com/_security/_query/role' \
 --header "Content-Type: application/json" \
 --data '"{\n    \"sort\": [\"name\"]\n}"'
Request examples
Run `POST /_security/_query/role` to lists all roles, sorted by the role name. 
{
    "sort": ["name"]
}
Run `POST /_security/_query/role` to query only the user access role, given its description. It returns only the best matching role because `size` is set to `1`. 
{
  "query": {
    "match": {
      "description": {
        "query": "user access"
      }
    }
  },
  "size": 1 
}
Response examples (200)
A successful response from `POST /_security/_query/role`. It returns a JSON structure that contains the information retrieved for one or more roles. 
{
    "total": 2,
    "count": 2,
    "roles": [ 
        {
          "name" : "my_admin_role",
          "cluster" : [
            "all"
          ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [
            "other_user"
          ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants full access to all management features within the cluster.",
          "_sort" : [
            "my_admin_role"
          ]
        },
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies.",
          "_sort" : [
            "my_user_role"
          ]
        }
    ]
}
A successful response from `POST /_security/_query/role`. 
{
    "total": 2,
    "count": 1,
    "roles": [
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies."
        }
    ]
}