From 89a85f39dc2956e32aa4398e356c6e4fbd66cdcc Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Mon, 10 May 2021 11:50:00 +1000 Subject: [PATCH 1/4] Add docs and rest api spec for saml complete logout --- .../api/security.saml_complete_logout.json | 27 ++++++ x-pack/docs/en/rest-api/security.asciidoc | 1 + .../security/saml-authenticate-api.asciidoc | 5 +- .../saml-complete-logout-api.asciidoc | 90 +++++++++++++++++++ .../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, 137 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..be78af3ecbab6 --- /dev/null +++ b/rest-api-spec/src/main/resources/rest-api-spec/api/security.saml_complete_logout.json @@ -0,0 +1,27 @@ +{ + "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"] + }, + "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 e653f52bf3212..5123e8510bdb2 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -103,6 +103,7 @@ realm when using a custom web application other than Kibana * <> * <> * <> +* <> * <> 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..7cc655424ad4f --- /dev/null +++ b/x-pack/docs/en/rest-api/security/saml-complete-logout-api.asciidoc @@ -0,0 +1,90 @@ +[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 eaae843b19966..f3398c062abcf 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 cba268d864f78..2f74e495ce95a 100644 --- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc @@ -1037,3 +1037,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 <>. From 3fe45e4ddcb83b9d277d1802ae4bbd7df0c6233d Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Mon, 10 May 2021 12:01:22 +1000 Subject: [PATCH 2/4] Fix docs build --- x-pack/docs/en/rest-api/security.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 5123e8510bdb2..1a3aa1a6e6a34 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -143,5 +143,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[] From 86f8d4116a18214ff8e46237084508f32865b51c Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Mon, 10 May 2021 12:16:20 +1000 Subject: [PATCH 3/4] remove linebreak --- .../en/rest-api/security/saml-complete-logout-api.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) 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 index 7cc655424ad4f..7969e723c2bf6 100644 --- 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 @@ -67,8 +67,7 @@ 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..." + "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] From 224e8d313bae1c0d7512076a1ebee70bc6753459 Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Mon, 31 May 2021 10:41:37 +1000 Subject: [PATCH 4/4] address feedback --- .../rest-api-spec/api/security.saml_complete_logout.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 index be78af3ecbab6..8a17b7a81c107 100644 --- 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 @@ -7,7 +7,8 @@ "stability":"stable", "visibility":"public", "headers":{ - "accept": [ "application/json"] + "accept": [ "application/json"], + "content_type": ["application/json"] }, "url":{ "paths":[