Skip to content

Commit

Permalink
[DOCS] Add Webhook connector SSL authentication configuration details (
Browse files Browse the repository at this point in the history
  • Loading branch information
lcawl authored Aug 23, 2023
1 parent 505d826 commit 4686472
Show file tree
Hide file tree
Showing 6 changed files with 61 additions and 49 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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 -->
Expand Down
58 changes: 18 additions & 40 deletions docs/management/connectors/action-types/webhook.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
31 changes: 31 additions & 0 deletions docs/management/connectors/pre-configured-connectors.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 2 additions & 2 deletions x-pack/plugins/actions/docs/openapi/bundled.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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"
}
}
},
Expand Down
5 changes: 3 additions & 2 deletions x-pack/plugins/actions/docs/openapi/bundled.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand Down Expand Up @@ -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`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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: >
Expand Down Expand Up @@ -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.

0 comments on commit 4686472

Please sign in to comment.