Add remaining security API examples (#3546) (#3559)

(cherry picked from commit a1856fe)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -477,8 +477,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
@@ -665,8 +664,13 @@ security-api-update-key,https://www.elastic.co/guide/en/elasticsearch/reference/
 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-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-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
@@ -701,6 +705,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

output/openapi/elasticsearch-serverless-openapi.json

@@ -217,7 +217,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:
@@ -253,7 +253,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
   /**
@@ -293,7 +293,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[]
   /**
@@ -430,7 +430,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
   /**

output/schema/schema.json

@@ -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/_doc_ids/table.csv

@@ -33,6 +33,11 @@ import { Name } from '@_types/common'
  */
 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/_types/Privileges.ts

@@ -23,17 +23,32 @@ 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 {
   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/_types/RoleDescriptor.ts

@@ -32,6 +32,11 @@ import { Names } from '@_types/common'
  */
 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_privileges/SecurityClearCachedPrivilegesRequest.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
@@ -33,8 +38,15 @@ import { Names, Namespace, Service } from '@_types/common'
  */
 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
   }
 }