mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 23:57:20 -04:00
255c9a7f95
**Problem:** For historical reasons, source files for the Elasticsearch Guide's security, watcher, and Logstash API docs are housed in the `x-pack/docs` directory. This can confuse new contributors who expect Elasticsearch Guide docs to be located in `docs/reference`. **Solution:** - Move the security, watcher, and Logstash API doc source files to the `docs/reference` directory - Update doc snippet tests to use security Rel: https://github.com/elastic/platform-docs-team/issues/208
168 lines
4.6 KiB
Text
168 lines
4.6 KiB
Text
[role="xpack"]
|
||
[[security-api-get-user-profile]]
|
||
=== Get user profiles API
|
||
++++
|
||
<titleabbrev>Get user profiles</titleabbrev>
|
||
++++
|
||
|
||
NOTE: The user profile feature is designed only for use by {kib} and
|
||
Elastic’s {observability}, {ents}, and {elastic-sec} 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.
|
||
|
||
Retrieves user profiles using a list of unique profile ID.
|
||
|
||
[[security-api-get-user-profile-request]]
|
||
==== {api-request-title}
|
||
|
||
`GET /_security/profile/<uid>`
|
||
|
||
[[security-api-get-user-profile-prereqs]]
|
||
==== {api-prereq-title}
|
||
|
||
To use this API, you must have _at least_ the `read_security`
|
||
<<privileges-list-cluster,cluster privilege>> (or a greater privilege
|
||
such as `manage_user_profile` or `manage_security`).
|
||
|
||
[[security-api-get-user-profile-desc]]
|
||
==== {api-description-title}
|
||
|
||
The get user profile API returns the user profile document matching a specified
|
||
`uid`, which is generated when
|
||
<<security-api-activate-user-profile,activating a user profile>>.
|
||
|
||
[[security-api-get-user-profile-path-params]]
|
||
==== {api-path-parms-title}
|
||
|
||
`uid`::
|
||
(Required, string) The unique identifier for the user profile. You can specify multiple IDs as
|
||
a comma-separated list.
|
||
|
||
[[security-api-get-user-profile-query-params]]
|
||
==== {api-query-parms-title}
|
||
|
||
`data`::
|
||
(Optional, string) 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 the content nested under the
|
||
specified `<key>`. Defaults to returning no content.
|
||
|
||
[[security-api-get-user-profile-response-body]]
|
||
==== {api-response-body-title}
|
||
|
||
A successful call returns the JSON representation of the user profile
|
||
and its internal versioning numbers. The API returns an empty object
|
||
if no profile document is found for the provided `uid`.
|
||
The content of the `data` field is not returned by default to avoid deserializing
|
||
a potential large payload.
|
||
|
||
[[security-api-get-user-profile-example]]
|
||
==== {api-examples-title}
|
||
|
||
[source,console]
|
||
----
|
||
GET /_security/profile/u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0
|
||
----
|
||
// TEST[setup:user_profiles]
|
||
|
||
The API returns the following response for a `uid` matching `u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0`:
|
||
|
||
[source,console-result]
|
||
----
|
||
{
|
||
"profiles": [
|
||
{
|
||
"uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
|
||
"enabled": true,
|
||
"last_synchronized": 1642650651037,
|
||
"user": {
|
||
"username": "jacknich",
|
||
"roles": [
|
||
"admin", "other_role1"
|
||
],
|
||
"realm_name": "native",
|
||
"full_name": "Jack Nicholson",
|
||
"email": "jacknich@example.com"
|
||
},
|
||
"labels": {
|
||
"direction": "north"
|
||
},
|
||
"data": {}, <1>
|
||
"_doc": {
|
||
"_primary_term": 88,
|
||
"_seq_no": 66
|
||
}
|
||
}
|
||
]
|
||
}
|
||
----
|
||
// TESTRESPONSE[s/1642650651037/$body.profiles.0.last_synchronized/]
|
||
// TESTRESPONSE[s/88/$body.profiles.0._doc._primary_term/]
|
||
// TESTRESPONSE[s/66/$body.profiles.0._doc._seq_no/]
|
||
|
||
<1> No content is returned in the `data` field by default.
|
||
|
||
The following request retrieves a subset of `data` that's nested under the
|
||
key `app1`, along with the user's profile:
|
||
|
||
[source,console]
|
||
----
|
||
GET /_security/profile/u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0?data=app1.key1
|
||
----
|
||
// TEST[continued]
|
||
|
||
[source,console-result]
|
||
----
|
||
{
|
||
"profiles": [
|
||
{
|
||
"uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
|
||
"enabled": true,
|
||
"last_synchronized": 1642650651037,
|
||
"user": {
|
||
"username": "jacknich",
|
||
"roles": [
|
||
"admin", "other_role1"
|
||
],
|
||
"realm_name": "native",
|
||
"full_name": "Jack Nicholson",
|
||
"email": "jacknich@example.com"
|
||
},
|
||
"labels": {
|
||
"direction": "north"
|
||
},
|
||
"data": {
|
||
"app1": {
|
||
"key1": "value1"
|
||
}
|
||
},
|
||
"_doc": {
|
||
"_primary_term": 88,
|
||
"_seq_no": 66
|
||
}
|
||
}
|
||
]
|
||
}
|
||
----
|
||
// TESTRESPONSE[s/1642650651037/$body.profiles.0.last_synchronized/]
|
||
// TESTRESPONSE[s/88/$body.profiles.0._doc._primary_term/]
|
||
// TESTRESPONSE[s/66/$body.profiles.0._doc._seq_no/]
|
||
|
||
If there has been any errors when retrieving the user profiles, they are returned in the `errors` field:
|
||
|
||
[source,js]
|
||
--------------------------------------------------
|
||
{
|
||
"profiles": [],
|
||
"errors": {
|
||
"count": 1,
|
||
"details": {
|
||
"u_FmxQt3gr1BBH5wpnz9HkouPj3Q710XkOgg1PWkwLPBW_5": {
|
||
"type": "resource_not_found_exception",
|
||
"reason": "profile document not found"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
--------------------------------------------------
|
||
// NOTCONSOLE
|