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

(cherry picked from commit 72c9fef)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -609,14 +609,17 @@ security-api-clear-role-cache,https://www.elastic.co/guide/en/elasticsearch/refe
 security-api-clear-service-token-caches,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-clear-service-token-caches.html
 security-api-create-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-create-api-key.html
 security-api-create-service-token,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-create-service-token.html
+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-delegate-pki,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delegate-pki-authentication.html
 security-api-delete-privilege,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-privilege.html
 security-api-delete-role-mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-role-mapping.html
 security-api-delete-role,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-role.html
 security-api-delete-service-token,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-service-token.html
 security-api-delete-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-user.html
 security-api-disable-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-disable-user.html
+security-api-disable-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-disable-user-profile.html
 security-api-enable-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-enable-user.html
+security-api-enable-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-enable-user-profile.html
 security-api-get-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-api-key.html
 security-api-get-builtin-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-builtin-privileges.html
 security-api-get-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-privileges.html
@@ -628,8 +631,10 @@ security-api-get-settings,https://www.elastic.co/guide/en/elasticsearch/referenc
 security-api-get-token,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-token.html
 security-api-get-user-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user-privileges.html
 security-api-get-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user.html
+security-api-get-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user-profile.html
 security-api-grant-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-grant-api-key.html
 security-api-has-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-has-privileges.html
+security-api-has-privileges-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-has-privileges-user-profile.html
 security-api-invalidate-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-invalidate-api-key.html
 security-api-invalidate-token,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-invalidate-token.html
 security-api-kibana-enrollment,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-kibana-enrollment.html
@@ -649,8 +654,13 @@ security-api-saml-logout,https://www.elastic.co/guide/en/elasticsearch/reference
 security-api-saml-prepare-authentication,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-prepare-authentication.html
 security-api-saml-sp-metadata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-sp-metadata.html
 security-api-ssl,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-ssl.html
-security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html
+security-api-suggest,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-suggest-user-profile.html
+security-api-update-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-api-key.html
 security-api-update-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-settings.html
+security-api-update-user-data,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-user-profile-data.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,16 +24,46 @@ 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
  * @cluster_privileges manage_user_profile
  */
 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

@@ -0,0 +1,11 @@
+# summary:
+# method_request: POST /_security/profile/_activate
+description: >
+  Run `POST /_security/profile/_activate` to activate a user profile.
+# type: request
+value: |-
+  {
+    "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,23 +25,32 @@ 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
  * @cluster_privileges manage_user_profile
+ * @doc_id security-api-enable-user-profile
  */
 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,15 @@ 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 {
   path_parts: {
@@ -38,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
   }