elasticsearch 8.17.0__py3-none-any.whl → 8.17.1__py3-none-any.whl

elasticsearch/_sync/client/security.py

@@ -45,14 +45,33 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Activate a user profile. Create or update a user profile on behalf of another
-        user.
+        user. NOTE: The user profile feature is designed only for use by Kibana and Elastic's
+        Observability, Enterprise Search, and Elastic Security solutions. Individual
+        users and external applications should not call this API directly. The calling
+        application must have either an `access_token` or a combination of `username`
+        and `password` for the user that the profile document is intended for. Elastic
+        reserves the right to change or remove this feature in future releases without
+        prior notice. This API creates or updates a profile document for end users with
+        information that is extracted from the user's authentication object including
+        `username`, `full_name,` `roles`, and the authentication realm. For example,
+        in the JWT `access_token` case, the profile user's `username` is extracted from
+        the JWT token claim pointed to by the `claims.principal` setting of the JWT realm
+        that authenticated the token. When updating a profile document, the API enables
+        the document if it was disabled. Any updates do not change existing content for
+        either the `labels` or `data` fields.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-activate-user-profile.html>`_
 
-        :param grant_type:
-        :param access_token:
-        :param password:
-        :param username:
+        :param grant_type: The type of grant.
+        :param access_token: The user's Elasticsearch access token or JWT. Both `access`
+            and `id` JWT token types are supported and they depend on the underlying
+            JWT realm configuration. If you specify the `access_token` grant type, this
+            parameter is required. It is not valid with other grant types.
+        :param password: The user's password. If you specify the `password` grant type,
+            this parameter is required. It is not valid with other grant types.
+        :param username: The username that identifies the user. If you specify the `password`
+            grant type, this parameter is required. It is not valid with other grant
+            types.
         """
         if grant_type is None and body is None:
             raise ValueError("Empty value passed for parameter 'grant_type'")
@@ -244,6 +263,94 @@ class SecurityClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters(
+        body_fields=("ids", "expiration", "metadata", "role_descriptors"),
+    )
+    def bulk_update_api_keys(
+        self,
+        *,
+        ids: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        error_trace: t.Optional[bool] = None,
+        expiration: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        metadata: t.Optional[t.Mapping[str, t.Any]] = None,
+        pretty: t.Optional[bool] = None,
+        role_descriptors: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
+        body: t.Optional[t.Dict[str, t.Any]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        Bulk update API keys. Update the attributes for multiple API keys. IMPORTANT:
+        It is not possible to use an API key as the authentication credential for this
+        API. To update API keys, the owner user's credentials are required. This API
+        is similar to the update API key API but enables you to apply the same update
+        to multiple API keys in one API call. This operation can greatly improve performance
+        over making individual updates. It is not possible to update expired or invalidated
+        API keys. This API supports updates to API key access scope, metadata and expiration.
+        The access scope of each 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 an 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. A successful request returns a JSON structure that
+        contains the IDs of all updated API keys, the IDs of API keys that already had
+        the requested changes and did not require an update, and error details for any
+        failed update.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-bulk-update-api-keys.html>`_
+
+        :param ids: The API key identifiers.
+        :param expiration: Expiration time for the API keys. By default, API keys never
+            expire. This property can be omitted to leave the value unchanged.
+        :param metadata: Arbitrary nested metadata to associate with the API keys. Within
+            the `metadata` object, top-level keys beginning with an underscore (`_`)
+            are reserved for system usage. Any information specified with this parameter
+            fully replaces metadata previously associated with the API key.
+        :param role_descriptors: The role descriptors to assign to the API keys. An 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, supply the `role_descriptors` parameter as 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. The structure of a role descriptor
+            is the same as the request for the create API keys API.
+        """
+        if ids is None and body is None:
+            raise ValueError("Empty value passed for parameter 'ids'")
+        __path_parts: t.Dict[str, str] = {}
+        __path = "/_security/api_key/_bulk_update"
+        __query: t.Dict[str, t.Any] = {}
+        __body: t.Dict[str, t.Any] = body if body is not None else {}
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if not __body:
+            if ids is not None:
+                __body["ids"] = ids
+            if expiration is not None:
+                __body["expiration"] = expiration
+            if metadata is not None:
+                __body["metadata"] = metadata
+            if role_descriptors is not None:
+                __body["role_descriptors"] = role_descriptors
+        __headers = {"accept": "application/json", "content-type": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="security.bulk_update_api_keys",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters(
         body_fields=("password", "password_hash"),
     )
@@ -773,6 +880,74 @@ class SecurityClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters(
+        body_fields=("x509_certificate_chain",),
+    )
+    def delegate_pki(
+        self,
+        *,
+        x509_certificate_chain: t.Optional[t.Sequence[str]] = None,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        pretty: t.Optional[bool] = None,
+        body: t.Optional[t.Dict[str, t.Any]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        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. This 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. IMPORTANT: The association between
+        the subject public key in the target certificate and the corresponding private
+        key is not validated. This is part of the TLS authentication process and it is
+        delegated to the proxy that calls this API. The proxy is trusted to have performed
+        the TLS authentication and this API translates that authentication into an Elasticsearch
+        access token.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-delegate-pki-authentication.html>`_
+
+        :param x509_certificate_chain: The X509Certificate chain, which is represented
+            as an ordered string array. Each string in the array is a base64-encoded
+            (Section 4 of RFC4648 - not base64url-encoded) of the certificate's DER encoding.
+            The first element is the target certificate that contains the subject distinguished
+            name that is requesting access. This may be followed by additional certificates;
+            each subsequent certificate is used to certify the previous one.
+        """
+        if x509_certificate_chain is None and body is None:
+            raise ValueError(
+                "Empty value passed for parameter 'x509_certificate_chain'"
+            )
+        __path_parts: t.Dict[str, str] = {}
+        __path = "/_security/delegate_pki"
+        __query: t.Dict[str, t.Any] = {}
+        __body: t.Dict[str, t.Any] = body if body is not None else {}
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if not __body:
+            if x509_certificate_chain is not None:
+                __body["x509_certificate_chain"] = x509_certificate_chain
+        __headers = {"accept": "application/json", "content-type": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="security.delegate_pki",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters()
     def delete_privileges(
         self,
@@ -1098,14 +1273,21 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Disable a user profile. Disable user profiles so that they are not visible in
-        user profile searches.
+        user profile searches. NOTE: The user profile feature is designed only for use
+        by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security
+        solutions. Individual users and external applications should not call this API
+        directly. Elastic reserves the right to change or remove this feature in future
+        releases without prior notice. When you activate a user profile, its automatically
+        enabled and visible in user profile searches. You can use the disable user profile
+        API to disable a user profile so it’s not visible in these searches. To re-enable
+        a disabled user profile, use the enable user profile API .
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-disable-user-profile.html>`_
 
         :param uid: Unique identifier for the user profile.
         :param refresh: If 'true', Elasticsearch refreshes 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' do nothing with refreshes.
+            this operation visible to search. If 'wait_for', it waits for a refresh to
+            make this operation visible to search. If 'false', it does nothing with refreshes.
         """
         if uid in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'uid'")
@@ -1195,14 +1377,20 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Enable a user profile. Enable user profiles to make them visible in user profile
-        searches.
+        searches. NOTE: The user profile feature is designed only for use by Kibana and
+        Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual
+        users and external applications should not call this API directly. Elastic reserves
+        the right to change or remove this feature in future releases without prior notice.
+        When you activate a user profile, it's automatically enabled and visible in user
+        profile searches. If you later disable the user profile, you can use the enable
+        user profile API to make the profile visible in these searches again.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-enable-user-profile.html>`_
 
-        :param uid: Unique identifier for the user profile.
+        :param uid: A unique identifier for the user profile.
         :param refresh: If 'true', Elasticsearch refreshes 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' do nothing with refreshes.
+            this operation visible to search. If 'wait_for', it waits for a refresh to
+            make this operation visible to search. If 'false', nothing is done with refreshes.
         """
         if uid in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'uid'")
@@ -1667,6 +1855,49 @@ class SecurityClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters()
+    def get_settings(
+        self,
+        *,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
+        pretty: t.Optional[bool] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        Get security index settings. Get the user-configurable settings for the security
+        internal index (`.security` and associated indices).
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-settings.html>`_
+
+        :param master_timeout: Period to wait for a connection to the master node. If
+            no response is received before the timeout expires, the request fails and
+            returns an error.
+        """
+        __path_parts: t.Dict[str, str] = {}
+        __path = "/_security/settings"
+        __query: t.Dict[str, t.Any] = {}
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if master_timeout is not None:
+            __query["master_timeout"] = master_timeout
+        if pretty is not None:
+            __query["pretty"] = pretty
+        __headers = {"accept": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "GET",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="security.get_settings",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters(
         body_fields=(
             "grant_type",
@@ -1860,15 +2091,19 @@ class SecurityClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get a user profile. Get a user's profile using the unique profile ID.
+        Get a user profile. Get a user's profile using the unique profile ID. NOTE: The
+        user profile feature is designed only for use by Kibana and Elastic's Observability,
+        Enterprise Search, and Elastic Security solutions. Individual users and external
+        applications should not call this API directly. Elastic reserves the right to
+        change or remove this feature in future releases without prior notice.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-get-user-profile.html>`_
 
         :param uid: A unique identifier for the user profile.
-        :param data: List of filters for the `data` field of the profile document. To
-            return all content use `data=*`. To return a subset of content use `data=<key>`
-            to retrieve content nested under the specified `<key>`. By default returns
-            no `data` content.
+        :param data: A comma-separated list of filters for the `data` field of the profile
+            document. To return all content use `data=*`. To return a subset of content
+            use `data=<key>` to retrieve content nested under the specified `<key>`.
+            By default returns no `data` content.
         """
         if uid in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'uid'")
@@ -2140,11 +2375,15 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Check user profile privileges. Determine whether the users associated with the
-        specified user profile IDs have all the requested privileges.
+        specified user profile IDs have all the requested privileges. NOTE: The user
+        profile feature is designed only for use by Kibana and Elastic's Observability,
+        Enterprise Search, and Elastic Security solutions. Individual users and external
+        applications should not call this API directly. Elastic reserves the right to
+        change or remove this feature in future releases without prior notice.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-has-privileges-user-profile.html>`_
 
-        :param privileges:
+        :param privileges: An object containing all the privileges to be checked.
         :param uids: A list of profile IDs. The privileges are checked for associated
             users of the profiles.
         """
@@ -2326,6 +2565,230 @@ class SecurityClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters(
+        body_fields=("nonce", "redirect_uri", "state", "realm"),
+    )
+    def oidc_authenticate(
+        self,
+        *,
+        nonce: t.Optional[str] = None,
+        redirect_uri: t.Optional[str] = None,
+        state: t.Optional[str] = None,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        pretty: t.Optional[bool] = None,
+        realm: t.Optional[str] = None,
+        body: t.Optional[t.Dict[str, t.Any]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        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. These 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.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-oidc-authenticate.html>`_
+
+        :param nonce: Associate a client session with an ID token and mitigate replay
+            attacks. This value needs to be the same as the one that was provided to
+            the `/_security/oidc/prepare` API or the one that was generated by Elasticsearch
+            and included in the response to that call.
+        :param redirect_uri: The URL to which the OpenID Connect Provider redirected
+            the User Agent in response to an authentication request after a successful
+            authentication. This URL must be provided as-is (URL encoded), taken from
+            the body of the response or as the value of a location header in the response
+            from the OpenID Connect Provider.
+        :param state: Maintain state between the authentication request and the response.
+            This value needs to be the same as the one that was provided to the `/_security/oidc/prepare`
+            API or the one that was generated by Elasticsearch and included in the response
+            to that call.
+        :param realm: The name of the OpenID Connect realm. This property is useful in
+            cases where multiple realms are defined.
+        """
+        if nonce is None and body is None:
+            raise ValueError("Empty value passed for parameter 'nonce'")
+        if redirect_uri is None and body is None:
+            raise ValueError("Empty value passed for parameter 'redirect_uri'")
+        if state is None and body is None:
+            raise ValueError("Empty value passed for parameter 'state'")
+        __path_parts: t.Dict[str, str] = {}
+        __path = "/_security/oidc/authenticate"
+        __query: t.Dict[str, t.Any] = {}
+        __body: t.Dict[str, t.Any] = body if body is not None else {}
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if not __body:
+            if nonce is not None:
+                __body["nonce"] = nonce
+            if redirect_uri is not None:
+                __body["redirect_uri"] = redirect_uri
+            if state is not None:
+                __body["state"] = state
+            if realm is not None:
+                __body["realm"] = realm
+        __headers = {"accept": "application/json", "content-type": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="security.oidc_authenticate",
+            path_parts=__path_parts,
+        )
+
+    @_rewrite_parameters(
+        body_fields=("access_token", "refresh_token"),
+    )
+    def oidc_logout(
+        self,
+        *,
+        access_token: t.Optional[str] = None,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        pretty: t.Optional[bool] = None,
+        refresh_token: t.Optional[str] = None,
+        body: t.Optional[t.Dict[str, t.Any]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        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. Elasticsearch
+        exposes all the necessary OpenID Connect related functionality with the OpenID
+        Connect APIs. These 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.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-oidc-logout.html>`_
+
+        :param access_token: The access token to be invalidated.
+        :param refresh_token: The refresh token to be invalidated.
+        """
+        if access_token is None and body is None:
+            raise ValueError("Empty value passed for parameter 'access_token'")
+        __path_parts: t.Dict[str, str] = {}
+        __path = "/_security/oidc/logout"
+        __query: t.Dict[str, t.Any] = {}
+        __body: t.Dict[str, t.Any] = body if body is not None else {}
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if not __body:
+            if access_token is not None:
+                __body["access_token"] = access_token
+            if refresh_token is not None:
+                __body["refresh_token"] = refresh_token
+        __headers = {"accept": "application/json", "content-type": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="security.oidc_logout",
+            path_parts=__path_parts,
+        )
+
+    @_rewrite_parameters(
+        body_fields=("iss", "login_hint", "nonce", "realm", "state"),
+    )
+    def oidc_prepare_authentication(
+        self,
+        *,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        iss: t.Optional[str] = None,
+        login_hint: t.Optional[str] = None,
+        nonce: t.Optional[str] = None,
+        pretty: t.Optional[bool] = None,
+        realm: t.Optional[str] = None,
+        state: t.Optional[str] = None,
+        body: t.Optional[t.Dict[str, t.Any]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        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. Elasticsearch
+        exposes all the necessary OpenID Connect related functionality with the OpenID
+        Connect APIs. These 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.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-oidc-prepare-authentication.html>`_
+
+        :param iss: In the case of a third party initiated single sign on, this is the
+            issuer identifier for the OP that the RP is to send the authentication request
+            to. It cannot be specified when *realm* is specified. One of *realm* or *iss*
+            is required.
+        :param login_hint: In the case of a third party initiated single sign on, it
+            is a string value that is included in the authentication request as the *login_hint*
+            parameter. This parameter is not valid when *realm* is specified.
+        :param nonce: The value used to associate a client session with an ID token and
+            to mitigate replay attacks. If the caller of the API does not provide a value,
+            Elasticsearch will generate one with sufficient entropy and return it in
+            the response.
+        :param realm: The name of the OpenID Connect realm in Elasticsearch the configuration
+            of which should be used in order to generate the authentication request.
+            It cannot be specified when *iss* is specified. One of *realm* or *iss* is
+            required.
+        :param state: The value used to maintain state between the authentication request
+            and the response, typically used as a Cross-Site Request Forgery mitigation.
+            If the caller of the API does not provide a value, Elasticsearch will generate
+            one with sufficient entropy and return it in the response.
+        """
+        __path_parts: t.Dict[str, str] = {}
+        __path = "/_security/oidc/prepare"
+        __query: t.Dict[str, t.Any] = {}
+        __body: t.Dict[str, t.Any] = body if body is not None else {}
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if not __body:
+            if iss is not None:
+                __body["iss"] = iss
+            if login_hint is not None:
+                __body["login_hint"] = login_hint
+            if nonce is not None:
+                __body["nonce"] = nonce
+            if realm is not None:
+                __body["realm"] = realm
+            if state is not None:
+                __body["state"] = state
+        __headers = {"accept": "application/json", "content-type": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="security.oidc_prepare_authentication",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters(
         body_name="privileges",
     )
@@ -3088,13 +3551,25 @@ class SecurityClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Authenticate SAML. Submits a SAML response message to Elasticsearch for consumption.
+        Authenticate SAML. Submit a SAML response message to Elasticsearch for consumption.
+        NOTE: This API is intended for use by custom web applications other than Kibana.
+        If you are using Kibana, refer to the documentation for configuring SAML single-sign-on
+        on the Elastic Stack. The SAML message that is submitted can be: * A response
+        to a SAML authentication request that was previously created using the SAML prepare
+        authentication API. * An unsolicited SAML message in the case of an IdP-initiated
+        single sign-on (SSO) flow. In either case, the SAML message needs to be a base64
+        encoded XML document with a root element of `<Response>`. After successful validation,
+        Elasticsearch responds with an Elasticsearch internal access token and refresh
+        token that can be subsequently used for authentication. This API endpoint essentially
+        exchanges SAML responses that indicate successful authentication in the IdP for
+        Elasticsearch access and refresh tokens, which can be used for authentication
+        against Elasticsearch.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-authenticate.html>`_
 
-        :param content: The SAML response as it was sent by the user’s browser, usually
+        :param content: The SAML response as it was sent by the user's browser, usually
             a Base64 encoded XML document.
-        :param ids: A json array with all the valid SAML Request Ids that the caller
+        :param ids: A JSON array with all the valid SAML Request Ids that the caller
             of the API has for the current user.
         :param realm: The name of the realm that should authenticate the SAML response.
             Useful in cases where many SAML realms are defined.
@@ -3151,10 +3626,19 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Logout of SAML completely. Verifies the logout response sent from the SAML IdP.
+        NOTE: This API is intended for use by custom web applications other than Kibana.
+        If you are using Kibana, refer to the documentation for configuring SAML single-sign-on
+        on the Elastic Stack. The SAML IdP may send a logout response back to the SP
+        after handling the SP-initiated SAML Single Logout. This API verifies the response
+        by ensuring the content is relevant and validating its signature. An empty response
+        is returned if the verification process is successful. The response can be sent
+        by the IdP with either the HTTP-Redirect or the HTTP-Post binding. The caller
+        of this API must prepare the request accordingly so that this API can handle
+        either of them.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-complete-logout.html>`_
 
-        :param ids: A json array with all the valid SAML Request Ids that the caller
+        :param ids: A JSON array with all the valid SAML Request Ids that the caller
             of the API has for the current user.
         :param realm: The name of the SAML realm in Elasticsearch for which the configuration
             is used to verify the logout response.
@@ -3216,25 +3700,33 @@ class SecurityClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Invalidate SAML. Submits a SAML LogoutRequest message to Elasticsearch for consumption.
+        Invalidate SAML. Submit a SAML LogoutRequest message to Elasticsearch for consumption.
+        NOTE: This API is intended for use by custom web applications other than Kibana.
+        If you are using Kibana, refer to the documentation for configuring SAML single-sign-on
+        on the Elastic Stack. The logout request comes from the SAML IdP during an IdP
+        initiated Single Logout. The custom web application can use this API to have
+        Elasticsearch process the `LogoutRequest`. After successful validation of the
+        request, Elasticsearch invalidates the access token and refresh token that corresponds
+        to that specific SAML principal and provides a URL that contains a SAML LogoutResponse
+        message. Thus the user can be redirected back to their IdP.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-invalidate.html>`_
 
         :param query_string: The query part of the URL that the user was redirected to
             by the SAML IdP to initiate the Single Logout. This query should include
-            a single parameter named SAMLRequest that contains a SAML logout request
+            a single parameter named `SAMLRequest` that contains a SAML logout request
             that is deflated and Base64 encoded. If the SAML IdP has signed the logout
-            request, the URL should include two extra parameters named SigAlg and Signature
+            request, the URL should include two extra parameters named `SigAlg` and `Signature`
             that contain the algorithm used for the signature and the signature value
-            itself. In order for Elasticsearch to be able to verify the IdP’s signature,
-            the value of the query_string field must be an exact match to the string
+            itself. In order for Elasticsearch to be able to verify the IdP's signature,
+            the value of the `query_string` field must be an exact match to the string
             provided by the browser. The client application must not attempt to parse
             or process the string in any way.
         :param acs: The Assertion Consumer Service URL that matches the one of the SAML
             realm in Elasticsearch that should be used. You must specify either this
-            parameter or the realm parameter.
+            parameter or the `realm` parameter.
         :param realm: The name of the SAML realm in Elasticsearch the configuration.
-            You must specify either this parameter or the acs parameter.
+            You must specify either this parameter or the `acs` parameter.
         """
         if query_string is None and body is None:
             raise ValueError("Empty value passed for parameter 'query_string'")
@@ -3284,12 +3776,19 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Logout of SAML. Submits a request to invalidate an access token and refresh token.
+        NOTE: This API is intended for use by custom web applications other than Kibana.
+        If you are using Kibana, refer to the documentation for configuring SAML single-sign-on
+        on the Elastic Stack. This API invalidates the tokens that were generated for
+        a user by the SAML authenticate API. If the SAML realm in Elasticsearch is configured
+        accordingly and the SAML IdP supports this, the Elasticsearch response contains
+        a URL to redirect the user to the IdP that contains a SAML logout request (starting
+        an SP-initiated SAML Single Logout).
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-logout.html>`_
 
         :param token: The access token that was returned as a response to calling the
             SAML authenticate API. Alternatively, the most recent token that was received
-            after refreshing the original one by using a refresh_token.
+            after refreshing the original one by using a `refresh_token`.
         :param refresh_token: The refresh token that was returned as a response to calling
             the SAML authenticate API. Alternatively, the most recent refresh token that
             was received after refreshing the original access token.
@@ -3340,19 +3839,31 @@ class SecurityClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Prepare SAML authentication. Creates a SAML authentication request (`<AuthnRequest>`)
-        as a URL string, based on the configuration of the respective SAML realm in Elasticsearch.
+        Prepare SAML authentication. Create a SAML authentication request (`<AuthnRequest>`)
+        as a URL string based on the configuration of the respective SAML realm in Elasticsearch.
+        NOTE: This API is intended for use by custom web applications other than Kibana.
+        If you are using Kibana, refer to the documentation for configuring SAML single-sign-on
+        on the Elastic Stack. This API returns a URL pointing to the SAML Identity Provider.
+        You can use the URL to redirect the browser of the user in order to continue
+        the authentication process. The URL includes a single parameter named `SAMLRequest`,
+        which contains a SAML Authentication request that is deflated and Base64 encoded.
+        If the configuration dictates that SAML authentication requests should be signed,
+        the URL has two extra parameters named `SigAlg` and `Signature`. These parameters
+        contain the algorithm used for the signature and the signature value itself.
+        It also returns a random string that uniquely identifies this SAML Authentication
+        request. The caller of this API needs to store this identifier as it needs to
+        be used in a following step of the authentication process.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-prepare-authentication.html>`_
 
         :param acs: The Assertion Consumer Service URL that matches the one of the SAML
             realms in Elasticsearch. The realm is used to generate the authentication
-            request. You must specify either this parameter or the realm parameter.
+            request. You must specify either this parameter or the `realm` parameter.
         :param realm: The name of the SAML realm in Elasticsearch for which the configuration
             is used to generate the authentication request. You must specify either this
-            parameter or the acs parameter.
+            parameter or the `acs` parameter.
         :param relay_state: A string that will be included in the redirect URL that this
-            API returns as the RelayState query parameter. If the Authentication Request
+            API returns as the `RelayState` query parameter. If the Authentication Request
             is signed, this value is used as part of the signature computation.
         """
         __path_parts: t.Dict[str, str] = {}
@@ -3397,7 +3908,10 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Create SAML service provider metadata. Generate SAML metadata for a SAML 2.0
-        Service Provider.
+        Service Provider. The SAML 2.0 specification provides a mechanism for Service
+        Providers to describe their capabilities and configuration using a metadata file.
+        This API generates Service Provider metadata based on the configuration of a
+        SAML realm in Elasticsearch.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-saml-sp-metadata.html>`_
 
@@ -3444,21 +3958,27 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Suggest a user profile. Get suggestions for user profiles that match specified
-        search criteria.
+        search criteria. NOTE: The user profile feature is designed only for use by Kibana
+        and Elastic's Observability, Enterprise Search, and Elastic Security solutions.
+        Individual users and external applications should not call this API directly.
+        Elastic reserves the right to change or remove this feature in future releases
+        without prior notice.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-suggest-user-profile.html>`_
 
-        :param data: List of filters for the `data` field of the profile document. To
-            return all content use `data=*`. To return a subset of content use `data=<key>`
-            to retrieve content nested under the specified `<key>`. By default returns
-            no `data` content.
+        :param data: A comma-separated list of filters for the `data` field of the profile
+            document. To return all content use `data=*`. To return a subset of content,
+            use `data=<key>` to retrieve content nested under the specified `<key>`.
+            By default, the API returns no `data` content. It is an error to specify
+            `data` as both the query parameter and the request body field.
         :param hint: Extra search criteria to improve relevance of the suggestion result.
             Profiles matching the spcified hint are ranked higher in the response. Profiles
-            not matching the hint don't exclude the profile from the response as long
-            as the profile matches the `name` field query.
-        :param name: Query string used to match name-related fields in user profile documents.
-            Name-related fields are the user's `username`, `full_name`, and `email`.
-        :param size: Number of profiles to return.
+            not matching the hint aren't excluded from the response as long as the profile
+            matches the `name` field query.
+        :param name: A query string used to match name-related fields in user profile
+            documents. Name-related fields are the user's `username`, `full_name`, and
+            `email`.
+        :param size: The number of profiles to return.
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_security/profile/_suggest"
@@ -3600,7 +4120,18 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Update a cross-cluster API key. Update the attributes of an existing cross-cluster
-        API key, which is used for API key based remote cluster access.
+        API key, which is used for API key based remote cluster access. To use this API,
+        you must have at least the `manage_security` cluster privilege. Users can only
+        update API keys that they created. 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. It's not possible
+        to update expired API keys, or API keys that have been invalidated by the invalidate
+        API key API. This API supports updates to an API key's access scope, metadata,
+        and expiration. The owner user's information, such as the `username` and `realm`,
+        is also updated automatically on every call. NOTE: This API cannot update REST
+        API keys, which should be updated by either the update API key or bulk update
+        API keys API.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-update-cross-cluster-api-key.html>`_
 
@@ -3609,8 +4140,8 @@ class SecurityClient(NamespacedClient):
             of permissions for cross cluster search and cross cluster replication. At
             least one of them must be specified. When specified, the new access assignment
             fully replaces the previously assigned access.
-        :param expiration: Expiration time for the API key. By default, API keys never
-            expire. This property can be omitted to leave the value unchanged.
+        :param expiration: The expiration time for the API key. By default, API keys
+            never expire. This property can be omitted to leave the value unchanged.
         :param 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. When specified, this information
@@ -3650,6 +4181,81 @@ class SecurityClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters(
+        body_fields=("security", "security_profile", "security_tokens"),
+        parameter_aliases={
+            "security-profile": "security_profile",
+            "security-tokens": "security_tokens",
+        },
+    )
+    def update_settings(
+        self,
+        *,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
+        pretty: t.Optional[bool] = None,
+        security: t.Optional[t.Mapping[str, t.Any]] = None,
+        security_profile: t.Optional[t.Mapping[str, t.Any]] = None,
+        security_tokens: t.Optional[t.Mapping[str, t.Any]] = None,
+        timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
+        body: t.Optional[t.Dict[str, t.Any]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        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`. 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.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-update-settings.html>`_
+
+        :param master_timeout: The period to wait for a connection to the master node.
+            If no response is received before the timeout expires, the request fails
+            and returns an error.
+        :param security: Settings for the index used for most security configuration,
+            including native realm users and roles configured with the API.
+        :param security_profile: Settings for the index used to store profile information.
+        :param security_tokens: Settings for the index used to store tokens.
+        :param timeout: The period to wait for a response. If no response is received
+            before the timeout expires, the request fails and returns an error.
+        """
+        __path_parts: t.Dict[str, str] = {}
+        __path = "/_security/settings"
+        __query: t.Dict[str, t.Any] = {}
+        __body: t.Dict[str, t.Any] = body if body is not None else {}
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if master_timeout is not None:
+            __query["master_timeout"] = master_timeout
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if timeout is not None:
+            __query["timeout"] = timeout
+        if not __body:
+            if security is not None:
+                __body["security"] = security
+            if security_profile is not None:
+                __body["security-profile"] = security_profile
+            if security_tokens is not None:
+                __body["security-tokens"] = security_tokens
+        __headers = {"accept": "application/json", "content-type": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "PUT",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="security.update_settings",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters(
         body_fields=("data", "labels"),
     )
@@ -3672,22 +4278,37 @@ class SecurityClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Update user profile data. Update specific data for the user profile that is associated
-        with a unique ID.
+        with a unique ID. NOTE: The user profile feature is designed only for use by
+        Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions.
+        Individual users and external applications should not call this API directly.
+        Elastic reserves the right to change or remove this feature in future releases
+        without prior notice. To use this API, you must have one of the following privileges:
+        * The `manage_user_profile` cluster privilege. * The `update_profile_data` global
+        privilege for the namespaces that are referenced in the request. This API updates
+        the `labels` and `data` fields of an existing user profile document with JSON
+        objects. New keys and their values are added to the profile document and conflicting
+        keys are replaced by data that's included in the request. For both labels and
+        data, content is namespaced by the top-level fields. The `update_profile_data`
+        global privilege grants privileges for updating only the allowed namespaces.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-update-user-profile-data.html>`_
 
         :param uid: A unique identifier for the user profile.
         :param data: Non-searchable data that you want to associate with the user profile.
-            This field supports a nested data structure.
+            This field supports a nested data structure. Within the `data` object, top-level
+            keys cannot begin with an underscore (`_`) or contain a period (`.`). The
+            data object is not searchable, but can be retrieved with the get user profile
+            API.
         :param if_primary_term: Only perform the operation if the document has this primary
             term.
         :param if_seq_no: Only perform the operation if the document has this sequence
             number.
         :param labels: Searchable data that you want to associate with the user profile.
-            This field supports a nested data structure.
+            This field supports a nested data structure. Within the labels object, top-level
+            keys cannot begin with an underscore (`_`) or contain a period (`.`).
         :param refresh: If 'true', Elasticsearch refreshes 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' do nothing with refreshes.
+            this operation visible to search. If 'wait_for', it waits for a refresh to
+            make this operation visible to search. If 'false', nothing is done with refreshes.
         """
         if uid in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'uid'")