Add docs and rest api spec for saml complete logout API (elastic#72867)

This PR adds the documentation and Rest API spec file for the SAML complete
logout API. It is a (overdued) follow up for elastic#56316

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
+    }
+  }
+}

x-pack/docs/en/rest-api/security.asciidoc

@@ -116,6 +116,7 @@ realm when using a custom web application other than Kibana
 * <<security-api-saml-authenticate, Submit an authentication response>>
 * <<security-api-saml-logout, Logout an authenticated user>>
 * <<security-api-saml-invalidate, Submit a logout request from the IdP>>
+* <<security-api-saml-complete-logout, Verify a logout response from the IdP>>
 * <<security-api-saml-sp-metadata,Generate SAML metadata>>
 
 
@@ -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[]

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
 <<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-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]]

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
+++++
+<titleabbrev>SAML complete logout</titleabbrev>
+++++
+
+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 <<saml-guide>>.
+
+[[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 <<security-api-saml-logout,SP-initiated SAML Single Logout>>.
+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 <<security-api-saml-authenticate,SAML authenticate API>>,
+<<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-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.

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 <<security-api-saml-authenticate,SAML authenticate API>>,
 <<security-api-saml-prepare-authentication,SAML prepare authentication API>>,
-and <<security-api-saml-logout,SAML logout API>>.
+<<security-api-saml-logout,SAML logout API>>, and
+<<security-api-saml-complete-logout, SAML complete logout API>>.
 
 [[security-api-saml-invalidate-request-body]]
 ==== {api-request-body-title}
@@ -39,11 +40,11 @@ and <<security-api-saml-logout,SAML logout API>>.
   (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`::

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 <<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-invalidate,SAML invalidate API>>, and
+<<security-api-saml-complete-logout, SAML complete logout API>>.
 
 [[security-api-saml-logout-request-body]]
 ==== {api-request-body-title}
@@ -47,7 +48,7 @@ and <<security-api-saml-invalidate,SAML invalidate API>>.
   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

x-pack/docs/en/rest-api/security/saml-prepare-authentication-api.asciidoc

@@ -34,8 +34,9 @@ the authentication process (see <<security-api-saml-authenticate,SAML authentica
 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-invalidate,SAML invalidate API>>, and
-<<security-api-saml-logout,SAML logout 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-prepare-authentication-request-body]]
 ==== {api-request-body-title}
@@ -51,7 +52,7 @@ clients. See also <<security-api-saml-authenticate,SAML authenticate API>>,
   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

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 <<security-api-saml-complete-logout,SAML complete logout API>>.