elasticsearch/x-pack/docs/en/rest-api/security/saml-logout-api.asciidoc

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

Submits a request to invalidate an access token and refresh token.

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-logout-request]]
==== {api-request-title}

`POST /_security/saml/logout`

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

This API invalidates the tokens that were generated for a user by the
<<security-api-saml-authenticate,SAML authenticate API>>.

If the SAML realm in {es} is configured accordingly and the SAML IdP supports
this, the {es} response contains a URL to redirect the user to the IdP
that contains a SAML logout request (starting an SP-initiated SAML Single Logout).

{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-authenticate,SAML authenticate API>>,
<<security-api-saml-prepare-authentication,SAML prepare authentication API>>,
and <<security-api-saml-invalidate,SAML invalidate API>>.

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

`token`::
  (Required, string) The access token that was returned as a response to calling the
  <<security-api-saml-authenticate,SAML authenticate API>>. Alternatively, the most
  recent token that was received after refreshing the original one by using a
  `refresh_token`.

`refresh_token`::
  (Optional, string) The refresh token that was returned as a response to calling the
  <<security-api-saml-authenticate,SAML authenticate API>>. Alternatively, the
  most recent refresh token that was received after refreshing the original access token.

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

`redirect`::
  (string) A URL that contains a SAML logout request as a parameter. The user
  can use this URL to be redirected back to the SAML IdP and to initiate Single
  Logout.

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

The following example invalidates the pair of tokens that were generated by
calling the <<security-api-saml-authenticate,SAML authenticate API>>
with a successful SAML response:

[source,console]
--------------------------------------------------
POST /_security/saml/logout
{
  "token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
  "refresh_token" : "mJdXLtmvTUSpoLwMvdBt_w"
}
--------------------------------------------------
// TEST[skip:can't test this without a valid SAML Response]

The API returns the following response:

[source,js]
--------------------------------------------------
{
  "redirect" : "https://my-idp.org/logout/SAMLRequest=...."
}
--------------------------------------------------
// NOTCONSOLE