IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« SAML prepare authentication API SAML logout API »
Elastic Docs ›Elasticsearch Guide [8.15] ›REST APIs ›Security APIs

SAML authenticate API

edit

SAML authenticate API

edit

Submits a SAML Response message to Elasticsearch for consumption.

This API is intended for use by custom web applications other than Kibana. If you are using Kibana, see the Configuring SAML single-sign-on on the Elastic Stack.

Request

edit

POST /_security/saml/authenticate

Description

edit

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

Elasticsearch exposes all the necessary SAML related functionality via the SAML APIs. These APIs are used internally by Kibana in order to provide SAML based authentication, but can also be used by other, custom web applications or other clients. See also SAML prepare authentication API, SAML invalidate API, SAML logout API, and SAML complete logout API.

Request body

edit
content
(Required, string) The SAML response as it was sent by the user’s browser, usually a Base64 encoded XML document.
ids
(Required, array) A json array with all the valid SAML Request Ids that the caller of the API has for the current user.
realm
(Optional, string) The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined.

Response body

edit
access_token
(string) The access token that was generated by Elasticsearch.
username
(string) The authenticated user’s name.
expires_in
(integer) The amount of time (in seconds) left until the token expires.
refresh_token
(string) The refresh token that was generated by Elasticsearch.
realm
(string) The name of the realm that the user was authenticated by.

Examples

edit

The following example exchanges a SAML Response indicating a successful authentication at the SAML IdP for an Elasticsearch access token and refresh token to be used in subsequent requests:

resp = client.security.saml_authenticate(
    content="PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
    ids=[
        "4fee3b046395c4e751011e97f8900b5273d56685"
    ],
)
print(resp)
const response = await client.security.samlAuthenticate({
  content:
    "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
  ids: ["4fee3b046395c4e751011e97f8900b5273d56685"],
});
console.log(response);
POST /_security/saml/authenticate
{
  "content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
  "ids" : ["4fee3b046395c4e751011e97f8900b5273d56685"]
}

The API returns the following response:

{
  "access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
  "username" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "mJdXLtmvTUSpoLwMvdBt_w",
  "realm": "saml1"
}
« SAML prepare authentication API SAML logout API »