[DOCS] Profile Has Privileges API (#87360)

Docs for the new Has Privileges API for profiles from #85898.

[Has privileges user profile API
preview](https://elasticsearch_87360.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/security-api-has-privileges-user-profiles.html).

rest-api-spec/src/main/resources/rest-api-spec/api/security.has_privileges_user_profile.json

@@ -0,0 +1,31 @@
+{
+  "security.has_privileges_user_profile":{
+    "documentation":{
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-has-privileges-user-profile.html",
+      "description":"Determines whether the users associated with the specified profile IDs have all the requested privileges."
+    },
+    "stability":"experimental",
+    "visibility":"feature_flag",
+    "feature_flag": "es.user_profile_feature_flag_enabled",
+    "headers":{
+      "accept": [ "application/json"],
+      "content_type": ["application/json"]
+    },
+    "url":{
+      "paths":[
+        {
+          "path":"/_security/profile/_has_privileges",
+          "methods":[
+            "GET",
+            "POST"
+          ]
+        }
+      ]
+    },
+    "params":{},
+    "body":{
+      "description":"The privileges to check and the list of profile IDs",
+      "required":true
+    }
+  }
+}

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

@@ -145,6 +145,7 @@ Use the following APIs to retrieve and manage user profiles.
 * <<security-api-enable-user-profile, Enable user profile>>
 * <<security-api-disable-user-profile, Disable user profile>>
 * <<security-api-suggest-user-profile, Suggest user profile>>
+* <<security-api-has-privileges-user-profile, Has Privileges user profile>>
 endif::[]
 
 include::security/authenticate.asciidoc[]
@@ -203,4 +204,5 @@ include::security/enable-user-profile.asciidoc[]
 include::security/get-user-profile.asciidoc[]
 include::security/suggest-user-profile.asciidoc[]
 include::security/update-user-profile-data.asciidoc[]
+include::security/has-privileges-user-profile.asciidoc[]
 endif::[]

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

@@ -0,0 +1,121 @@
+[role="xpack"]
+[[security-api-has-privileges-user-profile]]
+=== Has privileges user profile API
+++++
+<titleabbrev>Has privileges user profile</titleabbrev>
+++++
+[[security-api-has-privileges-user-profile]]
+
+beta::[]
+
+Determines whether the users associated with the specified <<user-profile, user profile>> IDs
+have all the requested privileges.
+
+[[security-api-has-privileges-user-profile-request]]
+==== {api-request-title}
+
+`GET /_security/profile/_has_privileges`
+
+`POST /_security/profile/_has_privileges`
+
+[[security-api-has-privileges-user-profile-prereqs]]
+==== {api-prereq-title}
+
+To use this API, you must have the `manage_user_profile` cluster privilege.
+
+[[security-api-has-privileges-user-profile-desc]]
+==== {api-description-title}
+
+This API uses the profile IDs, as returned by <<security-api-activate-user-profile>>,
+to identify the users for which to check the privileges of.
+It is similar to the <<security-api-has-privileges>> API, but unlike it, this API
+checks the privileges of other users, not of the user that's calling it.
+
+See <<security-privileges>> for the list of privileges that can be specified in this API.
+
+A successful call returns the subset list of profile IDs that have **all** the requested privileges.
+
+[[security-api-has-privileges-user-profile-request-body]]
+==== {api-request-body-title}
+
+`uids`:: (list) A list of <<security-api-activate-user-profile-response-body, profile IDs>>. The privileges are checked for associated users of the profiles.
+
+`privileges`:: The object containing all the privileges to be checked.
+`cluster`::: (list) A list of the cluster privileges that you want to check.
+`index`:::
+`names`:::: (list) A list of indices.
+`allow_restricted_indices`:::: (Boolean) This needs to be set to `true` (default
+is `false`) if using wildcards or regexps for patterns that cover restricted
+indices. Implicitly, restricted indices do not match index patterns because
+restricted indices usually have limited privileges and including them in
+pattern tests would render most such tests `false`. If restricted indices are
+explicitly included in the `names` list, privileges will be checked against
+them regardless of the value of `allow_restricted_indices`.
+`privileges`:::: (list) A list of the privileges that you want to check for the
+specified indices.
+`application`:::
+`application`:::: (string) The name of the application.
+`privileges`:::: (list) A list of the privileges that you want to check for the
+specified resources. May be either application privilege names, or the names of
+actions that are granted by those privileges.
+`resources`:::: (list) A list of resource names against which the privileges
+should be checked.
+
+Note that the `privileges` section above is identical to the
+<<security-api-has-privileges-request-body, request body of the other Has Privileges API>>.
+
+[[security-api-has-privileges-user-profile-response-body]]
+==== {api-response-body-title}
+
+A successful has privileges user profile API call returns a JSON structure that contains
+two list fields:
+
+`has_privilege_uids`:: (list) The subset of the requested profile IDs of the users that have
+**all** the requested privileges.
+
+`error_uids`:: (list) The subset of the requested profile IDs for which an error was
+encountered. It does **not** include the missing profile IDs or the profile IDs of
+the users that do not have all the requested privileges. This field is absent if empty.
+
+[[security-api-has-privileges-user-profile-example]]
+==== {api-examples-title}
+
+The following example checks whether the two users associated with the specified profiles have all the
+requested set of cluster, index, and application privileges:
+
+[source,console]
+--------------------------------------------------
+POST /_security/user/_has_privileges
+{
+  "uids": ["u_LQPnxDxEjIH0GOUoFkZr5Y57YUwSkL9Joiq-g4OCbPc_0", "u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1"],
+  "cluster": [ "monitor", "create_snapshot", "manage_ml" ],
+  "index" : [
+    {
+      "names": [ "suppliers", "products" ],
+      "privileges": [ "create_doc"]
+    },
+    {
+      "names": [ "inventory" ],
+      "privileges" : [ "read", "write" ]
+    }
+  ],
+  "application": [
+    {
+      "application": "inventory_manager",
+      "privileges" : [ "read", "data:write/inventory" ],
+      "resources" : [ "product/1852563" ]
+    }
+  ]
+}
+--------------------------------------------------
+// TEST[skip:TODO setup and tests will be possible once the profile uid is predictable]
+
+The following example output indicates that only one of the two users has all the privileges:
+
+[source,js]
+--------------------------------------------------
+{
+  "has_privilege_uids": ["u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1"]
+}
+--------------------------------------------------
+// NOTCONSOLE

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

@@ -13,6 +13,8 @@ Determines whether the logged in user has a specified list of privileges.
 
 `GET /_security/user/_has_privileges`
 
+`POST /_security/user/_has_privileges`
+
 
 [[security-api-has-privileges-prereqs]]
 ==== {api-prereq-title}

x-pack/docs/en/security/authentication/user-profile.asciidoc

@@ -74,6 +74,12 @@ that match given criteria. This API is designed to support user-suggestions,
 in collaboration with features such as those found in {kib}.
 However, the suggest user profile API is not intended to provide a general-purpose search API.
 
+Lastly, you can use the <<security-api-has-privileges-user-profile, has privileges API for
+user profiles>> to check the privileges of multiple users by specifying their profiles' unique IDs.
+This can be used in conjunction with the suggest user profile API in order to restrict the
+suggestions only to users that have the necessary permissions to actually perform
+the action in the context.
+
 ==== Limitations
 
 * Creating a new user profile requires a user's authentication details