[DOCS] Add examples for security user profile and SAML APIs

specification/_doc_ids/table.csv

@@ -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

specification/security/_types/GrantType.ts

@@ -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/security/activate_user_profile/Request.ts

@@ -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/activate_user_profile/examples/request/RequestExample1.yaml

@@ -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/disable_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/enable_user_profile/Request.ts

@@ -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/get_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/get_user_profile/Response.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/has_privileges_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
@@ -44,6 +47,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/has_privileges_user_profile/examples/request/RequestExample1.yaml

@@ -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/examples/response/ResponseExample1.yaml

@@ -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/saml_authenticate/Request.ts

@@ -23,11 +23,25 @@ import { Ids } from '@_types/common'
 /**
  * Authenticate SAML.
  *
- * Submits a SAML response message to Elasticsearch for consumption.
+ * Submit a SAML response message to Elasticsearch for consumption.
+ *
+ * NOTE: This API is intended for use by custom web applications other than Kibana.
+ * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.
+ *
+ * The SAML message that is submitted can be:
+ *
+ * * A response to a SAML authentication request that was previously created using the SAML prepare authentication API.
+ * * An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow.
+ *
+ * In either case, the SAML message needs to be a base64 encoded XML document with a root element of `<Response>`.
+ *
+ * After successful validation, Elasticsearch responds with an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.
+ * This API endpoint essentially exchanges SAML responses that indicate successful authentication in the IdP for Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch.
  * @rest_spec_name security.saml_authenticate
  * @availability stack since=7.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id security-api-saml-authenticate
+ * @ext_doc_id security-saml-guide
  */
 export interface Request extends RequestBase {
   urls: [
@@ -37,9 +51,9 @@ export interface Request extends RequestBase {
     }
   ]
   body: {
-    /** The SAML response as it was sent by the user’s browser, usually a Base64 encoded XML document. */
+    /** The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document. */
     content: string
-    /** A json array with all the valid SAML Request Ids that the caller of the API has for the current user. */
+    /** A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. */
     ids: Ids
     /** The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined. */
     realm?: string

specification/security/saml_authenticate/Response.ts

@@ -21,10 +21,25 @@ import { integer } from '@_types/Numeric'
 
 export class Response {
   body: {
+    /**
+     * The access token that was generated by Elasticsearch.
+     */
     access_token: string
+    /**
+     * The authenticated user's name.
+     */
     username: string
+    /**
+     * The amount of time (in seconds) left until the token expires.
+     */
     expires_in: integer
+    /**
+     * The refresh token that was generated by Elasticsearch.
+     */
     refresh_token: string
+    /**
+     * The name of the realm where the user was authenticated.
+     */
     realm: string
   }
 }

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

@@ -0,0 +1,10 @@
+# summary:
+# method_request: POST /_security/saml/authenticate
+description: >
+  Run `POST /_security/saml/authenticate` to exchange a SAML Response indicating a successful authentication at the SAML IdP for an Elasticsearch access token and refresh token to be used in subsequent requests.
+# type: request
+value: |-
+  {
+    "content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
+    "ids" : ["4fee3b046395c4e751011e97f8900b5273d56685"]
+  }

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

@@ -0,0 +1,12 @@
+# summary:
+description: A successful response from `POST /_security/saml/authenticate`.
+# type: response
+# response_code:
+value: |-
+  {
+    "access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
+    "username" : "Bearer",
+    "expires_in" : 1200,
+    "refresh_token": "mJdXLtmvTUSpoLwMvdBt_w",
+    "realm": "saml1"
+  }

specification/security/saml_complete_logout/Request.ts

@@ -24,10 +24,20 @@ import { Ids } from '@_types/common'
  * Logout of SAML completely.
  *
  * Verifies the logout response sent from the SAML IdP.
+ *
+ * NOTE: This API is intended for use by custom web applications other than Kibana.
+ * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.
+ *
+ * The SAML IdP may send a logout response back to the SP after handling the SP-initiated SAML Single Logout.
+ * This API verifies the response by ensuring the content is relevant and validating its signature.
+ * An empty response is returned if the verification process is successful.
+ * The response can be sent by the IdP with either the HTTP-Redirect or the HTTP-Post binding.
+ * The caller of this API must prepare the request accordingly so that this API can handle either of them.
  * @rest_spec_name security.saml_complete_logout
  * @availability stack since=7.14.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id security-api-saml-complete-logout
+ * @ext_doc_id security-saml-guide
  */
 export interface Request extends RequestBase {
   urls: [
@@ -39,9 +49,11 @@ export interface Request extends RequestBase {
   body: {
     /** The name of the SAML realm in Elasticsearch for which the configuration is used to verify the logout response. */
     realm: string
-    /**  A json array with all the valid SAML Request Ids that the caller of the API has for the current user. */
+    /**  A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. */
     ids: Ids
-    /** If the SAML IdP sends the logout response with the HTTP-Redirect binding, this field must be set to the query string of the redirect URI. */
+    /**
+     * If the SAML IdP sends the logout response with the HTTP-Redirect binding, this field must be set to the query string of the redirect URI.
+     */
     query_string?: string
     /** If the SAML IdP sends the logout response with the HTTP-Post binding, this field must be set to the value of the SAMLResponse form parameter from the logout response. */
     content?: string