mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 23:57:20 -04:00
255c9a7f95
**Problem:** For historical reasons, source files for the Elasticsearch Guide's security, watcher, and Logstash API docs are housed in the `x-pack/docs` directory. This can confuse new contributors who expect Elasticsearch Guide docs to be located in `docs/reference`. **Solution:** - Move the security, watcher, and Logstash API doc source files to the `docs/reference` directory - Update doc snippet tests to use security Rel: https://github.com/elastic/platform-docs-team/issues/208
104 lines
3.6 KiB
Text
104 lines
3.6 KiB
Text
[role="xpack"]
|
|
[[security-api-saml-authenticate]]
|
|
=== SAML authenticate API
|
|
++++
|
|
<titleabbrev>SAML authenticate</titleabbrev>
|
|
++++
|
|
|
|
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-stack>>.
|
|
|
|
[[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>>,
|
|
<<security-api-saml-logout,SAML logout API>>, and
|
|
<<security-api-saml-complete-logout, SAML complete 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
|