Add security API examples (#3490)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -607,6 +607,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
@@ -617,14 +618,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,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
 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/{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
@@ -635,9 +639,11 @@ 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-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-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
@@ -650,15 +656,22 @@ 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
 security-api-saml-logout,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-logout.html
 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-api-suggest,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-suggest-user-profile.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-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
 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

@@ -28,6 +28,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/_doc_ids/table.csv

@@ -0,0 +1,15 @@
+# summary:
+# 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" : "[email protected]",
+    "metadata" : {
+      "intelligence" : 7
+    }
+  }

specification/security/activate_user_profile/Request.ts

@@ -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": "[email protected]"
+    },
+    "labels": {},
+    "data": {},
+    "_doc": {
+      "_primary_term": 88,
+      "_seq_no": 66
+    }
+  }

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

@@ -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/activate_user_profile/examples/response/ResponseExample1.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/authenticate/SecurityAuthenticateRequest.ts

@@ -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/authenticate/examples/response/SecurityAuthenticateResponseExample1.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/request/SecurityBulkDeleteRoleRequestExample1.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/SecurityBulkDeleteRoleResponseExample1.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_delete_role/examples/response/SecurityBulkDeleteRoleResponseExample2.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
+            }
+        }
+    }
+  }