Add examples for security user profile APIs

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -24,6 +24,7 @@ export enum GrantType {
   password,
   /**
    * In this type of grant, you must supply an access token that was created by the Elasticsearch token service.
+   * If you are activating a user profile, you can alternatively supply a JWT (either a JWT `access_token` or a JWT `id_token`).
    */
   access_token
 }

output/schema/schema.json

@@ -24,6 +24,17 @@ import { RequestBase } from '@_types/Base'
  * Activate a user profile.
  *
  * Create or update a user profile on behalf of another user.
+ *
+ * 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.
+ * 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.
+ * Elastic reserves the right to change or remove this feature in future releases without prior notice.
+ *
+ * This 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.
+ * For example, in the JWT `access_token` case, the profile user's `username` is extracted from the JWT token claim pointed to by the `claims.principal` setting of the JWT realm that authenticated the token.
+ *
+ * When updating a profile document, the API enables the document if it was disabled.
+ * Any updates do not change existing content for either the `labels` or `data` fields.
  * @rest_spec_name security.activate_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
@@ -32,9 +43,28 @@ import { RequestBase } from '@_types/Base'
  */
 export interface Request extends RequestBase {
   body: {
+    /**
+     * The user's Elasticsearch access token or JWT.
+     * Both `access` and `id` JWT token types are supported and they depend on the underlying JWT realm configuration.
+     * If you specify the `access_token` grant type, this parameter is required.
+     * It is not valid with other grant types.
+     */
     access_token?: string
+    /**
+     * The type of grant.
+     */
     grant_type: GrantType
+    /**
+     * The user's password.
+     * If you specify the `password` grant type, this parameter is required.
+     * It is not valid with other grant types.
+     */
     password?: 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.
+     */
     username?: string
   }
 }

specification/security/_types/GrantType.ts

@@ -1,15 +1,11 @@
 # summary:
-# method_request: POST /_security/user/jacknich
+# method_request: POST /_security/profile/_activate
 description: >
-  Run `POST /_security/user/jacknich` to create a user.
+  Run `POST /_security/profile/_activate` to activate a user profile.
 # type: request
 value: |-
   {
-    "password" : "l0ng-r4nd0m-p@ssw0rd",
-    "roles" : [ "admin", "other_role1" ],
-    "full_name" : "Jack Nicholson",
-    "email" : "[email protected]",
-    "metadata" : {
-      "intelligence" : 7
-    }
+    "grant_type": "password",
+    "username" : "jacknich",
+    "password" : "l0ng-r4nd0m-p@ssw0rd"
   }

specification/security/activate_user_profile/Request.ts

@@ -25,10 +25,18 @@ import { Refresh } from '@_types/common'
  * Disable a user profile.
  *
  * Disable user profiles so that they are not visible in user profile searches.
+ *
+ * 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.
+ *
+ * When you activate a user profile, its automatically enabled and visible in user profile searches. You can use the disable user profile API to disable a user profile so it’s not visible in these searches.
+ * To re-enable a disabled user profile, use the enable user profile API .
  * @rest_spec_name security.disable_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_user_profile
+ * @doc_id security-api-disable-user-profile
  */
 export interface Request extends RequestBase {
   path_parts: {
@@ -39,9 +47,9 @@ export interface Request extends RequestBase {
   }
   query_parameters: {
     /**
-     * If 'true', Elasticsearch refreshes the affected shards to make this operation
-     * visible to search, if 'wait_for' then wait for a refresh to make this operation
-     * visible to search, if 'false' do nothing with refreshes.
+     * If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search.
+     * If 'wait_for', it waits for a refresh to make this operation visible to search.
+     * If 'false', it does nothing with refreshes.
      * @server_default false
      */
     refresh?: Refresh

specification/security/activate_user_profile/examples/request/RequestExample1.yaml

@@ -25,6 +25,13 @@ import { Refresh } from '@_types/common'
  * Enable a user profile.
  *
  * Enable user profiles to make them visible in user profile searches.
+ *
+ * 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.
+ *
+ * When you activate a user profile, it's automatically enabled and visible in user profile searches.
+ * If you later disable the user profile, you can use the enable user profile API to make the profile visible in these searches again.
  * @rest_spec_name security.enable_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
@@ -34,15 +41,16 @@ import { Refresh } from '@_types/common'
 export interface Request extends RequestBase {
   path_parts: {
     /**
-     * Unique identifier for the user profile.
+     * A unique identifier for the user profile.
      */
     uid: UserProfileId
   }
   query_parameters: {
     /**
      * If 'true', Elasticsearch refreshes the affected shards to make this operation
-     * visible to search, if 'wait_for' then wait for a refresh to make this operation
-     * visible to search, if 'false' do nothing with refreshes.
+     * visible to search.
+     * If 'wait_for', it waits for a refresh to make this operation visible to search.
+     * If 'false', nothing is done with refreshes.
      * @server_default false
      */
     refresh?: Refresh

specification/security/disable_user_profile/Request.ts

@@ -24,10 +24,14 @@ import { RequestBase } from '@_types/Base'
  * Get a user profile.
  *
  * Get a user's profile using the unique profile ID.
+ *
+ * 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.
  * @rest_spec_name security.get_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
- * @cluster_privileges manage_user_profile
+ * @cluster_privileges read_security
  * @doc_id security-api-get-user-profile
  */
 export interface Request extends RequestBase {
@@ -39,9 +43,9 @@ export interface Request extends RequestBase {
   }
   query_parameters: {
     /**
-     * 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>`.
+     * 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 returns no `data` content.
      */
     data?: string | string[]

specification/security/enable_user_profile/Request.ts

@@ -22,6 +22,11 @@ import { GetUserProfileErrors } from './types'
 
 export class Response {
   body: {
+    /**
+     * 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.
+     */
     profiles: UserProfileWithMetadata[]
     errors?: GetUserProfileErrors
   }

specification/security/get_user_profile/Request.ts

@@ -25,6 +25,9 @@ import { PrivilegesCheck } from './types'
  * Check user profile privileges.
  *
  * Determine whether the users associated with the specified user profile IDs have all the requested privileges.
+ *
+ * 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.
  * @rest_spec_name security.has_privileges_user_profile
  * @availability stack since=8.3.0 stability=stable
  * @availability serverless stability=stable visibility=private
@@ -38,6 +41,9 @@ export interface Request extends RequestBase {
      * A list of profile IDs. The privileges are checked for associated users of the profiles.
      */
     uids: UserProfileId[]
+    /**
+     * An object containing all the privileges to be checked.
+     */
     privileges: PrivilegesCheck
   }
 }

specification/security/get_user_profile/Response.ts

@@ -0,0 +1,33 @@
+# summary:
+# method_request: POST /_security/profile/_has_privileges
+description: >
+  Run `POST /_security/profile/_has_privileges` to check whether the two users associated with the specified profiles have all the requested set of cluster, index, and application privileges.
+# type: request
+value: |-
+  {
+    "uids": [
+      "u_LQPnxDxEjIH0GOUoFkZr5Y57YUwSkL9Joiq-g4OCbPc_0",
+      "u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1",
+      "u_does-not-exist_0"
+    ],
+    "privileges": {
+      "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" ]
+        }
+      ]
+    }
+  }

specification/security/has_privileges_user_profile/Request.ts

@@ -0,0 +1,18 @@
+# summary:
+description: >
+  A response from `POST /_security/profile/_has_privileges` that indicates only one of the three users has all the privileges and one of them is not found.
+# type: response
+# response_code:
+value: |-
+  {
+    "has_privilege_uids": ["u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1"],
+    "errors": {
+      "count": 1,
+      "details": {
+        "u_does-not-exist_0": {
+          "type": "resource_not_found_exception",
+          "reason": "profile document not found"
+        }
+      }
+    }
+  }

specification/security/has_privileges_user_profile/examples/request/RequestExample1.yaml

@@ -25,6 +25,10 @@ import { Hint } from './types'
  * Suggest a user profile.
  *
  * 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.
  * @rest_spec_name security.suggest_user_profiles
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
@@ -34,36 +38,37 @@ import { Hint } from './types'
 export interface Request extends RequestBase {
   query_parameters: {
     /**
-     * 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 returns no `data` content.
+     * 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.
      */
     data?: string | string[]
   }
   body: {
     /**
-     * Query string used to match name-related fields in user profile documents.
+     * 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`.
      */
     name?: string
     /**
-     * Number of profiles to return.
+     * The number of profiles to return.
      * @server_default 10
      */
     size?: long
     /**
-     * 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 returns no `data` content.
+     * 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.
      */
     data?: string | string[]
     /**
      * 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 don't exclude the profile from the response
-     * as long as the profile matches the `name` field query.
+     * Profiles not matching the hint aren't excluded from the response as long as the profile matches the `name` field query.
      */
     hint?: Hint
   }

specification/security/has_privileges_user_profile/examples/response/ResponseExample1.yaml

@@ -28,8 +28,17 @@ export class TotalUserProfiles {
 
 export class Response {
   body: {
+    /**
+     * Metadata about the number of matching profiles.
+     */
     total: TotalUserProfiles
+    /**
+     * The number of milliseconds it took Elasticsearch to run the request.
+     */
     took: long
+    /**
+     * A list of profile documents, ordered by relevance, that match the search criteria.
+     */
     profiles: UserProfile[]
   }
 }

specification/security/suggest_user_profiles/Request.ts

@@ -0,0 +1,20 @@
+# summary:
+# method_request: POST /_security/profile/_suggest
+description: >
+  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`.
+# type: request
+value: |-
+  {
+    "name": "jack",  
+    "hint": {
+      "uids": [  
+        "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
+        "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
+      ],
+      "labels": {
+        "direction": ["north", "east"]  
+      }
+    }
+  }