[DOCS] Add Webhook connector SSL authentication configuration details (#163983)

lcawl · web-flow · commit 4686472f9ec9 · 2023-08-23T11:45:08.000-07:00
diff --git a/docs/api-generated/connectors/connector-apis-passthru.asciidoc b/docs/api-generated/connectors/connector-apis-passthru.asciidoc
@@ -1459,7 +1459,7 @@ Any modifications made to this file will be overwritten.
       <div class="param">authType (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The type of authentication to use: basic, SSL, or none. </div>
         <div class="param-enum-header">Enum:</div>
         <div class="param-enum">webhook-authentication-basic</div><div class="param-enum">webhook-authentication-ssl</div><div class="param-enum">null</div>
-<div class="param">ca (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> A base64 encoded version of the certificate authority file, which is used to sign and validate certificates. </div>
+<div class="param">ca (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> A base64 encoded version of the certificate authority file that the connector can trust to sign and validate certificates. This option is available for all authentication types. </div>
 <div class="param">certType (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> If the <code>authType</code> is <code>webhook-authentication-ssl</code>, specifies whether the certificate authentication data is in a CRT and key file format or a PFX file format. </div>
         <div class="param-enum-header">Enum:</div>
         <div class="param-enum">ssl-crt-key</div><div class="param-enum">ssl-pfx</div>
@@ -1469,7 +1469,7 @@ Any modifications made to this file will be overwritten.
         <div class="param-enum-header">Enum:</div>
         <div class="param-enum">post</div><div class="param-enum">put</div>
 <div class="param">url (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The request URL. If you are using the <code>xpack.actions.allowedHosts</code> setting, add the hostname to the allowed hosts. </div>
-<div class="param">verificationMode (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> Controls the verification of certificates. Use <code>full</code> to validate that the provided certificate has an issue date that is within the <code>not_before</code> and <code>not_after</code> dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use <code>certificate</code> to validate the provided certificate and verifies that it is signed by a trusted authority; this option does not check the certificate hostname. Use <code>none</code> to skip certificate validation. </div>
+<div class="param">verificationMode (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> Controls the verification of certificates. Use <code>full</code> to validate that the certificate has an issue date within the <code>not_before</code> and <code>not_after</code> dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use <code>certificate</code> to validate the certificate and verify that it is signed by a trusted authority; this option does not check the certificate hostname. Use <code>none</code> to skip certificate validation. </div>
         <div class="param-enum-header">Enum:</div>
         <div class="param-enum">certificate</div><div class="param-enum">full</div><div class="param-enum">none</div>
     </div>  <!-- field-items -->
diff --git a/docs/management/connectors/action-types/webhook.asciidoc b/docs/management/connectors/action-types/webhook.asciidoc
@@ -28,49 +28,27 @@ image::management/connectors/images/webhook-connector.png[Webhook connector]
 Webhook connectors have the following configuration properties:
 
 Name::      The name of the connector.
-URL::       The request URL. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
-Method::    HTTP request method, either `post`(default) or `put`.
-Headers::   A set of key-value pairs sent as headers with the request
-Require authentication:: If true, a username and password for login type authentication must be provided.
-Username::      Username for HTTP basic authentication.
-Password::  Password for HTTP basic authentication.
-
-[float]
-[[preconfigured-webhook-configuration]]
-=== Create preconfigured connectors
-
-If you are running {kib} on-prem, you can define connectors by
-adding `xpack.actions.preconfigured` settings to your `kibana.yml` file.
-For example:
-
-[source,text]
+Method::    The HTTP request method, either `post`(default) or `put`.
+URL::       The request URL. If you are using the <<action-settings,`xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
+Authentication::
+The authentication type: none, basic, or SSL.
+If you choose basic authentication, you must provide a user name and password.
+If you choose SSL authentication, you must provide SSL server certificate authentication data in a CRT and key file format or a PFX file format. You can also optionally provide a passphrase if the files are password-protected.
+HTTP headers::   A set of key-value pairs sent as headers with the request.
+Certificate authority::
+A certificate authority (CA) that the connector can trust, for example to sign and validate server certificates.
+This option is available for all authentication types.
+CA file:::
+The certificate authority file.
+Verification mode:::
+Controls the certificate verification.
++
 --
-xpack.actions.preconfigured:
-  my-webhook:
-    name: preconfigured-webhook-connector-type
-    actionTypeId: .webhook
-    config:
-      url: https://test.host
-      method: post
-      headers:
-        testheader: testvalue
-    secrets:
-      user: testuser
-      password: passwordkeystorevalue
+* Use `full` to validate that the certificate has an issue date within the `not_before` and `not_after` dates, chains to a trusted certificate authority, and has a hostname or IP address that matches the names within the certificate.
+* Use `certificate` to validate the certificate and verifies that it is signed by a trusted authority; this option does not check the certificate hostname.
+* Use `none` to skip certificate validation.
 --
 
-Config defines information for the connector type.
-
-`url`:: A URL string that corresponds to *URL*.
-`method`:: A string that corresponds to *Method*.
-`headers`:: A record<string, string> that corresponds to *Headers*.
-`hasAuth`:: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
-
-Secrets defines sensitive information for the connector type.
-
-`user`:: A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
-`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.
-
 [float]
 [[webhook-action-configuration]]
 === Test connectors
diff --git a/docs/management/connectors/pre-configured-connectors.asciidoc b/docs/management/connectors/pre-configured-connectors.asciidoc
@@ -80,3 +80,34 @@ image::images/preconfigured-connectors-managing.png[Connectors managing tab with
 Clicking a preconfigured connector shows the description, but not the 
 configuration.
 
+[float]
+[[preconfigured-webhook-configuration]]
+=== Webhook preconfigured connector example
+
+The following example creates a <<webhook-action-type,webhook connector>> with basic authentication:
+
+[source,text]
+--
+xpack.actions.preconfigured:
+  my-webhook:
+    name: preconfigured-webhook-connector-type
+    actionTypeId: .webhook
+    config:
+      url: https://test.host <1>
+      method: post <2>
+      headers: <3>
+        testheader: testvalue
+      hasAuth: true <4>
+    secrets:
+      user: testuser <5>
+      password: passwordkeystorevalue <6>
+--
+
+<1> The web service request URL. If you are using the <<action-settings,`xpack.actions.allowedHosts`>> setting, make sure the hostname is added to the allowed hosts.
+<2> The HTTP request method, either `post`(default) or `put`.
+<3> A set of key-value pairs sent as headers with the request.
+<4> If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
+<5> A valid user name. Required if `hasAuth` is set to `true`.
+<6> A valid password. Required if `hasAuth` is set to `true`. NOTE: This value should be stored in the <<creating-keystore,{kib} keystore>>.
+
+NOTE: SSL authentication is not supported in preconfigured webhook connectors.
diff --git a/x-pack/plugins/actions/docs/openapi/bundled.json b/x-pack/plugins/actions/docs/openapi/bundled.json
@@ -2621,7 +2621,7 @@
           },
           "ca": {
             "type": "string",
-            "description": "A base64 encoded version of the certificate authority file, which is used to sign and validate certificates."
+            "description": "A base64 encoded version of the certificate authority file that the connector can trust to sign and validate certificates. This option is available for all authentication types.\n"
           },
           "certType": {
             "type": "string",
@@ -2661,7 +2661,7 @@
               "none"
             ],
             "default": "full",
-            "description": "Controls the verification of certificates. Use `full` to validate that the provided certificate has an issue date that is within the `not_before` and `not_after` dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use `certificate` to validate the provided certificate and verifies that it is signed by a trusted authority; this option does not check the certificate hostname. Use `none` to skip certificate validation.\n"
+            "description": "Controls the verification of certificates. Use `full` to validate that the certificate has an issue date within the `not_before` and `not_after` dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use `certificate` to validate the certificate and verify that it is signed by a trusted authority; this option does not check the certificate hostname. Use `none` to skip certificate validation.\n"
           }
         }
       },
diff --git a/x-pack/plugins/actions/docs/openapi/bundled.yaml b/x-pack/plugins/actions/docs/openapi/bundled.yaml
@@ -1768,7 +1768,8 @@ components:
             The type of authentication to use: basic, SSL, or none.
         ca:
           type: string
-          description: A base64 encoded version of the certificate authority file, which is used to sign and validate certificates.
+          description: |
+            A base64 encoded version of the certificate authority file that the connector can trust to sign and validate certificates. This option is available for all authentication types.
         certType:
           type: string
           description: |
@@ -1804,7 +1805,7 @@ components:
             - none
           default: full
           description: |
-            Controls the verification of certificates. Use `full` to validate that the provided certificate has an issue date that is within the `not_before` and `not_after` dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use `certificate` to validate the provided certificate and verifies that it is signed by a trusted authority; this option does not check the certificate hostname. Use `none` to skip certificate validation.
+            Controls the verification of certificates. Use `full` to validate that the certificate has an issue date within the `not_before` and `not_after` dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate. Use `certificate` to validate the certificate and verify that it is signed by a trusted authority; this option does not check the certificate hostname. Use `none` to skip certificate validation.
     secrets_properties_webhook:
       title: Connector secrets properties for a Webhook connector
       description: Defines secrets for connectors when type is `.webhook`.
diff --git a/x-pack/plugins/actions/docs/openapi/components/schemas/config_properties_webhook.yaml b/x-pack/plugins/actions/docs/openapi/components/schemas/config_properties_webhook.yaml
@@ -12,7 +12,9 @@ properties:
       The type of authentication to use: basic, SSL, or none.
   ca:
     type: string
-    description: A base64 encoded version of the certificate authority file, which is used to sign and validate certificates.
+    description: >
+      A base64 encoded version of the certificate authority file that the connector can trust to sign and validate certificates.
+      This option is available for all authentication types.
   certType:
     type: string
     description: >
@@ -50,6 +52,6 @@ properties:
     default: full
     description: >
       Controls the verification of certificates.
-      Use `full` to validate that the provided certificate has an issue date that is within the `not_before` and `not_after` dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate.
-      Use `certificate` to validate the provided certificate and verifies that it is signed by a trusted authority; this option does not check the certificate hostname.
+      Use `full` to validate that the certificate has an issue date within the `not_before` and `not_after` dates, chains to a trusted certificate authority (CA), and has a hostname or IP address that matches the names within the certificate.
+      Use `certificate` to validate the certificate and verify that it is signed by a trusted authority; this option does not check the certificate hostname.
       Use `none` to skip certificate validation.
