Security

class elasticsearch_serverless.client.SecurityClient(client: BaseClient)

Authenticate a user.

Authenticates a user and returns information about the authenticated user. Include the user information in a basic auth header. A successful call returns a JSON structure that shows user information such as their username, the roles that are assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user. If the user cannot be authenticated, this API returns a 401 status code.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-authenticate

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.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key

Parameters:

expiration – The expiration time for the API key. By default, API keys never expire.
metadata – 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.
name – A name for the API key.
refresh – 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.
role_descriptors – 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.

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.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-delete-role

Parameters:

name – The name of the role.
refresh – 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.

Get API key information.

Retrieves information for one or more API keys. NOTE: If you have only the manage_own_api_key privilege, this API returns only the API keys that you own. If you have read_security, manage_api_key or greater privileges (including manage_security), this API returns all API keys regardless of ownership.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-api-key

Parameters:

active_only – A boolean flag that can be used to query API keys that are currently active. An API key is considered active if it is neither invalidated, nor expired at query time. You can specify this together with other parameters such as owner or name. If active_only is false, the response will include both active and inactive (expired or invalidated) keys.
id – An API key id. This parameter cannot be used with any of name, realm_name or username.
name – An API key name. This parameter cannot be used with any of id, realm_name or username. It supports prefix search with wildcard.
owner – A boolean flag that can be used to 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.
realm_name – The name of an authentication realm. This parameter cannot be used with either id or name or when owner flag is set to true.
username – The username of a user. This parameter cannot be used with either id or name or when owner flag is set to true.
with_limited_by – 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.
with_profile_uid – Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists.

Get builtin privileges.

Get the list of cluster privileges and index privileges that are available in this version of Elasticsearch.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-builtin-privileges

Get roles.

Get 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 get roles API cannot retrieve roles that are defined in roles files.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-role

Parameters:: name – 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.

has_privileges(*, user: str | None = None, application: Sequence[Mapping[str, Any]] | None = None, cluster: Sequence[str | Literal['all', 'cancel_task', 'create_snapshot', 'cross_cluster_replication', 'cross_cluster_search', 'delegate_pki', 'grant_api_key', 'manage', 'manage_api_key', 'manage_autoscaling', 'manage_behavioral_analytics', 'manage_ccr', 'manage_data_frame_transforms', 'manage_data_stream_global_retention', 'manage_enrich', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines', 'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules', 'manage_search_synonyms', 'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile', 'manage_watcher', 'monitor', 'monitor_data_frame_transforms', 'monitor_data_stream_global_retention', 'monitor_enrich', 'monitor_inference', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_stats', 'monitor_text_structure', 'monitor_transform', 'monitor_watcher', 'none', 'post_behavioral_analytics_event', 'read_ccr', 'read_fleet_secrets', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client', 'write_connector_secrets', 'write_fleet_secrets']] | None = None, error_trace: bool | None = None, filter_path: str | Sequence[str] | None = None, human: bool | None = None, index: Sequence[Mapping[str, Any]] | None = None, pretty: bool | None = None, body: Dict[str, Any] | None = None) → ObjectApiResponse[Any]

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.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-has-privileges

Parameters:

user – Username
application –
cluster – A list of the cluster privileges that you want to check.
index –

Invalidate API keys.

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.

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, 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.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-invalidate-api-key

Parameters:

id –
ids – A list of API key ids. This parameter cannot be used with any of name, realm_name, or username.
name – An API key name. This parameter cannot be used with any of ids, realm_name or username.
owner – 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.
realm_name – The name of an authentication realm. This parameter cannot be used with either ids or name, or when owner flag is set to true.
username – The username of a user. This parameter cannot be used with either ids or name or when owner flag is set to true.

put_role(*, name: str, applications: Sequence[Mapping[str, Any]] | None = None, cluster: Sequence[str | Literal['all', 'cancel_task', 'create_snapshot', 'cross_cluster_replication', 'cross_cluster_search', 'delegate_pki', 'grant_api_key', 'manage', 'manage_api_key', 'manage_autoscaling', 'manage_behavioral_analytics', 'manage_ccr', 'manage_data_frame_transforms', 'manage_data_stream_global_retention', 'manage_enrich', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines', 'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules', 'manage_search_synonyms', 'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile', 'manage_watcher', 'monitor', 'monitor_data_frame_transforms', 'monitor_data_stream_global_retention', 'monitor_enrich', 'monitor_inference', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_stats', 'monitor_text_structure', 'monitor_transform', 'monitor_watcher', 'none', 'post_behavioral_analytics_event', 'read_ccr', 'read_fleet_secrets', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client', 'write_connector_secrets', 'write_fleet_secrets']] | None = None, description: str | None = None, error_trace: bool | None = None, filter_path: str | Sequence[str] | None = None, global_: Mapping[str, Any] | None = None, human: bool | None = None, indices: Sequence[Mapping[str, Any]] | None = None, metadata: Mapping[str, Any] | None = None, pretty: bool | None = None, refresh: bool | str | Literal['false', 'true', 'wait_for'] | None = None, remote_cluster: Sequence[Mapping[str, Any]] | None = None, remote_indices: Sequence[Mapping[str, Any]] | None = None, run_as: Sequence[str] | None = None, transient_metadata: Mapping[str, Any] | None = None, body: Dict[str, Any] | None = None) → ObjectApiResponse[Any]

Create or update roles.

The role management APIs are generally the preferred way to manage roles in the native realm, rather than using file-based role management. The create or update roles API cannot update roles that are defined in roles files. File-based role management is not available in Elastic Serverless.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role

Parameters:

name – The name of the role that is being created or updated. On Elasticsearch Serverless, the role name must begin with a letter or digit and can only contain letters, digits and the characters ‘_’, ‘-’, and ‘.’. Each role must have a unique name, as this will serve as the identifier for that role.
applications – A list of application privilege entries.
cluster – A list of cluster privileges. These privileges define the cluster-level actions for users with this role.
description – Optional description of the role descriptor
global – An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.
indices – A list of indices permissions entries.
metadata – Optional metadata. Within the metadata object, keys that begin with an underscore (_) are reserved for system use.
refresh – 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.
remote_cluster – A list of remote cluster permissions entries.
remote_indices – 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.
run_as – 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.
transient_metadata – Indicates roles that might be incompatible with the current cluster license, specifically roles with document and field level security. When the cluster license doesn’t allow certain features for a given role, this parameter is updated dynamically to list the incompatible features. If enabled is false, the role is ignored, but is still listed in the response from the authenticate API.

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.

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.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-query-api-keys

Parameters:

aggregations – Any aggregations to run over the corpus of returned API keys. Aggregations and queries work together. Aggregations are computed only on the API keys that match the query. This supports only a subset of aggregation types, namely: terms, range, date_range, missing, cardinality, value_count, composite, filter, and filters. Additionally, aggregations only run over the same subset of fields that query works with.
aggs – Any aggregations to run over the corpus of returned API keys. Aggregations and queries work together. Aggregations are computed only on the API keys that match the query. This supports only a subset of aggregation types, namely: terms, range, date_range, missing, cardinality, value_count, composite, filter, and filters. Additionally, aggregations only run over the same subset of fields that query works with.
from – 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.
query – A query to filter which API keys to return. 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 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.
search_after – The search after definition.
size – 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.
sort – 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.
typed_keys – Determines whether aggregation names are prefixed by their respective types in the response.
with_limited_by – 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 (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.
with_profile_uid – 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.

Find roles 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.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-query-role

Parameters:

from – 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.
query – A query to filter which roles to return. 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 roles: name, description, metadata, applications.application, applications.privileges, and applications.resources.
search_after – The search after definition.
size – 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.
sort – 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.

Update an 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. 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. 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.

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-update-api-key

Parameters:

id – The ID of the API key to update.
expiration – The expiration time for the API key. By default, API keys never expire. This property can be omitted to leave the expiration unchanged.
metadata – 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.
role_descriptors – 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.