[DOCS] Add examples for security user profile and SAML APIs (#3520)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -672,9 +672,10 @@ security-api-suggest,https://www.elastic.co/guide/en/elasticsearch/reference/{br
 security-api-cross-cluster-key-update,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-cross-cluster-api-key.html
 security-api-update-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-api-key.html
 security-api-update-user-data,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-user-profile-data.html
-security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html
 security-api-update-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-settings.html
 security-encrypt-internode,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-basic-setup.html#encrypt-internode-communication
+security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html
+security-saml-guide,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/saml-guide-stack.html
 service-accounts,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/service-accounts.html
 set-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/set-processor.html
 shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shape.html

output/schema/schema.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
 }

specification/_doc_ids/table.csv

@@ -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
@@ -38,9 +49,28 @@ 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" : "jacknich@example.com",
-    "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 {
   urls: [
@@ -45,9 +53,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
@@ -40,15 +47,16 @@ 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 {
@@ -45,9 +49,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
   }