User Profile - Beta docs for APIs (#83495)

This PR adds beta docs for the 3 existing APIs:
* Activate Profile
* Get Profile by ID
* Update Profile Data

Co-authored-by: Adam Locke <adam.locke@elastic.co>

x-pack/docs/build.gradle

@@ -1,3 +1,5 @@
+import org.elasticsearch.gradle.internal.info.BuildParams
+
 apply plugin: 'elasticsearch.docs-test'
 apply plugin: 'elasticsearch.rest-resources'
 
@@ -60,6 +62,11 @@ testClusters.matching { it.name == "integTest" }.configureEach {
   setting 'xpack.security.authc.realms.saml.saml1.sp.acs', 'https://kibana.org/api/security/saml/callback'
   setting 'xpack.security.authc.realms.saml.saml1.attributes.principal', 'uid'
   setting 'xpack.security.authc.realms.saml.saml1.attributes.name', 'urn:oid:2.5.4.3'
+
+  if (BuildParams.isSnapshotBuild() == false) {
+    systemProperty 'es.user_profile_feature_flag_enabled', 'true'
+  }
+
   user username: 'test_admin'
 }
 

x-pack/docs/en/rest-api/security.asciidoc

@@ -132,7 +132,18 @@ communicate with a secured {es} cluster.
 * <<security-api-node-enrollment, Enroll a new node>>
 * <<security-api-kibana-enrollment, Enroll a new {kib} instance>>
 
+[discrete]
+[[security-user-profile-apis]]
+=== User Profile
+
+Use the following APIs to retrieve and manage user profiles.
+
+* <<security-api-activiate-user-profile, Activate user profile>>
+* <<security-api-get-user-profile, Get user profile>>
+* <<security-api-update-user-profile-data, Update user profile data>>
+
 
+include::security/activate-user-profile.asciidoc[]
 include::security/authenticate.asciidoc[]
 include::security/change-password.asciidoc[]
 include::security/clear-cache.asciidoc[]
@@ -165,6 +176,7 @@ include::security/get-service-accounts.asciidoc[]
 include::security/get-service-credentials.asciidoc[]
 include::security/get-tokens.asciidoc[]
 include::security/get-user-privileges.asciidoc[]
+include::security/get-user-profile.asciidoc[]
 include::security/get-users.asciidoc[]
 include::security/grant-api-keys.asciidoc[]
 include::security/has-privileges.asciidoc[]
@@ -181,6 +193,4 @@ include::security/saml-invalidate-api.asciidoc[]
 include::security/saml-complete-logout-api.asciidoc[]
 include::security/saml-sp-metadata.asciidoc[]
 include::security/ssl.asciidoc[]
-include::security/get-user-profile.asciidoc[]
-include::security/activate-user-profile.asciidoc[]
 include::security/update-user-profile-data.asciidoc[]

x-pack/docs/en/rest-api/security/activate-user-profile.asciidoc

@@ -1,10 +1,131 @@
 [role="xpack"]
 [[security-api-activiate-user-profile]]
 === Activate user profile API
+
+beta::[]
+
 ++++
 <titleabbrev>Activate user profile</titleabbrev>
 ++++
 
-Creates or updates the user profile on behalf of another user
+Creates or updates a user profile on behalf of another user.
+
+[[security-api-activate-user-profile-request]]
+==== {api-request-title}
+
+`POST /_security/profile/_activate`
+
+[[security-api-activate-user-profile-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have the `manage_user_profile` cluster privilege.
+
+[[security-api-activate-user-profile-desc]]
+==== {api-description-title}
+
+The activate user profile API creates or updates a profile document for end
+users with information that is extracted from the user's authentication object,
+including `username`, `full_name`, `roles`, and the authentication realm.
+
+When updating a profile document, the API enables the document if it was
+disabled. Any updates do not change existing content for either the `access` or
+`data` fields.
+
+This API is intended only for use by applications (such as {kib}) that need to 
+create or update profiles for end users.
+
+IMPORTANT: The calling application must have either an `access_token`, or a
+combination of `username` and `password` for the user that the profile document
+is intended for.
+
+[role="child_attributes"]
+[[security-api-activate-user-profile-request-body]]
+==== {api-request-body-title}
+
+`access_token`::
+(Required*, string)
+The user's access token. If you specify the `access_token` grant type, this
+parameter is required. It is not valid with other grant types.
+
+`grant_type`::
+(Required, string)
+The type of grant.
++
+.Valid values for `grant_type`
+[%collapsible%open]
+====
+`access_token`::
+(Required*, string)
+In this type of grant, you must supply an access token that was created by the
+{es} token service. For more information, see
+<<security-api-get-token>> and <<token-service-settings>>.
+
+`password`::
+(Required*, string)
+In this type of grant, you must supply the `username` and `password` for the
+user that you want to create the API key for.
+====
+
+`password`::
+(Optional*, string)
+The user's password. If you specify the `password` grant type, this parameter is
+required. It is not valid with other grant types.
+
+`username`::
+(Optional*, string)
+The username that identifies the user. If you specify the `password` grant type,
+this parameter is required. It is not valid with other grant types.
+
+*Indicates that the setting is required in some, but not all situations.
+
+[[security-api-activate-user-profile-response-body]]
+==== {api-response-body-title}
+
+A successful activate user profile API call returns a JSON structure that contains
+the profile unique ID, user information, timestamp for the operation and version
+control numbers.
+
+[[security-api-activate-user-profile-example]]
+==== {api-examples-title}
+
+[source,console]
+----
+POST /_security/profile/_activate
+{
+  "grant_type": "password",
+  "username" : "jacknich",
+  "password" : "l0ng-r4nd0m-p@ssw0rd"
+}
+----
+// TEST[setup:jacknich_user]
+
+The API returns the following response:
 
-coming::[8.2.0]
+[source,console-result]
+----
+{
+  "uid": "u_kd2JMqwUQwSCCOxMv7M1vw",
+  "enabled": true,
+  "last_synchronized": 1642650651037,
+  "user": {
+    "username": "jacknich",
+    "roles": [
+      "admin", "other_role1"
+    ],
+    "realm_name": "native",
+    "full_name": "Jack Nicholson",
+    "email": "jacknich@example.com",
+    "active": true
+  },
+  "access": {},
+  "data": {},
+  "_doc": {
+    "_primary_term": 88,
+    "_seq_no": 66
+  }
+}
+----
+// TESTRESPONSE[s/u_kd2JMqwUQwSCCOxMv7M1vw/$body.uid/]
+// TESTRESPONSE[s/1642650651037/$body.last_synchronized/]
+// TESTRESPONSE[s/88/$body._doc._primary_term/]
+// TESTRESPONSE[s/66/$body._doc._seq_no/]

x-pack/docs/en/rest-api/security/get-user-profile.asciidoc

@@ -1,10 +1,137 @@
 [role="xpack"]
 [[security-api-get-user-profile]]
 === Get user profile API
+
+beta::[]
+
 ++++
 <titleabbrev>Get user profile</titleabbrev>
 ++++
 
-Retrieves a user's profile given the unique profile ID
+Retrieves a user's profile using the 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 `manage_user_profile` cluster privilege.
+
+
+[[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-activiate-user-profile,activating a user profile>>.
+
+[[security-api-get-user-profile-path-params]]
+==== {api-path-parms-title}
+
+`uid`::
+(Required, string) A unique identifier for the user profile.
+
+[[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_kd2JMqwUQwSCCOxMv7M1vw
+----
+// TEST[skip:uid is random and no way to ensure this uid exists]
+
+The API returns the following response for a `uid` matching `u_kd2JMqwUQwSCCOxMv7M1vw`:
+
+[source,js]
+----
+{
+  "u_kd2JMqwUQwSCCOxMv7M1vw": {
+    "uid": "u_kd2JMqwUQwSCCOxMv7M1vw",
+    "enabled": true,
+    "last_synchronized": 1642650651037,
+    "user": {
+      "username": "jacknich",
+      "roles": [
+        "admin", "other_role1"
+      ],
+      "realm_name": "native1",
+      "full_name": "Jack Nicholson",
+      "email": "jacknich@example.com",
+      "active": true
+    },
+    "access": {},
+    "data": {}, <1>
+    "_doc": {
+      "_primary_term": 1,
+      "_seq_no": 0
+    }
+  }
+}
+----
+// NOTCONSOLE
+// Besides the uid being random, the response cannot be compared against due to
+// the last_synchronized and _doc fields being unpredictable.
+
+<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_kd2JMqwUQwSCCOxMv7M1vw?data=app1.key1
+----
+// TEST[skip:uid is random and no way to ensure this uid exists]
 
-coming::[8.2.0]
+[source,js]
+----
+{
+  "u_kd2JMqwUQwSCCOxMv7M1vw": {
+    "uid": "u_kd2JMqwUQwSCCOxMv7M1vw",
+    "enabled": true,
+    "last_synchronized": 1642650651037,
+    "user": {
+      "username": "jacknich",
+      "roles": [
+        "admin", "other_role1"
+      ],
+      "realm_name": "native1",
+      "full_name": "Jack Nicholson",
+      "email": "jacknich@example.com",
+      "active": true
+    },
+    "access": {},
+    "data": {
+      "app1": {
+        "key1": "value1"
+      }
+    },
+    "_doc": {
+      "_primary_term": 1,
+      "_seq_no": 0
+    }
+  }
+}
+----
+// NOTCONSOLE

x-pack/docs/en/rest-api/security/update-user-profile-data.asciidoc

@@ -1,10 +1,172 @@
 [role="xpack"]
 [[security-api-update-user-profile-data]]
-=== Activate user profile data API
+=== Update user profile data API
+
+beta::[]
+
 ++++
 <titleabbrev>Update user profile data</titleabbrev>
 ++++
 
-Update application specific data for the user profile of the given unique ID.
+Updates specific data for the user profile that's associated with the specified
+unique ID.
+
+[[security-api-update-user-profile-data-request]]
+==== {api-request-title}
+
+`POST /_security/profile/_data/<uid>`
+
+[[security-api-update-user-profile-data-prereqs]]
+==== {api-prereq-title}
+
+To use this API, you must have one of the following privileges:
+
+* The `manage_user_profile` cluster privilege.
+* The `update_profile_data` global privilege for the namespaces that are
+referenced in the request.
+
+[[security-api-update-user-profile-data-desc]]
+==== {api-description-title}
+
+The update user profile API updates the `access` and `data` fields of an
+existing user profile document with JSON objects. New keys and their values are
+added to the profile document, and conflicting keys are replaced by data that's
+included in the request.
+
+For both `access` and `data`, content is namespaced by the top-level fields.
+The `update_profile_data` global privilege grants privileges for updating only
+the allowed namespaces.
+
+[[security-api-update-user-profile-data-path-params]]
+==== {api-path-parms-title}
+
+`uid`::
+(Required, string) A unique identifier for the user profile.
+
+[[security-api-update-user-profile-data-query-params]]
+==== {api-query-parms-title}
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=if_seq_no]
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=if_primary_term]
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=refresh]
+
+`uid`::
+(Required, string) A unique identifier for the user profile.
+
+[[security-api-update-user-profile-data-request-body]]
+==== {api-request-body-title}
+
+`access`::
+(Required*, object)
+Searchable data that you want to associate with the user profile.
+This field supports a nested data structure. Within the `access` object,
+top-level keys cannot begin with an underscore (`_`) or contain a period (`.`).
+
+`data`::
+(Required*, object)
+Non-searchable data that you want to associate with the user profile.
+This field supports a nested data structure. Within the `data` object, top-level
+keys cannot begin with an underscore (`_`) or contain a period (`.`)
+The `data` object is not searchable, but can be retrieved with the 
+<<security-api-get-user-profile,Get user profile API>>.
+
+*Indicates that the setting is required in some, but not all situations.
+
+[[security-api-update-user-profile-data-response-body]]
+==== {api-response-body-title}
+
+A successful update user profile data API call returns a JSON structure
+indicating that the request is acknowledged:
+
+[source,js]
+----
+{
+  "acknowledged": true
+}
+----
+// NOTCONSOLE
+
+[[security-api-update-user-profile-data-example]]
+==== {api-examples-title}
+
+The following request updates a profile document for a `uid` matching 
+`u_kd2JMqwUQwSCCOxMv7M1vw`:
+
+[source,console]
+----
+POST /_security/profile/_data/u_kd2JMqwUQwSCCOxMv7M1vw
+{
+  "access": {
+    "app1": {
+      "tag": "prod"
+    }
+  },
+  "data": {
+    "app1": {
+      "theme": "default"
+    }
+  }
+}
+----
+// TEST[skip:uid is random and no way to ensure this uid exists]
+
+You can update the profile data to replace some keys and add new keys:
+
+[source,console]
+----
+POST /_security/profile/_data/u_kd2JMqwUQwSCCOxMv7M1vw
+{
+  "access": {
+    "app1": {
+      "tag": "dev"
+    }
+  },
+  "data": {
+    "app1": {
+      "font": "large"
+    }
+  }
+}
+----
+// TEST[skip:uid is random and no way to ensure this uid exists]
+
+If you run the request again, the consolidated profile data is returned:
 
-coming::[8.2.0]
+[source,js]
+----
+{
+  "u_kd2JMqwUQwSCCOxMv7M1vw": {
+    "uid": "u_kd2JMqwUQwSCCOxMv7M1vw",
+    "enabled": true,
+    "last_synchronized": 1642650651037,
+    "user": {
+      "username": "jacknich",
+      "roles": [
+        "admin", "other_role1"
+      ],
+      "realm_name": "native1",
+      "full_name": "Jack Nicholson",
+      "email": "jacknich@example.com",
+      "active": true
+    },
+    "access": {
+      "app1": {
+        "tag": "dev"
+      }
+    },
+    "data": {
+      "app1": {
+        "theme": "default",
+        "font": "large"
+      }
+    },
+    "_doc": {
+      "_primary_term": 1,
+      "_seq_no": 0
+    }
+  }
+}
+----
+// NOTCONSOLE