From 83fe25d03f95429a32ee38af240aa8e1fc165185 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 20 Jan 2025 12:50:57 -0800 Subject: [PATCH] Add remaining security API examples (#3546) (cherry picked from commit a1856fea4db7401ba2345b070000caad5a4caabc) --- output/openapi/elasticsearch-openapi.json | 268 ++++++--- .../elasticsearch-serverless-openapi.json | 61 +- output/schema/schema.json | 560 ++++++++++-------- specification/_doc_ids/table.csv | 10 +- specification/security/_types/Privileges.ts | 8 +- .../security/_types/RoleDescriptor.ts | 23 +- .../SecurityClearCachedPrivilegesRequest.ts | 5 + .../SecurityClearCachedRealmsRequest.ts | 17 +- .../ClearCachedRolesRequest.ts | 5 + .../ClearCachedServiceTokensRequest.ts | 12 + .../SecurityCreateApiKeyRequest.ts | 27 +- .../CreateServiceTokenRequest.ts | 19 + .../CreateServiceTokenResponse.ts | 3 + .../CreateServiceTokenRequestExample1.yaml | 10 +- .../SecurityDelegatePkiRequest.ts | 1 + .../SecurityDeletePrivilegesRequest.ts | 13 + ...urityDeletePrivilegesResponseExample1.yaml | 1 + .../delete_role/SecurityDeleteRoleRequest.ts | 3 + .../delete_role/SecurityDeleteRoleResponse.ts | 8 +- .../SecurityDeleteRoleResponseExample1.yaml | 1 + .../SecurityDeleteRoleMappingRequest.ts | 9 + .../SecurityDeleteRoleMappingResponse.ts | 8 +- ...rityDeleteRoleMappingResponseExample1.yaml | 1 + .../DeleteServiceTokenRequest.ts | 9 + .../DeleteServiceTokenResponse.ts | 8 +- .../delete_user/SecurityDeleteUserRequest.ts | 3 + .../delete_user/SecurityDeleteUserResponse.ts | 8 +- .../SecurityDisableUserRequest.ts | 5 + .../enable_user/SecurityEnableUserRequest.ts | 4 + .../security/enroll_kibana/Request.ts | 3 + .../security/enroll_kibana/Response.ts | 11 + specification/security/enroll_node/Request.ts | 3 + .../security/enroll_node/Response.ts | 18 + .../SecurityGetBuiltinPrivilegesResponse.ts | 10 + .../SecurityGetPrivilegesRequest.ts | 14 + .../SecurityGetPrivilegesResponse.ts | 5 +- .../get_role/SecurityGetRoleRequest.ts | 4 +- .../get_role/SecurityGetRoleResponse.ts | 7 +- .../SecurityGetRoleMappingResponse.ts | 5 +- .../GetServiceAccountsRequest.ts | 9 +- .../GetServiceAccountsResponse.ts | 5 +- .../GetServiceCredentialsRequest.ts | 11 +- .../GetServiceCredentialsResponse.ts | 3 +- .../SecurityGetSettingsRequest.ts | 6 + .../get_token/GetUserAccessTokenRequest.ts | 40 ++ specification/security/get_token/types.ts | 20 + .../get_user/SecurityGetUserRequest.ts | 2 +- .../get_user/SecurityGetUserResponse.ts | 6 +- .../SecurityGetUserPrivilegesRequest.ts | 5 + .../SecurityGrantApiKeyRequest.ts | 18 +- specification/security/grant_api_key/types.ts | 1 - .../SecurityHasPrivilegesRequest.ts | 2 + .../SecurityHasPrivilegesResponse.ts | 3 + .../security/has_privileges/types.ts | 9 +- .../SecurityInvalidateApiKeyRequest.ts | 16 +- .../SecurityInvalidateApiKeyResponse.ts | 16 + .../SecurityInvalidateTokenRequest.ts | 23 +- .../SecurityInvalidateTokenResponse.ts | 16 + ...ecurityInvalidateTokenRequestExample6.yaml | 15 - .../security/oidc_authenticate/Request.ts | 1 + specification/security/oidc_logout/Request.ts | 1 + .../oidc_prepare_authentication/Request.ts | 1 + .../SecurityPutPrivilegesRequest.ts | 23 +- .../SecurityPutPrivilegesResponse.ts | 4 +- .../SecurityPutPrivilegesRequestExample1.yaml | 2 + .../put_role/SecurityPutRoleRequest.ts | 5 +- .../put_role/SecurityPutRoleResponse.ts | 7 +- .../SecurityPutRoleMappingRequest.ts | 45 +- .../put_user/SecurityPutUserRequest.ts | 47 +- .../put_user/SecurityPutUserResponse.ts | 8 +- .../SecurityPutUserRequestExample1.yaml | 15 +- .../query_api_keys/QueryApiKeysRequest.ts | 30 +- .../security/query_api_keys/types.ts | 2 +- .../security/query_role/QueryRolesRequest.ts | 23 +- .../security/query_role/QueryRolesResponse.ts | 7 +- .../request/QueryRolesRequestExample1.yaml | 8 + .../request/QueryRolesRequestExample2.yaml | 17 + .../response/QueryRolesResponseExample1.yaml | 85 +++ .../response/QueryRolesResponseExample2.yaml | 43 ++ .../query_user/SecurityQueryUserRequest.ts | 23 +- .../query_user/SecurityQueryUserResponse.ts | 2 +- .../SecurityQueryUserRequestExample1.yaml | 14 + .../SecurityQueryUserRequestExample2.yaml | 43 ++ .../SecurityQueryUserResponseExample1.yaml | 27 + .../SecurityQueryUserResponseExample2.yaml | 43 ++ .../SecurityQueryUserResponseExample3.yaml | 39 ++ .../security/update_api_key/Request.ts | 47 +- .../security/update_api_key/Response.ts | 2 +- .../examples/request/RequestExample1.yaml | 25 + .../examples/request/RequestExample2.yaml | 10 + .../examples/response/ResponseExample1.yaml | 10 + ...dateCrossClusterApiKeyRequestExample1.yaml | 2 +- .../SecurityUpdateSettingsRequest.ts | 7 +- ...SecurityUpdateSettingsRequestExample1.yaml | 16 + 94 files changed, 1619 insertions(+), 481 deletions(-) delete mode 100644 specification/security/invalidate_token/examples/request/SecurityInvalidateTokenRequestExample6.yaml create mode 100644 specification/security/query_role/examples/request/QueryRolesRequestExample1.yaml create mode 100644 specification/security/query_role/examples/request/QueryRolesRequestExample2.yaml create mode 100644 specification/security/query_role/examples/response/QueryRolesResponseExample1.yaml create mode 100644 specification/security/query_role/examples/response/QueryRolesResponseExample2.yaml create mode 100644 specification/security/query_user/examples/request/SecurityQueryUserRequestExample1.yaml create mode 100644 specification/security/query_user/examples/request/SecurityQueryUserRequestExample2.yaml create mode 100644 specification/security/query_user/examples/response/SecurityQueryUserResponseExample1.yaml create mode 100644 specification/security/query_user/examples/response/SecurityQueryUserResponseExample2.yaml create mode 100644 specification/security/query_user/examples/response/SecurityQueryUserResponseExample3.yaml create mode 100644 specification/security/update_api_key/examples/request/RequestExample1.yaml create mode 100644 specification/security/update_api_key/examples/request/RequestExample2.yaml create mode 100644 specification/security/update_api_key/examples/response/ResponseExample1.yaml create mode 100644 specification/security/update_settings/examples/request/SecurityUpdateSettingsRequestExample1.yaml diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 98ee64426d..cd9fc70c2b 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -29318,7 +29318,7 @@ { "in": "path", "name": "application", - "description": "A comma-separated list of application names", + "description": "A comma-separated list of applications.\nTo clear all applications, use an asterism (`*`).\nIt does not support other wildcard patterns.", "required": true, "deprecated": false, "schema": { @@ -29367,13 +29367,16 @@ "security" ], "summary": "Clear the user cache", - "description": "Evict users from the user cache. You can completely clear the cache or evict specific users.", + "description": "Evict users from the user cache.\nYou can completely clear the cache or evict specific users.\n\nUser credentials are cached in memory on each node to avoid connecting to a remote authentication service or hitting the disk for every incoming request.\nThere are realm settings that you can use to configure the user cache.\nFor more information, refer to the documentation about controlling the user cache.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/controlling-user-cache.html" + }, "operationId": "security-clear-cached-realms", "parameters": [ { "in": "path", "name": "realms", - "description": "Comma-separated list of realms to clear", + "description": "A comma-separated list of realms.\nTo clear all realms, use an asterisk (`*`).\nIt does not support other wildcard patterns.", "required": true, "deprecated": false, "schema": { @@ -29384,7 +29387,7 @@ { "in": "query", "name": "usernames", - "description": "Comma-separated list of usernames to clear from the cache", + "description": "A comma-separated list of the users to clear from the cache.\nIf you do not specify this parameter, the API evicts all users from the user cache.", "deprecated": false, "schema": { "type": "array", @@ -29440,7 +29443,7 @@ { "in": "path", "name": "name", - "description": "Role name", + "description": "A comma-separated list of roles to evict from the role cache.\nTo evict all roles, use an asterisk (`*`).\nIt does not support other wildcard patterns.", "required": true, "deprecated": false, "schema": { @@ -29488,7 +29491,7 @@ "security" ], "summary": "Clear service account token caches", - "description": "Evict a subset of all entries from the service account token caches.", + "description": "Evict a subset of all entries from the service account token caches.\nTwo 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.\nThis API clears matching entries from both caches.\n\nThe cache for service account tokens backed by the `.security` index is cleared automatically on state changes of the security index.\nThe cache for tokens backed by the `service_tokens` file is cleared automatically on file changes.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html" }, @@ -29497,7 +29500,7 @@ { "in": "path", "name": "namespace", - "description": "An identifier for the namespace", + "description": "The namespace, which is a top-level grouping of service accounts.", "required": true, "deprecated": false, "schema": { @@ -29508,7 +29511,7 @@ { "in": "path", "name": "service", - "description": "An identifier for the service name", + "description": "The name of the service, which must be unique within its namespace.", "required": true, "deprecated": false, "schema": { @@ -29519,7 +29522,7 @@ { "in": "path", "name": "name", - "description": "A comma-separated list of service token names", + "description": "A comma-separated list of token names to evict from the service account token caches.\nUse a wildcard (`*`) to evict all tokens that belong to a service account.\nIt does not support other wildcard patterns.", "required": true, "deprecated": false, "schema": { @@ -29681,7 +29684,10 @@ "security" ], "summary": "Create an API key", - "description": "Create an API key for access without requiring basic authentication.\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Create an API key for access without requiring basic authentication.\n\nIMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges.\nIf you specify privileges, the API returns an error.\n\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.\n\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\nTo configure or turn off the API key service, refer to API key service setting documentation.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#api-key-service-settings" + }, "operationId": "security-create-api-key", "parameters": [ { @@ -29703,7 +29709,10 @@ "security" ], "summary": "Create an API key", - "description": "Create an API key for access without requiring basic authentication.\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Create an API key for access without requiring basic authentication.\n\nIMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges.\nIf you specify privileges, the API returns an error.\n\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.\n\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\nTo configure or turn off the API key service, refer to API key service setting documentation.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#api-key-service-settings" + }, "operationId": "security-create-api-key-1", "parameters": [ { @@ -29725,7 +29734,7 @@ "security" ], "summary": "Invalidate API keys", - "description": "This API invalidates API keys created by the create API key or grant API key APIs.\nInvalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.\nThe `manage_api_key` privilege allows deleting any API keys.\nThe `manage_own_api_key` only allows deleting API keys that are owned by the user.\nIn addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:\n- Set the parameter `owner=true`.\n- Or, set both `username` and `realm_name` to match the user’s identity.\n- Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.", + "description": "This API invalidates API keys created by the create API key or grant API key APIs.\nInvalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.\n\nTo use this API, you must have at least the `manage_security`, `manage_api_key`, or `manage_own_api_key` cluster privileges.\nThe `manage_security` privilege allows deleting any API key, including both REST and cross cluster API keys.\nThe `manage_api_key` privilege allows deleting any REST API key, but not cross cluster API keys.\nThe `manage_own_api_key` only allows deleting REST API keys that are owned by the user.\nIn addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:\n\n- Set the parameter `owner=true`.\n- Or, set both `username` and `realm_name` to match the user's identity.\n- Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.", "operationId": "security-invalidate-api-key", "requestBody": { "content": { @@ -29747,7 +29756,7 @@ "$ref": "#/components/schemas/_types:Name" }, "owner": { - "description": "Can be used to query API keys owned by the currently authenticated user.\nThe `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones.", + "description": "Query API keys owned by the currently authenticated user.\nThe `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones.\n\nNOTE: At least one of `ids`, `name`, `username`, and `realm_name` must be specified if `owner` is `false`.", "type": "boolean" }, "realm_name": { @@ -29772,21 +29781,25 @@ "type": "object", "properties": { "error_count": { + "description": "The number of errors that were encountered when invalidating the API keys.", "type": "number" }, "error_details": { + "description": "Details about the errors.\nThis field is not present in the response when `error_count` is `0`.", "type": "array", "items": { "$ref": "#/components/schemas/_types:ErrorCause" } }, "invalidated_api_keys": { + "description": "The IDs of the API keys that were invalidated as part of this request.", "type": "array", "items": { "type": "string" } }, "previously_invalidated_api_keys": { + "description": "The IDs of the API keys that were already invalidated.", "type": "array", "items": { "type": "string" @@ -29890,7 +29903,7 @@ "security" ], "summary": "Create a service account token", - "description": "Create a service accounts token for access without requiring basic authentication.", + "description": "Create a service accounts token for access without requiring basic authentication.\n\nNOTE: Service account tokens never expire.\nYou must actively delete them if they are no longer needed.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html" }, @@ -29920,7 +29933,7 @@ "security" ], "summary": "Create a service account token", - "description": "Create a service accounts token for access without requiring basic authentication.", + "description": "Create a service accounts token for access without requiring basic authentication.\n\nNOTE: Service account tokens never expire.\nYou must actively delete them if they are no longer needed.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html" }, @@ -29959,7 +29972,7 @@ { "in": "path", "name": "namespace", - "description": "An identifier for the namespace", + "description": "The namespace, which is a top-level grouping of service accounts.", "required": true, "deprecated": false, "schema": { @@ -29970,7 +29983,7 @@ { "in": "path", "name": "service", - "description": "An identifier for the service name", + "description": "The service name.", "required": true, "deprecated": false, "schema": { @@ -29981,7 +29994,7 @@ { "in": "path", "name": "name", - "description": "An identifier for the token name", + "description": "The name of the service account token.", "required": true, "deprecated": false, "schema": { @@ -30009,6 +30022,7 @@ "type": "object", "properties": { "found": { + "description": "If the service account token is successfully deleted, the request returns `{\"found\": true}`.\nOtherwise, the response will have status code 404 and `found` is set to `false`.", "type": "boolean" } }, @@ -30029,7 +30043,7 @@ "security" ], "summary": "Create a service account token", - "description": "Create a service accounts token for access without requiring basic authentication.", + "description": "Create a service accounts token for access without requiring basic authentication.\n\nNOTE: Service account tokens never expire.\nYou must actively delete them if they are no longer needed.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html" }, @@ -30128,6 +30142,7 @@ "security" ], "summary": "Get application privileges", + "description": "To use this API, you must have one of the following privileges:\n\n* The `read_security` cluster privilege (or a greater privilege such as `manage_security` or `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -30152,6 +30167,7 @@ "security" ], "summary": "Delete application privileges", + "description": "To use this API, you must have one of the following privileges:\n\n* The `manage_security` cluster privilege (or a greater privilege such as `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -30160,7 +30176,7 @@ { "in": "path", "name": "application", - "description": "Application name", + "description": "The name of the application.\nApplication privileges are always associated with exactly one application.", "required": true, "deprecated": false, "schema": { @@ -30171,7 +30187,7 @@ { "in": "path", "name": "name", - "description": "Privilege name", + "description": "The name of the privilege.", "required": true, "deprecated": false, "schema": { @@ -30289,13 +30305,13 @@ "security" ], "summary": "Delete roles", - "description": "Delete roles in the native realm.", + "description": "Delete roles in the native realm.\nThe role management APIs are generally the preferred way to manage roles, rather than using file-based role management.\nThe delete roles API cannot remove roles that are defined in roles files.", "operationId": "security-delete-role", "parameters": [ { "in": "path", "name": "name", - "description": "Role name", + "description": "The name of the role.", "required": true, "deprecated": false, "schema": { @@ -30323,6 +30339,7 @@ "type": "object", "properties": { "found": { + "description": "If the role is successfully deleted, `found` is `true`.\nOtherwise, `found` is `false`.", "type": "boolean" } }, @@ -30364,7 +30381,7 @@ "security" ], "summary": "Create or update role mappings", - "description": "Role mappings define which roles are assigned to each user.\nEach mapping has rules that identify users and a list of roles that are granted to those users.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.\n\nThis API does not create roles. Rather, it maps users to existing roles.\nRoles can be created by using the create or update roles API or roles files.", + "description": "Role mappings define which roles are assigned to each user.\nEach mapping has rules that identify users and a list of roles that are granted to those users.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.\n\nNOTE: This API does not create roles. Rather, it maps users to existing roles.\nRoles can be created by using the create or update roles API or roles files.\n\n**Role templates**\n\nThe most common use for role mappings is to create a mapping from a known value on the user to a fixed role name.\nFor example, all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the superuser role in Elasticsearch.\nThe `roles` field is used for this purpose.\n\nFor more complex needs, it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user.\nThe `role_templates` field is used for this purpose.\n\nNOTE: To use role templates successfully, the relevant scripting feature must be enabled.\nOtherwise, all attempts to create a role mapping with role templates fail.\n\nAll of the user fields that are available in the role mapping rules are also available in the role templates.\nThus it is possible to assign a user to a role that reflects their username, their groups, or the name of the realm to which they authenticated.\n\nBy default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user.\nIf the format of the template is set to \"json\" then the template is expected to produce a JSON string or an array of JSON strings for the role names.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-roles.html" }, @@ -30392,7 +30409,7 @@ "security" ], "summary": "Create or update role mappings", - "description": "Role mappings define which roles are assigned to each user.\nEach mapping has rules that identify users and a list of roles that are granted to those users.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.\n\nThis API does not create roles. Rather, it maps users to existing roles.\nRoles can be created by using the create or update roles API or roles files.", + "description": "Role mappings define which roles are assigned to each user.\nEach mapping has rules that identify users and a list of roles that are granted to those users.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.\n\nNOTE: This API does not create roles. Rather, it maps users to existing roles.\nRoles can be created by using the create or update roles API or roles files.\n\n**Role templates**\n\nThe most common use for role mappings is to create a mapping from a known value on the user to a fixed role name.\nFor example, all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the superuser role in Elasticsearch.\nThe `roles` field is used for this purpose.\n\nFor more complex needs, it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user.\nThe `role_templates` field is used for this purpose.\n\nNOTE: To use role templates successfully, the relevant scripting feature must be enabled.\nOtherwise, all attempts to create a role mapping with role templates fail.\n\nAll of the user fields that are available in the role mapping rules are also available in the role templates.\nThus it is possible to assign a user to a role that reflects their username, their groups, or the name of the realm to which they authenticated.\n\nBy default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user.\nIf the format of the template is set to \"json\" then the template is expected to produce a JSON string or an array of JSON strings for the role names.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-roles.html" }, @@ -30420,12 +30437,16 @@ "security" ], "summary": "Delete role mappings", + "description": "Role mappings define which roles are assigned to each user.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files.\nThe delete role mappings API cannot remove role mappings that are defined in role mapping files.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-roles.html" + }, "operationId": "security-delete-role-mapping", "parameters": [ { "in": "path", "name": "name", - "description": "Role-mapping name", + "description": "The distinct name that identifies the role mapping.\nThe name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way.", "required": true, "deprecated": false, "schema": { @@ -30453,6 +30474,7 @@ "type": "object", "properties": { "found": { + "description": "If the mapping is successfully deleted, `found` is `true`.\nOtherwise, `found` is `false`.", "type": "boolean" } }, @@ -30494,7 +30516,7 @@ "security" ], "summary": "Create or update users", - "description": "A password is required for adding a new user but is optional when updating an existing user.\nTo change a user’s password without updating any other fields, use the change password API.", + "description": "Add and update users in the native realm.\nA password is required for adding a new user but is optional when updating an existing user.\nTo change a user's password without updating any other fields, use the change password API.", "operationId": "security-put-user", "parameters": [ { @@ -30518,7 +30540,7 @@ "security" ], "summary": "Create or update users", - "description": "A password is required for adding a new user but is optional when updating an existing user.\nTo change a user’s password without updating any other fields, use the change password API.", + "description": "Add and update users in the native realm.\nA password is required for adding a new user but is optional when updating an existing user.\nTo change a user's password without updating any other fields, use the change password API.", "operationId": "security-put-user-1", "parameters": [ { @@ -30548,7 +30570,7 @@ { "in": "path", "name": "username", - "description": "username", + "description": "An identifier for the user.", "required": true, "deprecated": false, "schema": { @@ -30576,6 +30598,7 @@ "type": "object", "properties": { "found": { + "description": "If the user is successfully deleted, the request returns `{\"found\": true}`.\nOtherwise, `found` is set to `false`.", "type": "boolean" } }, @@ -30595,7 +30618,7 @@ "security" ], "summary": "Disable users", - "description": "Disable users in the native realm.", + "description": "Disable users in the native realm.\nBy default, when you create users, they are enabled.\nYou can use this API to revoke a user's access to Elasticsearch.", "operationId": "security-disable-user", "parameters": [ { @@ -30616,7 +30639,7 @@ "security" ], "summary": "Disable users", - "description": "Disable users in the native realm.", + "description": "Disable users in the native realm.\nBy default, when you create users, they are enabled.\nYou can use this API to revoke a user's access to Elasticsearch.", "operationId": "security-disable-user-1", "parameters": [ { @@ -30685,7 +30708,7 @@ "security" ], "summary": "Enable users", - "description": "Enable users in the native realm.", + "description": "Enable users in the native realm.\nBy default, when you create users, they are enabled.", "operationId": "security-enable-user", "parameters": [ { @@ -30706,7 +30729,7 @@ "security" ], "summary": "Enable users", - "description": "Enable users in the native realm.", + "description": "Enable users in the native realm.\nBy default, when you create users, they are enabled.", "operationId": "security-enable-user-1", "parameters": [ { @@ -30775,7 +30798,7 @@ "security" ], "summary": "Enroll Kibana", - "description": "Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.", + "description": "Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.\n\nNOTE: This API is currently intended for internal use only by Kibana.\nKibana uses this API internally to configure itself for communications with an Elasticsearch cluster that already has security features enabled.", "operationId": "security-enroll-kibana", "responses": { "200": { @@ -30789,6 +30812,7 @@ "$ref": "#/components/schemas/security.enroll_kibana:Token" }, "http_ca": { + "description": "The CA certificate used to sign the node certificates that Elasticsearch uses for TLS on the HTTP layer.\nThe certificate is returned as a Base64 encoded string of the ASN.1 DER encoding of the certificate.", "type": "string" } }, @@ -30810,7 +30834,7 @@ "security" ], "summary": "Enroll a node", - "description": "Enroll a new node to allow it to join an existing cluster with security features enabled.", + "description": "Enroll a new node to allow it to join an existing cluster with security features enabled.\n\nThe response contains all the necessary information for the joining node to bootstrap discovery and security related settings so that it can successfully join the cluster.\nThe response contains key and certificate material that allows the caller to generate valid signed certificates for the HTTP layer of all nodes in the cluster.", "operationId": "security-enroll-node", "responses": { "200": { @@ -30821,21 +30845,27 @@ "type": "object", "properties": { "http_ca_key": { + "description": "The CA private key that can be used by the new node in order to sign its certificate for the HTTP layer, as a Base64 encoded string of the ASN.1 DER encoding of the key.", "type": "string" }, "http_ca_cert": { + "description": "The CA certificate that can be used by the new node in order to sign its certificate for the HTTP layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate.", "type": "string" }, "transport_ca_cert": { + "description": "The CA certificate that is used to sign the TLS certificate for the transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate.", "type": "string" }, "transport_key": { + "description": "The private key that the node can use for TLS for its transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the key.", "type": "string" }, "transport_cert": { + "description": "The certificate that the node can use for TLS for its transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate.", "type": "string" }, "nodes_addresses": { + "description": "A list of transport addresses in the form of `host:port` for the nodes that are already members of the cluster.", "type": "array", "items": { "type": "string" @@ -30878,6 +30908,7 @@ "type": "object", "properties": { "cluster": { + "description": "The list of cluster privileges that are understood by this version of Elasticsearch.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:ClusterPrivilege" @@ -30887,6 +30918,7 @@ "$ref": "#/components/schemas/_types:Indices" }, "remote_cluster": { + "description": "The list of remote_cluster privileges that are understood by this version of Elasticsearch.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:RemoteClusterPrivilege" @@ -30912,6 +30944,7 @@ "security" ], "summary": "Get application privileges", + "description": "To use this API, you must have one of the following privileges:\n\n* The `read_security` cluster privilege (or a greater privilege such as `manage_security` or `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -30928,6 +30961,7 @@ "security" ], "summary": "Create or update application privileges", + "description": "To use this API, you must have one of the following privileges:\n\n* The `manage_security` cluster privilege (or a greater privilege such as `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.\n\nApplication names are formed from a prefix, with an optional suffix that conform to the following rules:\n\n* The prefix must begin with a lowercase ASCII letter.\n* The prefix must contain only ASCII letters or digits.\n* The prefix must be at least 3 characters long.\n* If the suffix exists, it must begin with either a dash `-` or `_`.\n* The suffix cannot contain any of the following characters: `\\`, `/`, `*`, `?`, `\"`, `<`, `>`, `|`, `,`, `*`.\n* No part of the name can contain whitespace.\n\nPrivilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters `_`, `-`, and `.`.\n\nAction names can contain any number of printable ASCII characters and must contain at least one of the following characters: `/`, `*`, `:`.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -30952,6 +30986,7 @@ "security" ], "summary": "Create or update application privileges", + "description": "To use this API, you must have one of the following privileges:\n\n* The `manage_security` cluster privilege (or a greater privilege such as `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.\n\nApplication names are formed from a prefix, with an optional suffix that conform to the following rules:\n\n* The prefix must begin with a lowercase ASCII letter.\n* The prefix must contain only ASCII letters or digits.\n* The prefix must be at least 3 characters long.\n* If the suffix exists, it must begin with either a dash `-` or `_`.\n* The suffix cannot contain any of the following characters: `\\`, `/`, `*`, `?`, `\"`, `<`, `>`, `|`, `,`, `*`.\n* No part of the name can contain whitespace.\n\nPrivilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters `_`, `-`, and `.`.\n\nAction names can contain any number of printable ASCII characters and must contain at least one of the following characters: `/`, `*`, `:`.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -30978,6 +31013,7 @@ "security" ], "summary": "Get application privileges", + "description": "To use this API, you must have one of the following privileges:\n\n* The `read_security` cluster privilege (or a greater privilege such as `manage_security` or `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -31020,7 +31056,7 @@ "security" ], "summary": "Get service accounts", - "description": "Get a list of service accounts that match the provided path parameters.", + "description": "Get a list of service accounts that match the provided path parameters.\n\nNOTE: Currently, only the `elastic/fleet-server` service account is available.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html" }, @@ -31047,7 +31083,7 @@ "security" ], "summary": "Get service accounts", - "description": "Get a list of service accounts that match the provided path parameters.", + "description": "Get a list of service accounts that match the provided path parameters.\n\nNOTE: Currently, only the `elastic/fleet-server` service account is available.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html" }, @@ -31071,7 +31107,7 @@ "security" ], "summary": "Get service accounts", - "description": "Get a list of service accounts that match the provided path parameters.", + "description": "Get a list of service accounts that match the provided path parameters.\n\nNOTE: Currently, only the `elastic/fleet-server` service account is available.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html" }, @@ -31090,6 +31126,7 @@ "security" ], "summary": "Get service account credentials", + "description": "To use this API, you must have at least the `read_security` cluster privilege (or a greater privilege such as `manage_service_account` or `manage_security`).\n\nThe response includes service account tokens that were created with the create service account tokens API as well as file-backed tokens from all nodes of the cluster.\n\nNOTE: For tokens backed by the `service_tokens` file, the API collects them from all nodes of the cluster.\nTokens with the same name from different nodes are assumed to be the same token and are only counted once towards the total number of service tokens.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/service-accounts.html" }, @@ -31098,7 +31135,7 @@ { "in": "path", "name": "namespace", - "description": "Name of the namespace.", + "description": "The name of the namespace.", "required": true, "deprecated": false, "schema": { @@ -31109,7 +31146,7 @@ { "in": "path", "name": "service", - "description": "Name of the service name.", + "description": "The service name.", "required": true, "deprecated": false, "schema": { @@ -31162,7 +31199,7 @@ "security" ], "summary": "Get security index settings", - "description": "Get the user-configurable settings for the security internal index (`.security` and associated indices).", + "description": "Get the user-configurable settings for the security internal index (`.security` and associated indices).\nOnly a subset of the index settings — those that are user-configurable—will be shown.\nThis includes:\n\n* `index.auto_expand_replicas`\n* `index.number_of_replicas`", "operationId": "security-get-settings", "parameters": [ { @@ -31210,7 +31247,7 @@ "security" ], "summary": "Update security index settings", - "description": "Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use.", + "description": "Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified. This includes `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nNOTE: If `index.auto_expand_replicas` is set, `index.number_of_replicas` will be ignored during updates.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected.\nThis API does not yet support configuring the settings for indices before they are in use.", "operationId": "security-update-settings", "parameters": [ { @@ -31283,7 +31320,10 @@ "security" ], "summary": "Get a token", - "description": "Create a bearer token for access without requiring basic authentication.", + "description": "Create a bearer token for access without requiring basic authentication.\nThe tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface.\nAlternatively, you can explicitly enable the `xpack.security.authc.token.enabled` setting.\nWhen you are running in production mode, a bootstrap check prevents you from enabling the token service unless you also enable TLS on the HTTP interface.\n\nThe get token API takes the same parameters as a typical OAuth 2.0 token API except for the use of a JSON request body.\n\nA successful get token API call returns a JSON structure that contains the access token, the amount of time (seconds) that the token expires in, the type, and the scope if available.\n\nThe tokens returned by the get token API have a finite period of time for which they are valid and after that time period, they can no longer be used.\nThat time period is defined by the `xpack.security.authc.token.timeout` setting.\nIf you want to invalidate a token immediately, you can do so by using the invalidate token API.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup-https.html#encrypt-http-communication" + }, "operationId": "security-get-token", "requestBody": { "content": { @@ -31295,15 +31335,18 @@ "$ref": "#/components/schemas/security.get_token:AccessTokenGrantType" }, "scope": { + "description": "The scope of the token.\nCurrently tokens are only issued for a scope of FULL regardless of the value sent with the request.", "type": "string" }, "password": { "$ref": "#/components/schemas/_types:Password" }, "kerberos_ticket": { + "description": "The base64 encoded kerberos ticket.\nIf you specify the `_kerberos` grant type, this parameter is required.\nThis parameter is not valid with any other supported grant type.", "type": "string" }, "refresh_token": { + "description": "The string that was returned when you created the token, which enables you to extend its life.\nIf you specify the `refresh_token` grant type, this parameter is required.\nThis parameter is not valid with any other supported grant type.", "type": "string" }, "username": { @@ -31363,7 +31406,7 @@ "security" ], "summary": "Invalidate a token", - "description": "The access tokens returned by the get token API have a finite period of time for which they are valid.\nAfter that time period, they can no longer be used.\nThe time period is defined by the `xpack.security.authc.token.timeout` setting.\n\nThe refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once.\nIf you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.", + "description": "The access tokens returned by the get token API have a finite period of time for which they are valid.\nAfter that time period, they can no longer be used.\nThe time period is defined by the `xpack.security.authc.token.timeout` setting.\n\nThe refresh tokens returned by the get token API are only valid for 24 hours.\nThey can also be used exactly once.\nIf you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.\n\nNOTE: While all parameters are optional, at least one of them is required.\nMore specifically, either one of `token` or `refresh_token` parameters is required.\nIf none of these two are specified, then `realm_name` and/or `username` need to be specified.", "operationId": "security-invalidate-token", "requestBody": { "content": { @@ -31372,9 +31415,11 @@ "type": "object", "properties": { "token": { + "description": "An access token.\nThis parameter cannot be used if any of `refresh_token`, `realm_name`, or `username` are used.", "type": "string" }, "refresh_token": { + "description": "A refresh token.\nThis parameter cannot be used if any of `refresh_token`, `realm_name`, or `username` are used.", "type": "string" }, "realm_name": { @@ -31398,18 +31443,22 @@ "type": "object", "properties": { "error_count": { + "description": "The number of errors that were encountered when invalidating the tokens.", "type": "number" }, "error_details": { + "description": "Details about the errors.\nThis field is not present in the response when `error_count` is `0`.", "type": "array", "items": { "$ref": "#/components/schemas/_types:ErrorCause" } }, "invalidated_tokens": { + "description": "The number of the tokens that were invalidated as part of this request.", "type": "number" }, "previously_invalidated_tokens": { + "description": "The number of tokens that were already invalidated.", "type": "number" } }, @@ -31452,6 +31501,7 @@ "security" ], "summary": "Get user privileges", + "description": "Get the security privileges for the logged in user.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.\nTo check whether a user has a specific list of privileges, use the has privileges API.", "operationId": "security-get-user-privileges", "parameters": [ { @@ -31633,7 +31683,7 @@ "security" ], "summary": "Grant an API key", - "description": "Create an API key on behalf of another user.\nThis API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API.\nThe caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created.\nIt is not possible to use this API to create an API key without that user’s credentials.\nThe user, for whom the authentication credentials is provided, can optionally \"run as\" (impersonate) another user.\nIn this case, the API key will be created on behalf of the impersonated user.\n\nThis API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf.\n\nA successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nBy default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Create an API key on behalf of another user.\nThis API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API.\nThe caller must have authentication credentials for the user on whose behalf the API key will be created.\nIt is not possible to use this API to create an API key without that user's credentials.\nThe supported user authentication credential types are:\n\n* username and password\n* Elasticsearch access tokens\n* JWTs\n\nThe user, for whom the authentication credentials is provided, can optionally \"run as\" (impersonate) another user.\nIn this case, the API key will be created on behalf of the impersonated user.\n\nThis API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf.\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\n\nA successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nBy default, API keys never expire. You can specify expiration information when you create the API keys.", "operationId": "security-grant-api-key", "requestBody": { "content": { @@ -31648,7 +31698,7 @@ "$ref": "#/components/schemas/security.grant_api_key:ApiKeyGrantType" }, "access_token": { - "description": "The user’s access token.\nIf you specify the `access_token` grant type, this parameter is required.\nIt is not valid with other grant types.", + "description": "The user's access token.\nIf you specify the `access_token` grant type, this parameter is required.\nIt is not valid with other grant types.", "type": "string" }, "username": { @@ -31714,7 +31764,7 @@ "security" ], "summary": "Check user privileges", - "description": "Determine whether the specified user has a specified list of privileges.", + "description": "Determine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -31734,7 +31784,7 @@ "security" ], "summary": "Check user privileges", - "description": "Determine whether the specified user has a specified list of privileges.", + "description": "Determine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -31756,7 +31806,7 @@ "security" ], "summary": "Check user privileges", - "description": "Determine whether the specified user has a specified list of privileges.", + "description": "Determine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -31781,7 +31831,7 @@ "security" ], "summary": "Check user privileges", - "description": "Determine whether the specified user has a specified list of privileges.", + "description": "Determine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -32058,7 +32108,7 @@ "security" ], "summary": "Find API keys with a query", - "description": "Get a paginated list of API keys and their information. You can optionally filter the results with a query.", + "description": "Get a paginated list of API keys and their information.\nYou can optionally filter the results with a query.\n\nTo use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges.\nIf you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own.\nIf you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership.", "operationId": "security-query-api-keys", "parameters": [ { @@ -32086,7 +32136,7 @@ "security" ], "summary": "Find API keys with a query", - "description": "Get a paginated list of API keys and their information. You can optionally filter the results with a query.", + "description": "Get a paginated list of API keys and their information.\nYou can optionally filter the results with a query.\n\nTo use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges.\nIf you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own.\nIf you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership.", "operationId": "security-query-api-keys-1", "parameters": [ { @@ -32116,7 +32166,7 @@ "security" ], "summary": "Find roles with a query", - "description": "Get roles in a paginated manner. You can optionally filter the results with a query.", + "description": "Get roles in a paginated manner.\nThe role management APIs are generally the preferred way to manage roles, rather than using file-based role management.\nThe query roles API does not retrieve roles that are defined in roles files, nor built-in ones.\nYou can optionally filter the results with a query.\nAlso, the results can be paginated and sorted.", "operationId": "security-query-role", "requestBody": { "$ref": "#/components/requestBodies/security.query_role" @@ -32133,7 +32183,7 @@ "security" ], "summary": "Find roles with a query", - "description": "Get roles in a paginated manner. You can optionally filter the results with a query.", + "description": "Get roles in a paginated manner.\nThe role management APIs are generally the preferred way to manage roles, rather than using file-based role management.\nThe query roles API does not retrieve roles that are defined in roles files, nor built-in ones.\nYou can optionally filter the results with a query.\nAlso, the results can be paginated and sorted.", "operationId": "security-query-role-1", "requestBody": { "$ref": "#/components/requestBodies/security.query_role" @@ -32152,7 +32202,7 @@ "security" ], "summary": "Find users with a query", - "description": "Get information for users in a paginated manner.\nYou can optionally filter the results with a query.", + "description": "Get information for users in a paginated manner.\nYou can optionally filter the results with a query.\n\nNOTE: As opposed to the get user API, built-in users are excluded from the result.\nThis API is only for native users.", "operationId": "security-query-user", "parameters": [ { @@ -32174,7 +32224,7 @@ "security" ], "summary": "Find users with a query", - "description": "Get information for users in a paginated manner.\nYou can optionally filter the results with a query.", + "description": "Get information for users in a paginated manner.\nYou can optionally filter the results with a query.\n\nNOTE: As opposed to the get user API, built-in users are excluded from the result.\nThis API is only for native users.", "operationId": "security-query-user-1", "parameters": [ { @@ -32622,7 +32672,7 @@ "security" ], "summary": "Update an API key", - "description": "Updates attributes of an existing API key.\nUsers can only update API keys that they created or that were granted to them.\nUse this API to update API keys created by the create API Key or grant API Key APIs.\nIf you need to apply the same update to many API keys, you can use bulk update API Keys to reduce overhead.\nIt’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key.\nThis API supports updates to an API key’s access scope and metadata.\nThe access scope of an API key is derived from the `role_descriptors` you specify in the request, and a snapshot of the owner user’s permissions at the time of the request.\nThe snapshot of the owner’s permissions is updated automatically on every call.\nIf you don’t specify `role_descriptors` in the request, a call to this API might still change the API key’s access scope.\nThis change can occur if the owner user’s permissions have changed since the API key was created or last modified.\nTo update another user’s API key, use the `run_as` feature to submit a request on behalf of another user.\nIMPORTANT: It’s not possible to use an API key as the authentication credential for this API.\nTo update an API key, the owner user’s credentials are required.", + "description": "Update attributes of an existing API key.\nThis API supports updates to an API key's access scope, expiration, and metadata.\n\nTo use this API, you must have at least the `manage_own_api_key` cluster privilege.\nUsers can only update API keys that they created or that were granted to them.\nTo update another user’s API key, use the `run_as` feature to submit a request on behalf of another user.\n\nIMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required.\n\nUse this API to update API keys created by the create API key or grant API Key APIs.\nIf you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead.\nIt's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API.\n\nThe access scope of an API key is derived from the `role_descriptors` you specify in the request and a snapshot of the owner user's permissions at the time of the request.\nThe snapshot of the owner's permissions is updated automatically on every call.\n\nIMPORTANT: If you don't specify `role_descriptors` in the request, a call to this API might still change the API key's access scope.\nThis change can occur if the owner user's permissions have changed since the API key was created or last modified.", "operationId": "security-update-api-key", "parameters": [ { @@ -32644,7 +32694,7 @@ "type": "object", "properties": { "role_descriptors": { - "description": "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.", + "description": "The role descriptors to assign to this API key.\nThe API key's effective permissions are an intersection of its assigned privileges and the point in time snapshot of permissions of the owner user.\nYou can assign new privileges by specifying them in this parameter.\nTo remove assigned privileges, you can supply an empty `role_descriptors` parameter, that is to say, an empty object `{}`.\nIf an API key has no assigned privileges, it inherits the owner user's full permissions.\nThe snapshot of the owner's permissions is always updated, whether you supply the `role_descriptors` parameter or not.\nThe structure of a role descriptor is the same as the request for the create API keys API.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/security._types:RoleDescriptor" @@ -32670,7 +32720,7 @@ "type": "object", "properties": { "updated": { - "description": "If `true`, the API key was updated.\nIf `false`, the API key didn’t change because no change was detected.", + "description": "If `true`, the API key was updated.\nIf `false`, the API key didn't change because no change was detected.", "type": "boolean" } }, @@ -85616,7 +85666,7 @@ } }, "remote_cluster": { - "description": "A list of cluster permissions for remote clusters. Note - this is limited a subset of the cluster permissions.", + "description": "A list of cluster permissions for remote clusters.\nNOTE: This is limited a subset of the cluster permissions.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:RemoteClusterPrivileges" @@ -85647,7 +85697,10 @@ "$ref": "#/components/schemas/_types:Metadata" }, "run_as": { - "description": "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.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/run-as-privilege.html" + }, + "description": "A list of users that the API keys can impersonate.\nNOTE: In Elastic Cloud Serverless, the run-as feature is disabled.\nFor API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected.", "type": "array", "items": { "type": "string" @@ -86021,6 +86074,7 @@ "type": "object", "properties": { "workflows": { + "description": "A list of workflows to which the API key is restricted.\nNOTE: In order to use a role restriction, an API key must be created with a single role descriptor.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:RestrictionWorkflow" @@ -86260,9 +86314,11 @@ "type": "object", "properties": { "name": { + "description": "The name of the bearer token for the `elastic/kibana` service account.", "type": "string" }, "value": { + "description": "The value of the bearer token for the `elastic/kibana` service account.\nUse this value to authenticate the service account with Elasticsearch.", "type": "string" } }, @@ -86586,7 +86642,7 @@ } }, "remote_cluster": { - "description": "A list of cluster permissions for remote clusters. Note - this is limited a subset of the cluster permissions.", + "description": "A list of cluster permissions for remote clusters.\nNOTE: This is limited a subset of the cluster permissions.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:RemoteClusterPrivileges" @@ -86617,6 +86673,9 @@ "$ref": "#/components/schemas/_types:Metadata" }, "run_as": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/run-as-privilege.html" + }, "description": "A list of users that the API keys can impersonate.", "type": "array", "items": { @@ -86624,7 +86683,7 @@ } }, "description": { - "description": "Optional description of the role descriptor", + "description": "An optional description of the role descriptor.", "type": "string" }, "restriction": { @@ -86806,6 +86865,9 @@ "type": "object", "properties": { "field_security": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/field-and-document-access-control.html" + }, "description": "The document fields that the owners of the role have read access to.", "type": "array", "items": { @@ -86879,7 +86941,7 @@ "$ref": "#/components/schemas/_types:DurationLarge" }, "role_descriptors": { - "description": "The role descriptors for this API key.\nThis parameter is optional.\nWhen it is not specified or is an empty array, the API key has a point in time snapshot of permissions of the specified user or access token.\nIf you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the permissions of the user or access token.", + "description": "The role descriptors for this API key.\nWhen it is not specified or is an empty array, the API key has a point in time snapshot of permissions of the specified user or access token.\nIf you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the permissions of the user or access token.", "oneOf": [ { "type": "object", @@ -86921,14 +86983,14 @@ "type": "string" }, "privileges": { - "description": "A list of the privileges that you want to check for the specified resources. May be either application privilege names, or the names of actions that are granted by those privileges", + "description": "A list of the privileges that you want to check for the specified resources.\nIt may be either application privilege names or the names of actions that are granted by those privileges", "type": "array", "items": { "type": "string" } }, "resources": { - "description": "A list of resource names against which the privileges should be checked", + "description": "A list of resource names against which the privileges should be checked.", "type": "array", "items": { "type": "string" @@ -86955,7 +87017,7 @@ } }, "allow_restricted_indices": { - "description": "This needs to be set to true (default is false) if using wildcards or regexps for patterns that cover restricted indices.\nImplicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false.\nIf restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of allow_restricted_indices.", + "description": "This needs to be set to `true` (default is `false`) if using wildcards or regexps for patterns that cover restricted indices.\nImplicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false.\nIf restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of `allow_restricted_indices`.", "type": "boolean" } }, @@ -96064,6 +96126,7 @@ "type": "object", "properties": { "created": { + "description": "A successful call returns a JSON structure that shows whether the user has been created or updated.\nWhen an existing user is updated, `created` is set to `false`.", "type": "boolean" } }, @@ -96129,7 +96192,7 @@ "type": "number" }, "roles": { - "description": "The list of roles.", + "description": "A list of roles that match the query.\nThe returned role format is an extension of the role definition format.\nIt adds the `transient_metadata.enabled` and the `_sort` fields.\n`transient_metadata.enabled` is set to `false` in case the role is automatically disabled, for example when the role grants privileges that are not allowed by the installed license.\n`_sort` is present when the search query sorts on some field.\nIt contains the array of values that have been used for sorting.", "type": "array", "items": { "$ref": "#/components/schemas/security.query_role:QueryRole" @@ -96161,7 +96224,7 @@ "type": "number" }, "users": { - "description": "A list of user information.", + "description": "A list of users that match the query.", "type": "array", "items": { "$ref": "#/components/schemas/security.query_user:QueryUser" @@ -105205,7 +105268,7 @@ "security.create_service_token#namespace": { "in": "path", "name": "namespace", - "description": "An identifier for the namespace", + "description": "The name of the namespace, which is a top-level grouping of service accounts.", "required": true, "deprecated": false, "schema": { @@ -105216,7 +105279,7 @@ "security.create_service_token#service": { "in": "path", "name": "service", - "description": "An identifier for the service name", + "description": "The name of the service.", "required": true, "deprecated": false, "schema": { @@ -105227,7 +105290,7 @@ "security.create_service_token#name": { "in": "path", "name": "name", - "description": "An identifier for the token name", + "description": "The name for the service account token.\nIf omitted, a random name will be generated.\n\nToken names must be at least one and no more than 256 characters.\nThey can contain alphanumeric characters (a-z, A-Z, 0-9), dashes (`-`), and underscores (`_`), but cannot begin with an underscore.\n\nNOTE: Token names must be unique in the context of the associated service account.\nThey must also be globally unique with their fully qualified names, which are comprised of the service account principal and token name, such as `//`.", "required": true, "deprecated": false, "schema": { @@ -105248,7 +105311,7 @@ "security.disable_user#username": { "in": "path", "name": "username", - "description": "The username of the user to disable", + "description": "An identifier for the user.", "required": true, "deprecated": false, "schema": { @@ -105290,7 +105353,7 @@ "security.enable_user#username": { "in": "path", "name": "username", - "description": "The username of the user to enable", + "description": "An identifier for the user.", "required": true, "deprecated": false, "schema": { @@ -105332,7 +105395,7 @@ "security.get_privileges#application": { "in": "path", "name": "application", - "description": "Application name", + "description": "The name of the application.\nApplication privileges are always associated with exactly one application.\nIf you do not specify this parameter, the API returns information about all privileges for all applications.", "required": true, "deprecated": false, "schema": { @@ -105343,7 +105406,7 @@ "security.get_privileges#name": { "in": "path", "name": "name", - "description": "Privilege name", + "description": "The name of the privilege.\nIf you do not specify this parameter, the API returns information about all privileges for the requested application.", "required": true, "deprecated": false, "schema": { @@ -105354,7 +105417,7 @@ "security.get_role#name": { "in": "path", "name": "name", - "description": "The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles.", + "description": "The name of the role.\nYou can specify multiple roles as a comma-separated list.\nIf you do not specify this parameter, the API returns information about all roles.", "required": true, "deprecated": false, "schema": { @@ -105376,7 +105439,7 @@ "security.get_service_accounts#namespace": { "in": "path", "name": "namespace", - "description": "Name of the namespace. Omit this parameter to retrieve information about all service accounts. If you omit this parameter, you must also omit the `service` parameter.", + "description": "The name of the namespace.\nOmit this parameter to retrieve information about all service accounts.\nIf you omit this parameter, you must also omit the `service` parameter.", "required": true, "deprecated": false, "schema": { @@ -105387,7 +105450,7 @@ "security.get_service_accounts#service": { "in": "path", "name": "service", - "description": "Name of the service name. Omit this parameter to retrieve information about all service accounts that belong to the specified `namespace`.", + "description": "The service name.\nOmit this parameter to retrieve information about all service accounts that belong to the specified `namespace`.", "required": true, "deprecated": false, "schema": { @@ -105419,7 +105482,7 @@ "security.get_user#with_profile_uid": { "in": "query", "name": "with_profile_uid", - "description": "If true will return the User Profile ID for a user, if any.", + "description": "Determines whether to retrieve the user profile UID, if it exists, for the users.", "deprecated": false, "schema": { "type": "boolean" @@ -105471,7 +105534,7 @@ "security.put_role_mapping#name": { "in": "path", "name": "name", - "description": "Role-mapping name", + "description": "The distinct name that identifies the role mapping.\nThe name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way.", "required": true, "deprecated": false, "schema": { @@ -105492,7 +105555,7 @@ "security.put_user#username": { "in": "path", "name": "username", - "description": "The username of the User", + "description": "An identifier for the user.\n\nNOTE: Usernames must be at least 1 and no more than 507 characters.\nThey can contain alphanumeric characters (a-z, A-Z, 0-9), spaces, punctuation, and printable symbols in the Basic Latin (ASCII) block.\nLeading or trailing whitespace is not allowed.", "required": true, "deprecated": false, "schema": { @@ -105503,7 +105566,7 @@ "security.put_user#refresh": { "in": "query", "name": "refresh", - "description": "If `true` (the default) then refresh 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` then do nothing with refreshes.", + "description": "Valid values are `true`, `false`, and `wait_for`.\nThese values have the same meaning as in the index API, but the default value for this API is true.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Refresh" @@ -105513,7 +105576,7 @@ "security.query_api_keys#with_limited_by": { "in": "query", "name": "with_limited_by", - "description": "Return the snapshot of the owner user's role descriptors associated with the API key.\nAn API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors.", + "description": "Return the snapshot of the owner user's role descriptors associated with the API key.\nAn API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors (effectively limited by it).\nAn API key cannot retrieve any API key’s limited-by role descriptors (including itself) unless it has `manage_api_key` or higher privileges.", "deprecated": false, "schema": { "type": "boolean" @@ -105523,7 +105586,7 @@ "security.query_api_keys#with_profile_uid": { "in": "query", "name": "with_profile_uid", - "description": "Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists.", + "description": "Determines whether to also retrieve the profile UID for the API key owner principal.\nIf it exists, the profile UID is returned under the `profile_uid` response field for each API key.", "deprecated": false, "schema": { "type": "boolean" @@ -105543,7 +105606,7 @@ "security.query_user#with_profile_uid": { "in": "query", "name": "with_profile_uid", - "description": "If true will return the User Profile ID for the users in the query result, if any.", + "description": "Determines whether to retrieve the user profile UID, if it exists, for the users.", "deprecated": false, "schema": { "type": "boolean" @@ -108538,7 +108601,10 @@ "$ref": "#/components/schemas/_types:Name" }, "role_descriptors": { - "description": "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.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html" + }, + "description": "An array of role descriptors for this API key.\nWhen 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.\nIf 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.\nThe structure of role descriptor is the same as the request for the create role API.\nFor more details, refer to the create or update roles API.\n\nNOTE: 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.\nIn this case, you must explicitly specify a role descriptor with no privileges.\nThe derived API key can be used for authentication; it will not have authority to call Elasticsearch APIs.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/security._types:RoleDescriptor" @@ -108661,7 +108727,7 @@ } }, "remote_indices": { - "description": "A list of remote indices permissions entries.", + "description": "A list of remote indices permissions entries.\n\nNOTE: Remote indices are effective for remote clusters configured with the API key based model.\nThey have no effect for remote clusters configured with the certificate based model.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:RemoteIndicesPrivileges" @@ -108678,6 +108744,9 @@ "$ref": "#/components/schemas/_types:Metadata" }, "run_as": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/run-as-privilege.html" + }, "description": "A list of users that the owners of this role 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.", "type": "array", "items": { @@ -108708,18 +108777,21 @@ "type": "object", "properties": { "enabled": { + "description": "Mappings that have `enabled` set to `false` are ignored when role mapping is performed.", "type": "boolean" }, "metadata": { "$ref": "#/components/schemas/_types:Metadata" }, "roles": { + "description": "A list of role names that are granted to the users that match the role mapping rules.\nExactly one of `roles` or `role_templates` must be specified.", "type": "array", "items": { "type": "string" } }, "role_templates": { + "description": "A list of Mustache templates that will be evaluated to determine the roles names that should granted to the users that match the role mapping rules.\nExactly one of `roles` or `role_templates` must be specified.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:RoleTemplate" @@ -108750,6 +108822,7 @@ "$ref": "#/components/schemas/_types:Username" }, "email": { + "description": "The email of the user.", "oneOf": [ { "type": "string" @@ -108761,6 +108834,7 @@ ] }, "full_name": { + "description": "The full name of the user.", "oneOf": [ { "type": "string" @@ -108778,15 +108852,21 @@ "$ref": "#/components/schemas/_types:Password" }, "password_hash": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#hashing-settings" + }, + "description": "A hash of the user's password.\nThis must be produced using the same hashing algorithm as has been configured for password storage.\nFor more details, see the explanation of the `xpack.security.authc.password_hashing.algorithm` setting in the user cache and password hash algorithm documentation.\nUsing this parameter allows the client to pre-hash the password for performance and/or confidentiality reasons.\nThe `password` parameter and the `password_hash` parameter cannot be used in the same request.", "type": "string" }, "roles": { + "description": "A set of roles the user has.\nThe roles determine the user's access permissions.\nTo create a user without any roles, specify an empty list (`[]`).", "type": "array", "items": { "type": "string" } }, "enabled": { + "description": "Specifies whether the user is enabled.", "type": "boolean" } } @@ -108812,14 +108892,14 @@ "$ref": "#/components/schemas/security.query_api_keys:ApiKeyQueryContainer" }, "from": { - "description": "Starting document offset.\nBy default, you cannot page through more than 10,000 hits using the from and size parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "sort": { "$ref": "#/components/schemas/_types:Sort" }, "size": { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nIt must not be negative.\nThe `size` parameter can be set to `0`, in which case no API key matches are returned, only the aggregation results.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "search_after": { @@ -108840,14 +108920,14 @@ "$ref": "#/components/schemas/security.query_role:RoleQueryContainer" }, "from": { - "description": "Starting document offset.\nBy default, you cannot page through more than 10,000 hits using the from and size parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "sort": { "$ref": "#/components/schemas/_types:Sort" }, "size": { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "search_after": { @@ -108868,14 +108948,14 @@ "$ref": "#/components/schemas/security.query_user:UserQueryContainer" }, "from": { - "description": "Starting document offset.\nBy default, you cannot page through more than 10,000 hits using the from and size parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "sort": { "$ref": "#/components/schemas/_types:Sort" }, "size": { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "search_after": { diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 2c2e6f02b0..e70432189c 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -17380,7 +17380,10 @@ "security" ], "summary": "Create an API key", - "description": "Create an API key for access without requiring basic authentication.\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Create an API key for access without requiring basic authentication.\n\nIMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges.\nIf you specify privileges, the API returns an error.\n\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.\n\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\nTo configure or turn off the API key service, refer to API key service setting documentation.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#api-key-service-settings" + }, "operationId": "security-create-api-key", "parameters": [ { @@ -17402,7 +17405,10 @@ "security" ], "summary": "Create an API key", - "description": "Create an API key for access without requiring basic authentication.\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Create an API key for access without requiring basic authentication.\n\nIMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges.\nIf you specify privileges, the API returns an error.\n\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.\n\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\nTo configure or turn off the API key service, refer to API key service setting documentation.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#api-key-service-settings" + }, "operationId": "security-create-api-key-1", "parameters": [ { @@ -17424,7 +17430,7 @@ "security" ], "summary": "Invalidate API keys", - "description": "This API invalidates API keys created by the create API key or grant API key APIs.\nInvalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.\nThe `manage_api_key` privilege allows deleting any API keys.\nThe `manage_own_api_key` only allows deleting API keys that are owned by the user.\nIn addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:\n- Set the parameter `owner=true`.\n- Or, set both `username` and `realm_name` to match the user’s identity.\n- Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.", + "description": "This API invalidates API keys created by the create API key or grant API key APIs.\nInvalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.\n\nTo use this API, you must have at least the `manage_security`, `manage_api_key`, or `manage_own_api_key` cluster privileges.\nThe `manage_security` privilege allows deleting any API key, including both REST and cross cluster API keys.\nThe `manage_api_key` privilege allows deleting any REST API key, but not cross cluster API keys.\nThe `manage_own_api_key` only allows deleting REST API keys that are owned by the user.\nIn addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:\n\n- Set the parameter `owner=true`.\n- Or, set both `username` and `realm_name` to match the user's identity.\n- Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.", "operationId": "security-invalidate-api-key", "requestBody": { "content": { @@ -17446,7 +17452,7 @@ "$ref": "#/components/schemas/_types:Name" }, "owner": { - "description": "Can be used to query API keys owned by the currently authenticated user.\nThe `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones.", + "description": "Query API keys owned by the currently authenticated user.\nThe `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones.\n\nNOTE: At least one of `ids`, `name`, `username`, and `realm_name` must be specified if `owner` is `false`.", "type": "boolean" }, "realm_name": { @@ -17471,21 +17477,25 @@ "type": "object", "properties": { "error_count": { + "description": "The number of errors that were encountered when invalidating the API keys.", "type": "number" }, "error_details": { + "description": "Details about the errors.\nThis field is not present in the response when `error_count` is `0`.", "type": "array", "items": { "$ref": "#/components/schemas/_types:ErrorCause" } }, "invalidated_api_keys": { + "description": "The IDs of the API keys that were invalidated as part of this request.", "type": "array", "items": { "type": "string" } }, "previously_invalidated_api_keys": { + "description": "The IDs of the API keys that were already invalidated.", "type": "array", "items": { "type": "string" @@ -17511,7 +17521,7 @@ "security" ], "summary": "Check user privileges", - "description": "Determine whether the specified user has a specified list of privileges.", + "description": "Determine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -17531,7 +17541,7 @@ "security" ], "summary": "Check user privileges", - "description": "Determine whether the specified user has a specified list of privileges.", + "description": "Determine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -17553,7 +17563,7 @@ "security" ], "summary": "Check user privileges", - "description": "Determine whether the specified user has a specified list of privileges.", + "description": "Determine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -17578,7 +17588,7 @@ "security" ], "summary": "Check user privileges", - "description": "Determine whether the specified user has a specified list of privileges.", + "description": "Determine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html" }, @@ -17605,7 +17615,7 @@ "security" ], "summary": "Find API keys with a query", - "description": "Get a paginated list of API keys and their information. You can optionally filter the results with a query.", + "description": "Get a paginated list of API keys and their information.\nYou can optionally filter the results with a query.\n\nTo use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges.\nIf you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own.\nIf you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership.", "operationId": "security-query-api-keys", "parameters": [ { @@ -17633,7 +17643,7 @@ "security" ], "summary": "Find API keys with a query", - "description": "Get a paginated list of API keys and their information. You can optionally filter the results with a query.", + "description": "Get a paginated list of API keys and their information.\nYou can optionally filter the results with a query.\n\nTo use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges.\nIf you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own.\nIf you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership.", "operationId": "security-query-api-keys-1", "parameters": [ { @@ -17663,7 +17673,7 @@ "security" ], "summary": "Update an API key", - "description": "Updates attributes of an existing API key.\nUsers can only update API keys that they created or that were granted to them.\nUse this API to update API keys created by the create API Key or grant API Key APIs.\nIf you need to apply the same update to many API keys, you can use bulk update API Keys to reduce overhead.\nIt’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key.\nThis API supports updates to an API key’s access scope and metadata.\nThe access scope of an API key is derived from the `role_descriptors` you specify in the request, and a snapshot of the owner user’s permissions at the time of the request.\nThe snapshot of the owner’s permissions is updated automatically on every call.\nIf you don’t specify `role_descriptors` in the request, a call to this API might still change the API key’s access scope.\nThis change can occur if the owner user’s permissions have changed since the API key was created or last modified.\nTo update another user’s API key, use the `run_as` feature to submit a request on behalf of another user.\nIMPORTANT: It’s not possible to use an API key as the authentication credential for this API.\nTo update an API key, the owner user’s credentials are required.", + "description": "Update attributes of an existing API key.\nThis API supports updates to an API key's access scope, expiration, and metadata.\n\nTo use this API, you must have at least the `manage_own_api_key` cluster privilege.\nUsers can only update API keys that they created or that were granted to them.\nTo update another user’s API key, use the `run_as` feature to submit a request on behalf of another user.\n\nIMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required.\n\nUse this API to update API keys created by the create API key or grant API Key APIs.\nIf you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead.\nIt's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API.\n\nThe access scope of an API key is derived from the `role_descriptors` you specify in the request and a snapshot of the owner user's permissions at the time of the request.\nThe snapshot of the owner's permissions is updated automatically on every call.\n\nIMPORTANT: If you don't specify `role_descriptors` in the request, a call to this API might still change the API key's access scope.\nThis change can occur if the owner user's permissions have changed since the API key was created or last modified.", "operationId": "security-update-api-key", "parameters": [ { @@ -17685,7 +17695,7 @@ "type": "object", "properties": { "role_descriptors": { - "description": "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.", + "description": "The role descriptors to assign to this API key.\nThe API key's effective permissions are an intersection of its assigned privileges and the point in time snapshot of permissions of the owner user.\nYou can assign new privileges by specifying them in this parameter.\nTo remove assigned privileges, you can supply an empty `role_descriptors` parameter, that is to say, an empty object `{}`.\nIf an API key has no assigned privileges, it inherits the owner user's full permissions.\nThe snapshot of the owner's permissions is always updated, whether you supply the `role_descriptors` parameter or not.\nThe structure of a role descriptor is the same as the request for the create API keys API.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/security._types:RoleDescriptor" @@ -17711,7 +17721,7 @@ "type": "object", "properties": { "updated": { - "description": "If `true`, the API key was updated.\nIf `false`, the API key didn’t change because no change was detected.", + "description": "If `true`, the API key was updated.\nIf `false`, the API key didn't change because no change was detected.", "type": "boolean" } }, @@ -54337,7 +54347,10 @@ "$ref": "#/components/schemas/_types:Metadata" }, "run_as": { - "description": "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.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/run-as-privilege.html" + }, + "description": "A list of users that the API keys can impersonate.\nNOTE: In Elastic Cloud Serverless, the run-as feature is disabled.\nFor API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected.", "type": "array", "items": { "type": "string" @@ -54563,6 +54576,7 @@ "type": "object", "properties": { "workflows": { + "description": "A list of workflows to which the API key is restricted.\nNOTE: In order to use a role restriction, an API key must be created with a single role descriptor.", "type": "array", "items": { "$ref": "#/components/schemas/security._types:RestrictionWorkflow" @@ -54752,14 +54766,14 @@ "type": "string" }, "privileges": { - "description": "A list of the privileges that you want to check for the specified resources. May be either application privilege names, or the names of actions that are granted by those privileges", + "description": "A list of the privileges that you want to check for the specified resources.\nIt may be either application privilege names or the names of actions that are granted by those privileges", "type": "array", "items": { "type": "string" } }, "resources": { - "description": "A list of resource names against which the privileges should be checked", + "description": "A list of resource names against which the privileges should be checked.", "type": "array", "items": { "type": "string" @@ -54786,7 +54800,7 @@ } }, "allow_restricted_indices": { - "description": "This needs to be set to true (default is false) if using wildcards or regexps for patterns that cover restricted indices.\nImplicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false.\nIf restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of allow_restricted_indices.", + "description": "This needs to be set to `true` (default is `false`) if using wildcards or regexps for patterns that cover restricted indices.\nImplicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false.\nIf restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of `allow_restricted_indices`.", "type": "boolean" } }, @@ -62373,7 +62387,7 @@ "security.query_api_keys#with_limited_by": { "in": "query", "name": "with_limited_by", - "description": "Return the snapshot of the owner user's role descriptors associated with the API key.\nAn API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors.", + "description": "Return the snapshot of the owner user's role descriptors associated with the API key.\nAn API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors (effectively limited by it).\nAn API key cannot retrieve any API key’s limited-by role descriptors (including itself) unless it has `manage_api_key` or higher privileges.", "deprecated": false, "schema": { "type": "boolean" @@ -62383,7 +62397,7 @@ "security.query_api_keys#with_profile_uid": { "in": "query", "name": "with_profile_uid", - "description": "Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists.", + "description": "Determines whether to also retrieve the profile UID for the API key owner principal.\nIf it exists, the profile UID is returned under the `profile_uid` response field for each API key.", "deprecated": false, "schema": { "type": "boolean" @@ -64090,7 +64104,10 @@ "$ref": "#/components/schemas/_types:Name" }, "role_descriptors": { - "description": "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.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html" + }, + "description": "An array of role descriptors for this API key.\nWhen 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.\nIf 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.\nThe structure of role descriptor is the same as the request for the create role API.\nFor more details, refer to the create or update roles API.\n\nNOTE: 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.\nIn this case, you must explicitly specify a role descriptor with no privileges.\nThe derived API key can be used for authentication; it will not have authority to call Elasticsearch APIs.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/security._types:RoleDescriptor" @@ -64153,14 +64170,14 @@ "$ref": "#/components/schemas/security.query_api_keys:ApiKeyQueryContainer" }, "from": { - "description": "Starting document offset.\nBy default, you cannot page through more than 10,000 hits using the from and size parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "sort": { "$ref": "#/components/schemas/_types:Sort" }, "size": { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nIt must not be negative.\nThe `size` parameter can be set to `0`, in which case no API key matches are returned, only the aggregation results.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "type": "number" }, "search_after": { diff --git a/output/schema/schema.json b/output/schema/schema.json index 90224378cc..4841e154f9 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -16293,9 +16293,11 @@ "stability": "stable" } }, - "description": "Clear the user cache.\n\nEvict users from the user cache. You can completely clear the cache or evict specific users.", + "description": "Clear the user cache.\n\nEvict users from the user cache.\nYou can completely clear the cache or evict specific users.\n\nUser credentials are cached in memory on each node to avoid connecting to a remote authentication service or hitting the disk for every incoming request.\nThere are realm settings that you can use to configure the user cache.\nFor more information, refer to the documentation about controlling the user cache.", "docId": "security-api-clear-cache", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-clear-cache.html", + "extDocId": "security-user-cache", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/controlling-user-cache.html", "name": "security.clear_cached_realms", "request": { "name": "Request", @@ -16368,7 +16370,7 @@ "stability": "stable" } }, - "description": "Clear service account token caches.\n\nEvict a subset of all entries from the service account token caches.", + "description": "Clear service account token caches.\n\nEvict a subset of all entries from the service account token caches.\nTwo 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.\nThis API clears matching entries from both caches.\n\nThe cache for service account tokens backed by the `.security` index is cleared automatically on state changes of the security index.\nThe cache for tokens backed by the `service_tokens` file is cleared automatically on file changes.", "docId": "security-api-clear-service-token-caches", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-clear-service-token-caches.html", "extDocId": "service-accounts", @@ -16411,9 +16413,11 @@ "stability": "stable" } }, - "description": "Create an API key.\n\nCreate an API key for access without requiring basic authentication.\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Create an API key.\n\nCreate an API key for access without requiring basic authentication.\n\nIMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges.\nIf you specify privileges, the API returns an error.\n\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.\n\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\nTo configure or turn off the API key service, refer to API key service setting documentation.", "docId": "security-api-create-api-key", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-create-api-key.html", + "extDocId": "security-settings-api-keys", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-settings.html#api-key-service-settings", "name": "security.create_api_key", "privileges": { "cluster": [ @@ -16496,7 +16500,7 @@ "stability": "stable" } }, - "description": "Create a service account token.\n\nCreate a service accounts token for access without requiring basic authentication.", + "description": "Create a service account token.\n\nCreate a service accounts token for access without requiring basic authentication.\n\nNOTE: Service account tokens never expire.\nYou must actively delete them if they are no longer needed.", "docId": "security-api-create-service-token", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-create-service-token.html", "extDocId": "service-accounts", @@ -16542,7 +16546,7 @@ "stability": "stable" } }, - "description": "Delegate PKI authentication.\nThis API implements the exchange of an X509Certificate chain for an Elasticsearch access token.\nThe 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`.\nA successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw `username_pattern` of the respective realm.\n\nThis API is called by smart and trusted proxies, such as Kibana, which terminate the user's TLS session but still want to authenticate the user by using a PKI realm—-​as if the user connected directly to Elasticsearch.\n\nIMPORTANT: The association between the subject public key in the target certificate and the corresponding private key is not validated.\nThis is part of the TLS authentication process and it is delegated to the proxy that calls this API.\nThe proxy is trusted to have performed the TLS authentication and this API translates that authentication into an Elasticsearch access token.", + "description": "Delegate PKI authentication.\n\nThis API implements the exchange of an X509Certificate chain for an Elasticsearch access token.\nThe 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`.\nA successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw `username_pattern` of the respective realm.\n\nThis API is called by smart and trusted proxies, such as Kibana, which terminate the user's TLS session but still want to authenticate the user by using a PKI realm—-​as if the user connected directly to Elasticsearch.\n\nIMPORTANT: The association between the subject public key in the target certificate and the corresponding private key is not validated.\nThis is part of the TLS authentication process and it is delegated to the proxy that calls this API.\nThe proxy is trusted to have performed the TLS authentication and this API translates that authentication into an Elasticsearch access token.", "docId": "security-api-delegate-pki", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delegate-pki-authentication.html", "extDocId": "pki-realm", @@ -16585,12 +16589,17 @@ "stability": "stable" } }, - "description": "Delete application privileges.", + "description": "Delete application privileges.\n\nTo use this API, you must have one of the following privileges:\n\n* The `manage_security` cluster privilege (or a greater privilege such as `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.", "docId": "security-api-delete-privilege", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-privilege.html", "extDocId": "security-privileges", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html", "name": "security.delete_privileges", + "privileges": { + "cluster": [ + "manage_security" + ] + }, "request": { "name": "Request", "namespace": "security.delete_privileges" @@ -16622,7 +16631,7 @@ "stability": "stable" } }, - "description": "Delete roles.\n\nDelete roles in the native realm.", + "description": "Delete roles.\n\nDelete roles in the native realm.\nThe role management APIs are generally the preferred way to manage roles, rather than using file-based role management.\nThe delete roles API cannot remove roles that are defined in roles files.", "docId": "security-api-delete-role", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-role.html", "name": "security.delete_role", @@ -16663,9 +16672,11 @@ "stability": "stable" } }, - "description": "Delete role mappings.", + "description": "Delete role mappings.\n\nRole mappings define which roles are assigned to each user.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files.\nThe delete role mappings API cannot remove role mappings that are defined in role mapping files.", "docId": "security-api-delete-role-mapping", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-delete-role-mapping.html", + "extDocId": "mapping-roles", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-roles.html", "name": "security.delete_role_mapping", "privileges": { "cluster": [ @@ -16778,7 +16789,7 @@ "stability": "stable" } }, - "description": "Disable users.\n\nDisable users in the native realm.", + "description": "Disable users.\n\nDisable users in the native realm.\nBy default, when you create users, they are enabled.\nYou can use this API to revoke a user's access to Elasticsearch.", "docId": "security-api-disable-user", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-disable-user.html", "name": "security.disable_user", @@ -16857,7 +16868,7 @@ "stability": "stable" } }, - "description": "Enable users.\n\nEnable users in the native realm.", + "description": "Enable users.\n\nEnable users in the native realm.\nBy default, when you create users, they are enabled.", "docId": "security-api-enable-user", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-enable-user.html", "name": "security.enable_user", @@ -16937,7 +16948,7 @@ "stability": "stable" } }, - "description": "Enroll Kibana.\n\nEnable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.", + "description": "Enroll Kibana.\n\nEnable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.\n\nNOTE: This API is currently intended for internal use only by Kibana.\nKibana uses this API internally to configure itself for communications with an Elasticsearch cluster that already has security features enabled.", "docId": "security-api-kibana-enrollment", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-kibana-enrollment.html", "name": "security.enroll_kibana", @@ -16972,7 +16983,7 @@ "stability": "stable" } }, - "description": "Enroll a node.\n\nEnroll a new node to allow it to join an existing cluster with security features enabled.", + "description": "Enroll a node.\n\nEnroll a new node to allow it to join an existing cluster with security features enabled.\n\nThe response contains all the necessary information for the joining node to bootstrap discovery and security related settings so that it can successfully join the cluster.\nThe response contains key and certificate material that allows the caller to generate valid signed certificates for the HTTP layer of all nodes in the cluster.", "docId": "security-api-node-enrollment", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-node-enrollment.html", "name": "security.enroll_node", @@ -17096,7 +17107,7 @@ "stability": "stable" } }, - "description": "Get application privileges.", + "description": "Get application privileges.\n\nTo use this API, you must have one of the following privileges:\n\n* The `read_security` cluster privilege (or a greater privilege such as `manage_security` or `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.", "docId": "security-api-get-privileges", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-privileges.html", "extDocId": "security-privileges", @@ -17246,7 +17257,7 @@ "stability": "stable" } }, - "description": "Get service accounts.\n\nGet a list of service accounts that match the provided path parameters.", + "description": "Get service accounts.\n\nGet a list of service accounts that match the provided path parameters.\n\nNOTE: Currently, only the `elastic/fleet-server` service account is available.", "docId": "security-api-get-service-accounts", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-service-accounts.html", "extDocId": "service-accounts", @@ -17301,7 +17312,7 @@ "stability": "stable" } }, - "description": "Get service account credentials.", + "description": "Get service account credentials.\n\nTo use this API, you must have at least the `read_security` cluster privilege (or a greater privilege such as `manage_service_account` or `manage_security`).\n\nThe response includes service account tokens that were created with the create service account tokens API as well as file-backed tokens from all nodes of the cluster.\n\nNOTE: For tokens backed by the `service_tokens` file, the API collects them from all nodes of the cluster.\nTokens with the same name from different nodes are assumed to be the same token and are only counted once towards the total number of service tokens.", "docId": "security-api-get-service-credentials", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-service-credentials.html", "extDocId": "service-accounts", @@ -17340,7 +17351,7 @@ "visibility": "public" } }, - "description": "Get security index settings.\nGet the user-configurable settings for the security internal index (`.security` and associated indices).", + "description": "Get security index settings.\n\nGet the user-configurable settings for the security internal index (`.security` and associated indices).\nOnly a subset of the index settings — those that are user-configurable—will be shown.\nThis includes:\n\n* `index.auto_expand_replicas`\n* `index.number_of_replicas`", "docId": "security-api-get-settings", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-settings.html", "name": "security.get_settings", @@ -17384,9 +17395,11 @@ "stability": "stable" } }, - "description": "Get a token.\n\nCreate a bearer token for access without requiring basic authentication.", + "description": "Get a token.\n\nCreate a bearer token for access without requiring basic authentication.\nThe tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface.\nAlternatively, you can explicitly enable the `xpack.security.authc.token.enabled` setting.\nWhen you are running in production mode, a bootstrap check prevents you from enabling the token service unless you also enable TLS on the HTTP interface.\n\nThe get token API takes the same parameters as a typical OAuth 2.0 token API except for the use of a JSON request body.\n\nA successful get token API call returns a JSON structure that contains the access token, the amount of time (seconds) that the token expires in, the type, and the scope if available.\n\nThe tokens returned by the get token API have a finite period of time for which they are valid and after that time period, they can no longer be used.\nThat time period is defined by the `xpack.security.authc.token.timeout` setting.\nIf you want to invalidate a token immediately, you can do so by using the invalidate token API.", "docId": "security-api-get-token", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-token.html", + "extDocId": "security-encrypt-http", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-basic-setup-https.html#encrypt-http-communication", "name": "security.get_token", "privileges": { "cluster": [ @@ -17470,7 +17483,7 @@ "stability": "stable" } }, - "description": "Get user privileges.", + "description": "Get user privileges.\n\nGet the security privileges for the logged in user.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.\nTo check whether a user has a specific list of privileges, use the has privileges API.", "docId": "security-api-get-user-privileges", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-get-user-privileges.html", "name": "security.get_user_privileges", @@ -17547,7 +17560,7 @@ "stability": "stable" } }, - "description": "Grant an API key.\n\nCreate an API key on behalf of another user.\nThis API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API.\nThe caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created.\nIt is not possible to use this API to create an API key without that user’s credentials.\nThe user, for whom the authentication credentials is provided, can optionally \"run as\" (impersonate) another user.\nIn this case, the API key will be created on behalf of the impersonated user.\n\nThis API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf.\n\nA successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nBy default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Grant an API key.\n\nCreate an API key on behalf of another user.\nThis API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API.\nThe caller must have authentication credentials for the user on whose behalf the API key will be created.\nIt is not possible to use this API to create an API key without that user's credentials.\nThe supported user authentication credential types are:\n\n* username and password\n* Elasticsearch access tokens\n* JWTs\n\nThe user, for whom the authentication credentials is provided, can optionally \"run as\" (impersonate) another user.\nIn this case, the API key will be created on behalf of the impersonated user.\n\nThis API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf.\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\n\nA successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nBy default, API keys never expire. You can specify expiration information when you create the API keys.", "docId": "security-api-grant-api-key", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-grant-api-key.html", "name": "security.grant_api_key", @@ -17591,7 +17604,7 @@ "stability": "stable" } }, - "description": "Check user privileges.\n\nDetermine whether the specified user has a specified list of privileges.", + "description": "Check user privileges.\n\nDetermine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "docId": "security-api-has-privileges", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-has-privileges.html", "extDocId": "security-privileges", @@ -17687,7 +17700,7 @@ "stability": "stable" } }, - "description": "Invalidate API keys.\n\nThis API invalidates API keys created by the create API key or grant API key APIs.\nInvalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.\nThe `manage_api_key` privilege allows deleting any API keys.\nThe `manage_own_api_key` only allows deleting API keys that are owned by the user.\nIn addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:\n- Set the parameter `owner=true`.\n- Or, set both `username` and `realm_name` to match the user’s identity.\n- Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.", + "description": "Invalidate API keys.\n\nThis API invalidates API keys created by the create API key or grant API key APIs.\nInvalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.\n\nTo use this API, you must have at least the `manage_security`, `manage_api_key`, or `manage_own_api_key` cluster privileges.\nThe `manage_security` privilege allows deleting any API key, including both REST and cross cluster API keys.\nThe `manage_api_key` privilege allows deleting any REST API key, but not cross cluster API keys.\nThe `manage_own_api_key` only allows deleting REST API keys that are owned by the user.\nIn addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:\n\n- Set the parameter `owner=true`.\n- Or, set both `username` and `realm_name` to match the user's identity.\n- Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.", "docId": "security-api-invalidate-api-key", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-invalidate-api-key.html", "name": "security.invalidate_api_key", @@ -17732,7 +17745,7 @@ "stability": "stable" } }, - "description": "Invalidate a token.\n\nThe access tokens returned by the get token API have a finite period of time for which they are valid.\nAfter that time period, they can no longer be used.\nThe time period is defined by the `xpack.security.authc.token.timeout` setting.\n\nThe refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once.\nIf you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.", + "description": "Invalidate a token.\n\nThe access tokens returned by the get token API have a finite period of time for which they are valid.\nAfter that time period, they can no longer be used.\nThe time period is defined by the `xpack.security.authc.token.timeout` setting.\n\nThe refresh tokens returned by the get token API are only valid for 24 hours.\nThey can also be used exactly once.\nIf you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.\n\nNOTE: While all parameters are optional, at least one of them is required.\nMore specifically, either one of `token` or `refresh_token` parameters is required.\nIf none of these two are specified, then `realm_name` and/or `username` need to be specified.", "docId": "security-api-invalidate-token", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-invalidate-token.html", "name": "security.invalidate_token", @@ -17767,7 +17780,7 @@ "visibility": "public" } }, - "description": "Authenticate OpenID Connect.\nExchange an OpenID Connect authentication response message for an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", + "description": "Authenticate OpenID Connect.\n\nExchange an OpenID Connect authentication response message for an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", "docId": "security-api-oidc-authenticate", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-oidc-authenticate.html", "name": "security.oidc_authenticate", @@ -17802,7 +17815,7 @@ "visibility": "public" } }, - "description": "Logout of OpenID Connect.\nInvalidate an access token and a refresh token that were generated as a response to the `/_security/oidc/authenticate` API.\n\nIf the OpenID Connect authentication realm in Elasticsearch is accordingly configured, the response to this call will contain a URI pointing to the end session endpoint of the OpenID Connect Provider in order to perform single logout.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", + "description": "Logout of OpenID Connect.\n\nInvalidate an access token and a refresh token that were generated as a response to the `/_security/oidc/authenticate` API.\n\nIf the OpenID Connect authentication realm in Elasticsearch is accordingly configured, the response to this call will contain a URI pointing to the end session endpoint of the OpenID Connect Provider in order to perform single logout.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", "docId": "security-api-oidc-logout", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-oidc-logout.html", "name": "security.oidc_logout", @@ -17837,7 +17850,7 @@ "visibility": "public" } }, - "description": "Prepare OpenID connect authentication.\nCreate an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch.\n\nThe response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", + "description": "Prepare OpenID connect authentication.\n\nCreate an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch.\n\nThe response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", "docId": "security-api-oidc-prepare", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-oidc-prepare-authentication.html", "name": "security.oidc_prepare_authentication", @@ -17876,7 +17889,7 @@ "stability": "stable" } }, - "description": "Create or update application privileges.", + "description": "Create or update application privileges.\n\nTo use this API, you must have one of the following privileges:\n\n* The `manage_security` cluster privilege (or a greater privilege such as `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.\n\nApplication names are formed from a prefix, with an optional suffix that conform to the following rules:\n\n* The prefix must begin with a lowercase ASCII letter.\n* The prefix must contain only ASCII letters or digits.\n* The prefix must be at least 3 characters long.\n* If the suffix exists, it must begin with either a dash `-` or `_`.\n* The suffix cannot contain any of the following characters: `\\`, `/`, `*`, `?`, `\"`, `<`, `>`, `|`, `,`, `*`.\n* No part of the name can contain whitespace.\n\nPrivilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters `_`, `-`, and `.`.\n\nAction names can contain any number of printable ASCII characters and must contain at least one of the following characters: `/`, `*`, `:`.", "docId": "security-api-put-privileges", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-put-privileges.html", "extDocId": "security-privileges", @@ -17969,7 +17982,7 @@ "stability": "stable" } }, - "description": "Create or update role mappings.\n\nRole mappings define which roles are assigned to each user.\nEach mapping has rules that identify users and a list of roles that are granted to those users.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.\n\nThis API does not create roles. Rather, it maps users to existing roles.\nRoles can be created by using the create or update roles API or roles files.", + "description": "Create or update role mappings.\n\nRole mappings define which roles are assigned to each user.\nEach mapping has rules that identify users and a list of roles that are granted to those users.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.\n\nNOTE: This API does not create roles. Rather, it maps users to existing roles.\nRoles can be created by using the create or update roles API or roles files.\n\n**Role templates**\n\nThe most common use for role mappings is to create a mapping from a known value on the user to a fixed role name.\nFor example, all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the superuser role in Elasticsearch.\nThe `roles` field is used for this purpose.\n\nFor more complex needs, it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user.\nThe `role_templates` field is used for this purpose.\n\nNOTE: To use role templates successfully, the relevant scripting feature must be enabled.\nOtherwise, all attempts to create a role mapping with role templates fail.\n\nAll of the user fields that are available in the role mapping rules are also available in the role templates.\nThus it is possible to assign a user to a role that reflects their username, their groups, or the name of the realm to which they authenticated.\n\nBy default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user.\nIf the format of the template is set to \"json\" then the template is expected to produce a JSON string or an array of JSON strings for the role names.", "docId": "security-api-put-role-mapping", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-put-role-mapping.html", "extDocId": "mapping-roles", @@ -18011,7 +18024,7 @@ "stability": "stable" } }, - "description": "Create or update users.\n\nA password is required for adding a new user but is optional when updating an existing user.\nTo change a user’s password without updating any other fields, use the change password API.", + "description": "Create or update users.\n\nAdd and update users in the native realm.\nA password is required for adding a new user but is optional when updating an existing user.\nTo change a user's password without updating any other fields, use the change password API.", "docId": "security-api-put-user", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-put-user.html", "name": "security.put_user", @@ -18056,7 +18069,7 @@ "stability": "stable" } }, - "description": "Find API keys with a query.\n\nGet a paginated list of API keys and their information. You can optionally filter the results with a query.", + "description": "Find API keys with a query.\n\nGet a paginated list of API keys and their information.\nYou can optionally filter the results with a query.\n\nTo use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges.\nIf you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own.\nIf you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership.", "docId": "security-api-query-api-key", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-query-api-key.html", "name": "security.query_api_keys", @@ -18102,7 +18115,7 @@ "stability": "stable" } }, - "description": "Find roles with a query.\n\nGet roles in a paginated manner. You can optionally filter the results with a query.", + "description": "Find roles with a query.\n\nGet roles in a paginated manner.\nThe role management APIs are generally the preferred way to manage roles, rather than using file-based role management.\nThe query roles API does not retrieve roles that are defined in roles files, nor built-in ones.\nYou can optionally filter the results with a query.\nAlso, the results can be paginated and sorted.", "docId": "security-api-query-role", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-query-role.html", "name": "security.query_role", @@ -18147,7 +18160,7 @@ "stability": "stable" } }, - "description": "Find users with a query.\n\nGet information for users in a paginated manner.\nYou can optionally filter the results with a query.", + "description": "Find users with a query.\n\nGet information for users in a paginated manner.\nYou can optionally filter the results with a query.\n\nNOTE: As opposed to the get user API, built-in users are excluded from the result.\nThis API is only for native users.", "docId": "security-api-query-user", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-query-user.html", "name": "security.query_user", @@ -18476,7 +18489,7 @@ "stability": "stable" } }, - "description": "Update an API key.\n\nUpdates attributes of an existing API key.\nUsers can only update API keys that they created or that were granted to them.\nUse this API to update API keys created by the create API Key or grant API Key APIs.\nIf you need to apply the same update to many API keys, you can use bulk update API Keys to reduce overhead.\nIt’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key.\nThis API supports updates to an API key’s access scope and metadata.\nThe access scope of an API key is derived from the `role_descriptors` you specify in the request, and a snapshot of the owner user’s permissions at the time of the request.\nThe snapshot of the owner’s permissions is updated automatically on every call.\nIf you don’t specify `role_descriptors` in the request, a call to this API might still change the API key’s access scope.\nThis change can occur if the owner user’s permissions have changed since the API key was created or last modified.\nTo update another user’s API key, use the `run_as` feature to submit a request on behalf of another user.\nIMPORTANT: It’s not possible to use an API key as the authentication credential for this API.\nTo update an API key, the owner user’s credentials are required.", + "description": "Update an API key.\n\nUpdate attributes of an existing API key.\nThis API supports updates to an API key's access scope, expiration, and metadata.\n\nTo use this API, you must have at least the `manage_own_api_key` cluster privilege.\nUsers can only update API keys that they created or that were granted to them.\nTo update another user’s API key, use the `run_as` feature to submit a request on behalf of another user.\n\nIMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required.\n\nUse this API to update API keys created by the create API key or grant API Key APIs.\nIf you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead.\nIt's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API.\n\nThe access scope of an API key is derived from the `role_descriptors` you specify in the request and a snapshot of the owner user's permissions at the time of the request.\nThe snapshot of the owner's permissions is updated automatically on every call.\n\nIMPORTANT: If you don't specify `role_descriptors` in the request, a call to this API might still change the API key's access scope.\nThis change can occur if the owner user's permissions have changed since the API key was created or last modified.", "docId": "security-api-update-key", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-api-key.html", "name": "security.update_api_key", @@ -18557,7 +18570,7 @@ "visibility": "public" } }, - "description": "Update security index settings.\n\nUpdate the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use.", + "description": "Update security index settings.\n\nUpdate the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified. This includes `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nNOTE: If `index.auto_expand_replicas` is set, `index.number_of_replicas` will be ignored during updates.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected.\nThis API does not yet support configuring the settings for indices before they are in use.", "docId": "security-api-update-settings", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-settings.html", "name": "security.update_settings", @@ -192813,8 +192826,8 @@ "properties": [ { "description": "The document fields that the owners of the role have read access to.", - "docId": "field-and-document-access-control", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html", + "extDocId": "field-and-document-access-control", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html", "name": "field_security", "required": false, "type": { @@ -193080,8 +193093,8 @@ }, { "description": "The document fields that the owners of the role have read access to.", - "docId": "field-and-document-access-control", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html", + "extDocId": "field-and-document-access-control", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html", "name": "field_security", "required": false, "type": { @@ -193223,6 +193236,7 @@ }, "properties": [ { + "description": "A list of workflows to which the API key is restricted.\nNOTE: In order to use a role restriction, an API key must be created with a single role descriptor.", "name": "workflows", "required": true, "type": { @@ -193237,7 +193251,7 @@ } } ], - "specLocation": "security/_types/RoleDescriptor.ts#L130-L132" + "specLocation": "security/_types/RoleDescriptor.ts#L135-L141" }, { "kind": "enum", @@ -193251,7 +193265,7 @@ "name": "RestrictionWorkflow", "namespace": "security._types" }, - "specLocation": "security/_types/RoleDescriptor.ts#L134-L137" + "specLocation": "security/_types/RoleDescriptor.ts#L143-L146" }, { "kind": "interface", @@ -193319,7 +193333,7 @@ "since": "8.15.0" } }, - "description": "A list of cluster permissions for remote clusters. Note - this is limited a subset of the cluster permissions.", + "description": "A list of cluster permissions for remote clusters.\nNOTE: This is limited a subset of the cluster permissions.", "name": "remote_cluster", "required": false, "type": { @@ -193391,9 +193405,9 @@ } }, { - "description": "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.", - "docId": "run-as-privilege", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/run-as-privilege.html", + "description": "A list of users that the API keys can impersonate.\nNOTE: In Elastic Cloud Serverless, the run-as feature is disabled.\nFor API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected.", + "extDocId": "run-as-privilege", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/run-as-privilege.html", "name": "run_as", "required": false, "type": { @@ -193450,7 +193464,7 @@ } } ], - "specLocation": "security/_types/RoleDescriptor.ts#L33-L80" + "specLocation": "security/_types/RoleDescriptor.ts#L33-L83" }, { "kind": "interface", @@ -193538,7 +193552,7 @@ "since": "8.15.0" } }, - "description": "A list of cluster permissions for remote clusters. Note - this is limited a subset of the cluster permissions.", + "description": "A list of cluster permissions for remote clusters.\nNOTE: This is limited a subset of the cluster permissions.", "name": "remote_cluster", "required": false, "type": { @@ -193611,8 +193625,8 @@ }, { "description": "A list of users that the API keys can impersonate.", - "docId": "run-as-privilege", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/run-as-privilege.html", + "extDocId": "run-as-privilege", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/run-as-privilege.html", "name": "run_as", "required": false, "type": { @@ -193627,7 +193641,7 @@ } }, { - "description": "Optional description of the role descriptor", + "description": "An optional description of the role descriptor.", "name": "description", "required": false, "type": { @@ -193639,7 +193653,9 @@ } }, { - "description": "Restriction for when the role descriptor is allowed to be effective.", + "description": "A restriction for when the role descriptor is allowed to be effective.", + "extDocId": "role-restriction", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/role-restriction.html", "name": "restriction", "required": false, "type": { @@ -193669,7 +193685,7 @@ } } ], - "specLocation": "security/_types/RoleDescriptor.ts#L82-L128" + "specLocation": "security/_types/RoleDescriptor.ts#L85-L133" }, { "kind": "interface", @@ -193989,8 +194005,8 @@ "properties": [ { "description": "The document fields that the owners of the role have read access to.", - "docId": "field-and-document-access-control", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html", + "extDocId": "field-and-document-access-control", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html", "name": "field_security", "required": false, "type": { @@ -194219,8 +194235,8 @@ "properties": [ { "description": "The document fields that the owners of the role have read access to.", - "docId": "field-and-document-access-control", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html", + "extDocId": "field-and-document-access-control", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/field-and-document-access-control.html", "name": "field_security", "required": false, "type": { @@ -195516,7 +195532,7 @@ }, "path": [ { - "description": "A comma-separated list of application names", + "description": "A comma-separated list of applications.\nTo clear all applications, use an asterism (`*`).\nIt does not support other wildcard patterns.", "name": "application", "required": true, "type": { @@ -195529,7 +195545,7 @@ } ], "query": [], - "specLocation": "security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts#L23-L38" + "specLocation": "security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts#L23-L43" }, { "kind": "response", @@ -195597,7 +195613,7 @@ "body": { "kind": "no_body" }, - "description": "Clear the user cache.\n\nEvict users from the user cache. You can completely clear the cache or evict specific users.", + "description": "Clear the user cache.\n\nEvict users from the user cache.\nYou can completely clear the cache or evict specific users.\n\nUser credentials are cached in memory on each node to avoid connecting to a remote authentication service or hitting the disk for every incoming request.\nThere are realm settings that you can use to configure the user cache.\nFor more information, refer to the documentation about controlling the user cache.", "inherits": { "type": { "name": "RequestBase", @@ -195610,7 +195626,7 @@ }, "path": [ { - "description": "Comma-separated list of realms to clear", + "description": "A comma-separated list of realms.\nTo clear all realms, use an asterisk (`*`).\nIt does not support other wildcard patterns.", "name": "realms", "required": true, "type": { @@ -195624,7 +195640,7 @@ ], "query": [ { - "description": "Comma-separated list of usernames to clear from the cache", + "description": "A comma-separated list of the users to clear from the cache.\nIf you do not specify this parameter, the API evicts all users from the user cache.", "name": "usernames", "required": false, "type": { @@ -195639,7 +195655,7 @@ } } ], - "specLocation": "security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts#L23-L39" + "specLocation": "security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts#L23-L54" }, { "kind": "response", @@ -195720,7 +195736,7 @@ }, "path": [ { - "description": "Role name", + "description": "A comma-separated list of roles to evict from the role cache.\nTo evict all roles, use an asterisk (`*`).\nIt does not support other wildcard patterns.", "name": "name", "required": true, "type": { @@ -195733,7 +195749,7 @@ } ], "query": [], - "specLocation": "security/clear_cached_roles/ClearCachedRolesRequest.ts#L23-L37" + "specLocation": "security/clear_cached_roles/ClearCachedRolesRequest.ts#L23-L42" }, { "kind": "response", @@ -195801,7 +195817,7 @@ "body": { "kind": "no_body" }, - "description": "Clear service account token caches.\n\nEvict a subset of all entries from the service account token caches.", + "description": "Clear service account token caches.\n\nEvict a subset of all entries from the service account token caches.\nTwo 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.\nThis API clears matching entries from both caches.\n\nThe cache for service account tokens backed by the `.security` index is cleared automatically on state changes of the security index.\nThe cache for tokens backed by the `service_tokens` file is cleared automatically on file changes.", "inherits": { "type": { "name": "RequestBase", @@ -195814,7 +195830,7 @@ }, "path": [ { - "description": "An identifier for the namespace", + "description": "The namespace, which is a top-level grouping of service accounts.", "name": "namespace", "required": true, "type": { @@ -195826,7 +195842,7 @@ } }, { - "description": "An identifier for the service name", + "description": "The name of the service, which must be unique within its namespace.", "name": "service", "required": true, "type": { @@ -195838,7 +195854,7 @@ } }, { - "description": "A comma-separated list of service token names", + "description": "A comma-separated list of token names to evict from the service account token caches.\nUse a wildcard (`*`) to evict all tokens that belong to a service account.\nIt does not support other wildcard patterns.", "name": "name", "required": true, "type": { @@ -195851,7 +195867,7 @@ } ], "query": [], - "specLocation": "security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts#L23-L40" + "specLocation": "security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts#L23-L52" }, { "kind": "response", @@ -195920,7 +195936,7 @@ "kind": "properties", "properties": [ { - "description": "Expiration time for the API key. By default, API keys never expire.", + "description": "The expiration time for the API key.\nBy default, API keys never expire.", "name": "expiration", "required": false, "type": { @@ -195932,7 +195948,7 @@ } }, { - "description": "Specifies the name for this API key.", + "description": "A name for the API key.", "name": "name", "required": false, "type": { @@ -195944,9 +195960,9 @@ } }, { - "description": "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.", - "docId": "security-api-put-role", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-put-role.html", + "description": "An array of role descriptors for this API key.\nWhen 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.\nIf 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.\nThe structure of role descriptor is the same as the request for the create role API.\nFor more details, refer to the create or update roles API.\n\nNOTE: 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.\nIn this case, you must explicitly specify a role descriptor with no privileges.\nThe derived API key can be used for authentication; it will not have authority to call Elasticsearch APIs.", + "extDocId": "security-api-put-role", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-put-role.html", "name": "role_descriptors", "required": false, "type": { @@ -195988,7 +196004,7 @@ } ] }, - "description": "Create an API key.\n\nCreate an API key for access without requiring basic authentication.\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Create an API key.\n\nCreate an API key for access without requiring basic authentication.\n\nIMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges.\nIf you specify privileges, the API returns an error.\n\nA successful request returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nNOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.\n\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\nTo configure or turn off the API key service, refer to API key service setting documentation.", "inherits": { "type": { "name": "RequestBase", @@ -196014,7 +196030,7 @@ } } ], - "specLocation": "security/create_api_key/SecurityCreateApiKeyRequest.ts#L26-L61" + "specLocation": "security/create_api_key/SecurityCreateApiKeyRequest.ts#L26-L80" }, { "kind": "response", @@ -196258,7 +196274,7 @@ "body": { "kind": "no_body" }, - "description": "Create a service account token.\n\nCreate a service accounts token for access without requiring basic authentication.", + "description": "Create a service account token.\n\nCreate a service accounts token for access without requiring basic authentication.\n\nNOTE: Service account tokens never expire.\nYou must actively delete them if they are no longer needed.", "inherits": { "type": { "name": "RequestBase", @@ -196271,7 +196287,7 @@ }, "path": [ { - "description": "An identifier for the namespace", + "description": "The name of the namespace, which is a top-level grouping of service accounts.", "name": "namespace", "required": true, "type": { @@ -196283,7 +196299,7 @@ } }, { - "description": "An identifier for the service name", + "description": "The name of the service.", "name": "service", "required": true, "type": { @@ -196295,7 +196311,7 @@ } }, { - "description": "An identifier for the token name", + "description": "The name for the service account token.\nIf omitted, a random name will be generated.\n\nToken names must be at least one and no more than 256 characters.\nThey can contain alphanumeric characters (a-z, A-Z, 0-9), dashes (`-`), and underscores (`_`), but cannot begin with an underscore.\n\nNOTE: Token names must be unique in the context of the associated service account.\nThey must also be globally unique with their fully qualified names, which are comprised of the service account principal and token name, such as `//`.", "name": "name", "required": false, "type": { @@ -196321,7 +196337,7 @@ } } ], - "specLocation": "security/create_service_token/CreateServiceTokenRequest.ts#L23-L43" + "specLocation": "security/create_service_token/CreateServiceTokenRequest.ts#L23-L62" }, { "kind": "response", @@ -196356,7 +196372,7 @@ "name": "Response", "namespace": "security.create_service_token" }, - "specLocation": "security/create_service_token/CreateServiceTokenResponse.ts#L22-L27" + "specLocation": "security/create_service_token/CreateServiceTokenResponse.ts#L22-L30" }, { "kind": "interface", @@ -196638,7 +196654,7 @@ } ] }, - "description": "Delegate PKI authentication.\nThis API implements the exchange of an X509Certificate chain for an Elasticsearch access token.\nThe 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`.\nA successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw `username_pattern` of the respective realm.\n\nThis API is called by smart and trusted proxies, such as Kibana, which terminate the user's TLS session but still want to authenticate the user by using a PKI realm—-​as if the user connected directly to Elasticsearch.\n\nIMPORTANT: The association between the subject public key in the target certificate and the corresponding private key is not validated.\nThis is part of the TLS authentication process and it is delegated to the proxy that calls this API.\nThe proxy is trusted to have performed the TLS authentication and this API translates that authentication into an Elasticsearch access token.", + "description": "Delegate PKI authentication.\n\nThis API implements the exchange of an X509Certificate chain for an Elasticsearch access token.\nThe 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`.\nA successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw `username_pattern` of the respective realm.\n\nThis API is called by smart and trusted proxies, such as Kibana, which terminate the user's TLS session but still want to authenticate the user by using a PKI realm—-​as if the user connected directly to Elasticsearch.\n\nIMPORTANT: The association between the subject public key in the target certificate and the corresponding private key is not validated.\nThis is part of the TLS authentication process and it is delegated to the proxy that calls this API.\nThe proxy is trusted to have performed the TLS authentication and this API translates that authentication into an Elasticsearch access token.", "inherits": { "type": { "name": "RequestBase", @@ -196651,7 +196667,7 @@ }, "path": [], "query": [], - "specLocation": "security/delegate_pki/SecurityDelegatePkiRequest.ts#L22-L50" + "specLocation": "security/delegate_pki/SecurityDelegatePkiRequest.ts#L22-L51" }, { "kind": "response", @@ -196742,7 +196758,7 @@ "body": { "kind": "no_body" }, - "description": "Delete application privileges.", + "description": "Delete application privileges.\n\nTo use this API, you must have one of the following privileges:\n\n* The `manage_security` cluster privilege (or a greater privilege such as `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.", "inherits": { "type": { "name": "RequestBase", @@ -196755,7 +196771,7 @@ }, "path": [ { - "description": "Application name", + "description": "The name of the application.\nApplication privileges are always associated with exactly one application.", "name": "application", "required": true, "type": { @@ -196767,7 +196783,7 @@ } }, { - "description": "Privilege name", + "description": "The name of the privilege.", "name": "name", "required": true, "type": { @@ -196793,7 +196809,7 @@ } } ], - "specLocation": "security/delete_privileges/SecurityDeletePrivilegesRequest.ts#L23-L39" + "specLocation": "security/delete_privileges/SecurityDeletePrivilegesRequest.ts#L23-L52" }, { "kind": "response", @@ -196843,7 +196859,7 @@ "body": { "kind": "no_body" }, - "description": "Delete roles.\n\nDelete roles in the native realm.", + "description": "Delete roles.\n\nDelete roles in the native realm.\nThe role management APIs are generally the preferred way to manage roles, rather than using file-based role management.\nThe delete roles API cannot remove roles that are defined in roles files.", "inherits": { "type": { "name": "RequestBase", @@ -196856,7 +196872,7 @@ }, "path": [ { - "description": "Role name", + "description": "The name of the role.", "name": "name", "required": true, "type": { @@ -196882,7 +196898,7 @@ } } ], - "specLocation": "security/delete_role/SecurityDeleteRoleRequest.ts#L23-L40" + "specLocation": "security/delete_role/SecurityDeleteRoleRequest.ts#L23-L43" }, { "kind": "response", @@ -196890,6 +196906,7 @@ "kind": "properties", "properties": [ { + "description": "If the role is successfully deleted, `found` is `true`.\nOtherwise, `found` is `false`.", "name": "found", "required": true, "type": { @@ -196906,7 +196923,7 @@ "name": "Response", "namespace": "security.delete_role" }, - "specLocation": "security/delete_role/SecurityDeleteRoleResponse.ts#L20-L22" + "specLocation": "security/delete_role/SecurityDeleteRoleResponse.ts#L20-L28" }, { "kind": "request", @@ -196916,7 +196933,7 @@ "body": { "kind": "no_body" }, - "description": "Delete role mappings.", + "description": "Delete role mappings.\n\nRole mappings define which roles are assigned to each user.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files.\nThe delete role mappings API cannot remove role mappings that are defined in role mapping files.", "inherits": { "type": { "name": "RequestBase", @@ -196929,7 +196946,7 @@ }, "path": [ { - "description": "Role-mapping name", + "description": "The distinct name that identifies the role mapping.\nThe name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way.", "name": "name", "required": true, "type": { @@ -196955,7 +196972,7 @@ } } ], - "specLocation": "security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts#L23-L38" + "specLocation": "security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts#L23-L47" }, { "kind": "response", @@ -196963,6 +196980,7 @@ "kind": "properties", "properties": [ { + "description": "If the mapping is successfully deleted, `found` is `true`.\nOtherwise, `found` is `false`.", "name": "found", "required": true, "type": { @@ -196979,7 +196997,7 @@ "name": "Response", "namespace": "security.delete_role_mapping" }, - "specLocation": "security/delete_role_mapping/SecurityDeleteRoleMappingResponse.ts#L20-L22" + "specLocation": "security/delete_role_mapping/SecurityDeleteRoleMappingResponse.ts#L20-L28" }, { "kind": "request", @@ -197002,7 +197020,7 @@ }, "path": [ { - "description": "An identifier for the namespace", + "description": "The namespace, which is a top-level grouping of service accounts.", "name": "namespace", "required": true, "type": { @@ -197014,7 +197032,7 @@ } }, { - "description": "An identifier for the service name", + "description": "The service name.", "name": "service", "required": true, "type": { @@ -197026,7 +197044,7 @@ } }, { - "description": "An identifier for the token name", + "description": "The name of the service account token.", "name": "name", "required": true, "type": { @@ -197052,7 +197070,7 @@ } } ], - "specLocation": "security/delete_service_token/DeleteServiceTokenRequest.ts#L23-L43" + "specLocation": "security/delete_service_token/DeleteServiceTokenRequest.ts#L23-L52" }, { "kind": "response", @@ -197060,6 +197078,7 @@ "kind": "properties", "properties": [ { + "description": "If the service account token is successfully deleted, the request returns `{\"found\": true}`.\nOtherwise, the response will have status code 404 and `found` is set to `false`.", "name": "found", "required": true, "type": { @@ -197076,7 +197095,7 @@ "name": "Response", "namespace": "security.delete_service_token" }, - "specLocation": "security/delete_service_token/DeleteServiceTokenResponse.ts#L20-L22" + "specLocation": "security/delete_service_token/DeleteServiceTokenResponse.ts#L20-L28" }, { "kind": "request", @@ -197099,7 +197118,7 @@ }, "path": [ { - "description": "username", + "description": "An identifier for the user.", "name": "username", "required": true, "type": { @@ -197125,7 +197144,7 @@ } } ], - "specLocation": "security/delete_user/SecurityDeleteUserRequest.ts#L23-L39" + "specLocation": "security/delete_user/SecurityDeleteUserRequest.ts#L23-L42" }, { "kind": "response", @@ -197133,6 +197152,7 @@ "kind": "properties", "properties": [ { + "description": "If the user is successfully deleted, the request returns `{\"found\": true}`.\nOtherwise, `found` is set to `false`.", "name": "found", "required": true, "type": { @@ -197149,7 +197169,7 @@ "name": "Response", "namespace": "security.delete_user" }, - "specLocation": "security/delete_user/SecurityDeleteUserResponse.ts#L20-L22" + "specLocation": "security/delete_user/SecurityDeleteUserResponse.ts#L20-L28" }, { "kind": "request", @@ -197159,7 +197179,7 @@ "body": { "kind": "no_body" }, - "description": "Disable users.\n\nDisable users in the native realm.", + "description": "Disable users.\n\nDisable users in the native realm.\nBy default, when you create users, they are enabled.\nYou can use this API to revoke a user's access to Elasticsearch.", "inherits": { "type": { "name": "RequestBase", @@ -197172,7 +197192,7 @@ }, "path": [ { - "description": "The username of the user to disable", + "description": "An identifier for the user.", "name": "username", "required": true, "type": { @@ -197198,7 +197218,7 @@ } } ], - "specLocation": "security/disable_user/SecurityDisableUserRequest.ts#L23-L39" + "specLocation": "security/disable_user/SecurityDisableUserRequest.ts#L23-L44" }, { "kind": "response", @@ -197288,7 +197308,7 @@ "body": { "kind": "no_body" }, - "description": "Enable users.\n\nEnable users in the native realm.", + "description": "Enable users.\n\nEnable users in the native realm.\nBy default, when you create users, they are enabled.", "inherits": { "type": { "name": "RequestBase", @@ -197301,7 +197321,7 @@ }, "path": [ { - "description": "The username of the user to enable", + "description": "An identifier for the user.", "name": "username", "required": true, "type": { @@ -197327,7 +197347,7 @@ } } ], - "specLocation": "security/enable_user/SecurityEnableUserRequest.ts#L23-L39" + "specLocation": "security/enable_user/SecurityEnableUserRequest.ts#L23-L43" }, { "kind": "response", @@ -197417,7 +197437,7 @@ "body": { "kind": "no_body" }, - "description": "Enroll Kibana.\n\nEnable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.", + "description": "Enroll Kibana.\n\nEnable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.\n\nNOTE: This API is currently intended for internal use only by Kibana.\nKibana uses this API internally to configure itself for communications with an Elasticsearch cluster that already has security features enabled.", "inherits": { "type": { "name": "RequestBase", @@ -197430,7 +197450,7 @@ }, "path": [], "query": [], - "specLocation": "security/enroll_kibana/Request.ts#L22-L30" + "specLocation": "security/enroll_kibana/Request.ts#L22-L33" }, { "kind": "response", @@ -197449,6 +197469,7 @@ } }, { + "description": "The CA certificate used to sign the node certificates that Elasticsearch uses for TLS on the HTTP layer.\nThe certificate is returned as a Base64 encoded string of the ASN.1 DER encoding of the certificate.", "name": "http_ca", "required": true, "type": { @@ -197465,7 +197486,7 @@ "name": "Response", "namespace": "security.enroll_kibana" }, - "specLocation": "security/enroll_kibana/Response.ts#L20-L25" + "specLocation": "security/enroll_kibana/Response.ts#L20-L29" }, { "kind": "interface", @@ -197475,6 +197496,7 @@ }, "properties": [ { + "description": "The name of the bearer token for the `elastic/kibana` service account.", "name": "name", "required": true, "type": { @@ -197486,6 +197508,7 @@ } }, { + "description": "The value of the bearer token for the `elastic/kibana` service account.\nUse this value to authenticate the service account with Elasticsearch.", "name": "value", "required": true, "type": { @@ -197497,7 +197520,7 @@ } } ], - "specLocation": "security/enroll_kibana/Response.ts#L27-L30" + "specLocation": "security/enroll_kibana/Response.ts#L31-L41" }, { "kind": "request", @@ -197507,7 +197530,7 @@ "body": { "kind": "no_body" }, - "description": "Enroll a node.\n\nEnroll a new node to allow it to join an existing cluster with security features enabled.", + "description": "Enroll a node.\n\nEnroll a new node to allow it to join an existing cluster with security features enabled.\n\nThe response contains all the necessary information for the joining node to bootstrap discovery and security related settings so that it can successfully join the cluster.\nThe response contains key and certificate material that allows the caller to generate valid signed certificates for the HTTP layer of all nodes in the cluster.", "inherits": { "type": { "name": "RequestBase", @@ -197520,7 +197543,7 @@ }, "path": [], "query": [], - "specLocation": "security/enroll_node/Request.ts#L22-L30" + "specLocation": "security/enroll_node/Request.ts#L22-L33" }, { "kind": "response", @@ -197528,6 +197551,7 @@ "kind": "properties", "properties": [ { + "description": "The CA private key that can be used by the new node in order to sign its certificate for the HTTP layer, as a Base64 encoded string of the ASN.1 DER encoding of the key.", "name": "http_ca_key", "required": true, "type": { @@ -197539,6 +197563,7 @@ } }, { + "description": "The CA certificate that can be used by the new node in order to sign its certificate for the HTTP layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate.", "name": "http_ca_cert", "required": true, "type": { @@ -197550,6 +197575,7 @@ } }, { + "description": "The CA certificate that is used to sign the TLS certificate for the transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate.", "name": "transport_ca_cert", "required": true, "type": { @@ -197561,6 +197587,7 @@ } }, { + "description": "The private key that the node can use for TLS for its transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the key.", "name": "transport_key", "required": true, "type": { @@ -197572,6 +197599,7 @@ } }, { + "description": "The certificate that the node can use for TLS for its transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate.", "name": "transport_cert", "required": true, "type": { @@ -197583,6 +197611,7 @@ } }, { + "description": "A list of transport addresses in the form of `host:port` for the nodes that are already members of the cluster.", "name": "nodes_addresses", "required": true, "type": { @@ -197602,7 +197631,7 @@ "name": "Response", "namespace": "security.enroll_node" }, - "specLocation": "security/enroll_node/Response.ts#L20-L29" + "specLocation": "security/enroll_node/Response.ts#L20-L47" }, { "kind": "request", @@ -197802,6 +197831,7 @@ "kind": "properties", "properties": [ { + "description": "The list of cluster privileges that are understood by this version of Elasticsearch.", "name": "cluster", "required": true, "type": { @@ -197816,6 +197846,7 @@ } }, { + "description": "The list of index privileges that are understood by this version of Elasticsearch.", "name": "index", "required": true, "type": { @@ -197827,6 +197858,12 @@ } }, { + "availability": { + "stack": { + "since": "8.15.0" + } + }, + "description": "The list of remote_cluster privileges that are understood by this version of Elasticsearch.", "name": "remote_cluster", "required": true, "type": { @@ -197846,7 +197883,7 @@ "name": "Response", "namespace": "security.get_builtin_privileges" }, - "specLocation": "security/get_builtin_privileges/SecurityGetBuiltinPrivilegesResponse.ts#L26-L32" + "specLocation": "security/get_builtin_privileges/SecurityGetBuiltinPrivilegesResponse.ts#L26-L42" }, { "kind": "request", @@ -197856,7 +197893,7 @@ "body": { "kind": "no_body" }, - "description": "Get application privileges.", + "description": "Get application privileges.\n\nTo use this API, you must have one of the following privileges:\n\n* The `read_security` cluster privilege (or a greater privilege such as `manage_security` or `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.", "inherits": { "type": { "name": "RequestBase", @@ -197869,7 +197906,7 @@ }, "path": [ { - "description": "Application name", + "description": "The name of the application.\nApplication privileges are always associated with exactly one application.\nIf you do not specify this parameter, the API returns information about all privileges for all applications.", "name": "application", "required": false, "type": { @@ -197881,7 +197918,7 @@ } }, { - "description": "Privilege name", + "description": "The name of the privilege.\nIf you do not specify this parameter, the API returns information about all privileges for the requested application.", "name": "name", "required": false, "type": { @@ -197894,7 +197931,7 @@ } ], "query": [], - "specLocation": "security/get_privileges/SecurityGetPrivilegesRequest.ts#L23-L37" + "specLocation": "security/get_privileges/SecurityGetPrivilegesRequest.ts#L23-L51" }, { "kind": "response", @@ -197934,7 +197971,7 @@ "name": "Response", "namespace": "security.get_privileges" }, - "specLocation": "security/get_privileges/SecurityGetPrivilegesResponse.ts#L23-L26" + "specLocation": "security/get_privileges/SecurityGetPrivilegesResponse.ts#L23-L29" }, { "kind": "request", @@ -197957,7 +197994,7 @@ }, "path": [ { - "description": "The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles.", + "description": "The name of the role.\nYou can specify multiple roles as a comma-separated list.\nIf you do not specify this parameter, the API returns information about all roles.", "name": "name", "required": false, "type": { @@ -197970,7 +198007,7 @@ } ], "query": [], - "specLocation": "security/get_role/SecurityGetRoleRequest.ts#L23-L42" + "specLocation": "security/get_role/SecurityGetRoleRequest.ts#L23-L44" }, { "kind": "response", @@ -197999,7 +198036,7 @@ "name": "Response", "namespace": "security.get_role" }, - "specLocation": "security/get_role/SecurityGetRoleResponse.ts#L23-L26" + "specLocation": "security/get_role/SecurityGetRoleResponse.ts#L23-L31" }, { "kind": "interface", @@ -198264,7 +198301,7 @@ "name": "Response", "namespace": "security.get_role_mapping" }, - "specLocation": "security/get_role_mapping/SecurityGetRoleMappingResponse.ts#L23-L26" + "specLocation": "security/get_role_mapping/SecurityGetRoleMappingResponse.ts#L23-L29" }, { "kind": "request", @@ -198274,7 +198311,7 @@ "body": { "kind": "no_body" }, - "description": "Get service accounts.\n\nGet a list of service accounts that match the provided path parameters.", + "description": "Get service accounts.\n\nGet a list of service accounts that match the provided path parameters.\n\nNOTE: Currently, only the `elastic/fleet-server` service account is available.", "inherits": { "type": { "name": "RequestBase", @@ -198287,7 +198324,7 @@ }, "path": [ { - "description": "Name of the namespace. Omit this parameter to retrieve information about all service accounts. If you omit this parameter, you must also omit the `service` parameter.", + "description": "The name of the namespace.\nOmit this parameter to retrieve information about all service accounts.\nIf you omit this parameter, you must also omit the `service` parameter.", "name": "namespace", "required": false, "type": { @@ -198299,7 +198336,7 @@ } }, { - "description": "Name of the service name. Omit this parameter to retrieve information about all service accounts that belong to the specified `namespace`.", + "description": "The service name.\nOmit this parameter to retrieve information about all service accounts that belong to the specified `namespace`.", "name": "service", "required": false, "type": { @@ -198312,7 +198349,7 @@ } ], "query": [], - "specLocation": "security/get_service_accounts/GetServiceAccountsRequest.ts#L23-L45" + "specLocation": "security/get_service_accounts/GetServiceAccountsRequest.ts#L23-L50" }, { "kind": "response", @@ -198341,7 +198378,7 @@ "name": "Response", "namespace": "security.get_service_accounts" }, - "specLocation": "security/get_service_accounts/GetServiceAccountsResponse.ts#L23-L26" + "specLocation": "security/get_service_accounts/GetServiceAccountsResponse.ts#L23-L29" }, { "kind": "interface", @@ -198441,7 +198478,7 @@ "body": { "kind": "no_body" }, - "description": "Get service account credentials.", + "description": "Get service account credentials.\n\nTo use this API, you must have at least the `read_security` cluster privilege (or a greater privilege such as `manage_service_account` or `manage_security`).\n\nThe response includes service account tokens that were created with the create service account tokens API as well as file-backed tokens from all nodes of the cluster.\n\nNOTE: For tokens backed by the `service_tokens` file, the API collects them from all nodes of the cluster.\nTokens with the same name from different nodes are assumed to be the same token and are only counted once towards the total number of service tokens.", "inherits": { "type": { "name": "RequestBase", @@ -198454,7 +198491,7 @@ }, "path": [ { - "description": "Name of the namespace.", + "description": "The name of the namespace.", "name": "namespace", "required": true, "type": { @@ -198466,7 +198503,7 @@ } }, { - "description": "Name of the service name.", + "description": "The service name.", "name": "service", "required": true, "type": { @@ -198479,7 +198516,7 @@ } ], "query": [], - "specLocation": "security/get_service_credentials/GetServiceCredentialsRequest.ts#L23-L43" + "specLocation": "security/get_service_credentials/GetServiceCredentialsRequest.ts#L23-L50" }, { "kind": "response", @@ -198531,7 +198568,7 @@ } }, { - "description": "Contains service account credentials collected from all nodes of the cluster", + "description": "Service account credentials collected from all nodes of the cluster.", "name": "nodes_credentials", "required": true, "type": { @@ -198548,7 +198585,7 @@ "name": "Response", "namespace": "security.get_service_credentials" }, - "specLocation": "security/get_service_credentials/GetServiceCredentialsResponse.ts#L25-L33" + "specLocation": "security/get_service_credentials/GetServiceCredentialsResponse.ts#L25-L34" }, { "kind": "request", @@ -198558,7 +198595,7 @@ "body": { "kind": "no_body" }, - "description": "Get security index settings.\nGet the user-configurable settings for the security internal index (`.security` and associated indices).", + "description": "Get security index settings.\n\nGet the user-configurable settings for the security internal index (`.security` and associated indices).\nOnly a subset of the index settings — those that are user-configurable—will be shown.\nThis includes:\n\n* `index.auto_expand_replicas`\n* `index.number_of_replicas`", "inherits": { "type": { "name": "RequestBase", @@ -198584,7 +198621,7 @@ } } ], - "specLocation": "security/get_settings/SecurityGetSettingsRequest.ts#L23-L39" + "specLocation": "security/get_settings/SecurityGetSettingsRequest.ts#L23-L45" }, { "kind": "response", @@ -198639,15 +198676,19 @@ "kind": "enum", "members": [ { + "description": "This grant type implements the Resource Owner Password Credentials Grant of OAuth2.\nIn this grant, a trusted client exchanges the end user's credentials for an access token and (possibly) a refresh token.\nThe request needs to be made by an authenticated user but happens on behalf of another authenticated user (the one whose credentials are passed as request parameters).\nThis grant type is not suitable or designed for the self-service user creation of tokens.", "name": "password" }, { + "description": "This grant type implements the Client Credentials Grant of OAuth2.\nIt is geared for machine to machine communication and is not suitable or designed for the self-service user creation of tokens.\nIt generates only access tokens that cannot be refreshed.\nThe premise is that the entity that uses `client_credentials` has constant access to a set of (client, not end-user) credentials and can authenticate itself at will.", "name": "client_credentials" }, { + "description": "This grant type is supported internally and implements SPNEGO based Kerberos support.\nThe `_kerberos` grant type may change from version to version.", "name": "_kerberos" }, { + "description": "This grant type implements the Refresh Token Grant of OAuth2.\nIn this grant a user exchanges a previously issued refresh token for a new access token and a new refresh token.", "name": "refresh_token" } ], @@ -198655,7 +198696,7 @@ "name": "AccessTokenGrantType", "namespace": "security.get_token" }, - "specLocation": "security/get_token/types.ts#L23-L28" + "specLocation": "security/get_token/types.ts#L23-L48" }, { "kind": "interface", @@ -198715,7 +198756,7 @@ } } ], - "specLocation": "security/get_token/types.ts#L40-L45" + "specLocation": "security/get_token/types.ts#L60-L65" }, { "kind": "interface", @@ -198747,7 +198788,7 @@ } } ], - "specLocation": "security/get_token/types.ts#L35-L38" + "specLocation": "security/get_token/types.ts#L55-L58" }, { "kind": "request", @@ -198758,6 +198799,7 @@ "kind": "properties", "properties": [ { + "description": "The type of grant.\nSupported grant types are: `password`, `_kerberos`, `client_credentials`, and `refresh_token`.", "name": "grant_type", "required": false, "type": { @@ -198769,6 +198811,7 @@ } }, { + "description": "The scope of the token.\nCurrently tokens are only issued for a scope of FULL regardless of the value sent with the request.", "name": "scope", "required": false, "type": { @@ -198780,6 +198823,7 @@ } }, { + "description": "The user's password.\nIf you specify the `password` grant type, this parameter is required.\nThis parameter is not valid with any other supported grant type.", "name": "password", "required": false, "type": { @@ -198791,6 +198835,7 @@ } }, { + "description": "The base64 encoded kerberos ticket.\nIf you specify the `_kerberos` grant type, this parameter is required.\nThis parameter is not valid with any other supported grant type.", "name": "kerberos_ticket", "required": false, "type": { @@ -198802,6 +198847,7 @@ } }, { + "description": "The string that was returned when you created the token, which enables you to extend its life.\nIf you specify the `refresh_token` grant type, this parameter is required.\nThis parameter is not valid with any other supported grant type.", "name": "refresh_token", "required": false, "type": { @@ -198813,6 +198859,7 @@ } }, { + "description": "The username that identifies the user.\nIf you specify the `password` grant type, this parameter is required.\nThis parameter is not valid with any other supported grant type.", "name": "username", "required": false, "type": { @@ -198825,7 +198872,7 @@ } ] }, - "description": "Get a token.\n\nCreate a bearer token for access without requiring basic authentication.", + "description": "Get a token.\n\nCreate a bearer token for access without requiring basic authentication.\nThe tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface.\nAlternatively, you can explicitly enable the `xpack.security.authc.token.enabled` setting.\nWhen you are running in production mode, a bootstrap check prevents you from enabling the token service unless you also enable TLS on the HTTP interface.\n\nThe get token API takes the same parameters as a typical OAuth 2.0 token API except for the use of a JSON request body.\n\nA successful get token API call returns a JSON structure that contains the access token, the amount of time (seconds) that the token expires in, the type, and the scope if available.\n\nThe tokens returned by the get token API have a finite period of time for which they are valid and after that time period, they can no longer be used.\nThat time period is defined by the `xpack.security.authc.token.timeout` setting.\nIf you want to invalidate a token immediately, you can do so by using the invalidate token API.", "inherits": { "type": { "name": "RequestBase", @@ -198838,7 +198885,7 @@ }, "path": [], "query": [], - "specLocation": "security/get_token/GetUserAccessTokenRequest.ts#L25-L44" + "specLocation": "security/get_token/GetUserAccessTokenRequest.ts#L25-L84" }, { "kind": "response", @@ -198960,7 +199007,7 @@ } } ], - "specLocation": "security/get_token/types.ts#L30-L33" + "specLocation": "security/get_token/types.ts#L50-L53" }, { "kind": "request", @@ -199018,7 +199065,7 @@ "since": "8.5.0" } }, - "description": "If true will return the User Profile ID for a user, if any.", + "description": "Determines whether to retrieve the user profile UID, if it exists, for the users.", "name": "with_profile_uid", "required": false, "serverDefault": false, @@ -199060,7 +199107,7 @@ "name": "Response", "namespace": "security.get_user" }, - "specLocation": "security/get_user/SecurityGetUserResponse.ts#L23-L26" + "specLocation": "security/get_user/SecurityGetUserResponse.ts#L23-L30" }, { "kind": "request", @@ -199070,7 +199117,7 @@ "body": { "kind": "no_body" }, - "description": "Get user privileges.", + "description": "Get user privileges.\n\nGet the security privileges for the logged in user.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.\nTo check whether a user has a specific list of privileges, use the has privileges API.", "inherits": { "type": { "name": "RequestBase", @@ -199131,7 +199178,7 @@ } } ], - "specLocation": "security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts#L23-L38" + "specLocation": "security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts#L23-L43" }, { "kind": "response", @@ -199391,7 +199438,7 @@ "name": "ApiKeyGrantType", "namespace": "security.grant_api_key" }, - "specLocation": "security/grant_api_key/types.ts#L48-L51" + "specLocation": "security/grant_api_key/types.ts#L47-L50" }, { "kind": "interface", @@ -199424,7 +199471,7 @@ } }, { - "description": "The role descriptors for this API key.\nThis parameter is optional.\nWhen it is not specified or is an empty array, the API key has a point in time snapshot of permissions of the specified user or access token.\nIf you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the permissions of the user or access token.", + "description": "The role descriptors for this API key.\nWhen it is not specified or is an empty array, the API key has a point in time snapshot of permissions of the specified user or access token.\nIf you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the permissions of the user or access token.", "name": "role_descriptors", "required": false, "type": { @@ -199485,7 +199532,7 @@ } } ], - "specLocation": "security/grant_api_key/types.ts#L25-L46" + "specLocation": "security/grant_api_key/types.ts#L25-L45" }, { "kind": "request", @@ -199496,7 +199543,7 @@ "kind": "properties", "properties": [ { - "description": "Defines the API key.", + "description": "The API key.", "name": "api_key", "required": true, "type": { @@ -199520,7 +199567,7 @@ } }, { - "description": "The user’s access token.\nIf you specify the `access_token` grant type, this parameter is required.\nIt is not valid with other grant types.", + "description": "The user's access token.\nIf you specify the `access_token` grant type, this parameter is required.\nIt is not valid with other grant types.", "name": "access_token", "required": false, "type": { @@ -199544,7 +199591,7 @@ } }, { - "description": "The user’s password. If you specify the `password` grant type, this parameter is required.\nIt is not valid with other grant types.", + "description": "The user's password.\nIf you specify the `password` grant type, this parameter is required.\nIt is not valid with other grant types.", "name": "password", "required": false, "type": { @@ -199569,7 +199616,7 @@ } ] }, - "description": "Grant an API key.\n\nCreate an API key on behalf of another user.\nThis API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API.\nThe caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created.\nIt is not possible to use this API to create an API key without that user’s credentials.\nThe user, for whom the authentication credentials is provided, can optionally \"run as\" (impersonate) another user.\nIn this case, the API key will be created on behalf of the impersonated user.\n\nThis API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf.\n\nA successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nBy default, API keys never expire. You can specify expiration information when you create the API keys.", + "description": "Grant an API key.\n\nCreate an API key on behalf of another user.\nThis API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API.\nThe caller must have authentication credentials for the user on whose behalf the API key will be created.\nIt is not possible to use this API to create an API key without that user's credentials.\nThe supported user authentication credential types are:\n\n* username and password\n* Elasticsearch access tokens\n* JWTs\n\nThe user, for whom the authentication credentials is provided, can optionally \"run as\" (impersonate) another user.\nIn this case, the API key will be created on behalf of the impersonated user.\n\nThis API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf.\nThe API keys are created by the Elasticsearch API key service, which is automatically enabled.\n\nA successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name.\nIf applicable, it also returns expiration information for the API key in milliseconds.\n\nBy default, API keys never expire. You can specify expiration information when you create the API keys.", "inherits": { "type": { "name": "RequestBase", @@ -199582,7 +199629,7 @@ }, "path": [], "query": [], - "specLocation": "security/grant_api_key/SecurityGrantApiKeyRequest.ts#L24-L78" + "specLocation": "security/grant_api_key/SecurityGrantApiKeyRequest.ts#L24-L86" }, { "kind": "response", @@ -199681,7 +199728,7 @@ } }, { - "description": "A list of the privileges that you want to check for the specified resources. May be either application privilege names, or the names of actions that are granted by those privileges", + "description": "A list of the privileges that you want to check for the specified resources.\nIt may be either application privilege names or the names of actions that are granted by those privileges", "name": "privileges", "required": true, "type": { @@ -199696,7 +199743,7 @@ } }, { - "description": "A list of resource names against which the privileges should be checked", + "description": "A list of resource names against which the privileges should be checked.", "name": "resources", "required": true, "type": { @@ -199711,7 +199758,7 @@ } } ], - "specLocation": "security/has_privileges/types.ts#L24-L31" + "specLocation": "security/has_privileges/types.ts#L24-L32" }, { "kind": "type_alias", @@ -199719,7 +199766,7 @@ "name": "ApplicationsPrivileges", "namespace": "security.has_privileges" }, - "specLocation": "security/has_privileges/types.ts#L46-L46", + "specLocation": "security/has_privileges/types.ts#L47-L47", "type": { "kind": "dictionary_of", "key": { @@ -199774,7 +199821,7 @@ } }, { - "description": "This needs to be set to true (default is false) if using wildcards or regexps for patterns that cover restricted indices.\nImplicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false.\nIf restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of allow_restricted_indices.", + "description": "This needs to be set to `true` (default is `false`) if using wildcards or regexps for patterns that cover restricted indices.\nImplicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false.\nIf restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of `allow_restricted_indices`.", "name": "allow_restricted_indices", "required": false, "type": { @@ -199786,7 +199833,7 @@ } } ], - "specLocation": "security/has_privileges/types.ts#L33-L44" + "specLocation": "security/has_privileges/types.ts#L34-L45" }, { "kind": "type_alias", @@ -199794,7 +199841,7 @@ "name": "Privileges", "namespace": "security.has_privileges" }, - "specLocation": "security/has_privileges/types.ts#L48-L48", + "specLocation": "security/has_privileges/types.ts#L49-L49", "type": { "kind": "dictionary_of", "key": { @@ -199867,7 +199914,7 @@ } ] }, - "description": "Check user privileges.\n\nDetermine whether the specified user has a specified list of privileges.", + "description": "Check user privileges.\n\nDetermine whether the specified user has a specified list of privileges.\nAll users can use this API, but only to determine their own privileges.\nTo check the privileges of other users, you must use the run as feature.", "inherits": { "type": { "name": "RequestBase", @@ -199893,7 +199940,7 @@ } ], "query": [], - "specLocation": "security/has_privileges/SecurityHasPrivilegesRequest.ts#L25-L47" + "specLocation": "security/has_privileges/SecurityHasPrivilegesRequest.ts#L25-L49" }, { "kind": "type_alias", @@ -199901,7 +199948,7 @@ "name": "ResourcePrivileges", "namespace": "security.has_privileges" }, - "specLocation": "security/has_privileges/types.ts#L47-L47", + "specLocation": "security/has_privileges/types.ts#L48-L48", "type": { "kind": "dictionary_of", "key": { @@ -200009,7 +200056,7 @@ "name": "Response", "namespace": "security.has_privileges" }, - "specLocation": "security/has_privileges/SecurityHasPrivilegesResponse.ts#L24-L32" + "specLocation": "security/has_privileges/SecurityHasPrivilegesResponse.ts#L24-L35" }, { "kind": "interface", @@ -200246,7 +200293,7 @@ } }, { - "description": "Can be used to query API keys owned by the currently authenticated user.\nThe `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones.", + "description": "Query API keys owned by the currently authenticated user.\nThe `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones.\n\nNOTE: At least one of `ids`, `name`, `username`, and `realm_name` must be specified if `owner` is `false`.", "name": "owner", "required": false, "serverDefault": false, @@ -200271,7 +200318,7 @@ } }, { - "description": "The username of a user.\nThis parameter cannot be used with either `ids` or `name`, or when `owner` flag is set to `true`.", + "description": "The username of a user.\nThis parameter cannot be used with either `ids` or `name` or when `owner` flag is set to `true`.", "name": "username", "required": false, "type": { @@ -200284,7 +200331,7 @@ } ] }, - "description": "Invalidate API keys.\n\nThis API invalidates API keys created by the create API key or grant API key APIs.\nInvalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.\nThe `manage_api_key` privilege allows deleting any API keys.\nThe `manage_own_api_key` only allows deleting API keys that are owned by the user.\nIn addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:\n- Set the parameter `owner=true`.\n- Or, set both `username` and `realm_name` to match the user’s identity.\n- Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.", + "description": "Invalidate API keys.\n\nThis API invalidates API keys created by the create API key or grant API key APIs.\nInvalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.\n\nTo use this API, you must have at least the `manage_security`, `manage_api_key`, or `manage_own_api_key` cluster privileges.\nThe `manage_security` privilege allows deleting any API key, including both REST and cross cluster API keys.\nThe `manage_api_key` privilege allows deleting any REST API key, but not cross cluster API keys.\nThe `manage_own_api_key` only allows deleting REST API keys that are owned by the user.\nIn addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats:\n\n- Set the parameter `owner=true`.\n- Or, set both `username` and `realm_name` to match the user's identity.\n- Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field.", "inherits": { "type": { "name": "RequestBase", @@ -200297,7 +200344,7 @@ }, "path": [], "query": [], - "specLocation": "security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts#L23-L70" + "specLocation": "security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts#L23-L76" }, { "kind": "response", @@ -200305,6 +200352,7 @@ "kind": "properties", "properties": [ { + "description": "The number of errors that were encountered when invalidating the API keys.", "name": "error_count", "required": true, "type": { @@ -200316,6 +200364,7 @@ } }, { + "description": "Details about the errors.\nThis field is not present in the response when `error_count` is `0`.", "name": "error_details", "required": false, "type": { @@ -200330,6 +200379,7 @@ } }, { + "description": "The IDs of the API keys that were invalidated as part of this request.", "name": "invalidated_api_keys", "required": true, "type": { @@ -200344,6 +200394,7 @@ } }, { + "description": "The IDs of the API keys that were already invalidated.", "name": "previously_invalidated_api_keys", "required": true, "type": { @@ -200363,7 +200414,7 @@ "name": "Response", "namespace": "security.invalidate_api_key" }, - "specLocation": "security/invalidate_api_key/SecurityInvalidateApiKeyResponse.ts#L23-L30" + "specLocation": "security/invalidate_api_key/SecurityInvalidateApiKeyResponse.ts#L23-L46" }, { "kind": "request", @@ -200374,6 +200425,7 @@ "kind": "properties", "properties": [ { + "description": "An access token.\nThis parameter cannot be used if any of `refresh_token`, `realm_name`, or `username` are used.", "name": "token", "required": false, "type": { @@ -200385,6 +200437,7 @@ } }, { + "description": "A refresh token.\nThis parameter cannot be used if any of `refresh_token`, `realm_name`, or `username` are used.", "name": "refresh_token", "required": false, "type": { @@ -200396,6 +200449,7 @@ } }, { + "description": "The name of an authentication realm.\nThis parameter cannot be used with either `refresh_token` or `token`.", "name": "realm_name", "required": false, "type": { @@ -200407,6 +200461,7 @@ } }, { + "description": "The username of a user.\nThis parameter cannot be used with either `refresh_token` or `token`.", "name": "username", "required": false, "type": { @@ -200419,7 +200474,7 @@ } ] }, - "description": "Invalidate a token.\n\nThe access tokens returned by the get token API have a finite period of time for which they are valid.\nAfter that time period, they can no longer be used.\nThe time period is defined by the `xpack.security.authc.token.timeout` setting.\n\nThe refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once.\nIf you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.", + "description": "Invalidate a token.\n\nThe access tokens returned by the get token API have a finite period of time for which they are valid.\nAfter that time period, they can no longer be used.\nThe time period is defined by the `xpack.security.authc.token.timeout` setting.\n\nThe refresh tokens returned by the get token API are only valid for 24 hours.\nThey can also be used exactly once.\nIf you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.\n\nNOTE: While all parameters are optional, at least one of them is required.\nMore specifically, either one of `token` or `refresh_token` parameters is required.\nIf none of these two are specified, then `realm_name` and/or `username` need to be specified.", "inherits": { "type": { "name": "RequestBase", @@ -200432,7 +200487,7 @@ }, "path": [], "query": [], - "specLocation": "security/invalidate_token/SecurityInvalidateTokenRequest.ts#L23-L44" + "specLocation": "security/invalidate_token/SecurityInvalidateTokenRequest.ts#L23-L65" }, { "kind": "response", @@ -200440,6 +200495,7 @@ "kind": "properties", "properties": [ { + "description": "The number of errors that were encountered when invalidating the tokens.", "name": "error_count", "required": true, "type": { @@ -200451,6 +200507,7 @@ } }, { + "description": "Details about the errors.\nThis field is not present in the response when `error_count` is `0`.", "name": "error_details", "required": false, "type": { @@ -200465,6 +200522,7 @@ } }, { + "description": "The number of the tokens that were invalidated as part of this request.", "name": "invalidated_tokens", "required": true, "type": { @@ -200476,6 +200534,7 @@ } }, { + "description": "The number of tokens that were already invalidated.", "name": "previously_invalidated_tokens", "required": true, "type": { @@ -200492,7 +200551,7 @@ "name": "Response", "namespace": "security.invalidate_token" }, - "specLocation": "security/invalidate_token/SecurityInvalidateTokenResponse.ts#L23-L30" + "specLocation": "security/invalidate_token/SecurityInvalidateTokenResponse.ts#L23-L46" }, { "kind": "request", @@ -200552,7 +200611,7 @@ } ] }, - "description": "Authenticate OpenID Connect.\nExchange an OpenID Connect authentication response message for an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", + "description": "Authenticate OpenID Connect.\n\nExchange an OpenID Connect authentication response message for an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", "inherits": { "type": { "name": "RequestBase", @@ -200565,7 +200624,7 @@ }, "path": [], "query": [], - "specLocation": "security/oidc_authenticate/Request.ts#L22-L54" + "specLocation": "security/oidc_authenticate/Request.ts#L22-L55" }, { "kind": "response", @@ -200662,7 +200721,7 @@ } ] }, - "description": "Logout of OpenID Connect.\nInvalidate an access token and a refresh token that were generated as a response to the `/_security/oidc/authenticate` API.\n\nIf the OpenID Connect authentication realm in Elasticsearch is accordingly configured, the response to this call will contain a URI pointing to the end session endpoint of the OpenID Connect Provider in order to perform single logout.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", + "description": "Logout of OpenID Connect.\n\nInvalidate an access token and a refresh token that were generated as a response to the `/_security/oidc/authenticate` API.\n\nIf the OpenID Connect authentication realm in Elasticsearch is accordingly configured, the response to this call will contain a URI pointing to the end session endpoint of the OpenID Connect Provider in order to perform single logout.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", "inherits": { "type": { "name": "RequestBase", @@ -200675,7 +200734,7 @@ }, "path": [], "query": [], - "specLocation": "security/oidc_logout/Request.ts#L22-L45" + "specLocation": "security/oidc_logout/Request.ts#L22-L46" }, { "kind": "response", @@ -200772,7 +200831,7 @@ } ] }, - "description": "Prepare OpenID connect authentication.\nCreate an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch.\n\nThe response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", + "description": "Prepare OpenID connect authentication.\n\nCreate an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch.\n\nThe response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process.\n\nElasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs.\nThese APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.", "inherits": { "type": { "name": "RequestBase", @@ -200785,7 +200844,7 @@ }, "path": [], "query": [], - "specLocation": "security/oidc_prepare_authentication/Request.ts#L22-L64" + "specLocation": "security/oidc_prepare_authentication/Request.ts#L22-L65" }, { "kind": "response", @@ -200940,7 +200999,7 @@ } } }, - "description": "Create or update application privileges.", + "description": "Create or update application privileges.\n\nTo use this API, you must have one of the following privileges:\n\n* The `manage_security` cluster privilege (or a greater privilege such as `all`).\n* The \"Manage Application Privileges\" global privilege for the application being referenced in the request.\n\nApplication names are formed from a prefix, with an optional suffix that conform to the following rules:\n\n* The prefix must begin with a lowercase ASCII letter.\n* The prefix must contain only ASCII letters or digits.\n* The prefix must be at least 3 characters long.\n* If the suffix exists, it must begin with either a dash `-` or `_`.\n* The suffix cannot contain any of the following characters: `\\`, `/`, `*`, `?`, `\"`, `<`, `>`, `|`, `,`, `*`.\n* No part of the name can contain whitespace.\n\nPrivilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters `_`, `-`, and `.`.\n\nAction names can contain any number of printable ASCII characters and must contain at least one of the following characters: `/`, `*`, `:`.", "inherits": { "type": { "name": "RequestBase", @@ -200966,7 +201025,7 @@ } } ], - "specLocation": "security/put_privileges/SecurityPutPrivilegesRequest.ts#L25-L40" + "specLocation": "security/put_privileges/SecurityPutPrivilegesRequest.ts#L25-L61" }, { "kind": "response", @@ -201006,7 +201065,7 @@ "name": "Response", "namespace": "security.put_privileges" }, - "specLocation": "security/put_privileges/SecurityPutPrivilegesResponse.ts#L23-L26" + "specLocation": "security/put_privileges/SecurityPutPrivilegesResponse.ts#L23-L28" }, { "kind": "request", @@ -201089,7 +201148,7 @@ "since": "8.14.0" } }, - "description": "A list of remote indices permissions entries.", + "description": "A list of remote indices permissions entries.\n\nNOTE: Remote indices are effective for remote clusters configured with the API key based model.\nThey have no effect for remote clusters configured with the certificate based model.", "name": "remote_indices", "required": false, "type": { @@ -201137,8 +201196,8 @@ }, { "description": "A list of users that the owners of this role 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.", - "docId": "run-as-privilege", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/run-as-privilege.html", + "extDocId": "run-as-privilege", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/run-as-privilege.html", "name": "run_as", "required": false, "type": { @@ -201224,7 +201283,7 @@ } } ], - "specLocation": "security/put_role/SecurityPutRoleRequest.ts#L32-L103" + "specLocation": "security/put_role/SecurityPutRoleRequest.ts#L32-L106" }, { "kind": "response", @@ -201232,6 +201291,7 @@ "kind": "properties", "properties": [ { + "description": "When an existing role is updated, `created` is set to `false`.", "name": "role", "required": true, "type": { @@ -201248,7 +201308,7 @@ "name": "Response", "namespace": "security.put_role" }, - "specLocation": "security/put_role/SecurityPutRoleResponse.ts#L22-L24" + "specLocation": "security/put_role/SecurityPutRoleResponse.ts#L22-L29" }, { "kind": "request", @@ -201259,6 +201319,7 @@ "kind": "properties", "properties": [ { + "description": "Mappings that have `enabled` set to `false` are ignored when role mapping is performed.", "name": "enabled", "required": false, "type": { @@ -201270,6 +201331,7 @@ } }, { + "description": "Additional metadata that helps define which roles are assigned to each user.\nWithin the metadata object, keys beginning with `_` are reserved for system usage.", "name": "metadata", "required": false, "type": { @@ -201281,6 +201343,7 @@ } }, { + "description": "A list of role names that are granted to the users that match the role mapping rules.\nExactly one of `roles` or `role_templates` must be specified.", "name": "roles", "required": false, "type": { @@ -201295,6 +201358,7 @@ } }, { + "description": "A list of Mustache templates that will be evaluated to determine the roles names that should granted to the users that match the role mapping rules.\nExactly one of `roles` or `role_templates` must be specified.", "name": "role_templates", "required": false, "type": { @@ -201309,6 +201373,7 @@ } }, { + "description": "The rules that determine which users should be matched by the mapping.\nA rule is a logical condition that is expressed by using a JSON DSL.", "name": "rules", "required": false, "type": { @@ -201335,7 +201400,7 @@ } ] }, - "description": "Create or update role mappings.\n\nRole mappings define which roles are assigned to each user.\nEach mapping has rules that identify users and a list of roles that are granted to those users.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.\n\nThis API does not create roles. Rather, it maps users to existing roles.\nRoles can be created by using the create or update roles API or roles files.", + "description": "Create or update role mappings.\n\nRole mappings define which roles are assigned to each user.\nEach mapping has rules that identify users and a list of roles that are granted to those users.\nThe role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.\n\nNOTE: This API does not create roles. Rather, it maps users to existing roles.\nRoles can be created by using the create or update roles API or roles files.\n\n**Role templates**\n\nThe most common use for role mappings is to create a mapping from a known value on the user to a fixed role name.\nFor example, all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the superuser role in Elasticsearch.\nThe `roles` field is used for this purpose.\n\nFor more complex needs, it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user.\nThe `role_templates` field is used for this purpose.\n\nNOTE: To use role templates successfully, the relevant scripting feature must be enabled.\nOtherwise, all attempts to create a role mapping with role templates fail.\n\nAll of the user fields that are available in the role mapping rules are also available in the role templates.\nThus it is possible to assign a user to a role that reflects their username, their groups, or the name of the realm to which they authenticated.\n\nBy default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user.\nIf the format of the template is set to \"json\" then the template is expected to produce a JSON string or an array of JSON strings for the role names.", "inherits": { "type": { "name": "RequestBase", @@ -201348,7 +201413,7 @@ }, "path": [ { - "description": "Role-mapping name", + "description": "The distinct name that identifies the role mapping.\nThe name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way.", "name": "name", "required": true, "type": { @@ -201374,7 +201439,7 @@ } } ], - "specLocation": "security/put_role_mapping/SecurityPutRoleMappingRequest.ts#L25-L58" + "specLocation": "security/put_role_mapping/SecurityPutRoleMappingRequest.ts#L25-L97" }, { "kind": "response", @@ -201431,6 +201496,7 @@ } }, { + "description": "The email of the user.", "name": "email", "required": false, "type": { @@ -201454,6 +201520,7 @@ } }, { + "description": "The full name of the user.", "name": "full_name", "required": false, "type": { @@ -201477,6 +201544,7 @@ } }, { + "description": "Arbitrary metadata that you want to associate with the user.", "name": "metadata", "required": false, "type": { @@ -201488,6 +201556,7 @@ } }, { + "description": "The user's password.\nPasswords must be at least 6 characters long.\nWhen adding a user, one of `password` or `password_hash` is required.\nWhen updating an existing user, the password is optional, so that other fields on the user (such as their roles) may be updated without modifying the user's password", "name": "password", "required": false, "type": { @@ -201499,6 +201568,9 @@ } }, { + "description": "A hash of the user's password.\nThis must be produced using the same hashing algorithm as has been configured for password storage.\nFor more details, see the explanation of the `xpack.security.authc.password_hashing.algorithm` setting in the user cache and password hash algorithm documentation.\nUsing this parameter allows the client to pre-hash the password for performance and/or confidentiality reasons.\nThe `password` parameter and the `password_hash` parameter cannot be used in the same request.", + "extDocId": "security-settings-hashing", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-settings.html#hashing-settings", "name": "password_hash", "required": false, "type": { @@ -201510,6 +201582,7 @@ } }, { + "description": "A set of roles the user has.\nThe roles determine the user's access permissions.\nTo create a user without any roles, specify an empty list (`[]`).", "name": "roles", "required": false, "type": { @@ -201524,8 +201597,10 @@ } }, { + "description": "Specifies whether the user is enabled.", "name": "enabled", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -201536,7 +201611,7 @@ } ] }, - "description": "Create or update users.\n\nA password is required for adding a new user but is optional when updating an existing user.\nTo change a user’s password without updating any other fields, use the change password API.", + "description": "Create or update users.\n\nAdd and update users in the native realm.\nA password is required for adding a new user but is optional when updating an existing user.\nTo change a user's password without updating any other fields, use the change password API.", "inherits": { "type": { "name": "RequestBase", @@ -201549,7 +201624,7 @@ }, "path": [ { - "description": "The username of the User", + "description": "An identifier for the user.\n\nNOTE: Usernames must be at least 1 and no more than 507 characters.\nThey can contain alphanumeric characters (a-z, A-Z, 0-9), spaces, punctuation, and printable symbols in the Basic Latin (ASCII) block.\nLeading or trailing whitespace is not allowed.", "name": "username", "required": true, "type": { @@ -201563,9 +201638,10 @@ ], "query": [ { - "description": "If `true` (the default) then refresh 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` then do nothing with refreshes.", + "description": "Valid values are `true`, `false`, and `wait_for`.\nThese values have the same meaning as in the index API, but the default value for this API is true.", "name": "refresh", "required": false, + "serverDefault": "true", "type": { "kind": "instance_of", "type": { @@ -201575,7 +201651,7 @@ } } ], - "specLocation": "security/put_user/SecurityPutUserRequest.ts#L23-L50" + "specLocation": "security/put_user/SecurityPutUserRequest.ts#L23-L95" }, { "kind": "response", @@ -201583,6 +201659,7 @@ "kind": "properties", "properties": [ { + "description": "A successful call returns a JSON structure that shows whether the user has been created or updated.\nWhen an existing user is updated, `created` is set to `false`.", "name": "created", "required": true, "type": { @@ -201599,7 +201676,7 @@ "name": "Response", "namespace": "security.put_user" }, - "specLocation": "security/put_user/SecurityPutUserResponse.ts#L20-L22" + "specLocation": "security/put_user/SecurityPutUserResponse.ts#L20-L28" }, { "kind": "type_alias", @@ -201966,7 +202043,7 @@ }, "properties": [ { - "description": "matches documents matching boolean combinations of other queries.", + "description": "Matches documents matching boolean combinations of other queries.", "docId": "query-dsl-bool-query", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/query-dsl-bool-query.html", "name": "bool", @@ -202216,7 +202293,7 @@ } }, { - "description": "A query to filter which API keys to return.\nIf the query parameter is missing, it is equivalent to a `match_all` query.\nThe query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,\n`ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.\nYou can query the following public information associated with an API key: `id`, `type`, `name`,\n`creation`, `expiration`, `invalidated`, `invalidation`, `username`, `realm`, and `metadata`.", + "description": "A query to filter which API keys to return.\nIf the query parameter is missing, it is equivalent to a `match_all` query.\nThe query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,\n`ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.\nYou can query the following public information associated with an API key: `id`, `type`, `name`,\n`creation`, `expiration`, `invalidated`, `invalidation`, `username`, `realm`, and `metadata`.\n\nNOTE: The queryable string values associated with API keys are internally mapped as keywords.\nConsequently, if no `analyzer` parameter is specified for a `match` query, then the provided match query string is interpreted as a single keyword value.\nSuch a match query is hence equivalent to a `term` query.", "name": "query", "required": false, "type": { @@ -202228,7 +202305,7 @@ } }, { - "description": "Starting document offset.\nBy default, you cannot page through more than 10,000 hits using the from and size parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "from", "required": false, "serverDefault": 0, @@ -202241,9 +202318,9 @@ } }, { - "description": "Other than `id`, all public fields of an API key are eligible for sorting.\nIn addition, sort can also be applied to the `_doc` field to sort by index order.", - "docId": "sort-search-results", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", + "description": "The sort definition.\nOther than `id`, all public fields of an API key are eligible for sorting.\nIn addition, sort can also be applied to the `_doc` field to sort by index order.", + "extDocId": "sort-search-results", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", "name": "sort", "required": false, "type": { @@ -202255,7 +202332,7 @@ } }, { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nIt must not be negative.\nThe `size` parameter can be set to `0`, in which case no API key matches are returned, only the aggregation results.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "size", "required": false, "serverDefault": 10, @@ -202268,7 +202345,9 @@ } }, { - "description": "Search after definition", + "description": "The search after definition.", + "extDocId": "search-after", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after", "name": "search_after", "required": false, "type": { @@ -202281,7 +202360,7 @@ } ] }, - "description": "Find API keys with a query.\n\nGet a paginated list of API keys and their information. You can optionally filter the results with a query.", + "description": "Find API keys with a query.\n\nGet a paginated list of API keys and their information.\nYou can optionally filter the results with a query.\n\nTo use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges.\nIf you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own.\nIf you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership.", "inherits": { "type": { "name": "RequestBase", @@ -202301,7 +202380,7 @@ "since": "8.5.0" } }, - "description": "Return the snapshot of the owner user's role descriptors associated with the API key.\nAn API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors.", + "description": "Return the snapshot of the owner user's role descriptors associated with the API key.\nAn API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors (effectively limited by it).\nAn API key cannot retrieve any API key’s limited-by role descriptors (including itself) unless it has `manage_api_key` or higher privileges.", "name": "with_limited_by", "required": false, "type": { @@ -202319,7 +202398,7 @@ "since": "8.14.0" } }, - "description": "Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists.", + "description": "Determines whether to also retrieve the profile UID for the API key owner principal.\nIf it exists, the profile UID is returned under the `profile_uid` response field for each API key.", "name": "with_profile_uid", "required": false, "serverDefault": false, @@ -202351,7 +202430,7 @@ } } ], - "specLocation": "security/query_api_keys/QueryApiKeysRequest.ts#L26-L102" + "specLocation": "security/query_api_keys/QueryApiKeysRequest.ts#L26-L118" }, { "kind": "response", @@ -202476,7 +202555,7 @@ "kind": "properties", "properties": [ { - "description": "A query to filter which roles to return.\nIf the query parameter is missing, it is equivalent to a `match_all` query.\nThe query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,\n`ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.\nYou can query the following information associated with roles: `name`, `description`, `metadata`,\n`applications.application`, `applications.privileges`, `applications.resources`.", + "description": "A query to filter which roles to return.\nIf the query parameter is missing, it is equivalent to a `match_all` query.\nThe query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,\n`ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.\nYou can query the following information associated with roles: `name`, `description`, `metadata`,\n`applications.application`, `applications.privileges`, and `applications.resources`.", "name": "query", "required": false, "type": { @@ -202488,7 +202567,7 @@ } }, { - "description": "Starting document offset.\nBy default, you cannot page through more than 10,000 hits using the from and size parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "from", "required": false, "serverDefault": 0, @@ -202501,7 +202580,7 @@ } }, { - "description": "All public fields of a role are eligible for sorting.\nIn addition, sort can also be applied to the `_doc` field to sort by index order.", + "description": "The sort definition.\nYou can sort on `username`, `roles`, or `enabled`.\nIn addition, sort can also be applied to the `_doc` field to sort by index order.", "docId": "sort-search-results", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", "name": "sort", @@ -202515,7 +202594,7 @@ } }, { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "size", "required": false, "serverDefault": 10, @@ -202528,7 +202607,9 @@ } }, { - "description": "Search after definition", + "description": "The search after definition.", + "extDocId": "search-after", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after", "name": "search_after", "required": false, "type": { @@ -202541,7 +202622,7 @@ } ] }, - "description": "Find roles with a query.\n\nGet roles in a paginated manner. You can optionally filter the results with a query.", + "description": "Find roles with a query.\n\nGet roles in a paginated manner.\nThe role management APIs are generally the preferred way to manage roles, rather than using file-based role management.\nThe query roles API does not retrieve roles that are defined in roles files, nor built-in ones.\nYou can optionally filter the results with a query.\nAlso, the results can be paginated and sorted.", "inherits": { "type": { "name": "RequestBase", @@ -202554,7 +202635,7 @@ }, "path": [], "query": [], - "specLocation": "security/query_role/QueryRolesRequest.ts#L25-L70" + "specLocation": "security/query_role/QueryRolesRequest.ts#L25-L79" }, { "kind": "response", @@ -202586,7 +202667,7 @@ } }, { - "description": "The list of roles.", + "description": "A list of roles that match the query.\nThe returned role format is an extension of the role definition format.\nIt adds the `transient_metadata.enabled` and the `_sort` fields.\n`transient_metadata.enabled` is set to `false` in case the role is automatically disabled, for example when the role grants privileges that are not allowed by the installed license.\n`_sort` is present when the search query sorts on some field.\nIt contains the array of values that have been used for sorting.", "name": "roles", "required": true, "type": { @@ -202606,7 +202687,7 @@ "name": "Response", "namespace": "security.query_role" }, - "specLocation": "security/query_role/QueryRolesResponse.ts#L23-L38" + "specLocation": "security/query_role/QueryRolesResponse.ts#L23-L43" }, { "kind": "interface", @@ -202867,7 +202948,7 @@ "kind": "properties", "properties": [ { - "description": "A query to filter which users to return.\nIf the query parameter is missing, it is equivalent to a `match_all` query.\nThe query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,\n`ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.\nYou can query the following information associated with user: `username`, `roles`, `enabled`", + "description": "A query to filter which users to return.\nIf the query parameter is missing, it is equivalent to a `match_all` query.\nThe query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,\n`ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.\nYou can query the following information associated with user: `username`, `roles`, `enabled`, `full_name`, and `email`.", "name": "query", "required": false, "type": { @@ -202879,7 +202960,7 @@ } }, { - "description": "Starting document offset.\nBy default, you cannot page through more than 10,000 hits using the from and size parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The starting document offset.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "from", "required": false, "serverDefault": 0, @@ -202892,9 +202973,9 @@ } }, { - "description": "Fields eligible for sorting are: username, roles, enabled\nIn addition, sort can also be applied to the `_doc` field to sort by index order.", - "docId": "sort-search-results", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", + "description": "The sort definition.\nFields eligible for sorting are: `username`, `roles`, `enabled`.\nIn addition, sort can also be applied to the `_doc` field to sort by index order.", + "extDocId": "sort-search-results", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html", "name": "sort", "required": false, "type": { @@ -202906,7 +202987,7 @@ } }, { - "description": "The number of hits to return.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", + "description": "The number of hits to return.\nIt must not be negative.\nBy default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.\nTo page through more hits, use the `search_after` parameter.", "name": "size", "required": false, "serverDefault": 10, @@ -202919,7 +203000,9 @@ } }, { - "description": "Search after definition", + "description": "The search after definition", + "extDocId": "search-after", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html#search-after", "name": "search_after", "required": false, "type": { @@ -202932,7 +203015,7 @@ } ] }, - "description": "Find users with a query.\n\nGet information for users in a paginated manner.\nYou can optionally filter the results with a query.", + "description": "Find users with a query.\n\nGet information for users in a paginated manner.\nYou can optionally filter the results with a query.\n\nNOTE: As opposed to the get user API, built-in users are excluded from the result.\nThis API is only for native users.", "inherits": { "type": { "name": "RequestBase", @@ -202946,9 +203029,10 @@ "path": [], "query": [ { - "description": "If true will return the User Profile ID for the users in the query result, if any.", + "description": "Determines whether to retrieve the user profile UID, if it exists, for the users.", "name": "with_profile_uid", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -202958,7 +203042,7 @@ } } ], - "specLocation": "security/query_user/SecurityQueryUserRequest.ts#L25-L76" + "specLocation": "security/query_user/SecurityQueryUserRequest.ts#L25-L85" }, { "kind": "response", @@ -202990,7 +203074,7 @@ } }, { - "description": "A list of user information.", + "description": "A list of users that match the query.", "name": "users", "required": true, "type": { @@ -204081,9 +204165,7 @@ "kind": "properties", "properties": [ { - "description": "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.", - "docId": "security-api-put-role", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-put-role.html", + "description": "The role descriptors to assign to this API key.\nThe API key's effective permissions are an intersection of its assigned privileges and the point in time snapshot of permissions of the owner user.\nYou can assign new privileges by specifying them in this parameter.\nTo remove assigned privileges, you can supply an empty `role_descriptors` parameter, that is to say, an empty object `{}`.\nIf an API key has no assigned privileges, it inherits the owner user's full permissions.\nThe snapshot of the owner's permissions is always updated, whether you supply the `role_descriptors` parameter or not.\nThe structure of a role descriptor is the same as the request for the create API keys API.", "name": "role_descriptors", "required": false, "type": { @@ -204106,7 +204188,7 @@ } }, { - "description": "Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with _ are reserved for system usage.", + "description": "Arbitrary metadata that you want to associate with the API key.\nIt supports a nested data structure.\nWithin the metadata object, keys beginning with `_` are reserved for system usage.\nWhen specified, this value fully replaces the metadata previously associated with the API key.", "name": "metadata", "required": false, "type": { @@ -204118,7 +204200,7 @@ } }, { - "description": "Expiration time for the API key.", + "description": "The expiration time for the API key.\nBy default, API keys never expire.\nThis property can be omitted to leave the expiration unchanged.", "name": "expiration", "required": false, "type": { @@ -204131,7 +204213,7 @@ } ] }, - "description": "Update an API key.\n\nUpdates attributes of an existing API key.\nUsers can only update API keys that they created or that were granted to them.\nUse this API to update API keys created by the create API Key or grant API Key APIs.\nIf you need to apply the same update to many API keys, you can use bulk update API Keys to reduce overhead.\nIt’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key.\nThis API supports updates to an API key’s access scope and metadata.\nThe access scope of an API key is derived from the `role_descriptors` you specify in the request, and a snapshot of the owner user’s permissions at the time of the request.\nThe snapshot of the owner’s permissions is updated automatically on every call.\nIf you don’t specify `role_descriptors` in the request, a call to this API might still change the API key’s access scope.\nThis change can occur if the owner user’s permissions have changed since the API key was created or last modified.\nTo update another user’s API key, use the `run_as` feature to submit a request on behalf of another user.\nIMPORTANT: It’s not possible to use an API key as the authentication credential for this API.\nTo update an API key, the owner user’s credentials are required.", + "description": "Update an API key.\n\nUpdate attributes of an existing API key.\nThis API supports updates to an API key's access scope, expiration, and metadata.\n\nTo use this API, you must have at least the `manage_own_api_key` cluster privilege.\nUsers can only update API keys that they created or that were granted to them.\nTo update another user’s API key, use the `run_as` feature to submit a request on behalf of another user.\n\nIMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required.\n\nUse this API to update API keys created by the create API key or grant API Key APIs.\nIf you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead.\nIt's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API.\n\nThe access scope of an API key is derived from the `role_descriptors` you specify in the request and a snapshot of the owner user's permissions at the time of the request.\nThe snapshot of the owner's permissions is updated automatically on every call.\n\nIMPORTANT: If you don't specify `role_descriptors` in the request, a call to this API might still change the API key's access scope.\nThis change can occur if the owner user's permissions have changed since the API key was created or last modified.", "inherits": { "type": { "name": "RequestBase", @@ -204157,7 +204239,7 @@ } ], "query": [], - "specLocation": "security/update_api_key/Request.ts#L26-L68" + "specLocation": "security/update_api_key/Request.ts#L26-L85" }, { "kind": "response", @@ -204165,7 +204247,7 @@ "kind": "properties", "properties": [ { - "description": "If `true`, the API key was updated.\nIf `false`, the API key didn’t change because no change was detected.", + "description": "If `true`, the API key was updated.\nIf `false`, the API key didn't change because no change was detected.", "name": "updated", "required": true, "type": { @@ -204329,7 +204411,7 @@ } ] }, - "description": "Update security index settings.\n\nUpdate the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use.", + "description": "Update security index settings.\n\nUpdate the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified. This includes `index.auto_expand_replicas` and `index.number_of_replicas`.\n\nNOTE: If `index.auto_expand_replicas` is set, `index.number_of_replicas` will be ignored during updates.\n\nIf a specific index is not in use on the system and settings are provided for it, the request will be rejected.\nThis API does not yet support configuring the settings for indices before they are in use.", "inherits": { "type": { "name": "RequestBase", @@ -204367,7 +204449,7 @@ } } ], - "specLocation": "security/update_settings/SecurityUpdateSettingsRequest.ts#L24-L62" + "specLocation": "security/update_settings/SecurityUpdateSettingsRequest.ts#L24-L65" }, { "kind": "response", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index f6da90f0ef..0fd41ba498 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -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 diff --git a/specification/security/_types/Privileges.ts b/specification/security/_types/Privileges.ts index 6836f8494e..af6933b2d7 100644 --- a/specification/security/_types/Privileges.ts +++ b/specification/security/_types/Privileges.ts @@ -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 /** diff --git a/specification/security/_types/RoleDescriptor.ts b/specification/security/_types/RoleDescriptor.ts index 57ea1ac0ab..8f559bbf60 100644 --- a/specification/security/_types/RoleDescriptor.ts +++ b/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 { */ 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 { 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 } 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[] } diff --git a/specification/security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts b/specification/security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts index 6eabd081ec..33907eedb3 100644 --- a/specification/security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts +++ b/specification/security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts @@ -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 } } diff --git a/specification/security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts b/specification/security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts index 1428d0f501..d4e086f849 100644 --- a/specification/security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts +++ b/specification/security/clear_cached_realms/SecurityClearCachedRealmsRequest.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[] } } diff --git a/specification/security/clear_cached_roles/ClearCachedRolesRequest.ts b/specification/security/clear_cached_roles/ClearCachedRolesRequest.ts index 0726788063..95a98b0ca5 100644 --- a/specification/security/clear_cached_roles/ClearCachedRolesRequest.ts +++ b/specification/security/clear_cached_roles/ClearCachedRolesRequest.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 } } diff --git a/specification/security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts b/specification/security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts index b30bcd3818..b4c9bb8f9b 100644 --- a/specification/security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts +++ b/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 @@ -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 } } diff --git a/specification/security/create_api_key/SecurityCreateApiKeyRequest.ts b/specification/security/create_api_key/SecurityCreateApiKeyRequest.ts index 5c15dab953..48fba4add7 100644 --- a/specification/security/create_api_key/SecurityCreateApiKeyRequest.ts +++ b/specification/security/create_api_key/SecurityCreateApiKeyRequest.ts @@ -27,28 +27,47 @@ 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 { query_parameters: { 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 /** diff --git a/specification/security/create_service_token/CreateServiceTokenRequest.ts b/specification/security/create_service_token/CreateServiceTokenRequest.ts index c67d3ece8a..99287c01c4 100644 --- a/specification/security/create_service_token/CreateServiceTokenRequest.ts +++ b/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 @@ -33,8 +36,24 @@ import { Name, Namespace, Refresh, Service } from '@_types/common' */ 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 `//`. + */ name?: Name } query_parameters: { diff --git a/specification/security/create_service_token/CreateServiceTokenResponse.ts b/specification/security/create_service_token/CreateServiceTokenResponse.ts index 59d9cd28e6..169d2d6943 100644 --- a/specification/security/create_service_token/CreateServiceTokenResponse.ts +++ b/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 diff --git a/specification/security/create_service_token/examples/response/CreateServiceTokenRequestExample1.yaml b/specification/security/create_service_token/examples/response/CreateServiceTokenRequestExample1.yaml index 6874681d7d..4931e3f95d 100644 --- a/specification/security/create_service_token/examples/response/CreateServiceTokenRequestExample1.yaml +++ b/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" + } } diff --git a/specification/security/delegate_pki/SecurityDelegatePkiRequest.ts b/specification/security/delegate_pki/SecurityDelegatePkiRequest.ts index a0499586cf..ec413a056c 100644 --- a/specification/security/delegate_pki/SecurityDelegatePkiRequest.ts +++ b/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. diff --git a/specification/security/delete_privileges/SecurityDeletePrivilegesRequest.ts b/specification/security/delete_privileges/SecurityDeletePrivilegesRequest.ts index ad01fe7f03..9b9dc7df94 100644 --- a/specification/security/delete_privileges/SecurityDeletePrivilegesRequest.ts +++ b/specification/security/delete_privileges/SecurityDeletePrivilegesRequest.ts @@ -22,15 +22,28 @@ 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 */ 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: { diff --git a/specification/security/delete_privileges/examples/response/SecurityDeletePrivilegesResponseExample1.yaml b/specification/security/delete_privileges/examples/response/SecurityDeletePrivilegesResponseExample1.yaml index 08f616dfa3..0df3f3433d 100644 --- a/specification/security/delete_privileges/examples/response/SecurityDeletePrivilegesResponseExample1.yaml +++ b/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: |- diff --git a/specification/security/delete_role/SecurityDeleteRoleRequest.ts b/specification/security/delete_role/SecurityDeleteRoleRequest.ts index 2144e7c1dd..956262a416 100644 --- a/specification/security/delete_role/SecurityDeleteRoleRequest.ts +++ b/specification/security/delete_role/SecurityDeleteRoleRequest.ts @@ -24,6 +24,8 @@ import { Name, Refresh } from '@_types/common' * Delete roles. * * Delete roles in the native realm. + * The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. + * The delete roles API cannot remove roles that are defined in roles files. * @rest_spec_name security.delete_role * @availability stack stability=stable * @availability serverless stability=stable visibility=private @@ -32,6 +34,7 @@ import { Name, Refresh } from '@_types/common' */ export interface Request extends RequestBase { path_parts: { + /** The name of the role. */ name: Name } query_parameters: { diff --git a/specification/security/delete_role/SecurityDeleteRoleResponse.ts b/specification/security/delete_role/SecurityDeleteRoleResponse.ts index e8b1f82528..4760c0c003 100644 --- a/specification/security/delete_role/SecurityDeleteRoleResponse.ts +++ b/specification/security/delete_role/SecurityDeleteRoleResponse.ts @@ -18,5 +18,11 @@ */ export class Response { - body: { found: boolean } + body: { + /** + * If the role is successfully deleted, `found` is `true`. + * Otherwise, `found` is `false`. + */ + found: boolean + } } diff --git a/specification/security/delete_role/examples/response/SecurityDeleteRoleResponseExample1.yaml b/specification/security/delete_role/examples/response/SecurityDeleteRoleResponseExample1.yaml index d9a6ecdd9c..2fec9e3f06 100644 --- a/specification/security/delete_role/examples/response/SecurityDeleteRoleResponseExample1.yaml +++ b/specification/security/delete_role/examples/response/SecurityDeleteRoleResponseExample1.yaml @@ -1,6 +1,7 @@ # summary: description: > A successful response from `DELETE /_security/role/my_admin_role`. + If the role is successfully deleted, `found` is set to `true`. # type: response # response_code: value: |- diff --git a/specification/security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts b/specification/security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts index 46bf8b145b..a02f1bc0fe 100644 --- a/specification/security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts +++ b/specification/security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts @@ -22,14 +22,23 @@ import { Name, Refresh } from '@_types/common' /** * Delete role mappings. + * + * Role mappings define which roles are assigned to each user. + * The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. + * The delete role mappings API cannot remove role mappings that are defined in role mapping files. * @rest_spec_name security.delete_role_mapping * @availability stack since=5.5.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_security * @doc_id security-api-delete-role-mapping + * @ext_doc_id mapping-roles */ export interface Request extends RequestBase { path_parts: { + /** + * The distinct name that identifies the role mapping. + * The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way. + */ name: Name } query_parameters: { diff --git a/specification/security/delete_role_mapping/SecurityDeleteRoleMappingResponse.ts b/specification/security/delete_role_mapping/SecurityDeleteRoleMappingResponse.ts index e8b1f82528..2e8b6bfb9c 100644 --- a/specification/security/delete_role_mapping/SecurityDeleteRoleMappingResponse.ts +++ b/specification/security/delete_role_mapping/SecurityDeleteRoleMappingResponse.ts @@ -18,5 +18,11 @@ */ export class Response { - body: { found: boolean } + body: { + /** + * If the mapping is successfully deleted, `found` is `true`. + * Otherwise, `found` is `false`. + */ + found: boolean + } } diff --git a/specification/security/delete_role_mapping/examples/response/SecurityDeleteRoleMappingResponseExample1.yaml b/specification/security/delete_role_mapping/examples/response/SecurityDeleteRoleMappingResponseExample1.yaml index db59697bff..6156aa5aee 100644 --- a/specification/security/delete_role_mapping/examples/response/SecurityDeleteRoleMappingResponseExample1.yaml +++ b/specification/security/delete_role_mapping/examples/response/SecurityDeleteRoleMappingResponseExample1.yaml @@ -1,6 +1,7 @@ # summary: description: > A successful response from `DELETE /_security/role_mapping/mapping1`. + If the mapping is successfully deleted, `found` is `true`. # type: response # response_code: value: |- diff --git a/specification/security/delete_service_token/DeleteServiceTokenRequest.ts b/specification/security/delete_service_token/DeleteServiceTokenRequest.ts index 0de93627f3..f4785a69ba 100644 --- a/specification/security/delete_service_token/DeleteServiceTokenRequest.ts +++ b/specification/security/delete_service_token/DeleteServiceTokenRequest.ts @@ -33,8 +33,17 @@ import { Name, Namespace, Refresh, 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 service name. + */ service: Service + /** + * The name of the service account token. + */ name: Name } query_parameters: { diff --git a/specification/security/delete_service_token/DeleteServiceTokenResponse.ts b/specification/security/delete_service_token/DeleteServiceTokenResponse.ts index e8b1f82528..f8bd1565fa 100644 --- a/specification/security/delete_service_token/DeleteServiceTokenResponse.ts +++ b/specification/security/delete_service_token/DeleteServiceTokenResponse.ts @@ -18,5 +18,11 @@ */ export class Response { - body: { found: boolean } + body: { + /** + * If the service account token is successfully deleted, the request returns `{"found": true}`. + * Otherwise, the response will have status code 404 and `found` is set to `false`. + */ + found: boolean + } } diff --git a/specification/security/delete_user/SecurityDeleteUserRequest.ts b/specification/security/delete_user/SecurityDeleteUserRequest.ts index 8297ccd048..27ad82125e 100644 --- a/specification/security/delete_user/SecurityDeleteUserRequest.ts +++ b/specification/security/delete_user/SecurityDeleteUserRequest.ts @@ -31,6 +31,9 @@ import { Refresh, Username } from '@_types/common' */ export interface Request extends RequestBase { path_parts: { + /** + * An identifier for the user. + */ username: Username } query_parameters: { diff --git a/specification/security/delete_user/SecurityDeleteUserResponse.ts b/specification/security/delete_user/SecurityDeleteUserResponse.ts index e8b1f82528..ab0370432c 100644 --- a/specification/security/delete_user/SecurityDeleteUserResponse.ts +++ b/specification/security/delete_user/SecurityDeleteUserResponse.ts @@ -18,5 +18,11 @@ */ export class Response { - body: { found: boolean } + body: { + /** + * If the user is successfully deleted, the request returns `{"found": true}`. + * Otherwise, `found` is set to `false`. + */ + found: boolean + } } diff --git a/specification/security/disable_user/SecurityDisableUserRequest.ts b/specification/security/disable_user/SecurityDisableUserRequest.ts index 054372d410..9d3d92f947 100644 --- a/specification/security/disable_user/SecurityDisableUserRequest.ts +++ b/specification/security/disable_user/SecurityDisableUserRequest.ts @@ -24,6 +24,8 @@ import { Refresh, Username } from '@_types/common' * Disable users. * * Disable users in the native realm. + * By default, when you create users, they are enabled. + * You can use this API to revoke a user's access to Elasticsearch. * @rest_spec_name security.disable_user * @availability stack stability=stable * @cluster_privileges manage_security @@ -31,6 +33,9 @@ import { Refresh, Username } from '@_types/common' */ export interface Request extends RequestBase { path_parts: { + /** + * An identifier for the user. + */ username: Username } query_parameters: { diff --git a/specification/security/enable_user/SecurityEnableUserRequest.ts b/specification/security/enable_user/SecurityEnableUserRequest.ts index 3abafb269b..06b673b926 100644 --- a/specification/security/enable_user/SecurityEnableUserRequest.ts +++ b/specification/security/enable_user/SecurityEnableUserRequest.ts @@ -24,6 +24,7 @@ import { Refresh, Username } from '@_types/common' * Enable users. * * Enable users in the native realm. + * By default, when you create users, they are enabled. * @rest_spec_name security.enable_user * @availability stack stability=stable * @cluster_privileges manage_security @@ -31,6 +32,9 @@ import { Refresh, Username } from '@_types/common' */ export interface Request extends RequestBase { path_parts: { + /** + * An identifier for the user. + */ username: Username } query_parameters: { diff --git a/specification/security/enroll_kibana/Request.ts b/specification/security/enroll_kibana/Request.ts index 8a370f767b..726c08fca5 100644 --- a/specification/security/enroll_kibana/Request.ts +++ b/specification/security/enroll_kibana/Request.ts @@ -23,6 +23,9 @@ import { RequestBase } from '@_types/Base' * Enroll Kibana. * * Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster. + * + * NOTE: This API is currently intended for internal use only by Kibana. + * Kibana uses this API internally to configure itself for communications with an Elasticsearch cluster that already has security features enabled. * @rest_spec_name security.enroll_kibana * @availability stack since=8.0.0 stability=stable * @doc_id security-api-kibana-enrollment diff --git a/specification/security/enroll_kibana/Response.ts b/specification/security/enroll_kibana/Response.ts index ea90ab44ef..6be2b68906 100644 --- a/specification/security/enroll_kibana/Response.ts +++ b/specification/security/enroll_kibana/Response.ts @@ -20,11 +20,22 @@ export class Response { body: { token: Token + /** + * The CA certificate used to sign the node certificates that Elasticsearch uses for TLS on the HTTP layer. + * The certificate is returned as a Base64 encoded string of the ASN.1 DER encoding of the certificate. + */ http_ca: string } } export class Token { + /** + * The name of the bearer token for the `elastic/kibana` service account. + */ name: string + /** + * The value of the bearer token for the `elastic/kibana` service account. + * Use this value to authenticate the service account with Elasticsearch. + */ value: string } diff --git a/specification/security/enroll_node/Request.ts b/specification/security/enroll_node/Request.ts index daaebbf266..1b8221dbdd 100644 --- a/specification/security/enroll_node/Request.ts +++ b/specification/security/enroll_node/Request.ts @@ -23,6 +23,9 @@ import { RequestBase } from '@_types/Base' * Enroll a node. * * Enroll a new node to allow it to join an existing cluster with security features enabled. + * + * The response contains all the necessary information for the joining node to bootstrap discovery and security related settings so that it can successfully join the cluster. + * The response contains key and certificate material that allows the caller to generate valid signed certificates for the HTTP layer of all nodes in the cluster. * @rest_spec_name security.enroll_node * @availability stack since=8.0.0 stability=stable * @doc_id security-api-node-enrollment diff --git a/specification/security/enroll_node/Response.ts b/specification/security/enroll_node/Response.ts index b81c869a0c..b9b0e86677 100644 --- a/specification/security/enroll_node/Response.ts +++ b/specification/security/enroll_node/Response.ts @@ -19,11 +19,29 @@ export class Response { body: { + /** + * The CA private key that can be used by the new node in order to sign its certificate for the HTTP layer, as a Base64 encoded string of the ASN.1 DER encoding of the key. + */ http_ca_key: string + /** + * The CA certificate that can be used by the new node in order to sign its certificate for the HTTP layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate. + */ http_ca_cert: string + /** + * The CA certificate that is used to sign the TLS certificate for the transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate. + */ transport_ca_cert: string + /** + * The private key that the node can use for TLS for its transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the key. + */ transport_key: string + /** + * The certificate that the node can use for TLS for its transport layer, as a Base64 encoded string of the ASN.1 DER encoding of the certificate. + */ transport_cert: string + /** + * A list of transport addresses in the form of `host:port` for the nodes that are already members of the cluster. + */ nodes_addresses: string[] } } diff --git a/specification/security/get_builtin_privileges/SecurityGetBuiltinPrivilegesResponse.ts b/specification/security/get_builtin_privileges/SecurityGetBuiltinPrivilegesResponse.ts index 125f035940..6995a42392 100644 --- a/specification/security/get_builtin_privileges/SecurityGetBuiltinPrivilegesResponse.ts +++ b/specification/security/get_builtin_privileges/SecurityGetBuiltinPrivilegesResponse.ts @@ -25,8 +25,18 @@ import { Indices } from '@_types/common' export class Response { body: { + /** + * The list of cluster privileges that are understood by this version of Elasticsearch. + */ cluster: ClusterPrivilege[] + /** + * The list of index privileges that are understood by this version of Elasticsearch. + */ index: Indices + /** + * The list of remote_cluster privileges that are understood by this version of Elasticsearch. + * @availability stack since=8.15.0 + */ remote_cluster: RemoteClusterPrivilege[] } } diff --git a/specification/security/get_privileges/SecurityGetPrivilegesRequest.ts b/specification/security/get_privileges/SecurityGetPrivilegesRequest.ts index 2e0267657d..2fd42b5972 100644 --- a/specification/security/get_privileges/SecurityGetPrivilegesRequest.ts +++ b/specification/security/get_privileges/SecurityGetPrivilegesRequest.ts @@ -22,6 +22,11 @@ import { Name, Names } from '@_types/common' /** * Get application privileges. + * + * To use this API, you must have one of the following privileges: + * + * * The `read_security` cluster privilege (or a greater privilege such as `manage_security` or `all`). + * * The "Manage Application Privileges" global privilege for the application being referenced in the request. * @rest_spec_name security.get_privileges * @availability stack since=6.4.0 stability=stable * @availability serverless stability=stable visibility=private @@ -31,7 +36,16 @@ import { Name, Names } from '@_types/common' */ export interface Request extends RequestBase { path_parts: { + /** + * The name of the application. + * Application privileges are always associated with exactly one application. + * If you do not specify this parameter, the API returns information about all privileges for all applications. + */ application?: Name + /** + * The name of the privilege. + * If you do not specify this parameter, the API returns information about all privileges for the requested application. + */ name?: Names } } diff --git a/specification/security/get_privileges/SecurityGetPrivilegesResponse.ts b/specification/security/get_privileges/SecurityGetPrivilegesResponse.ts index eb1370188b..47eb09eef9 100644 --- a/specification/security/get_privileges/SecurityGetPrivilegesResponse.ts +++ b/specification/security/get_privileges/SecurityGetPrivilegesResponse.ts @@ -21,6 +21,9 @@ import { Actions } from '@security/put_privileges/types' import { Dictionary } from '@spec_utils/Dictionary' export class Response { - /** @codegen_name privileges */ + /** + * A successful call returns an object keyed by application name and privilege name. + * If the privilege is not defined, the request responds with a 404 status. + * @codegen_name privileges */ body: Dictionary> } diff --git a/specification/security/get_role/SecurityGetRoleRequest.ts b/specification/security/get_role/SecurityGetRoleRequest.ts index 61d8fe12d6..4788c230ea 100644 --- a/specification/security/get_role/SecurityGetRoleRequest.ts +++ b/specification/security/get_role/SecurityGetRoleRequest.ts @@ -35,7 +35,9 @@ import { Names } from '@_types/common' export interface Request extends RequestBase { path_parts: { /** - * The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about all roles. + * The name of the role. + * You can specify multiple roles as a comma-separated list. + * If you do not specify this parameter, the API returns information about all roles. */ name?: Names } diff --git a/specification/security/get_role/SecurityGetRoleResponse.ts b/specification/security/get_role/SecurityGetRoleResponse.ts index da2520f6ce..6ba40a0c20 100644 --- a/specification/security/get_role/SecurityGetRoleResponse.ts +++ b/specification/security/get_role/SecurityGetRoleResponse.ts @@ -21,6 +21,11 @@ import { Dictionary } from '@spec_utils/Dictionary' import { Role } from './types' export class Response { - /** @codegen_name roles */ + /** + * A successful call returns an array of roles with the JSON representation of the role. + * The returned role format is a simple extension of the role definition format, only adding an extra field `transient_metadata.enabled`. + * This field is false in case the role is automatically disabled, for example when the license level does not allow some permissions that the role grants. + * If the role is not defined in the native realm, the request returns 404. + * @codegen_name roles */ body: Dictionary } diff --git a/specification/security/get_role_mapping/SecurityGetRoleMappingResponse.ts b/specification/security/get_role_mapping/SecurityGetRoleMappingResponse.ts index 628a94bc7a..2d4a273408 100644 --- a/specification/security/get_role_mapping/SecurityGetRoleMappingResponse.ts +++ b/specification/security/get_role_mapping/SecurityGetRoleMappingResponse.ts @@ -21,6 +21,9 @@ import { RoleMapping } from '@security/_types/RoleMapping' import { Dictionary } from '@spec_utils/Dictionary' export class Response { - /** @codegen_name role_mappings */ + /** + * A successful call retrieves an object, where the keys are the names of the request mappings and the values are the JSON representation of those mappings. + * If there is no mapping with the requested name, the response will have status code 404. + * @codegen_name role_mappings */ body: Dictionary } diff --git a/specification/security/get_service_accounts/GetServiceAccountsRequest.ts b/specification/security/get_service_accounts/GetServiceAccountsRequest.ts index 1f896c188d..bfb87788d4 100644 --- a/specification/security/get_service_accounts/GetServiceAccountsRequest.ts +++ b/specification/security/get_service_accounts/GetServiceAccountsRequest.ts @@ -24,6 +24,8 @@ import { Namespace, Service } from '@_types/common' * Get service accounts. * * Get a list of service accounts that match the provided path parameters. + * + * NOTE: Currently, only the `elastic/fleet-server` service account is available. * @rest_spec_name security.get_service_accounts * @availability stack since=7.13.0 stability=stable * @availability serverless stability=stable visibility=private @@ -34,11 +36,14 @@ import { Namespace, Service } from '@_types/common' export interface Request extends RequestBase { path_parts: { /** - * Name of the namespace. Omit this parameter to retrieve information about all service accounts. If you omit this parameter, you must also omit the `service` parameter. + * The name of the namespace. + * Omit this parameter to retrieve information about all service accounts. + * If you omit this parameter, you must also omit the `service` parameter. */ namespace?: Namespace /** - * Name of the service name. Omit this parameter to retrieve information about all service accounts that belong to the specified `namespace`. + * The service name. + * Omit this parameter to retrieve information about all service accounts that belong to the specified `namespace`. */ service?: Service } diff --git a/specification/security/get_service_accounts/GetServiceAccountsResponse.ts b/specification/security/get_service_accounts/GetServiceAccountsResponse.ts index 1f6adaad96..a6fd19168b 100644 --- a/specification/security/get_service_accounts/GetServiceAccountsResponse.ts +++ b/specification/security/get_service_accounts/GetServiceAccountsResponse.ts @@ -21,6 +21,9 @@ import { Dictionary } from '@spec_utils/Dictionary' import { RoleDescriptorWrapper } from './types' export class Response { - /** @codegen_name service_accoutns */ + /** + * A successful call returns a JSON object of service accounts. + * The API returns an empty object if no service account is found. + * @codegen_name service_accoutns */ body: Dictionary } diff --git a/specification/security/get_service_credentials/GetServiceCredentialsRequest.ts b/specification/security/get_service_credentials/GetServiceCredentialsRequest.ts index 53aa1da854..3552df2fc7 100644 --- a/specification/security/get_service_credentials/GetServiceCredentialsRequest.ts +++ b/specification/security/get_service_credentials/GetServiceCredentialsRequest.ts @@ -22,6 +22,13 @@ import { Name, Namespace } from '@_types/common' /** * Get service account credentials. + * + * To use this API, you must have at least the `read_security` cluster privilege (or a greater privilege such as `manage_service_account` or `manage_security`). + * + * The response includes service account tokens that were created with the create service account tokens API as well as file-backed tokens from all nodes of the cluster. + * + * NOTE: For tokens backed by the `service_tokens` file, the API collects them from all nodes of the cluster. + * Tokens with the same name from different nodes are assumed to be the same token and are only counted once towards the total number of service tokens. * @rest_spec_name security.get_service_credentials * @availability stack since=7.13.0 stability=stable * @availability serverless stability=stable visibility=private @@ -32,11 +39,11 @@ import { Name, Namespace } from '@_types/common' export interface Request extends RequestBase { path_parts: { /** - * Name of the namespace. + * The name of the namespace. */ namespace: Namespace /** - * Name of the service name. + * The service name. */ service: Name } diff --git a/specification/security/get_service_credentials/GetServiceCredentialsResponse.ts b/specification/security/get_service_credentials/GetServiceCredentialsResponse.ts index 9c7025f164..71c001f48e 100644 --- a/specification/security/get_service_credentials/GetServiceCredentialsResponse.ts +++ b/specification/security/get_service_credentials/GetServiceCredentialsResponse.ts @@ -27,7 +27,8 @@ export class Response { service_account: string count: integer tokens: Dictionary - /** Contains service account credentials collected from all nodes of the cluster */ + /** + * Service account credentials collected from all nodes of the cluster. */ nodes_credentials: NodesCredentials } } diff --git a/specification/security/get_settings/SecurityGetSettingsRequest.ts b/specification/security/get_settings/SecurityGetSettingsRequest.ts index 5259df096d..fdfdfdb285 100644 --- a/specification/security/get_settings/SecurityGetSettingsRequest.ts +++ b/specification/security/get_settings/SecurityGetSettingsRequest.ts @@ -22,7 +22,13 @@ import { Duration } from '@_types/Time' /** * Get security index settings. + * * Get the user-configurable settings for the security internal index (`.security` and associated indices). + * Only a subset of the index settings — those that are user-configurable—will be shown. + * This includes: + * + * * `index.auto_expand_replicas` + * * `index.number_of_replicas` * @rest_spec_name security.get_settings * @availability stack stability=stable visibility=public * @doc_id security-api-get-settings diff --git a/specification/security/get_token/GetUserAccessTokenRequest.ts b/specification/security/get_token/GetUserAccessTokenRequest.ts index 551e075fe0..a7cb1c642b 100644 --- a/specification/security/get_token/GetUserAccessTokenRequest.ts +++ b/specification/security/get_token/GetUserAccessTokenRequest.ts @@ -26,19 +26,59 @@ import { AccessTokenGrantType } from './types' * Get a token. * * Create a bearer token for access without requiring basic authentication. + * The tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface. + * Alternatively, you can explicitly enable the `xpack.security.authc.token.enabled` setting. + * When you are running in production mode, a bootstrap check prevents you from enabling the token service unless you also enable TLS on the HTTP interface. + * + * The get token API takes the same parameters as a typical OAuth 2.0 token API except for the use of a JSON request body. + * + * A successful get token API call returns a JSON structure that contains the access token, the amount of time (seconds) that the token expires in, the type, and the scope if available. + * + * The tokens returned by the get token API have a finite period of time for which they are valid and after that time period, they can no longer be used. + * That time period is defined by the `xpack.security.authc.token.timeout` setting. + * If you want to invalidate a token immediately, you can do so by using the invalidate token API. * @rest_spec_name security.get_token * @availability stack since=5.5.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage_token * @doc_id security-api-get-token + * @ext_doc_id security-encrypt-http */ export interface Request extends RequestBase { body: { + /** + * The type of grant. + * Supported grant types are: `password`, `_kerberos`, `client_credentials`, and `refresh_token`. + */ grant_type?: AccessTokenGrantType + /** + * The scope of the token. + * Currently tokens are only issued for a scope of FULL regardless of the value sent with the request. + */ scope?: string + /** + * The user's password. + * If you specify the `password` grant type, this parameter is required. + * This parameter is not valid with any other supported grant type. + */ password?: Password + /** + * The base64 encoded kerberos ticket. + * If you specify the `_kerberos` grant type, this parameter is required. + * This parameter is not valid with any other supported grant type. + */ kerberos_ticket?: string + /** + * The string that was returned when you created the token, which enables you to extend its life. + * If you specify the `refresh_token` grant type, this parameter is required. + * This parameter is not valid with any other supported grant type. + */ refresh_token?: string + /** + * The username that identifies the user. + * If you specify the `password` grant type, this parameter is required. + * This parameter is not valid with any other supported grant type. + */ username?: Username } } diff --git a/specification/security/get_token/types.ts b/specification/security/get_token/types.ts index a1937f1f3e..bde8117339 100644 --- a/specification/security/get_token/types.ts +++ b/specification/security/get_token/types.ts @@ -21,9 +21,29 @@ import { User } from '@security/_types/User' import { Name } from '@_types/common' export enum AccessTokenGrantType { + /** + * This grant type implements the Resource Owner Password Credentials Grant of OAuth2. + * In this grant, a trusted client exchanges the end user's credentials for an access token and (possibly) a refresh token. + * The request needs to be made by an authenticated user but happens on behalf of another authenticated user (the one whose credentials are passed as request parameters). + * This grant type is not suitable or designed for the self-service user creation of tokens. + */ password, + /** + * This grant type implements the Client Credentials Grant of OAuth2. + * It is geared for machine to machine communication and is not suitable or designed for the self-service user creation of tokens. + * It generates only access tokens that cannot be refreshed. + * The premise is that the entity that uses `client_credentials` has constant access to a set of (client, not end-user) credentials and can authenticate itself at will. + */ client_credentials, + /** + * This grant type is supported internally and implements SPNEGO based Kerberos support. + * The `_kerberos` grant type may change from version to version. + */ _kerberos, + /** + * This grant type implements the Refresh Token Grant of OAuth2. + * In this grant a user exchanges a previously issued refresh token for a new access token and a new refresh token. + */ refresh_token } diff --git a/specification/security/get_user/SecurityGetUserRequest.ts b/specification/security/get_user/SecurityGetUserRequest.ts index 0ed476eab8..2e01ccbcc2 100644 --- a/specification/security/get_user/SecurityGetUserRequest.ts +++ b/specification/security/get_user/SecurityGetUserRequest.ts @@ -36,7 +36,7 @@ export interface Request extends RequestBase { } query_parameters: { /** - * If true will return the User Profile ID for a user, if any. + * Determines whether to retrieve the user profile UID, if it exists, for the users. * @server_default false * @availability stack since=8.5.0 * @availability serverless diff --git a/specification/security/get_user/SecurityGetUserResponse.ts b/specification/security/get_user/SecurityGetUserResponse.ts index 46bdc603f9..b1e2cd4748 100644 --- a/specification/security/get_user/SecurityGetUserResponse.ts +++ b/specification/security/get_user/SecurityGetUserResponse.ts @@ -21,6 +21,10 @@ import { User } from '@security/_types/User' import { Dictionary } from '@spec_utils/Dictionary' export class Response { - /** @codegen_name users */ + /** + * A successful call returns an array of users with the JSON representation of the users. + * Note that user passwords are not included. + * If the user is not defined in the native realm, a 404 response code occurs. + * @codegen_name users */ body: Dictionary } diff --git a/specification/security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts b/specification/security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts index 4b81405970..d10cdea0ca 100644 --- a/specification/security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts +++ b/specification/security/get_user_privileges/SecurityGetUserPrivilegesRequest.ts @@ -22,6 +22,11 @@ import { Name } from '@_types/common' /** * Get user privileges. + * + * Get the security privileges for the logged in user. + * All users can use this API, but only to determine their own privileges. + * To check the privileges of other users, you must use the run as feature. + * To check whether a user has a specific list of privileges, use the has privileges API. * @rest_spec_name security.get_user_privileges * @availability stack since=6.5.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/security/grant_api_key/SecurityGrantApiKeyRequest.ts b/specification/security/grant_api_key/SecurityGrantApiKeyRequest.ts index f35a580e5d..6422862653 100644 --- a/specification/security/grant_api_key/SecurityGrantApiKeyRequest.ts +++ b/specification/security/grant_api_key/SecurityGrantApiKeyRequest.ts @@ -26,12 +26,19 @@ import { ApiKeyGrantType, GrantApiKey } from './types' * * Create an API key on behalf of another user. * This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. - * The caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created. - * It is not possible to use this API to create an API key without that user’s credentials. + * The caller must have authentication credentials for the user on whose behalf the API key will be created. + * It is not possible to use this API to create an API key without that user's credentials. + * The supported user authentication credential types are: + * + * * username and password + * * Elasticsearch access tokens + * * JWTs + * * The user, for whom the authentication credentials is provided, can optionally "run as" (impersonate) another user. * In this case, the API key will be created on behalf of the impersonated user. * * This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf. + * The API keys are created by the Elasticsearch API key service, which is automatically enabled. * * A successful grant API key API call 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. @@ -46,7 +53,7 @@ import { ApiKeyGrantType, GrantApiKey } from './types' export interface Request extends RequestBase { body: { /** - * Defines the API key. + * The API key. */ api_key: GrantApiKey /** @@ -54,7 +61,7 @@ export interface Request extends RequestBase { */ grant_type: ApiKeyGrantType /** - * The user’s access token. + * The user's access token. * If you specify the `access_token` grant type, this parameter is required. * It is not valid with other grant types. */ @@ -66,7 +73,8 @@ export interface Request extends RequestBase { */ username?: Username /** - * The user’s password. If you specify the `password` grant type, this parameter is required. + * The user's password. + * If you specify the `password` grant type, this parameter is required. * It is not valid with other grant types. */ password?: Password diff --git a/specification/security/grant_api_key/types.ts b/specification/security/grant_api_key/types.ts index 2957d81ecd..cf3fad4868 100644 --- a/specification/security/grant_api_key/types.ts +++ b/specification/security/grant_api_key/types.ts @@ -30,7 +30,6 @@ export class GrantApiKey { expiration?: DurationLarge /** * The role descriptors for this API key. - * This parameter is optional. * When it is not specified or is an empty array, the API key has a point in time snapshot of permissions of the specified user or access token. * If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the permissions of the user or access token. */ diff --git a/specification/security/has_privileges/SecurityHasPrivilegesRequest.ts b/specification/security/has_privileges/SecurityHasPrivilegesRequest.ts index 31a6963523..e64f4dfa98 100644 --- a/specification/security/has_privileges/SecurityHasPrivilegesRequest.ts +++ b/specification/security/has_privileges/SecurityHasPrivilegesRequest.ts @@ -26,6 +26,8 @@ import { ApplicationPrivilegesCheck, IndexPrivilegesCheck } from './types' * Check user privileges. * * Determine whether the specified user has a specified list of privileges. + * All users can use this API, but only to determine their own privileges. + * To check the privileges of other users, you must use the run as feature. * @rest_spec_name security.has_privileges * @availability stack since=6.4.0 stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/security/has_privileges/SecurityHasPrivilegesResponse.ts b/specification/security/has_privileges/SecurityHasPrivilegesResponse.ts index b5872fcedf..fe2ed6aa5d 100644 --- a/specification/security/has_privileges/SecurityHasPrivilegesResponse.ts +++ b/specification/security/has_privileges/SecurityHasPrivilegesResponse.ts @@ -22,6 +22,9 @@ import { IndexName, Username } from '@_types/common' import { ApplicationsPrivileges, Privileges } from './types' export class Response { + /** + * A successful call returns a JSON structure that shows whether each specified privilege is assigned to the user. + */ body: { application: ApplicationsPrivileges cluster: Dictionary diff --git a/specification/security/has_privileges/types.ts b/specification/security/has_privileges/types.ts index f14246a75d..32416dffe9 100644 --- a/specification/security/has_privileges/types.ts +++ b/specification/security/has_privileges/types.ts @@ -24,9 +24,10 @@ import { Indices, Name } from '@_types/common' export class ApplicationPrivilegesCheck { /** The name of the application. */ application: string - /** A list of the privileges that you want to check for the specified resources. May be either application privilege names, or the names of actions that are granted by those privileges */ + /** A list of the privileges that you want to check for the specified resources. + * It may be either application privilege names or the names of actions that are granted by those privileges */ privileges: string[] - /** A list of resource names against which the privileges should be checked */ + /** A list of resource names against which the privileges should be checked. */ resources: string[] } @@ -36,9 +37,9 @@ export class IndexPrivilegesCheck { /** A list of the privileges that you want to check for the specified indices. */ privileges: IndexPrivilege[] /** - * This needs to be set to true (default is false) if using wildcards or regexps for patterns that cover restricted indices. + * This needs to be set to `true` (default is `false`) if using wildcards or regexps for patterns that cover restricted indices. * Implicitly, restricted indices do not match index patterns because restricted indices usually have limited privileges and including them in pattern tests would render most such tests false. - * If restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of allow_restricted_indices. + * If restricted indices are explicitly included in the names list, privileges will be checked against them regardless of the value of `allow_restricted_indices`. */ allow_restricted_indices?: boolean } diff --git a/specification/security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts b/specification/security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts index 628b4f88b3..bf271414dc 100644 --- a/specification/security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts +++ b/specification/security/invalidate_api_key/SecurityInvalidateApiKeyRequest.ts @@ -25,11 +25,15 @@ import { Id, Name, Username } from '@_types/common' * * This API invalidates API keys created by the create API key or grant API key APIs. * Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted. - * The `manage_api_key` privilege allows deleting any API keys. - * The `manage_own_api_key` only allows deleting API keys that are owned by the user. + * + * To use this API, you must have at least the `manage_security`, `manage_api_key`, or `manage_own_api_key` cluster privileges. + * The `manage_security` privilege allows deleting any API key, including both REST and cross cluster API keys. + * The `manage_api_key` privilege allows deleting any REST API key, but not cross cluster API keys. + * The `manage_own_api_key` only allows deleting REST API keys that are owned by the user. * In addition, with the `manage_own_api_key` privilege, an invalidation request must be issued in one of the three formats: + * * - Set the parameter `owner=true`. - * - Or, set both `username` and `realm_name` to match the user’s identity. + * - Or, set both `username` and `realm_name` to match the user's identity. * - Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the `ids` field. * @rest_spec_name security.invalidate_api_key * @availability stack since=6.7.0 stability=stable @@ -51,8 +55,10 @@ export interface Request extends RequestBase { */ name?: Name /** - * Can be used to query API keys owned by the currently authenticated user. + * Query API keys owned by the currently authenticated user. * The `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones. + * + * NOTE: At least one of `ids`, `name`, `username`, and `realm_name` must be specified if `owner` is `false`. * @server_default false */ owner?: boolean @@ -63,7 +69,7 @@ export interface Request extends RequestBase { realm_name?: string /** * The username of a user. - * This parameter cannot be used with either `ids` or `name`, or when `owner` flag is set to `true`. + * This parameter cannot be used with either `ids` or `name` or when `owner` flag is set to `true`. */ username?: Username } diff --git a/specification/security/invalidate_api_key/SecurityInvalidateApiKeyResponse.ts b/specification/security/invalidate_api_key/SecurityInvalidateApiKeyResponse.ts index 93ba493245..ef3a504419 100644 --- a/specification/security/invalidate_api_key/SecurityInvalidateApiKeyResponse.ts +++ b/specification/security/invalidate_api_key/SecurityInvalidateApiKeyResponse.ts @@ -21,10 +21,26 @@ import { ErrorCause } from '@_types/Errors' import { integer } from '@_types/Numeric' export class Response { + /** + * A successful call returns a JSON structure that contains the ids of the API keys that were invalidated, the IDs of the API keys that had already been invalidated, and potentially a list of errors encountered while invalidating specific API keys. + */ body: { + /** + * The number of errors that were encountered when invalidating the API keys. + */ error_count: integer + /** + * Details about the errors. + * This field is not present in the response when `error_count` is `0`. + */ error_details?: ErrorCause[] + /** + * The IDs of the API keys that were invalidated as part of this request. + */ invalidated_api_keys: string[] + /** + * The IDs of the API keys that were already invalidated. + */ previously_invalidated_api_keys: string[] } } diff --git a/specification/security/invalidate_token/SecurityInvalidateTokenRequest.ts b/specification/security/invalidate_token/SecurityInvalidateTokenRequest.ts index c763233c4f..4ca66adefb 100644 --- a/specification/security/invalidate_token/SecurityInvalidateTokenRequest.ts +++ b/specification/security/invalidate_token/SecurityInvalidateTokenRequest.ts @@ -27,8 +27,13 @@ import { Name, Username } from '@_types/common' * After that time period, they can no longer be used. * The time period is defined by the `xpack.security.authc.token.timeout` setting. * - * The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once. + * The refresh tokens returned by the get token API are only valid for 24 hours. + * They can also be used exactly once. * If you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API. + * + * NOTE: While all parameters are optional, at least one of them is required. + * More specifically, either one of `token` or `refresh_token` parameters is required. + * If none of these two are specified, then `realm_name` and/or `username` need to be specified. * @rest_spec_name security.invalidate_token * @availability stack since=5.5.0 stability=stable * @availability serverless stability=stable visibility=private @@ -36,9 +41,25 @@ import { Name, Username } from '@_types/common' */ export interface Request extends RequestBase { body: { + /** + * An access token. + * This parameter cannot be used if any of `refresh_token`, `realm_name`, or `username` are used. + */ token?: string + /** + * A refresh token. + * This parameter cannot be used if any of `refresh_token`, `realm_name`, or `username` are used. + */ refresh_token?: string + /** + * The name of an authentication realm. + * This parameter cannot be used with either `refresh_token` or `token`. + */ realm_name?: Name + /** + * The username of a user. + * This parameter cannot be used with either `refresh_token` or `token`. + */ username?: Username } } diff --git a/specification/security/invalidate_token/SecurityInvalidateTokenResponse.ts b/specification/security/invalidate_token/SecurityInvalidateTokenResponse.ts index 9d5513fb47..d8ab308227 100644 --- a/specification/security/invalidate_token/SecurityInvalidateTokenResponse.ts +++ b/specification/security/invalidate_token/SecurityInvalidateTokenResponse.ts @@ -21,10 +21,26 @@ import { ErrorCause } from '@_types/Errors' import { long } from '@_types/Numeric' export class Response { + /** + * A successful call returns a JSON structure that contains the number of tokens that were invalidated, the number of tokens that had already been invalidated, and potentially a list of errors encountered while invalidating specific tokens. + */ body: { + /** + * The number of errors that were encountered when invalidating the tokens. + */ error_count: long + /** + * Details about the errors. + * This field is not present in the response when `error_count` is `0`. + */ error_details?: ErrorCause[] + /** + * The number of the tokens that were invalidated as part of this request. + */ invalidated_tokens: long + /** + * The number of tokens that were already invalidated. + */ previously_invalidated_tokens: long } } diff --git a/specification/security/invalidate_token/examples/request/SecurityInvalidateTokenRequestExample6.yaml b/specification/security/invalidate_token/examples/request/SecurityInvalidateTokenRequestExample6.yaml deleted file mode 100644 index ee76cbe16e..0000000000 --- a/specification/security/invalidate_token/examples/request/SecurityInvalidateTokenRequestExample6.yaml +++ /dev/null @@ -1,15 +0,0 @@ -# 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" : "jacknich@example.com", - "metadata" : { - "intelligence" : 7 - } - } diff --git a/specification/security/oidc_authenticate/Request.ts b/specification/security/oidc_authenticate/Request.ts index ca422e2402..8e1c2bd563 100644 --- a/specification/security/oidc_authenticate/Request.ts +++ b/specification/security/oidc_authenticate/Request.ts @@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base' /** * Authenticate OpenID Connect. + * * Exchange an OpenID Connect authentication response message for an Elasticsearch internal access token and refresh token that can be subsequently used for authentication. * * Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs. diff --git a/specification/security/oidc_logout/Request.ts b/specification/security/oidc_logout/Request.ts index 5a4dd3bd4a..c6f5e9cb1b 100644 --- a/specification/security/oidc_logout/Request.ts +++ b/specification/security/oidc_logout/Request.ts @@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base' /** * Logout of OpenID Connect. + * * Invalidate an access token and a refresh token that were generated as a response to the `/_security/oidc/authenticate` API. * * If the OpenID Connect authentication realm in Elasticsearch is accordingly configured, the response to this call will contain a URI pointing to the end session endpoint of the OpenID Connect Provider in order to perform single logout. diff --git a/specification/security/oidc_prepare_authentication/Request.ts b/specification/security/oidc_prepare_authentication/Request.ts index 354dc6afb5..3135ce1cf8 100644 --- a/specification/security/oidc_prepare_authentication/Request.ts +++ b/specification/security/oidc_prepare_authentication/Request.ts @@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base' /** * Prepare OpenID connect authentication. + * * Create an oAuth 2.0 authentication request as a URL string based on the configuration of the OpenID Connect authentication realm in Elasticsearch. * * The response of this API is a URL pointing to the Authorization Endpoint of the configured OpenID Connect Provider, which can be used to redirect the browser of the user in order to continue the authentication process. diff --git a/specification/security/put_privileges/SecurityPutPrivilegesRequest.ts b/specification/security/put_privileges/SecurityPutPrivilegesRequest.ts index 20574835da..c6924903ed 100644 --- a/specification/security/put_privileges/SecurityPutPrivilegesRequest.ts +++ b/specification/security/put_privileges/SecurityPutPrivilegesRequest.ts @@ -24,6 +24,24 @@ import { Actions } from './types' /** * Create or update 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. + * + * Application names are formed from a prefix, with an optional suffix that conform to the following rules: + * + * * The prefix must begin with a lowercase ASCII letter. + * * The prefix must contain only ASCII letters or digits. + * * The prefix must be at least 3 characters long. + * * If the suffix exists, it must begin with either a dash `-` or `_`. + * * The suffix cannot contain any of the following characters: `\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, `*`. + * * No part of the name can contain whitespace. + * + * Privilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters `_`, `-`, and `.`. + * + * Action names can contain any number of printable ASCII characters and must contain at least one of the following characters: `/`, `*`, `:`. * @rest_spec_name security.put_privileges * @availability stack since=6.4.0 stability=stable * @availability serverless stability=stable visibility=private @@ -35,6 +53,9 @@ export interface Request extends RequestBase { query_parameters: { refresh?: Refresh } - /** @codegen_name privileges */ + /** + * The body is a JSON object where the names of the fields are the application names and the value of each field is an object. + * The fields in this inner object are the names of the privileges and each value is a JSON object, + * @codegen_name privileges */ body: Dictionary> } diff --git a/specification/security/put_privileges/SecurityPutPrivilegesResponse.ts b/specification/security/put_privileges/SecurityPutPrivilegesResponse.ts index c84a510cca..a8e9610ca6 100644 --- a/specification/security/put_privileges/SecurityPutPrivilegesResponse.ts +++ b/specification/security/put_privileges/SecurityPutPrivilegesResponse.ts @@ -21,6 +21,8 @@ import { CreatedStatus } from '@security/_types/CreatedStatus' import { Dictionary } from '@spec_utils/Dictionary' export class Response { - /** @codegen_name result */ + /** + * A successful call returns a JSON structure that shows whether the privilege has been created or updated. + * @codegen_name result */ body: Dictionary> } diff --git a/specification/security/put_privileges/examples/request/SecurityPutPrivilegesRequestExample1.yaml b/specification/security/put_privileges/examples/request/SecurityPutPrivilegesRequestExample1.yaml index 2ec7c91d91..45b84d7287 100644 --- a/specification/security/put_privileges/examples/request/SecurityPutPrivilegesRequestExample1.yaml +++ b/specification/security/put_privileges/examples/request/SecurityPutPrivilegesRequestExample1.yaml @@ -3,6 +3,8 @@ summary: Add a privilege description: > Run `PUT /_security/privilege` to add a single application privilege. The wildcard (`*`) means that this privilege grants access to all actions that start with `data:read/`. + Elasticsearch does not assign any meaning to these actions. However, + if the request includes an application privilege such as `data:read/users` or `data:read/settings`, the has privileges API respects the use of a wildcard and returns `true`. # type: request value: |- { diff --git a/specification/security/put_role/SecurityPutRoleRequest.ts b/specification/security/put_role/SecurityPutRoleRequest.ts index 04398a94b9..c33a87f87b 100644 --- a/specification/security/put_role/SecurityPutRoleRequest.ts +++ b/specification/security/put_role/SecurityPutRoleRequest.ts @@ -72,6 +72,9 @@ export interface Request extends RequestBase { indices?: IndicesPrivileges[] /** * A list of remote indices permissions entries. + * + * NOTE: Remote indices are effective for remote clusters configured with the API key based model. + * They have no effect for remote clusters configured with the certificate based model. * @availability stack since=8.14.0 * */ @@ -88,7 +91,7 @@ export interface Request extends RequestBase { metadata?: Metadata /** * A list of users that the owners of this role 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 + * @ext_doc_id run-as-privilege */ run_as?: string[] /** diff --git a/specification/security/put_role/SecurityPutRoleResponse.ts b/specification/security/put_role/SecurityPutRoleResponse.ts index 94cdc9669a..ab8ee24335 100644 --- a/specification/security/put_role/SecurityPutRoleResponse.ts +++ b/specification/security/put_role/SecurityPutRoleResponse.ts @@ -20,5 +20,10 @@ import { CreatedStatus } from '@security/_types/CreatedStatus' export class Response { - body: { role: CreatedStatus } + body: { + /** + * When an existing role is updated, `created` is set to `false`. + */ + role: CreatedStatus + } } diff --git a/specification/security/put_role_mapping/SecurityPutRoleMappingRequest.ts b/specification/security/put_role_mapping/SecurityPutRoleMappingRequest.ts index 0ebc98a6da..ab854e14ff 100644 --- a/specification/security/put_role_mapping/SecurityPutRoleMappingRequest.ts +++ b/specification/security/put_role_mapping/SecurityPutRoleMappingRequest.ts @@ -29,8 +29,26 @@ import { Metadata, Name, Refresh } from '@_types/common' * Each mapping has rules that identify users and a list of roles that are granted to those users. * The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files. * - * This API does not create roles. Rather, it maps users to existing roles. + * NOTE: This API does not create roles. Rather, it maps users to existing roles. * Roles can be created by using the create or update roles API or roles files. + * + * **Role templates** + * + * The most common use for role mappings is to create a mapping from a known value on the user to a fixed role name. + * For example, all users in the `cn=admin,dc=example,dc=com` LDAP group should be given the superuser role in Elasticsearch. + * The `roles` field is used for this purpose. + * + * For more complex needs, it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user. + * The `role_templates` field is used for this purpose. + * + * NOTE: To use role templates successfully, the relevant scripting feature must be enabled. + * Otherwise, all attempts to create a role mapping with role templates fail. + * + * All of the user fields that are available in the role mapping rules are also available in the role templates. + * Thus it is possible to assign a user to a role that reflects their username, their groups, or the name of the realm to which they authenticated. + * + * By default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user. + * If the format of the template is set to "json" then the template is expected to produce a JSON string or an array of JSON strings for the role names. * @rest_spec_name security.put_role_mapping * @availability stack since=5.5.0 stability=stable * @availability serverless stability=stable visibility=private @@ -40,18 +58,39 @@ import { Metadata, Name, Refresh } from '@_types/common' */ export interface Request extends RequestBase { path_parts: { + /** + * The distinct name that identifies the role mapping. + * The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way. + */ name: Name } query_parameters: { refresh?: Refresh } body: { + /** + * Mappings that have `enabled` set to `false` are ignored when role mapping is performed. + */ enabled?: boolean + /** + * Additional metadata that helps define which roles are assigned to each user. + * Within the metadata object, keys beginning with `_` are reserved for system usage. + */ metadata?: Metadata - // Exactly one of roles or role_templates must be specified + /** + * A list of role names that are granted to the users that match the role mapping rules. + * Exactly one of `roles` or `role_templates` must be specified. + */ roles?: string[] - // Exactly one of roles or role_templates must be specified + /** + * A list of Mustache templates that will be evaluated to determine the roles names that should granted to the users that match the role mapping rules. + * Exactly one of `roles` or `role_templates` must be specified. + */ role_templates?: RoleTemplate[] + /** + * The rules that determine which users should be matched by the mapping. + * A rule is a logical condition that is expressed by using a JSON DSL. + */ rules?: RoleMappingRule run_as?: string[] } diff --git a/specification/security/put_user/SecurityPutUserRequest.ts b/specification/security/put_user/SecurityPutUserRequest.ts index d97fb0dade..9442faec93 100644 --- a/specification/security/put_user/SecurityPutUserRequest.ts +++ b/specification/security/put_user/SecurityPutUserRequest.ts @@ -23,8 +23,9 @@ import { Metadata, Password, Refresh, Username } from '@_types/common' /** * Create or update users. * + * Add and update users in the native realm. * A password is required for adding a new user but is optional when updating an existing user. - * To change a user’s password without updating any other fields, use the change password API. + * To change a user's password without updating any other fields, use the change password API. * @rest_spec_name security.put_user * @availability stack stability=stable * @cluster_privileges manage_security @@ -32,19 +33,63 @@ import { Metadata, Password, Refresh, Username } from '@_types/common' */ export interface Request extends RequestBase { path_parts: { + /** + * An identifier for the user. + * + * NOTE: Usernames must be at least 1 and no more than 507 characters. + * They can contain alphanumeric characters (a-z, A-Z, 0-9), spaces, punctuation, and printable symbols in the Basic Latin (ASCII) block. + * Leading or trailing whitespace is not allowed. + */ username: Username } query_parameters: { + /** + * Valid values are `true`, `false`, and `wait_for`. + * These values have the same meaning as in the index API, but the default value for this API is true. + * @server_default true + */ refresh?: Refresh } body: { username?: Username + /** + * The email of the user. + */ email?: string | null + /** + * The full name of the user. + */ full_name?: string | null + /** + * Arbitrary metadata that you want to associate with the user. + */ metadata?: Metadata + /** + * The user's password. + * Passwords must be at least 6 characters long. + * When adding a user, one of `password` or `password_hash` is required. + * When updating an existing user, the password is optional, so that other fields on the user (such as their roles) may be updated without modifying the user's password + */ password?: Password + /** + * A hash of the user's password. + * This must be produced using the same hashing algorithm as has been configured for password storage. + * For more details, see the explanation of the `xpack.security.authc.password_hashing.algorithm` setting in the user cache and password hash algorithm documentation. + * Using this parameter allows the client to pre-hash the password for performance and/or confidentiality reasons. + * The `password` parameter and the `password_hash` parameter cannot be used in the same request. + * @ext_doc_id security-settings-hashing + */ password_hash?: string + /** + * A set of roles the user has. + * The roles determine the user's access permissions. + * To create a user without any roles, specify an empty list (`[]`). + */ roles?: string[] + /** + * Specifies whether the user is enabled. + * @server_default true + */ enabled?: boolean } } diff --git a/specification/security/put_user/SecurityPutUserResponse.ts b/specification/security/put_user/SecurityPutUserResponse.ts index 668db6d933..0d4ea96926 100644 --- a/specification/security/put_user/SecurityPutUserResponse.ts +++ b/specification/security/put_user/SecurityPutUserResponse.ts @@ -18,5 +18,11 @@ */ export class Response { - body: { created: boolean } + body: { + /** + * A successful call returns a JSON structure that shows whether the user has been created or updated. + * When an existing user is updated, `created` is set to `false`. + */ + created: boolean + } } diff --git a/specification/security/put_user/examples/request/SecurityPutUserRequestExample1.yaml b/specification/security/put_user/examples/request/SecurityPutUserRequestExample1.yaml index c7a0baf0af..ac6e5a5453 100644 --- a/specification/security/put_user/examples/request/SecurityPutUserRequestExample1.yaml +++ b/specification/security/put_user/examples/request/SecurityPutUserRequestExample1.yaml @@ -1,11 +1,14 @@ # summary: -# method_request: POST /_security/profile/_activate -description: > - Run `POST /_security/profile/_activate` to activate a user profile. +# method_request: POST /_security/user/jacknich +description: Run `POST /_security/user/jacknich` to activate a user profile. # type: request value: |- { - "grant_type": "password", - "username" : "jacknich", - "password" : "l0ng-r4nd0m-p@ssw0rd" + "password" : "l0ng-r4nd0m-p@ssw0rd", + "roles" : [ "admin", "other_role1" ], + "full_name" : "Jack Nicholson", + "email" : "jacknich@example.com", + "metadata" : { + "intelligence" : 7 + } } diff --git a/specification/security/query_api_keys/QueryApiKeysRequest.ts b/specification/security/query_api_keys/QueryApiKeysRequest.ts index 476a4a6d11..5d9e9574c7 100644 --- a/specification/security/query_api_keys/QueryApiKeysRequest.ts +++ b/specification/security/query_api_keys/QueryApiKeysRequest.ts @@ -26,7 +26,12 @@ import { ApiKeyAggregationContainer, ApiKeyQueryContainer } from './types' /** * Find API keys with a query. * - * Get a paginated list of API keys and their information. You can optionally filter the results with a query. + * Get a paginated list of API keys and their information. + * You can optionally filter the results with a query. + * + * To use this API, you must have at least the `manage_own_api_key` or the `read_security` cluster privileges. + * If you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own. + * If you have the `read_security`, `manage_api_key`, or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership. * @rest_spec_name security.query_api_keys * @availability stack since=7.15.0 stability=stable * @availability serverless stability=stable visibility=public @@ -37,13 +42,15 @@ export interface Request extends RequestBase { query_parameters: { /** * Return the snapshot of the owner user's role descriptors associated with the API key. - * An API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors. + * An API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors (effectively limited by it). + * An API key cannot retrieve any API key’s limited-by role descriptors (including itself) unless it has `manage_api_key` or higher privileges. * @availability stack since=8.5.0 * @availability serverless */ with_limited_by?: boolean /** - * Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists. + * Determines whether to also retrieve the profile UID for the API key owner principal. + * If it exists, the profile UID is returned under the `profile_uid` response field for each API key. * @server_default false * @availability stack since=8.14.0 * @availability serverless @@ -73,29 +80,38 @@ export interface Request extends RequestBase { * `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. * You can query the following public information associated with an API key: `id`, `type`, `name`, * `creation`, `expiration`, `invalidated`, `invalidation`, `username`, `realm`, and `metadata`. + * + * NOTE: The queryable string values associated with API keys are internally mapped as keywords. + * Consequently, if no `analyzer` parameter is specified for a `match` query, then the provided match query string is interpreted as a single keyword value. + * Such a match query is hence equivalent to a `term` query. */ query?: ApiKeyQueryContainer /** - * Starting document offset. - * By default, you cannot page through more than 10,000 hits using the from and size parameters. + * The starting document offset. + * It must not be negative. + * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. * To page through more hits, use the `search_after` parameter. * @server_default 0 */ from?: integer /** + * The sort definition. * Other than `id`, all public fields of an API key are eligible for sorting. * In addition, sort can also be applied to the `_doc` field to sort by index order. - * @doc_id sort-search-results */ + * @ext_doc_id sort-search-results */ sort?: Sort /** * The number of hits to return. + * It must not be negative. + * The `size` parameter can be set to `0`, in which case no API key matches are returned, only the aggregation results. * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. * To page through more hits, use the `search_after` parameter. * @server_default 10 */ size?: integer /** - * Search after definition + * The search after definition. + * @ext_doc_id search-after */ search_after?: SortResults } diff --git a/specification/security/query_api_keys/types.ts b/specification/security/query_api_keys/types.ts index 695e71cdf3..b7051d4a81 100644 --- a/specification/security/query_api_keys/types.ts +++ b/specification/security/query_api_keys/types.ts @@ -144,7 +144,7 @@ export type ApiKeyAggregate = */ export class ApiKeyQueryContainer { /** - * matches documents matching boolean combinations of other queries. + * Matches documents matching boolean combinations of other queries. * @doc_id query-dsl-bool-query */ bool?: BoolQuery diff --git a/specification/security/query_role/QueryRolesRequest.ts b/specification/security/query_role/QueryRolesRequest.ts index 46b5bca940..b471e93d08 100644 --- a/specification/security/query_role/QueryRolesRequest.ts +++ b/specification/security/query_role/QueryRolesRequest.ts @@ -25,7 +25,11 @@ import { RoleQueryContainer } from './types' /** * Find roles with a query. * - * Get roles in a paginated manner. You can optionally filter the results with a query. + * Get roles in a paginated manner. + * The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. + * The query roles API does not retrieve roles that are defined in roles files, nor built-in ones. + * You can optionally filter the results with a query. + * Also, the results can be paginated and sorted. * @rest_spec_name security.query_role * @availability stack since=8.15.0 stability=stable * @availability serverless stability=stable visibility=private @@ -40,30 +44,35 @@ export interface Request extends RequestBase { * The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, * `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. * You can query the following information associated with roles: `name`, `description`, `metadata`, - * `applications.application`, `applications.privileges`, `applications.resources`. + * `applications.application`, `applications.privileges`, and `applications.resources`. */ query?: RoleQueryContainer /** - * Starting document offset. - * By default, you cannot page through more than 10,000 hits using the from and size parameters. + * The starting document offset. + * It must not be negative. + * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. * To page through more hits, use the `search_after` parameter. * @server_default 0 */ from?: integer /** - * All public fields of a role are eligible for sorting. + * The sort definition. + * You can sort on `username`, `roles`, or `enabled`. * In addition, sort can also be applied to the `_doc` field to sort by index order. - * @doc_id sort-search-results */ + * @doc_id sort-search-results + */ sort?: Sort /** * The number of hits to return. + * It must not be negative. * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. * To page through more hits, use the `search_after` parameter. * @server_default 10 */ size?: integer /** - * Search after definition + * The search after definition. + * @ext_doc_id search-after */ search_after?: SortResults } diff --git a/specification/security/query_role/QueryRolesResponse.ts b/specification/security/query_role/QueryRolesResponse.ts index c71f50638c..e793b69aa9 100644 --- a/specification/security/query_role/QueryRolesResponse.ts +++ b/specification/security/query_role/QueryRolesResponse.ts @@ -31,7 +31,12 @@ export class Response { */ count: integer /** - * The list of roles. + * A list of roles that match the query. + * The returned role format is an extension of the role definition format. + * It adds the `transient_metadata.enabled` and the `_sort` fields. + * `transient_metadata.enabled` is set to `false` in case the role is automatically disabled, for example when the role grants privileges that are not allowed by the installed license. + * `_sort` is present when the search query sorts on some field. + * It contains the array of values that have been used for sorting. */ roles: QueryRole[] } diff --git a/specification/security/query_role/examples/request/QueryRolesRequestExample1.yaml b/specification/security/query_role/examples/request/QueryRolesRequestExample1.yaml new file mode 100644 index 0000000000..ca91b4b361 --- /dev/null +++ b/specification/security/query_role/examples/request/QueryRolesRequestExample1.yaml @@ -0,0 +1,8 @@ +summary: Query roles by name +# method_request: POST /_security/_query/role +description: Run `POST /_security/_query/role` to lists all roles, sorted by the role name. +# type: request +value: |- + { + "sort": ["name"] + } diff --git a/specification/security/query_role/examples/request/QueryRolesRequestExample2.yaml b/specification/security/query_role/examples/request/QueryRolesRequestExample2.yaml new file mode 100644 index 0000000000..2b063c40fe --- /dev/null +++ b/specification/security/query_role/examples/request/QueryRolesRequestExample2.yaml @@ -0,0 +1,17 @@ +summary: Query roles by description +# method_request: POST /_security/_query/role +description: > + Run `POST /_security/_query/role` to query only the user access role, given its description. + It returns only the best matching role because `size` is set to `1`. +# type: request +value: |- + { + "query": { + "match": { + "description": { + "query": "user access" + } + } + }, + "size": 1 + } diff --git a/specification/security/query_role/examples/response/QueryRolesResponseExample1.yaml b/specification/security/query_role/examples/response/QueryRolesResponseExample1.yaml new file mode 100644 index 0000000000..fc9372a03c --- /dev/null +++ b/specification/security/query_role/examples/response/QueryRolesResponseExample1.yaml @@ -0,0 +1,85 @@ +summary: Query roles by name +description: > + A successful response from `POST /_security/_query/role`. + It returns a JSON structure that contains the information retrieved for one or more roles. +# type: response +# response_code: +value: |- + { + "total": 2, + "count": 2, + "roles": [ + { + "name" : "my_admin_role", + "cluster" : [ + "all" + ], + "indices" : [ + { + "names" : [ + "index1", + "index2" + ], + "privileges" : [ + "all" + ], + "field_security" : { + "grant" : [ + "title", + "body" + ] + }, + "allow_restricted_indices" : false + } + ], + "applications" : [ ], + "run_as" : [ + "other_user" + ], + "metadata" : { + "version" : 1 + }, + "transient_metadata" : { + "enabled" : true + }, + "description" : "Grants full access to all management features within the cluster.", + "_sort" : [ + "my_admin_role" + ] + }, + { + "name" : "my_user_role", + "cluster" : [ ], + "indices" : [ + { + "names" : [ + "index1", + "index2" + ], + "privileges" : [ + "all" + ], + "field_security" : { + "grant" : [ + "title", + "body" + ] + }, + "allow_restricted_indices" : false + } + ], + "applications" : [ ], + "run_as" : [ ], + "metadata" : { + "version" : 1 + }, + "transient_metadata" : { + "enabled" : true + }, + "description" : "Grants user access to some indicies.", + "_sort" : [ + "my_user_role" + ] + } + ] + } diff --git a/specification/security/query_role/examples/response/QueryRolesResponseExample2.yaml b/specification/security/query_role/examples/response/QueryRolesResponseExample2.yaml new file mode 100644 index 0000000000..9a8496c367 --- /dev/null +++ b/specification/security/query_role/examples/response/QueryRolesResponseExample2.yaml @@ -0,0 +1,43 @@ +summary: Query roles by description +description: > + A successful response from `POST /_security/_query/role`. +# type: response +# response_code: +value: |- + { + "total": 2, + "count": 1, + "roles": [ + { + "name" : "my_user_role", + "cluster" : [ ], + "indices" : [ + { + "names" : [ + "index1", + "index2" + ], + "privileges" : [ + "all" + ], + "field_security" : { + "grant" : [ + "title", + "body" + ] + }, + "allow_restricted_indices" : false + } + ], + "applications" : [ ], + "run_as" : [ ], + "metadata" : { + "version" : 1 + }, + "transient_metadata" : { + "enabled" : true + }, + "description" : "Grants user access to some indicies." + } + ] + } diff --git a/specification/security/query_user/SecurityQueryUserRequest.ts b/specification/security/query_user/SecurityQueryUserRequest.ts index 58cb904acd..05ce2a94f4 100644 --- a/specification/security/query_user/SecurityQueryUserRequest.ts +++ b/specification/security/query_user/SecurityQueryUserRequest.ts @@ -27,6 +27,9 @@ import { UserQueryContainer } from './types' * * Get information for users in a paginated manner. * You can optionally filter the results with a query. + * + * NOTE: As opposed to the get user API, built-in users are excluded from the result. + * This API is only for native users. * @rest_spec_name security.query_user * @availability stack since=8.14.0 stability=stable * @availability serverless stability=stable visibility=private @@ -40,36 +43,42 @@ export interface Request extends RequestBase { * If the query parameter is missing, it is equivalent to a `match_all` query. * The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, * `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. - * You can query the following information associated with user: `username`, `roles`, `enabled` + * You can query the following information associated with user: `username`, `roles`, `enabled`, `full_name`, and `email`. */ query?: UserQueryContainer /** - * Starting document offset. - * By default, you cannot page through more than 10,000 hits using the from and size parameters. + * The starting document offset. + * It must not be negative. + * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. * To page through more hits, use the `search_after` parameter. * @server_default 0 */ from?: integer /** - * Fields eligible for sorting are: username, roles, enabled + * The sort definition. + * Fields eligible for sorting are: `username`, `roles`, `enabled`. * In addition, sort can also be applied to the `_doc` field to sort by index order. - * @doc_id sort-search-results */ + * @ext_doc_id sort-search-results + */ sort?: Sort /** * The number of hits to return. + * It must not be negative. * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. * To page through more hits, use the `search_after` parameter. * @server_default 10 */ size?: integer /** - * Search after definition + * The search after definition + * @ext_doc_id search-after */ search_after?: SortResults } query_parameters: { /** - * If true will return the User Profile ID for the users in the query result, if any. + * Determines whether to retrieve the user profile UID, if it exists, for the users. + * @server_default false */ with_profile_uid?: boolean } diff --git a/specification/security/query_user/SecurityQueryUserResponse.ts b/specification/security/query_user/SecurityQueryUserResponse.ts index fa1f6511ef..9b3f51456e 100644 --- a/specification/security/query_user/SecurityQueryUserResponse.ts +++ b/specification/security/query_user/SecurityQueryUserResponse.ts @@ -31,7 +31,7 @@ export class Response { */ count: integer /** - * A list of user information. + * A list of users that match the query. */ users: QueryUser[] } diff --git a/specification/security/query_user/examples/request/SecurityQueryUserRequestExample1.yaml b/specification/security/query_user/examples/request/SecurityQueryUserRequestExample1.yaml new file mode 100644 index 0000000000..6281c01206 --- /dev/null +++ b/specification/security/query_user/examples/request/SecurityQueryUserRequestExample1.yaml @@ -0,0 +1,14 @@ +summary: Query users by role prefix +# method_request: POST /_security/_query/user?with_profile_uid=true +description: > + Run `POST /_security/_query/user?with_profile_uid=true` to get users that have roles that are prefixed with `other`. + It will also include the user `profile_uid` in the response. +# type: request +value: |- + { + "query": { + "prefix": { + "roles": "other" + } + } + } diff --git a/specification/security/query_user/examples/request/SecurityQueryUserRequestExample2.yaml b/specification/security/query_user/examples/request/SecurityQueryUserRequestExample2.yaml new file mode 100644 index 0000000000..dba7c1d5d2 --- /dev/null +++ b/specification/security/query_user/examples/request/SecurityQueryUserRequestExample2.yaml @@ -0,0 +1,43 @@ +summary: Query users with multiple conditions +# method_request: POST /_security/_query/user +description: > + Run `POST /_security/_query/user`. + Use a `bool` query to issue complex logical conditions: + The `email` must end with `example.com`. + The user must be enabled. + The result will be filtered to only contain users with at least one role that contains the substring `other`. + The offset to begin the search result is the second (zero-based index) user. + The page size of the response is two users. + The result is sorted by `username` in descending order. +# type: request +value: |- + { + "query": { + "bool": { + "must": [ + { + "wildcard": { + "email": "*example.com" + } + }, + { + "term": { + "enabled": true + } + } + ], + "filter": [ + { + "wildcard": { + "roles": "*other*" + } + } + ] + } + }, + "from": 1, + "size": 2, + "sort": [ + { "username": { "order": "desc"} } + ] + } diff --git a/specification/security/query_user/examples/response/SecurityQueryUserResponseExample1.yaml b/specification/security/query_user/examples/response/SecurityQueryUserResponseExample1.yaml new file mode 100644 index 0000000000..b4d11f3bee --- /dev/null +++ b/specification/security/query_user/examples/response/SecurityQueryUserResponseExample1.yaml @@ -0,0 +1,27 @@ +summary: Query users by role prefix +description: > + A successful response from `POST /_security/_query/user?with_profile_uid=true` that contains users that have roles that are prefixed with `other`. + It also includes the user `profile_uid` in the response. +# type: response +# response_code: +value: |- + { + "total": 1, + "count": 1, + "users": [ + { + "username": "jacknich", + "roles": [ + "admin", + "other_role1" + ], + "full_name": "Jack Nicholson", + "email": "jacknich@example.com", + "metadata": { + "intelligence": 7 + }, + "enabled": true, + "profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0" + } + ] + } diff --git a/specification/security/query_user/examples/response/SecurityQueryUserResponseExample2.yaml b/specification/security/query_user/examples/response/SecurityQueryUserResponseExample2.yaml new file mode 100644 index 0000000000..15b53c9f79 --- /dev/null +++ b/specification/security/query_user/examples/response/SecurityQueryUserResponseExample2.yaml @@ -0,0 +1,43 @@ +summary: Query users with multiple conditions +description: > + A successful response from `POST /_security/_query/user` that uses a `bool` query to issue complex logical conditions and uses `from`, `size`, and `sort` to help paginate the result. + The sort value is `username`. +# type: response +# response_code: +value: |- + { + "total": 5, + "count": 2, + "users": [ + { + "username": "ray", + "roles": [ + "other_role3" + ], + "full_name": "Ray Nicholson", + "email": "rayn@example.com", + "metadata": { + "intelligence": 7 + }, + "enabled": true, + "_sort": [ + "ray" + ] + }, + { + "username": "lorraine", + "roles": [ + "other_role3" + ], + "full_name": "Lorraine Nicholson", + "email": "lorraine@example.com", + "metadata": { + "intelligence": 7 + }, + "enabled": true, + "_sort": [ + "lorraine" + ] + } + ] + } diff --git a/specification/security/query_user/examples/response/SecurityQueryUserResponseExample3.yaml b/specification/security/query_user/examples/response/SecurityQueryUserResponseExample3.yaml new file mode 100644 index 0000000000..706ac5b42f --- /dev/null +++ b/specification/security/query_user/examples/response/SecurityQueryUserResponseExample3.yaml @@ -0,0 +1,39 @@ +summary: Query all users +description: > + A successful response from `GET /_security/_query/user`, which lists all users. + It returns a JSON structure that contains the information retrieved from one or more users. +# type: response +# response_code: +value: |- + { + "total": 2, + "count": 2, + "users": [ + { + "username": "jacknich", + "roles": [ + "admin", + "other_role1" + ], + "full_name": "Jack Nicholson", + "email": "jacknich@example.com", + "metadata": { + "intelligence": 7 + }, + "enabled": true + }, + { + "username": "sandrakn", + "roles": [ + "admin", + "other_role1" + ], + "full_name": "Sandra Knight", + "email": "sandrakn@example.com", + "metadata": { + "intelligence": 7 + }, + "enabled": true + } + ] + } diff --git a/specification/security/update_api_key/Request.ts b/specification/security/update_api_key/Request.ts index 414124f3d2..b017d37ba2 100644 --- a/specification/security/update_api_key/Request.ts +++ b/specification/security/update_api_key/Request.ts @@ -26,19 +26,24 @@ import { Duration } from '@_types/Time' /** * Update an API key. * - * Updates attributes of an existing API key. + * Update attributes of an existing API key. + * This API supports updates to an API key's access scope, expiration, and metadata. + * + * To use this API, you must have at least the `manage_own_api_key` cluster privilege. * Users can only update API keys that they created or that were granted to them. - * Use this API to update API keys created by the create API Key or grant API Key APIs. - * If you need to apply the same update to many API keys, you can use bulk update API Keys to reduce overhead. - * It’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key. - * This API supports updates to an API key’s access scope and metadata. - * The access scope of an API key is derived from the `role_descriptors` you specify in the request, and a snapshot of the owner user’s permissions at the time of the request. - * The snapshot of the owner’s permissions is updated automatically on every call. - * If you don’t specify `role_descriptors` in the request, a call to this API might still change the API key’s access scope. - * This change can occur if the owner user’s permissions have changed since the API key was created or last modified. * To update another user’s API key, use the `run_as` feature to submit a request on behalf of another user. - * IMPORTANT: It’s not possible to use an API key as the authentication credential for this API. - * To update an API key, the owner user’s credentials are required. + * + * IMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required. + * + * Use this API to update API keys created by the create API key or grant API Key APIs. + * If you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead. + * It's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API. + * + * The access scope of an API key is derived from the `role_descriptors` you specify in the request and a snapshot of the owner user's permissions at the time of the request. + * The snapshot of the owner's permissions is updated automatically on every call. + * + * IMPORTANT: If you don't specify `role_descriptors` in the request, a call to this API might still change the API key's access scope. + * This change can occur if the owner user's permissions have changed since the API key was created or last modified. * @rest_spec_name security.update_api_key * @availability stack since=8.4.0 stability=stable * @availability serverless stability=stable visibility=public @@ -54,15 +59,27 @@ export interface Request extends RequestBase { } body: { /** - * 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 + * The role descriptors to assign to this API key. + * The API key's effective permissions are an intersection of its assigned privileges and the point in time snapshot of permissions of the owner user. + * You can assign new privileges by specifying them in this parameter. + * To remove assigned privileges, you can supply an empty `role_descriptors` parameter, that is to say, an empty object `{}`. + * If an API key has no assigned privileges, it inherits the owner user's full permissions. + * The snapshot of the owner's permissions is always updated, whether you supply the `role_descriptors` parameter or not. + * The structure of a role descriptor is the same as the request for the create API keys API. */ role_descriptors?: Dictionary /** - * Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with _ are reserved for system usage. + * Arbitrary metadata that you want to associate with the API key. + * It supports a nested data structure. + * Within the metadata object, keys beginning with `_` are reserved for system usage. + * When specified, this value fully replaces the metadata previously associated with the API key. */ metadata?: Metadata - /** Expiration time for the API key. */ + /** + * The expiration time for the API key. + * By default, API keys never expire. + * This property can be omitted to leave the expiration unchanged. + * */ expiration?: Duration } } diff --git a/specification/security/update_api_key/Response.ts b/specification/security/update_api_key/Response.ts index 4fd7257fa5..7093960376 100644 --- a/specification/security/update_api_key/Response.ts +++ b/specification/security/update_api_key/Response.ts @@ -21,7 +21,7 @@ export class Response { body: { /** * If `true`, the API key was updated. - * If `false`, the API key didn’t change because no change was detected. + * If `false`, the API key didn't change because no change was detected. */ updated: boolean } diff --git a/specification/security/update_api_key/examples/request/RequestExample1.yaml b/specification/security/update_api_key/examples/request/RequestExample1.yaml new file mode 100644 index 0000000000..36fbbdf51b --- /dev/null +++ b/specification/security/update_api_key/examples/request/RequestExample1.yaml @@ -0,0 +1,25 @@ +summary: Update role and metadata +# method_request: PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx +description: > + Run `PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx` to assign new role descriptors and metadata to an API key. +# type: request +value: |- + { + "role_descriptors": { + "role-a": { + "indices": [ + { + "names": ["*"], + "privileges": ["write"] + } + ] + } + }, + "metadata": { + "environment": { + "level": 2, + "trusted": true, + "tags": ["production"] + } + } + } diff --git a/specification/security/update_api_key/examples/request/RequestExample2.yaml b/specification/security/update_api_key/examples/request/RequestExample2.yaml new file mode 100644 index 0000000000..cceb7734a0 --- /dev/null +++ b/specification/security/update_api_key/examples/request/RequestExample2.yaml @@ -0,0 +1,10 @@ +summary: Remove permissions +# method_request: PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx +description: > + Run `PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx` to remove the API key's previously assigned permissions. + It will inherit the owner user's full permissions. +# type: request +value: |- + { + "role_descriptors": {} + } diff --git a/specification/security/update_api_key/examples/response/ResponseExample1.yaml b/specification/security/update_api_key/examples/response/ResponseExample1.yaml new file mode 100644 index 0000000000..d003ec1af4 --- /dev/null +++ b/specification/security/update_api_key/examples/response/ResponseExample1.yaml @@ -0,0 +1,10 @@ +summary: Update role and metadata +description: > + A successful response from `PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx`. + The API key's effective permissions after the update will be the intersection of the supplied role descriptors and the owner user's permissions. +# type: response +# response_code: +value: |- + { + "updated": true + } diff --git a/specification/security/update_cross_cluster_api_key/examples/request/UpdateCrossClusterApiKeyRequestExample1.yaml b/specification/security/update_cross_cluster_api_key/examples/request/UpdateCrossClusterApiKeyRequestExample1.yaml index 37d5973869..69e5de85a7 100644 --- a/specification/security/update_cross_cluster_api_key/examples/request/UpdateCrossClusterApiKeyRequestExample1.yaml +++ b/specification/security/update_cross_cluster_api_key/examples/request/UpdateCrossClusterApiKeyRequestExample1.yaml @@ -1,7 +1,7 @@ # summary: # method_request: PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx description: > - Run `PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx` to update a cross-cluster AsPI key, assigning it new access scope and metadata. + Run `PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx` to update a cross-cluster API key, assigning it new access scope and metadata. # type: request value: |- { diff --git a/specification/security/update_settings/SecurityUpdateSettingsRequest.ts b/specification/security/update_settings/SecurityUpdateSettingsRequest.ts index 94c9c75320..657ac05e84 100644 --- a/specification/security/update_settings/SecurityUpdateSettingsRequest.ts +++ b/specification/security/update_settings/SecurityUpdateSettingsRequest.ts @@ -24,9 +24,12 @@ import { Duration } from '@_types/Time' /** * Update security index settings. * - * Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified, for example `index.auto_expand_replicas` and `index.number_of_replicas`. + * Update the user-configurable settings for the security internal index (`.security` and associated indices). Only a subset of settings are allowed to be modified. This includes `index.auto_expand_replicas` and `index.number_of_replicas`. * - * If a specific index is not in use on the system and settings are provided for it, the request will be rejected. This API does not yet support configuring the settings for indices before they are in use. + * NOTE: If `index.auto_expand_replicas` is set, `index.number_of_replicas` will be ignored during updates. + * + * If a specific index is not in use on the system and settings are provided for it, the request will be rejected. + * This API does not yet support configuring the settings for indices before they are in use. * @rest_spec_name security.update_settings * @availability stack stability=stable visibility=public * @cluster_privileges manage_security diff --git a/specification/security/update_settings/examples/request/SecurityUpdateSettingsRequestExample1.yaml b/specification/security/update_settings/examples/request/SecurityUpdateSettingsRequestExample1.yaml new file mode 100644 index 0000000000..dc26d82edb --- /dev/null +++ b/specification/security/update_settings/examples/request/SecurityUpdateSettingsRequestExample1.yaml @@ -0,0 +1,16 @@ +# summary: +# method_request: PUT /_security/settings +description: Run `PUT /_security/settings` to modify the security settings. +# type: request +value: |- + { + "security": { + "index.auto_expand_replicas": "0-all" + }, + "security-tokens": { + "index.auto_expand_replicas": "0-all" + }, + "security-profile": { + "index.auto_expand_replicas": "0-all" + } + }