Add remaining security API examples (#3546)

specification/_doc_ids/table.csv

@@ -490,8 +490,7 @@ reroute-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branc
 render-search-template-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/render-search-template-api.html
 reset-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/reset-transform.html
 restore-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-restore-snapshot.html
-sql-delete-async-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-async-sql-search-api.html
-sql-clear-cursor-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-sql-cursor-api.html
+role-restriction,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/role-restriction.html
 rollup-agg-limitations,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-agg-limitations.html
 rollup-delete-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-delete-job.html
 rollup-get-job,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rollup-get-job.html
@@ -676,9 +675,14 @@ security-api-cross-cluster-key-update,https://www.elastic.co/guide/en/elasticsea
 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-api-update-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-settings.html
+security-application-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html#application-privileges
+security-encrypt-http,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-basic-setup-https.html#encrypt-http-communication
 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
+security-settings-api-keys,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-settings.html#api-key-service-settings
+security-settings-hashing,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-settings.html#hashing-settings
+security-user-cache,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/controlling-user-cache.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
@@ -716,6 +720,8 @@ query-dsl-sparse-vector-query,https://www.elastic.co/guide/en/elasticsearch/refe
 split-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/split-processor.html
 sql-async-search-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-api.html
 sql-async-status-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-async-sql-search-status-api.html
+sql-clear-cursor-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clear-sql-cursor-api.html
+sql-delete-async-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-async-sql-search-api.html
 sql-rest-columnar,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-columnar.html
 sql-rest-filtering,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-filtering.html
 sql-rest-format,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sql-rest-format.html

specification/security/_types/Privileges.ts

@@ -216,7 +216,7 @@ export enum RemoteClusterPrivilege {
 export class IndicesPrivileges {
   /**
    * The document fields that the owners of the role have read access to.
-   * @doc_id field-and-document-access-control
+   * @ext_doc_id field-and-document-access-control
    */
   field_security?: FieldSecurity
   // We're using IndexName | IndexName[] instead of Indices in this file on purpose:
@@ -252,7 +252,7 @@ export class RemoteIndicesPrivileges {
   clusters: Names
   /**
    * The document fields that the owners of the role have read access to.
-   * @doc_id field-and-document-access-control
+   * @ext_doc_id field-and-document-access-control
    */
   field_security?: FieldSecurity
   /**
@@ -292,7 +292,7 @@ export class RemoteClusterPrivileges {
 export class UserIndicesPrivileges {
   /**
    * The document fields that the owners of the role have read access to.
-   * @doc_id field-and-document-access-control
+   * @ext_doc_id field-and-document-access-control
    */
   field_security?: FieldSecurity[]
   /**
@@ -429,7 +429,7 @@ export class ReplicationAccess {
 export class SearchAccess {
   /**
    * The document fields that the owners of the role have read access to.
-   * @doc_id field-and-document-access-control
+   * @ext_doc_id field-and-document-access-control
    */
   field_security?: FieldSecurity
   /**

specification/security/_types/RoleDescriptor.ts

@@ -46,7 +46,8 @@ export class RoleDescriptor {
    */
   remote_indices?: RemoteIndicesPrivileges[]
   /**
-   * A list of cluster permissions for remote clusters. Note - this is limited a subset of the cluster permissions.
+   * A list of cluster permissions for remote clusters.
+   * NOTE: This is limited a subset of the cluster permissions.
    * @availability stack since=8.15.0
    */
   remote_cluster?: RemoteClusterPrivileges[]
@@ -64,8 +65,10 @@ export class RoleDescriptor {
    */
   metadata?: Metadata
   /**
-   * A list of users that the API keys can impersonate. *Note*: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected.
-   * @doc_id run-as-privilege
+   * A list of users that the API keys can impersonate.
+   * NOTE: In Elastic Cloud Serverless, the run-as feature is disabled.
+   * For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected.
+   * @ext_doc_id run-as-privilege
    */
   run_as?: string[]
   /**
@@ -95,7 +98,8 @@ export class RoleDescriptorRead implements OverloadOf<RoleDescriptor> {
    */
   remote_indices?: RemoteIndicesPrivileges[]
   /**
-   * A list of cluster permissions for remote clusters. Note - this is limited a subset of the cluster permissions.
+   * A list of cluster permissions for remote clusters.
+   * NOTE: This is limited a subset of the cluster permissions.
    * @availability stack since=8.15.0
    */
   remote_cluster?: RemoteClusterPrivileges[]
@@ -113,21 +117,26 @@ export class RoleDescriptorRead implements OverloadOf<RoleDescriptor> {
   metadata?: Metadata
   /**
    * A list of users that the API keys can impersonate.
-   * @doc_id run-as-privilege
+   * @ext_doc_id run-as-privilege
    */
   run_as?: string[]
   /**
-   * Optional description of the role descriptor
+   * An optional description of the role descriptor.
    */
   description?: string
   /**
-   * Restriction for when the role descriptor is allowed to be effective.
+   * A restriction for when the role descriptor is allowed to be effective.
+   * @ext_doc_id role-restriction
    */
   restriction?: Restriction
   transient_metadata?: Dictionary<string, UserDefinedValue>
 }
 
 export class Restriction {
+  /**
+   * A list of workflows to which the API key is restricted.
+   * NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.
+   */
   workflows: RestrictionWorkflow[]
 }
 

specification/security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts

@@ -39,6 +39,11 @@ export interface Request extends RequestBase {
     }
   ]
   path_parts: {
+    /**
+     * A comma-separated list of applications.
+     * To clear all applications, use an asterism (`*`).
+     * It does not support other wildcard patterns.
+     */
     application: Name
   }
 }

specification/security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts

@@ -23,11 +23,17 @@ import { Names } from '@_types/common'
 /**
  * Clear the user cache.
  *
- * Evict users from the user cache. You can completely clear the cache or evict specific users.
+ * Evict users from the user cache.
+ * You can completely clear the cache or evict specific users.
+ *
+ * User credentials are cached in memory on each node to avoid connecting to a remote authentication service or hitting the disk for every incoming request.
+ * There are realm settings that you can use to configure the user cache.
+ * For more information, refer to the documentation about controlling the user cache.
  * @rest_spec_name security.clear_cached_realms
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id security-api-clear-cache
+ * @ext_doc_id security-user-cache
  */
 export interface Request extends RequestBase {
   urls: [
@@ -37,9 +43,18 @@ export interface Request extends RequestBase {
     }
   ]
   path_parts: {
+    /**
+     * A comma-separated list of realms.
+     * To clear all realms, use an asterisk (`*`).
+     * It does not support other wildcard patterns.
+     */
     realms: Names
   }
   query_parameters: {
+    /**
+     * A comma-separated list of the users to clear from the cache.
+     * If you do not specify this parameter, the API evicts all users from the user cache.
+     */
     usernames?: string[]
   }
 }

specification/security/clear_cached_roles/ClearCachedRolesRequest.ts

@@ -38,6 +38,11 @@ export interface Request extends RequestBase {
     }
   ]
   path_parts: {
+    /**
+     * A comma-separated list of roles to evict from the role cache.
+     * To evict all roles, use an asterisk (`*`).
+     * It does not support other wildcard patterns.
+     */
     name: Names
   }
 }

specification/security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts

@@ -24,6 +24,11 @@ import { Names, Namespace, Service } from '@_types/common'
  * Clear service account token caches.
  *
  * Evict a subset of all entries from the service account token caches.
+ * Two separate caches exist for service account tokens: one cache for tokens backed by the `service_tokens` file, and another for tokens backed by the `.security` index.
+ * This API clears matching entries from both caches.
+ *
+ * The cache for service account tokens backed by the `.security` index is cleared automatically on state changes of the security index.
+ * The cache for tokens backed by the `service_tokens` file is cleared automatically on file changes.
  * @rest_spec_name security.clear_cached_service_tokens
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
@@ -39,8 +44,15 @@ export interface Request extends RequestBase {
     }
   ]
   path_parts: {
+    /** The namespace, which is a top-level grouping of service accounts. */
     namespace: Namespace
+    /** The name of the service, which must be unique within its namespace. */
     service: Service
+    /**
+     * A comma-separated list of token names to evict from the service account token caches.
+     * Use a wildcard (`*`) to evict all tokens that belong to a service account.
+     * It does not support other wildcard patterns.
+     */
     name: Names
   }
 }

specification/security/create_api_key/SecurityCreateApiKeyRequest.ts

@@ -27,15 +27,23 @@ import { Duration } from '@_types/Time'
  * Create an API key.
  *
  * Create an API key for access without requiring basic authentication.
+ *
+ * IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges.
+ * If you specify privileges, the API returns an error.
+ *
  * A successful request returns a JSON structure that contains the API key, its unique id, and its name.
  * If applicable, it also returns expiration information for the API key in milliseconds.
+ *
  * NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.
  *
+ * The API keys are created by the Elasticsearch API key service, which is automatically enabled.
+ * To configure or turn off the API key service, refer to API key service setting documentation.
  * @rest_spec_name security.create_api_key
  * @availability stack since=6.7.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @cluster_privileges manage_own_api_key
  * @doc_id security-api-create-api-key
+ * @ext_doc_id security-settings-api-keys
  */
 export interface Request extends RequestBase {
   urls: [
@@ -48,13 +56,24 @@ export interface Request extends RequestBase {
     refresh?: Refresh
   }
   body: {
-    /** Expiration time for the API key. By default, API keys never expire. */
+    /**
+     * The expiration time for the API key.
+     * By default, API keys never expire.
+     */
     expiration?: Duration
-    /** Specifies the name for this API key. */
+    /** A name for the API key. */
     name?: Name
     /**
-     *  An array of role descriptors for this API key. This parameter is optional. When it is not specified or is an empty array, then the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors then the resultant permissions would be an intersection of API keys permissions and authenticated user’s permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for create role API. For more details, see create or update roles API.
-     * @doc_id security-api-put-role
+     * An array of role descriptors for this API key.
+     * When it is not specified or it is an empty array, the API key will have a point in time snapshot of permissions of the authenticated user.
+     * If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the authenticated user's permissions thereby limiting the access scope for API keys.
+     * The structure of role descriptor is the same as the request for the create role API.
+     * For more details, refer to the create or update roles API.
+     *
+     * NOTE: Due to the way in which this permission intersection is calculated, it is not possible to create an API key that is a child of another API key, unless the derived key is created without any privileges.
+     * In this case, you must explicitly specify a role descriptor with no privileges.
+     * The derived API key can be used for authentication; it will not have authority to call Elasticsearch APIs.
+     * @ext_doc_id security-api-put-role
      */
     role_descriptors?: Dictionary<string, RoleDescriptor>
     /**

specification/security/create_service_token/CreateServiceTokenRequest.ts

@@ -24,6 +24,9 @@ import { Name, Namespace, Refresh, Service } from '@_types/common'
  * Create a service account token.
  *
  * Create a service accounts token for access without requiring basic authentication.
+ *
+ * NOTE: Service account tokens never expire.
+ * You must actively delete them if they are no longer needed.
  * @rest_spec_name security.create_service_token
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
@@ -43,8 +46,24 @@ export interface Request extends RequestBase {
     }
   ]
   path_parts: {
+    /**
+     * The name of the namespace, which is a top-level grouping of service accounts.
+     */
     namespace: Namespace
+    /**
+     * The name of the service.
+     */
     service: Service
+    /**
+     * The name for the service account token.
+     * If omitted, a random name will be generated.
+     *
+     * Token names must be at least one and no more than 256 characters.
+     * They can contain alphanumeric characters (a-z, A-Z, 0-9), dashes (`-`), and underscores (`_`), but cannot begin with an underscore.
+     *
+     * NOTE: Token names must be unique in the context of the associated service account.
+     * They must also be globally unique with their fully qualified names, which are comprised of the service account principal and token name, such as `<namespace>/<service>/<token-name>`.
+     */
     name?: Name
   }
   query_parameters: {

specification/security/create_service_token/CreateServiceTokenResponse.ts

@@ -20,6 +20,9 @@
 import { Token } from './types'
 
 export class Response {
+  /**
+   * A successful create service account token API call returns a JSON structure that contains the service account token, its name, and its secret value.
+   */
   body: {
     created: boolean
     token: Token

specification/security/create_service_token/examples/response/CreateServiceTokenRequestExample1.yaml

@@ -1,10 +1,14 @@
 # summary:
 description: >
-  A successful response from `POST /_security/user/jacknich`.
-  When an existing user is updated, `created` is set to `false`.
+  A successful response from `POST /_security/service/elastic/fleet-server/credential/token/token1`.
+  The response includes the service account token, its name, and its secret value as a bearer token.
 # type: response
 # response_code:
 value: |-
   {
-    "created": true 
+    "created": true,
+    "token": {
+      "name": "token1",
+      "value": "AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ" 
+    }
   }

specification/security/delegate_pki/SecurityDelegatePkiRequest.ts

@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 
 /**
  * Delegate PKI authentication.
+ *
  * This API implements the exchange of an X509Certificate chain for an Elasticsearch access token.
  * The certificate chain is validated, according to RFC 5280, by sequentially considering the trust configuration of every installed PKI realm that has `delegation.enabled` set to `true`.
  * A successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw `username_pattern` of the respective realm.

specification/security/delete_privileges/SecurityDeletePrivilegesRequest.ts

@@ -22,9 +22,15 @@ import { Name, Names, Refresh } from '@_types/common'
 
 /**
  * Delete application privileges.
+ *
+ * To use this API, you must have one of the following privileges:
+ *
+ * * The `manage_security` cluster privilege (or a greater privilege such as `all`).
+ * * The "Manage Application Privileges" global privilege for the application being referenced in the request.
  * @rest_spec_name security.delete_privileges
  * @availability stack since=6.4.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @cluster_privileges manage_security
  * @doc_id security-api-delete-privilege
  * @ext_doc_id security-privileges
  */
@@ -36,7 +42,14 @@ export interface Request extends RequestBase {
     }
   ]
   path_parts: {
+    /**
+     * The name of the application.
+     * Application privileges are always associated with exactly one application.
+     */
     application: Name
+    /**
+     * The name of the privilege.
+     */
     name: Names
   }
   query_parameters: {

specification/security/delete_privileges/examples/response/SecurityDeletePrivilegesResponseExample1.yaml

@@ -1,6 +1,7 @@
 # summary:
 description: >
   A successful response from `DELETE /_security/privilege/myapp/read`.
+  If the privilege is successfully deleted, `found` is set to `true`.
 # type: response
 # response_code:
 value: |-