From 4686472f9ec930c1cfe56d87f70e4ce2dcc70be4 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 23 Aug 2023 11:45:08 -0700 Subject: [PATCH] [DOCS] Add Webhook connector SSL authentication configuration details (#163983) --- .../connector-apis-passthru.asciidoc | 4 +- .../connectors/action-types/webhook.asciidoc | 58 ++++++------------- .../pre-configured-connectors.asciidoc | 31 ++++++++++ .../plugins/actions/docs/openapi/bundled.json | 4 +- .../plugins/actions/docs/openapi/bundled.yaml | 5 +- .../schemas/config_properties_webhook.yaml | 8 ++- 6 files changed, 61 insertions(+), 49 deletions(-) diff --git a/docs/api-generated/connectors/connector-apis-passthru.asciidoc b/docs/api-generated/connectors/connector-apis-passthru.asciidoc index 08a7d8d9638b0..f5128f88f1b1e 100644 --- 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.
authType (optional)
String The type of authentication to use: basic, SSL, or none.
Enum:
webhook-authentication-basic
webhook-authentication-ssl
null
-
ca (optional)
String A base64 encoded version of the certificate authority file, which is used to sign and validate certificates.
+
ca (optional)
String 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 (optional)
String If the authType is webhook-authentication-ssl, specifies whether the certificate authentication data is in a CRT and key file format or a PFX file format.
Enum:
ssl-crt-key
ssl-pfx
@@ -1469,7 +1469,7 @@ Any modifications made to this file will be overwritten.
Enum:
post
put
url (optional)
String The request URL. If you are using the xpack.actions.allowedHosts setting, add the hostname to the allowed hosts.
-
verificationMode (optional)
String 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.
+
verificationMode (optional)
String 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.
Enum:
certificate
full
none
diff --git a/docs/management/connectors/action-types/webhook.asciidoc b/docs/management/connectors/action-types/webhook.asciidoc index 89c7a618ecbc7..1868f96d14c1d 100644 --- 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 <> 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 <> 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 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 <>. 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 index 43643f0f611ba..9284a66ea9480 100644 --- 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 <> 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 <> 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 <>. + +NOTE: SSL authentication is not supported in preconfigured webhook connectors. \ No newline at end of file diff --git a/x-pack/plugins/actions/docs/openapi/bundled.json b/x-pack/plugins/actions/docs/openapi/bundled.json index a42bc290c753f..67191da3842d6 100644 --- 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 index 24d7b2ac6fe7c..5da86f4563a6c 100644 --- 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 index 8047f963352b9..fe45366eca264 100644 --- 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.