mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 21:18:31 +00:00
09773efb41
This is useful in cases where the caller of the API needs to know the name of the realm that consumed the SAML Response and authenticated the user and this is not self evident (i.e. because there are many saml realms defined in ES). Currently, the way to learn the realm name would be to make a subsequent request to the `_authenticate` API.
101 lines
3.5 KiB
Plaintext
101 lines
3.5 KiB
Plaintext
[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
|