Suggest a user profile Generally available; Added in 8.2.0

POST /_security/profile/_suggest
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_security/profile/_suggest

POST /_security/profile/_suggest

Get suggestions for user profiles that match specified search criteria.

NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice.

Required authorization

  • Cluster privileges: read_security

Query parameters

  • data string | array[string]

    A comma-separated list of filters for the data field of the profile document. To return all content use data=*. To return a subset of content, use data=<key> to retrieve content nested under the specified <key>. By default, the API returns no data content. It is an error to specify data as both the query parameter and the request body field.

application/json

Body

  • name string

    A query string used to match name-related fields in user profile documents. Name-related fields are the user's username, full_name, and email.

  • size number

    The number of profiles to return.

    Default value is 10.

  • data string | array[string]

    A comma-separated list of filters for the data field of the profile document. To return all content use data=*. To return a subset of content, use data=<key> to retrieve content nested under the specified <key>. By default, the API returns no data content. It is an error to specify data as both the query parameter and the request body field.

    One of:
    string-1 string array-2 array[string]
  • hint object

    Extra search criteria to improve relevance of the suggestion result. Profiles matching the spcified hint are ranked higher in the response. Profiles not matching the hint aren't excluded from the response as long as the profile matches the name field query.

    Hide hint attributes Show hint attributes object
    • uids array[string]

      A list of profile UIDs to match against.

    • labels object

      A single key-value pair to match against the labels section of a profile. A profile is considered matching if it matches at least one of the strings.

Responses

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

      Metadata about the number of matching profiles.

      Hide total attributes Show total attributes object
      • value number Required
      • relation string Required
    • took number Required

      The number of milliseconds it took Elasticsearch to run the request.

    • profiles array[object] Required

      A list of profile documents, ordered by relevance, that match the search criteria.

      Hide profiles attributes Show profiles attributes object
      • uid string Required
      • user object Required
        Hide user attributes Show user attributes object
      • data object Required
        Hide data attribute Show data attribute object
        • * object Additional properties
      • labels object Required
        Hide labels attribute Show labels attribute object
        • * object Additional properties
      • enabled boolean
POST /_security/profile/_suggest 
POST /_security/profile/_suggest
{
  "name": "jack",  
  "hint": {
    "uids": [  
      "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
    ],
    "labels": {
      "direction": ["north", "east"]  
    }
  }
}
resp = client.security.suggest_user_profiles(
    name="jack",
    hint={
        "uids": [
            "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
            "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
        ],
        "labels": {
            "direction": [
                "north",
                "east"
            ]
        }
    },
)
const response = await client.security.suggestUserProfiles({
  name: "jack",
  hint: {
    uids: [
      "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
    ],
    labels: {
      direction: ["north", "east"],
    },
  },
});
response = client.security.suggest_user_profiles(
  body: {
    "name": "jack",
    "hint": {
      "uids": [
        "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
        "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
      ],
      "labels": {
        "direction": [
          "north",
          "east"
        ]
      }
    }
  }
)
$resp = $client->security()->suggestUserProfiles([
    "body" => [
        "name" => "jack",
        "hint" => [
            "uids" => array(
                "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
                "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
            ),
            "labels" => [
                "direction" => array(
                    "north",
                    "east",
                ),
            ],
        ],
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"name":"jack","hint":{"uids":["u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0","u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"],"labels":{"direction":["north","east"]}}}' "$ELASTICSEARCH_URL/_security/profile/_suggest"
Request example
Run `POST /_security/profile/_suggest` to get suggestions for profile documents with name-related fields matching `jack`. It specifies both `uids` and `labels` hints for better relevance. The `labels` hint ranks profiles higher if their `direction` label matches either `north` or `east`. 
{
  "name": "jack",  
  "hint": {
    "uids": [  
      "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
    ],
    "labels": {
      "direction": ["north", "east"]  
    }
  }
}
Response examples (200)
A successful response from `GET /_security/saml/metadata/saml1`. It contains the SAML metadata that was generated for the SAML realm as an XML string. 
{
    "metadata" : "<?xml version=\"1.0\" encoding=\"UTF-8\"?><md:EntityDescriptor xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"https://kibana.org\"><md:SPSSODescriptor AuthnRequestsSigned=\"false\" WantAssertionsSigned=\"true\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"><md:SingleLogoutService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"https://kibana.org/logout\"/><md:AssertionConsumerService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://kibana.org/api/security/saml/callback\" index=\"1\" isDefault=\"true\"/></md:SPSSODescriptor></md:EntityDescriptor>"
}