OpenSearch/x-pack/docs/en/rest-api/security/saml-authenticate-api.asciidoc

[role="xpack"]
[[security-api-saml-authenticate]]
=== SAML authenticate API

Submits a SAML `Response` message to {es} for consumption.

NOTE: This API is intended for use by custom web applications other than {kib}.
If you are using {kib}, see the <<saml-guide>>.

[[security-api-saml-authenticate-request]]
==== {api-request-title}

`POST /_security/saml/authenticate`

[[security-api-saml-authenticate-desc]]
==== {api-description-title}

The SAML message that is submitted can be:

* a response to a SAML authentication request that was previously created using the
<<security-api-saml-prepare-authentication, 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, {es} responds with an
{es} 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 {es} access and refresh tokens,
which can be used for authentication against {es}.

{es} exposes all the necessary SAML related functionality via the SAML APIs.
These APIs are used internally by {kib} in order to provide SAML based
authentication, but can also be used by other, custom web applications or other
clients. See also
<<security-api-saml-prepare-authentication,SAML prepare authentication API>>,
<<security-api-saml-invalidate,SAML invalidate API>> and
<<security-api-saml-logout,SAML logout API>>.


[[security-api-saml-authenticate-request-body]]
==== {api-request-body-title}

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

[[security-api-saml-authenticate-response-body]]
==== {api-response-body-title}

`access_token`::
  (string) The access token that was generated by {es}.
`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 {es}.
`realm`::
  (string) The name of the realm that the user was authenticated by.

[[security-api-saml-authenticate-example]]
==== {api-examples-title}

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

[source,console]
--------------------------------------------------
POST /_security/saml/authenticate
{
  "content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
  "ids" : ["4fee3b046395c4e751011e97f8900b5273d56685"]
}
--------------------------------------------------
// TEST[skip:handled in IT]

The API returns the following response:

[source,js]
--------------------------------------------------
{
  "access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
  "username" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "mJdXLtmvTUSpoLwMvdBt_w",
  "realm": "saml1"
}
--------------------------------------------------
// NOTCONSOLE