[8.17] Add security API examples (#3490)

docs/overlays/elasticsearch-openapi-overlays.yaml

@@ -566,9 +566,6 @@ actions:
               examples:
                 updateWatcherSettingsRequestExample1: 
                   $ref: "../../specification/watcher/get_settings/examples/200_response/WatcherGetSettingsResponseExample1.yaml"
-<<<<<<< HEAD
-
-=======
 ## Examples for inference
   - target: "$.components['requestBodies']['inference.stream_inference']"
     description: "Add example for inference stream request"
@@ -578,4 +575,3 @@ actions:
           examples:
             streamInferenceRequestExample1:
               $ref: "../../specification/inference/stream_inference/examples/request/StreamInferenceRequestExample1.yaml"
->>>>>>> cf1f2c9ae (Add inference.stream_inference and inference.update (#3399))

specification/_doc_ids/table.csv

@@ -599,6 +599,7 @@ searchable-snapshots-api-stats,https://www.elastic.co/guide/en/elasticsearch/ref
 searchable-snapshots-apis,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/searchable-snapshots-apis.html
 search-templates,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-template.html
 secure-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/secure-settings.html
+security-api-activate-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-activate-user-profile.html
 security-api-authenticate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-authenticate.html
 security-api-bulk-update-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-bulk-update-api-keys.html
 security-api-change-password,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-change-password.html
@@ -610,6 +611,7 @@ security-api-clear-service-token-caches,https://www.elastic.co/guide/en/elastics
 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-cross-cluster-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-create-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
@@ -619,7 +621,7 @@ security-api-delete-user,https://www.elastic.co/guide/en/elasticsearch/reference
 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-enable-user-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/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
@@ -630,6 +632,7 @@ security-api-get-service-credentials,https://www.elastic.co/guide/en/elasticsear
 security-api-get-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-settings.html
 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-profile,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user-profile.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
@@ -647,6 +650,8 @@ security-api-put-role-mapping,https://www.elastic.co/guide/en/elasticsearch/refe
 security-api-put-role,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-put-role.html
 security-api-put-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-put-user.html
 security-api-query-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-query-api-key.html
+security-api-query-role,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-query-role.html
+security-api-query-user,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-query-user.html
 security-api-saml-authenticate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-authenticate.html
 security-api-saml-complete-logout,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-complete-logout.html
 security-api-saml-invalidate,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-invalidate.html
@@ -656,10 +661,10 @@ security-api-saml-sp-metadata,https://www.elastic.co/guide/en/elasticsearch/refe
 security-api-ssl,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-ssl.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-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-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

specification/security/activate_user_profile/Request.ts

@@ -39,6 +39,7 @@ import { RequestBase } from '@_types/Base'
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_user_profile
+ * @doc_id security-api-activate-user-profile
  */
 export interface Request extends RequestBase {
   body: {

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

@@ -1,4 +1,5 @@
 # summary:
+<<<<<<< HEAD
 # method_request: POST /_security/profile/_activate
 description: >
   Run `POST /_security/profile/_activate` to activate a user profile.
@@ -8,4 +9,19 @@ value: |-
     "grant_type": "password",
     "username" : "jacknich",
     "password" : "l0ng-r4nd0m-p@ssw0rd"
+=======
+# method_request: POST /_security/user/jacknich
+description: >
+  Run `POST /_security/user/jacknich` to create a user.
+# type: request
+value: |-
+  {
+    "password" : "l0ng-r4nd0m-p@ssw0rd",
+    "roles" : [ "admin", "other_role1" ],
+    "full_name" : "Jack Nicholson",
+    "email" : "jacknich@example.com",
+    "metadata" : {
+      "intelligence" : 7
+    }
+>>>>>>> fb93809aa (Add security API examples (#3490))
   }

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

@@ -0,0 +1,25 @@
+# summary:
+description: A successful response from `POST /_security/profile/_activate`.
+# type: response
+# response_code:
+value: |-
+  {
+    "uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
+    "enabled": true,
+    "last_synchronized": 1642650651037,
+    "user": {
+      "username": "jacknich",
+      "roles": [
+        "admin", "other_role1"
+      ],
+      "realm_name": "native",
+      "full_name": "Jack Nicholson",
+      "email": "jacknich@example.com"
+    },
+    "labels": {},
+    "data": {},
+    "_doc": {
+      "_primary_term": 88,
+      "_seq_no": 66
+    }
+  }

specification/security/authenticate/SecurityAuthenticateRequest.ts

@@ -29,5 +29,6 @@ import { RequestBase } from '@_types/Base'
  * @rest_spec_name security.authenticate
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @doc_id security-api-authenticate
  */
 export interface Request extends RequestBase {}

specification/security/authenticate/examples/response/SecurityAuthenticateResponseExample1.yaml

@@ -0,0 +1,24 @@
+# summary:
+description: A successful response from `GET /_security/_authenticate`.
+# type: response
+# response_code: 200
+value: |-
+  {
+    "username": "rdeniro",
+    "roles": [
+      "admin"
+    ],
+    "full_name": null,
+    "email":  null,
+    "metadata": { },
+    "enabled": true,
+    "authentication_realm": {
+      "name" : "file",
+      "type" : "file"
+    },
+    "lookup_realm": {
+      "name" : "file",
+      "type" : "file"
+    },
+    "authentication_type": "realm"
+  }

specification/security/bulk_delete_role/examples/request/SecurityBulkDeleteRoleRequestExample1.yaml

@@ -0,0 +1,9 @@
+summary: Bulk delete example 1
+# method_request: DELETE /_security/role
+description: >
+  Run DELETE /_security/role` to delete `my_admin_role` and `my_user_role` roles.
+# type: request
+value: |-
+  {
+    "names": ["my_admin_role", "my_user_role"]
+  }

specification/security/bulk_delete_role/examples/response/SecurityBulkDeleteRoleResponseExample1.yaml

@@ -0,0 +1,11 @@
+summary: A successful response
+description: A successful response from `DELETE /_security/role`.
+# type: response
+# response_code:
+value: |-
+  {
+    "deleted": [
+        "my_admin_role",
+        "my_user_role"
+    ]
+  }

specification/security/bulk_delete_role/examples/response/SecurityBulkDeleteRoleResponseExample2.yaml

@@ -0,0 +1,15 @@
+summary: A response with not_found roles
+description: >
+  A partially successful response from `DELETE /_security/role`.
+  If a role cannot be found, it appears in the `not_found` list in the response.
+# type: response
+# response_code:
+value: |-
+  {
+    "deleted": [
+        "my_admin_role"
+    ],
+    "not_found": [
+        "not_an_existing_role"
+    ]
+  }

specification/security/bulk_delete_role/examples/response/SecurityBulkDeleteRoleResponseExample3.yaml

@@ -0,0 +1,21 @@
+summary: A response with errors
+description: >
+  A partially successful response from `DELETE /_security/role`.
+  If part of a request fails or is invalid, the response includes `errors`.
+# type: response
+# response_code:
+value: |-
+  {
+    "deleted": [
+        "my_admin_role"
+    ],
+    "errors": {
+        "count": 1,
+        "details": {
+            "superuser": {
+                "type": "illegal_argument_exception",
+                "reason": "role [superuser] is reserved and cannot be deleted"
+            }
+        }
+    }
+  }

specification/security/bulk_put_role/examples/request/SecurityBulkPutRoleRequestExample1.yaml

@@ -0,0 +1,91 @@
+summary: Bulk role success
+# method_request: POST /_security/role
+description: >
+  Run `POST /_security/role` to add roles called `my_admin_role` and `my_user_role`.
+# type: request
+value: |-
+  {
+    "roles": {
+        "my_admin_role": {
+            "cluster": [
+                "all"
+            ],
+            "indices": [
+                {
+                    "names": [
+                        "index1",
+                        "index2"
+                    ],
+                    "privileges": [
+                        "all"
+                    ],
+                    "field_security": {
+                        "grant": [
+                            "title",
+                            "body"
+                        ]
+                    },
+                    "query": "{\"match\": {\"title\": \"foo\"}}"
+                }
+            ],
+            "applications": [
+                {
+                    "application": "myapp",
+                    "privileges": [
+                        "admin",
+                        "read"
+                    ],
+                    "resources": [
+                        "*"
+                    ]
+                }
+            ],
+            "run_as": [
+                "other_user"
+            ],
+            "metadata": {
+                "version": 1
+            }
+        },
+        "my_user_role": {
+            "cluster": [
+                "all"
+            ],
+            "indices": [
+                {
+                    "names": [
+                        "index1"
+                    ],
+                    "privileges": [
+                        "read"
+                    ],
+                    "field_security": {
+                        "grant": [
+                            "title",
+                            "body"
+                        ]
+                    },
+                    "query": "{\"match\": {\"title\": \"foo\"}}"
+                }
+            ],
+            "applications": [
+                {
+                    "application": "myapp",
+                    "privileges": [
+                        "admin",
+                        "read"
+                    ],
+                    "resources": [
+                        "*"
+                    ]
+                }
+            ],
+            "run_as": [
+                "other_user"
+            ],
+            "metadata": {
+                "version": 1
+            }
+        }
+    }
+  }