Add examples for security SAML APIs

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -672,9 +672,10 @@ security-api-suggest,https://www.elastic.co/guide/en/elasticsearch/reference/{br
 security-api-cross-cluster-key-update,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-cross-cluster-api-key.html
 security-api-update-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-api-key.html
 security-api-update-user-data,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-user-profile-data.html
-security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html
 security-api-update-settings,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-update-settings.html
 security-encrypt-internode,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-basic-setup.html#encrypt-internode-communication
+security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html
+security-saml-guide,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/saml-guide-stack.html
 service-accounts,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/service-accounts.html
 set-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/set-processor.html
 shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shape.html

output/schema/schema.json

@@ -23,11 +23,25 @@ import { Ids } from '@_types/common'
 /**
  * Authenticate SAML.
  *
- * Submits a SAML response message to Elasticsearch for consumption.
+ * Submit a SAML response message to Elasticsearch for consumption.
+ *
+ * NOTE: This API is intended for use by custom web applications other than Kibana.
+ * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.
+ *
+ * The SAML message that is submitted can be:
+ *
+ * * A response to a SAML authentication request that was previously created using the SAML prepare authentication API.
+ * * An unsolicited SAML message in the case of an IdP-initiated single sign-on (SSO) flow.
+ *
+ * In either case, the SAML message needs to be a base64 encoded XML document with a root element of `<Response>`.
+ *
+ * After successful validation, Elasticsearch responds with an Elasticsearch 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 Elasticsearch access and refresh tokens, which can be used for authentication against Elasticsearch.
  * @rest_spec_name security.saml_authenticate
  * @availability stack since=7.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id security-api-saml-authenticate
+ * @ext_doc_id security-saml-guide
  */
 export interface Request extends RequestBase {
   urls: [
@@ -37,9 +51,9 @@ export interface Request extends RequestBase {
     }
   ]
   body: {
-    /** The SAML response as it was sent by the user’s browser, usually a Base64 encoded XML document. */
+    /** The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document. */
     content: string
-    /** A json array with all the valid SAML Request Ids that the caller of the API has for the current user. */
+    /** A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. */
     ids: Ids
     /** The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined. */
     realm?: string

specification/_doc_ids/table.csv

@@ -21,10 +21,25 @@ import { integer } from '@_types/Numeric'
 
 export class Response {
   body: {
+    /**
+     * The access token that was generated by Elasticsearch.
+     */
     access_token: string
+    /**
+     * The authenticated user's name.
+     */
     username: string
+    /**
+     * The amount of time (in seconds) left until the token expires.
+     */
     expires_in: integer
+    /**
+     * The refresh token that was generated by Elasticsearch.
+     */
     refresh_token: string
+    /**
+     * The name of the realm where the user was authenticated.
+     */
     realm: string
   }
 }

specification/security/saml_authenticate/Request.ts

@@ -0,0 +1,10 @@
+# summary:
+# method_request: POST /_security/saml/authenticate
+description: >
+  Run `POST /_security/saml/authenticate` to exchange a SAML Response indicating a successful authentication at the SAML IdP for an Elasticsearch access token and refresh token to be used in subsequent requests.
+# type: request
+value: |-
+  {
+    "content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
+    "ids" : ["4fee3b046395c4e751011e97f8900b5273d56685"]
+  }

specification/security/saml_authenticate/Response.ts

@@ -0,0 +1,12 @@
+# summary:
+description: A successful response from `POST /_security/saml/authenticate`.
+# type: response
+# response_code:
+value: |-
+  {
+    "access_token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
+    "username" : "Bearer",
+    "expires_in" : 1200,
+    "refresh_token": "mJdXLtmvTUSpoLwMvdBt_w",
+    "realm": "saml1"
+  }

specification/security/saml_authenticate/examples/request/RequestExample1.yaml

@@ -24,10 +24,20 @@ import { Ids } from '@_types/common'
  * Logout of SAML completely.
  *
  * Verifies the logout response sent from the SAML IdP.
+ *
+ * NOTE: This API is intended for use by custom web applications other than Kibana.
+ * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.
+ *
+ * The SAML IdP may send a logout response back to the SP after handling the 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.
  * @rest_spec_name security.saml_complete_logout
  * @availability stack since=7.14.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id security-api-saml-complete-logout
+ * @ext_doc_id security-saml-guide
  */
 export interface Request extends RequestBase {
   urls: [
@@ -39,9 +49,11 @@ export interface Request extends RequestBase {
   body: {
     /** The name of the SAML realm in Elasticsearch for which the configuration is used to verify the logout response. */
     realm: string
-    /**  A json array with all the valid SAML Request Ids that the caller of the API has for the current user. */
+    /**  A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. */
     ids: Ids
-    /** 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. */
+    /**
+     * 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.
+     */
     query_string?: 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. */
     content?: string

specification/security/saml_authenticate/examples/response/ResponseExample1.yaml

@@ -20,5 +20,8 @@
 import { Void } from '@spec_utils/VoidValue'
 
 export class Response {
+  /**
+   * The API returns an empty response on success.
+   */
   body: Void
 }

specification/security/saml_complete_logout/Request.ts

@@ -0,0 +1,11 @@
+summary: HTTP-Redirect binding
+# method_request: POST /_security/saml/complete_logout
+description: >
+  Run `POST /_security/saml/complete_logout` to verify the logout response sent by the SAML IdP using the HTTP-Redirect binding.
+# type: request
+value: |-
+  {
+    "realm": "saml1",
+    "ids": [ "_1c368075e0b3..." ],
+    "query_string": "SAMLResponse=fZHLasMwEEVbfb1bf...&SigAlg=http%3A%2F%2Fwww.w3.org%2F2000%2F09%2Fxmldsig%23rsa-sha1&Signature=CuCmFn%2BLqnaZGZJqK..."
+  }

specification/security/saml_complete_logout/Response.ts

@@ -0,0 +1,11 @@
+summary: HTTP-Post binding
+# method_request: POST /_security/saml/complete_logout
+description: >
+  Run `POST /_security/saml/complete_logout` to verify the logout response sent by the SAML IdP using the HTTP-Post binding.
+# type: request
+value: |-
+  {
+    "realm": "saml1",
+    "ids": [ "_1c368075e0b3..." ],
+    "content": "PHNhbWxwOkxvZ291dFJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46..."
+  }

specification/security/saml_complete_logout/examples/request/RequestExample1.yaml

@@ -22,11 +22,20 @@ import { RequestBase } from '@_types/Base'
 /**
  * Invalidate SAML.
  *
- * Submits a SAML LogoutRequest message to Elasticsearch for consumption.
+ * Submit a SAML LogoutRequest message to Elasticsearch for consumption.
+ *
+ * NOTE: This API is intended for use by custom web applications other than Kibana.
+ * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.
+ *
+ * The logout request comes from the SAML IdP during an IdP initiated Single Logout.
+ * The custom web application can use this API to have Elasticsearch process the `LogoutRequest`.
+ * After successful validation of the request, Elasticsearch invalidates the access token and refresh token that corresponds to that specific SAML principal and provides a URL that contains a SAML LogoutResponse message.
+ * Thus the user can be redirected back to their IdP.
  * @rest_spec_name security.saml_invalidate
  * @availability stack since=7.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id security-api-saml-invalidate
+ * @ext_doc_id security-saml-guide
  */
 export interface Request extends RequestBase {
   urls: [
@@ -36,17 +45,17 @@ export interface Request extends RequestBase {
     }
   ]
   body: {
-    /** The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the realm parameter. */
+    /** The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this parameter or the `realm` parameter. */
     acs?: 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, 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 Elasticsearch to be able to verify the IdP’s signature, the value of the query_string field must be an exact match to the string provided by the browser.
+     * 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, 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 Elasticsearch to be able to verify the IdP's signature, the value of the `query_string` field must be an exact match to the string provided by the browser.
      * The client application must not attempt to parse or process the string in any way.
      */
     query_string: string
-    /** The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the acs parameter. */
+    /** The name of the SAML realm in Elasticsearch the configuration. You must specify either this parameter or the `acs` parameter. */
     realm?: string
   }
 }

specification/security/saml_complete_logout/examples/request/RequestExample2.yaml

@@ -21,8 +21,17 @@ import { integer } from '@_types/Numeric'
 
 export class Response {
   body: {
+    /**
+     * The number of tokens that were invalidated as part of this logout.
+     */
     invalidated: integer
+    /**
+     * The realm name of the SAML realm in Elasticsearch that authenticated the user.
+     */
     realm: string
+    /**
+     * A SAML logout response as a parameter so that the user can be redirected back to the SAML IdP.
+     */
     redirect: string
   }
 }

specification/security/saml_invalidate/Request.ts

@@ -0,0 +1,10 @@
+# summary:
+# method_request: POST /_security/saml/invalidate
+description: >
+  Run `POST /_security/saml/invalidate` to invalidate all the tokens for realm `saml1` pertaining to the user that is identified in the SAML Logout Request.
+# type: request
+value: |-
+  {
+    "query_string" : "SAMLRequest=nZFda4MwFIb%2FiuS%2BmviRpqFaClKQdbvo2g12M2KMraCJ9cRR9utnW4Wyi13sMie873MeznJ1aWrnS3VQGR0j4mLkKC1NUeljjA77zYyhVbIE0dR%2By7fmaHq7U%2BdegXWGpAZ%2B%2F4pR32luBFTAtWgUcCv56%2Fp5y30X87Yz1khTIycdgpUW9kY7WdsC9zxoXTvMvWuVV98YyMnSGH2SYE5pwALBIr9QKiwDGpW0oGVUznGeMyJZKFkQ4jBf5HnhUymjIhzCAL3KNFihbYx8TBYzzGaY7EnIyZwHzCWMfiDnbRIftkSjJr%2BFu0e9v%2B0EgOquRiiZjKpiVFp6j50T4WXoyNJ%2FEWC9fdqc1t%2F1%2B2F3aUpjzhPiXpqMz1%2FHSn4A&SigAlg=http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=MsAYz2NFdovMG2mXf6TSpu5vlQQyEJAg%2B4KCwBqJTmrb3yGXKUtIgvjqf88eCAK32v3eN8vupjPC8LglYmke1ZnjK0%2FKxzkvSjTVA7mMQe2AQdKbkyC038zzRq%2FYHcjFDE%2Bz0qISwSHZY2NyLePmwU7SexEXnIz37jKC6NMEhus%3D",
+    "realm" : "saml1"
+  }

specification/security/saml_invalidate/Response.ts

@@ -0,0 +1,10 @@
+# summary:
+description: A successful response from `POST /_security/saml/invalidate`.
+# type: response
+# response_code:
+value: |-
+  {
+    "redirect" : "https://my-idp.org/logout/SAMLResponse=....",
+    "invalidated" : 2,
+    "realm" : "saml1"
+  }

specification/security/saml_invalidate/examples/request/RequestExample1.yaml

@@ -23,10 +23,17 @@ import { RequestBase } from '@_types/Base'
  * Logout of SAML.
  *
  * Submits a request to invalidate an access token and refresh token.
+ *
+ * NOTE: This API is intended for use by custom web applications other than Kibana.
+ * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.
+ *
+ * This API invalidates the tokens that were generated for a user by the SAML authenticate API.
+ * If the SAML realm in Elasticsearch is configured accordingly and the SAML IdP supports this, the Elasticsearch response contains a URL to redirect the user to the IdP that contains a SAML logout request (starting an SP-initiated SAML Single Logout).
  * @rest_spec_name security.saml_logout
  * @availability stack since=7.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id security-api-saml-logout
+ * @ext_doc_id security-saml-guide
  */
 export interface Request extends RequestBase {
   urls: [
@@ -38,7 +45,7 @@ export interface Request extends RequestBase {
   body: {
     /**
      * The access token that was returned as a response to calling the SAML authenticate API.
-     * Alternatively, the most recent token that was received after refreshing the original one by using a refresh_token.
+     * Alternatively, the most recent token that was received after refreshing the original one by using a `refresh_token`.
      */
     token: string
     /**

specification/security/saml_invalidate/examples/response/ResponseExample1.yaml

@@ -19,6 +19,10 @@
 
 export class Response {
   body: {
+    /**
+     * A URL that contains a SAML logout request as a parameter.
+     * You can use this URL to be redirected back to the SAML IdP and to initiate Single Logout.
+     */
     redirect: string
   }
 }

specification/security/saml_logout/Request.ts

@@ -0,0 +1,10 @@
+# summary:
+# method_request: POST /_security/saml/logout
+description: >
+  Run `POST /_security/saml/logout` to invalidate the pair of tokens that were generated by calling the SAML authenticate API with a successful SAML response.
+# type: request
+value: |-
+  {
+    "token" : "46ToAxZVaXVVZTVKOVF5YU04ZFJVUDVSZlV3",
+    "refresh_token" : "mJdXLtmvTUSpoLwMvdBt_w"
+  }

specification/security/saml_logout/Response.ts

@@ -0,0 +1,8 @@
+# summary:
+description: A successful response from `POST /_security/saml/logout`.
+# type: response
+# response_code:
+value: |-
+  {
+    "redirect" : "https://my-idp.org/logout/SAMLRequest=...."
+  }

specification/security/saml_logout/examples/request/RequestExample1.yaml

@@ -22,11 +22,23 @@ import { RequestBase } from '@_types/Base'
 /**
  * Prepare SAML authentication.
  *
- * Creates a SAML authentication request (`<AuthnRequest>`) as a URL string, based on the configuration of the respective SAML realm in Elasticsearch.
+ * Create a SAML authentication request (`<AuthnRequest>`) as a URL string based on the configuration of the respective SAML realm in Elasticsearch.
+ *
+ * NOTE: This API is intended for use by custom web applications other than Kibana.
+ * If you are using Kibana, refer to the documentation for configuring SAML single-sign-on on the Elastic Stack.
+ *
+ * This API returns a URL pointing to the SAML Identity Provider.
+ * You can use the URL to redirect the browser of the user in order to continue the authentication process.
+ * The URL includes a single parameter named `SAMLRequest`, which contains a SAML Authentication request that is deflated and Base64 encoded.
+ * If the configuration dictates that SAML authentication requests should be signed, the URL has two extra parameters named `SigAlg` and `Signature`.
+ * These parameters contain the algorithm used for the signature and the signature value itself.
+ * It also returns a random string that uniquely identifies this SAML Authentication request.
+ * The caller of this API needs to store this identifier as it needs to be used in a following step of the authentication process.
  * @rest_spec_name security.saml_prepare_authentication
  * @availability stack since=7.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id security-api-saml-prepare-authentication
+ * @ext_doc_id security-saml-guide
  */
 export interface Request extends RequestBase {
   urls: [
@@ -38,16 +50,16 @@ export interface Request extends RequestBase {
   body: {
     /**
      * The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch.
-     * The realm is used to generate the authentication request. You must specify either this parameter or the realm parameter.
+     * The realm is used to generate the authentication request. You must specify either this parameter or the `realm` parameter.
      */
     acs?: string
     /**
      * The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request.
-     * You must specify either this parameter or the acs parameter.
+     * You must specify either this parameter or the `acs` parameter.
      */
     realm?: string
     /**
-     * A string that will be included in the redirect URL that this API returns as the RelayState query parameter.
+     * A string that will be included in the redirect URL that this API returns as the `RelayState` query parameter.
      * If the Authentication Request is signed, this value is used as part of the signature computation.
      */
     relay_state?: string

specification/security/saml_logout/examples/response/ResponseExample1.yaml

@@ -21,8 +21,17 @@ import { Id } from '@_types/common'
 
 export class Response {
   body: {
+    /**
+     * A unique identifier for the SAML Request to be stored by the caller of the API.
+     */
     id: Id
+    /**
+     * The name of the Elasticsearch realm that was used to construct the authentication request.
+     */
     realm: string
+    /**
+     * The URL to redirect the user to.
+     */
     redirect: string
   }
 }

specification/security/saml_prepare_authentication/Request.ts

@@ -0,0 +1,9 @@
+summary: Prepare with a realm
+# method_request: POST /_security/saml/prepare
+description: >
+  Run `POST /_security/saml/prepare` to generate a SAML authentication request for the SAML realm named `saml1`.
+# type: request
+value: |-
+  {
+    "realm" : "saml1"
+  }

specification/security/saml_prepare_authentication/Response.ts

@@ -0,0 +1,9 @@
+summary: Prepare with an ACS
+# method_request: POST /_security/saml/prepare
+description: >
+  Run `POST /_security/saml/prepare` to generate a SAML authentication request for the SAML realm with an Assertion Consuming Service (ACS) URL.
+# type: request
+value: |-
+  {
+    "acs" : "https://kibana.org/api/security/saml/callback"
+  }