From bdc72b45924ce2c25cab500352ae47c1fb9d360e Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Mon, 31 May 2021 11:28:16 +1000 Subject: [PATCH] Add docs and rest api spec for saml complete logout API (#72867) This PR adds the documentation and Rest API spec file for the SAML complete logout API. It is a (overdued) follow up for #56316 --- .../api/security.saml_complete_logout.json | 28 ++++++ x-pack/docs/en/rest-api/security.asciidoc | 2 + .../security/saml-authenticate-api.asciidoc | 5 +- .../saml-complete-logout-api.asciidoc | 89 +++++++++++++++++++ .../security/saml-invalidate-api.asciidoc | 11 +-- .../security/saml-logout-api.asciidoc | 5 +- .../saml-prepare-authentication-api.asciidoc | 7 +- .../authentication/saml-guide.asciidoc | 3 + 8 files changed, 138 insertions(+), 12 deletions(-) create mode 100644 rest-api-spec/src/main/resources/rest-api-spec/api/security.saml_complete_logout.json create mode 100644 x-pack/docs/en/rest-api/security/saml-complete-logout-api.asciidoc diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/security.saml_complete_logout.json b/rest-api-spec/src/main/resources/rest-api-spec/api/security.saml_complete_logout.json new file mode 100644 index 0000000000000..8a17b7a81c107 --- /dev/null +++ b/rest-api-spec/src/main/resources/rest-api-spec/api/security.saml_complete_logout.json @@ -0,0 +1,28 @@ +{ + "security.saml_complete_logout":{ + "documentation":{ + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-saml-complete-logout.html", + "description":"Verifies the logout response sent from the SAML IdP" + }, + "stability":"stable", + "visibility":"public", + "headers":{ + "accept": [ "application/json"], + "content_type": ["application/json"] + }, + "url":{ + "paths":[ + { + "path":"/_security/saml/complete_logout", + "methods":[ + "POST" + ] + } + ] + }, + "body":{ + "description":"The logout response to verify", + "required":true + } + } +} diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index a19aa6c469815..554bf2071bb28 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -116,6 +116,7 @@ realm when using a custom web application other than Kibana * <> * <> * <> +* <> * <> @@ -160,5 +161,6 @@ include::security/saml-prepare-authentication-api.asciidoc[] include::security/saml-authenticate-api.asciidoc[] include::security/saml-logout-api.asciidoc[] include::security/saml-invalidate-api.asciidoc[] +include::security/saml-complete-logout-api.asciidoc[] include::security/saml-sp-metadata.asciidoc[] include::security/ssl.asciidoc[] diff --git a/x-pack/docs/en/rest-api/security/saml-authenticate-api.asciidoc b/x-pack/docs/en/rest-api/security/saml-authenticate-api.asciidoc index fbac7645ad914..c8bf40b2d9d61 100644 --- a/x-pack/docs/en/rest-api/security/saml-authenticate-api.asciidoc +++ b/x-pack/docs/en/rest-api/security/saml-authenticate-api.asciidoc @@ -38,8 +38,9 @@ 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 <>, -<> and -<>. +<>, +<>, and +<>. [[security-api-saml-authenticate-request-body]] diff --git a/x-pack/docs/en/rest-api/security/saml-complete-logout-api.asciidoc b/x-pack/docs/en/rest-api/security/saml-complete-logout-api.asciidoc new file mode 100644 index 0000000000000..7969e723c2bf6 --- /dev/null +++ b/x-pack/docs/en/rest-api/security/saml-complete-logout-api.asciidoc @@ -0,0 +1,89 @@ +[role="xpack"] +[[security-api-saml-complete-logout]] +=== SAML complete logout API +++++ +SAML complete logout +++++ + +Verifies the logout response sent from the SAML IdP. + +NOTE: This API is intended for use by custom web applications other than {kib}. +If you are using {kib}, see the <>. + +[[security-api-saml-complete-logout-request]] +==== {api-request-title} + +`POST /_security/saml/complete_logout` + +[[security-api-saml-complete-logout-desc]] +==== {api-description-title} + +The SAML IdP may send a logout response back to the SP after handling +the <>. +This API verifies the response by ensuring the content is relevant +and validating its signature. An empty response is returned if +the verification process is successful. +The response can be sent by the IdP with either the HTTP-Redirect or +the HTTP-Post binding. The caller of this API must prepare the request +accordingly so that this API can handle either of them. + +{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 <>, +<>, +<>, and +<>. + +[[security-api-saml-complete-logout-request-body]] +==== {api-request-body-title} + +`realm`:: + (Required, string) The name of the SAML realm in {es} for which the configuration is + used to verify the logout response. + +`ids`:: + (Required, array) A json array with all the valid SAML Request Ids that the caller of + the API has for the current user. + +`queryString`:: + (Optional, string) If the SAML IdP sends the logout response with the HTTP-Redirect + binding, this field must be set to the query string of the redirect URI. + +`content`:: + (Optional, string) If the SAML IdP sends the logout response with the HTTP-Post + binding, this field must be set to the value of the `SAMLResponse` form parameter + from the logout response. + +[[security-api-saml-complete-logout-example]] +==== {api-examples-title} + +The following example verifies the logout response sent by the SAML IdP +using the HTTP-Redirect binding: + +[source,console] +-------------------------------------------------- +POST /_security/saml/complete_logout +{ + "realm": "saml1", + "ids": [ "_1c368075e0b3..." ], + "queryString": "SAMLResponse=fZHLasMwEEVbfb1bf...&SigAlg=http%3A%2F%2Fwww.w3.org%2F2000%2F09%2Fxmldsig%23rsa-sha1&Signature=CuCmFn%2BLqnaZGZJqK..." +} +-------------------------------------------------- +// TEST[skip:can't test this without a valid SAML Logout Response] + +If the logout response is sent with the HTTP-Post binding, it can be verified +as the follows: + +[source,console] +-------------------------------------------------- +POST /_security/saml/complete_logout +{ + "realm": "saml1", + "ids": [ "_1c368075e0b3..." ], + "content": "PHNhbWxwOkxvZ291dFJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46..." +} +-------------------------------------------------- +// TEST[skip:can't test this without a valid SAML Logout Response] + +The API returns an empty response on success. diff --git a/x-pack/docs/en/rest-api/security/saml-invalidate-api.asciidoc b/x-pack/docs/en/rest-api/security/saml-invalidate-api.asciidoc index 23ca1508c5b59..8e43d3175a9b3 100644 --- a/x-pack/docs/en/rest-api/security/saml-invalidate-api.asciidoc +++ b/x-pack/docs/en/rest-api/security/saml-invalidate-api.asciidoc @@ -30,7 +30,8 @@ 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 <>, <>, -and <>. +<>, and +<>. [[security-api-saml-invalidate-request-body]] ==== {api-request-body-title} @@ -39,11 +40,11 @@ and <>. (Optional, string) The Assertion Consumer Service URL that matches the one of the SAML realm in {es} that should be used. You must specify either this parameter or the `realm` parameter. -`queryString`:: +`queryString`:: (Required, string) The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout. This query should include a single parameter named `SAMLRequest` that contains a SAML logout request that is - deflated and Base64 encoded. If the SAML IdP has signed the logout request, + deflated and Base64 encoded. If the SAML IdP has signed the logout request, the URL should include two extra parameters named `SigAlg` and `Signature` that contain the algorithm used for the signature and the signature value itself. In order for {es} to be able to verify the IdP's signature, the value of the queryString field must be an exact match to the string provided by the browser. @@ -54,12 +55,12 @@ The client application must not attempt to parse or process the string in any wa either this parameter or the `acs` parameter. [[security-api-saml-invalidate-response-body]] -==== {api-response-body-title} +==== {api-response-body-title} `invalidated`:: (integer) The number of tokens that were invalidated as part of this logout. -`realm`:: +`realm`:: (string) The realm name of the SAML realm in {es} that authenticated the user. `redirect`:: diff --git a/x-pack/docs/en/rest-api/security/saml-logout-api.asciidoc b/x-pack/docs/en/rest-api/security/saml-logout-api.asciidoc index 71738021ecc4f..5333ae0a717b1 100644 --- a/x-pack/docs/en/rest-api/security/saml-logout-api.asciidoc +++ b/x-pack/docs/en/rest-api/security/saml-logout-api.asciidoc @@ -30,7 +30,8 @@ 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 <>, <>, -and <>. +<>, and +<>. [[security-api-saml-logout-request-body]] ==== {api-request-body-title} @@ -47,7 +48,7 @@ and <>. most recent refresh token that was received after refreshing the original access token. [[security-api-saml-logout-response-body]] -==== {api-response-body-title} +==== {api-response-body-title} `redirect`:: (string) A URL that contains a SAML logout request as a parameter. The user diff --git a/x-pack/docs/en/rest-api/security/saml-prepare-authentication-api.asciidoc b/x-pack/docs/en/rest-api/security/saml-prepare-authentication-api.asciidoc index d3b66596294e4..470aa747fbf7e 100644 --- a/x-pack/docs/en/rest-api/security/saml-prepare-authentication-api.asciidoc +++ b/x-pack/docs/en/rest-api/security/saml-prepare-authentication-api.asciidoc @@ -34,8 +34,9 @@ the authentication process (see <>, -<>, and -<>. +<>, +<>, and +<>. [[security-api-saml-prepare-authentication-request-body]] ==== {api-request-body-title} @@ -51,7 +52,7 @@ clients. See also <>, parameter. [[security-api-saml-prepare-authentication-response-body]] -==== {api-response-body-title} +==== {api-response-body-title} `id`:: (string) A unique identifier for the SAML Request to be stored by the caller diff --git a/x-pack/docs/en/security/authentication/saml-guide.asciidoc b/x-pack/docs/en/security/authentication/saml-guide.asciidoc index eb8038d8446a7..a28d1056d5c0f 100644 --- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc @@ -1028,3 +1028,6 @@ POST /_security/saml/invalidate The custom web application will then need to also handle the response, which will include a `redirect` parameter with a URL in the IdP that contains the SAML Logout response. The application should redirect the user there to complete the logout. + +For SP-initiated Single Logout, the IdP may send back a logout response which can be verified by {es} +using the <>.