Core
API v2.x
2
APIAPI v2.x

searchUsersByCredentials #

Available since 2.13.0

Given a credentials related search query, returns matched users' kuid. Since credentials depend on the authentication strategy, so do the search query.

If you are using a custom strategy plugin, you must first implement the optional search method in order to use this action.

This method is not intended to be exposed to the end user. A full list of users ids should be considered as sensitive data.

Query Syntax #

HTTP #

URL: http://kuzzle:7512/credentials/<strategy>/users/_search
Method: POST
Body:
{
  "bool": {
    "must": [
      {
        "match": {
          // example with the "local" authentication strategy
          "username":  "test@example.com"
        }
      }
    ]
  }
}

Other protocols #

{
  "controller": "security",
  "action": "searchUsersByCredentials",
  "strategy": "<strategy>",
  "body": {
    "query":{
      "bool": {
        "must": [
          {
            "match": {
              // example with the "local" authentication strategy
              "username":  "test@example.com"
            }
          }
        ]
      }
    }
  },
}

Arguments #

  • strategy: authentication strategy

Optional: #

  • from: paginates search results by defining the offset from the first result you want to fetch. Usually used with the size argument
  • size: set the maximum number of documents returned per result page
  • lang: specify the query language to use. By default, it's elasticsearch but koncorde can also be used.

There is a limit to how many documents can be returned by a single search query. That limit is by default set at 10000 documents (see limits.documentsFetchCount), and you can't get over it even with the from and size pagination options.

Body properties #

Properties on which the query applies depend entirely on the authentication strategy.

Optional: #

If the body is left empty, the result will return all available users for this strategy.

Koncorde bool operator and regexp clause are not supported for search queries.

Response #

Returns a search result set, with the following properties:

  • hits: Array of matched users. Each hit has the following properties:
    • kuid: Users unique identifier
    • ...: Other properties depending on the authentication strategy
  • total: Total of matched users.
{
  "action": "searchUsersByCredentials",
  "controller": "security",
  "error": null,
  "node": "knode-smooth-hawking-65812",
  "requestId": "52772769-2e15-45f6-b27b-a702fec09c18",
  "result": {
    "hits": [
      {
        kuid: "kuid",
        // example with the "local" authentication strategy
        username: "test@example.com"
      }
    ],
    "total": 1
  },
  "status": 200,
  "volatile": null
}
Edit this page on Github(opens new window)