Prepare SAML authentication Added in 7.5.0

POST /_security/saml/prepare
Api key auth Basic auth Bearer auth

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.

External documentation
application/json

Body Required

  • acs string

    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.

  • realm string

    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.

  • relay_state string

    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.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • id string Required
    • realm string Required

      The name of the Elasticsearch realm that was used to construct the authentication request.

    • redirect string Required

      The URL to redirect the user to.
POST /_security/saml/prepare 
curl \
 --request POST http://api.example.com/_security/saml/prepare \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"acs":"string","realm":"string","relay_state":"string"}'
Request examples 
{
  "acs": "string",
  "realm": "string",
  "relay_state": "string"
}
Response examples (200) 
{
  "id": "string",
  "realm": "string",
  "redirect": "string"
}