async def saml_prepare_authentication(
        self,
        *,
        acs: 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,
        relay_state: t.Optional[str] = None,
        body: t.Optional[t.Dict[str, t.Any]] = None,
    ) -> ObjectApiResponse[t.Any]:
        """
        .. raw:: html

          <p>Prepare SAML authentication.</p>
          <p>Create a SAML authentication request (<code>&lt;AuthnRequest&gt;</code>) as a URL string based on the configuration of the respective SAML realm in Elasticsearch.</p>
          <p>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.</p>
          <p>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 <code>SAMLRequest</code>, 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 <code>SigAlg</code> and <code>Signature</code>.
          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.</p>


        `<https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-saml-prepare-authentication>`_

        :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.
        :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.
        :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
            is signed, this value is used as part of the signature computation.
        """
        __path_parts: t.Dict[str, str] = {}
        __path = "/_security/saml/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 acs is not None:
                __body["acs"] = acs
            if realm is not None:
                __body["realm"] = realm
            if relay_state is not None:
                __body["relay_state"] = relay_state
        __headers = {"accept": "application/json", "content-type": "application/json"}
        return await self.perform_request(  # type: ignore[return-value]
            "POST",
            __path,
            params=__query,
            headers=__headers,
            body=__body,
            endpoint_id="security.saml_prepare_authentication",
            path_parts=__path_parts,
        )

        .. raw:: html

          <p>Prepare SAML authentication.</p>
          <p>Create a SAML authentication request (<code>&lt;AuthnRequest&gt;</code>) as a URL string based on the configuration of the respective SAML realm in Elasticsearch.</p>
          <p>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.</p>
          <p>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 <code>SAMLRequest</code>, 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 <code>SigAlg</code> and <code>Signature</code>.
          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.</p>


        `<https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-saml-prepare-authentication>`_

        :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.
        :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.
        :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
            is signed, this value is used as part of the signature computation.
        
elasticsearch/_async/client/security.py