From 2ee177a4162427519bd2dcd93630e50c291bcef1 Mon Sep 17 00:00:00 2001 From: Derek Ditch Date: Tue, 4 Jun 2019 12:24:16 -0500 Subject: [PATCH 1/5] [DOCS] Updates for API usage --- docs/api/spaces-management/post.asciidoc | 17 +++++++++-------- docs/api/using-api.asciidoc | 23 +++++++++++++---------- docs/setup/settings.asciidoc | 16 +++++++++------- 3 files changed, 31 insertions(+), 25 deletions(-) diff --git a/docs/api/spaces-management/post.asciidoc b/docs/api/spaces-management/post.asciidoc index d8c194d8dc2b5..8226a999f21f9 100644 --- a/docs/api/spaces-management/post.asciidoc +++ b/docs/api/spaces-management/post.asciidoc @@ -16,28 +16,29 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi [[spaces-api-post-request-body]] ==== Request body -`id`:: +`id`:: (Required, string) The space ID that is part of the Kibana URL when inside the space. You are unable to change the ID with the update operation. -`name`:: +`name`:: (Required, string) The display name for the space. -`description`:: +`description`:: (Optional, string) The description for the space. -`disabledFeatures`:: +`disabledFeatures`:: (Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <>. -`initials`:: +`initials`:: (Optional, string) Specifies the initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters. -`color`:: +`color`:: (Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name. +NOTE: The hexadecimal color code must include only lowercase letters. -`imageUrl`:: +`imageUrl`:: (Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images. - + [[spaces-api-post-response-codes]] ==== Response codes diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc index 82071af463636..93f8bf1dfb4ee 100644 --- a/docs/api/using-api.asciidoc +++ b/docs/api/using-api.asciidoc @@ -1,7 +1,7 @@ [[using-api]] == Using the APIs -Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols. +Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols. It is recommended that you use HTTPs on port 5601 because it is more secure. @@ -34,13 +34,16 @@ For example, the following `curl` command exports a dashboard: curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" -- -The following {kib} APIs are available: +[float] +[[api-request-headers]] +=== Request headers + +For all non whitelisted APIs, you must use a header. For information on how to whitelist APIs, refer to the <> documentation. + +{kib} APIs support the following headers: + +`kbn-xsrf: true`:: + By default, {kib} requires the `kbn-xsrf` header for all API interactions. -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +`Content-Type: application/json`:: + {kib} APIs use JSON for the request and response bodies. To interact with the APIs, configure the `Content-Type` accordingly. diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index f2c06a3737c7c..e0aebaa3fabb9 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -32,7 +32,7 @@ strongly recommend that you keep the default CSP rules that ship with Kibana. `csp.strict:`:: *Default: `true`* Blocks access to Kibana to any browser that does not enforce even rudimentary CSP rules. In practice, this will disable -support for older, less safe browsers like Internet Explorer. +support for older, less safe browsers like Internet Explorer. See <> for more information. `csp.warnLegacyBrowsers:`:: *Default: `true`* Shows a warning message after @@ -316,19 +316,21 @@ all http requests to https over the port configured as `server.port`. `server.ssl.supportedProtocols:`:: *Default: TLSv1.1, TLSv1.2* An array of supported protocols with versions. Valid protocols: `TLSv1`, `TLSv1.1`, `TLSv1.2` +`server.xsrf.whitelist:`:: Definition. + `status.allowAnonymous:`:: *Default: false* If authentication is enabled, setting this to `true` enables unauthenticated users to access the Kibana server status API and status page. -`telemetry.allowChangingOptInStatus`:: *Default: true*. If `true`, -users are able to change the telemetry setting at a later time in -<>. If `false`, -{kib} looks at the value of `telemetry.optIn` to determine whether to send +`telemetry.allowChangingOptInStatus`:: *Default: true*. If `true`, +users are able to change the telemetry setting at a later time in +<>. If `false`, +{kib} looks at the value of `telemetry.optIn` to determine whether to send telemetry data or not. `telemetry.allowChangingOptInStatus` and `telemetry.optIn` cannot be `false` at the same time. -`telemetry.optIn`:: *Default: true* If `true`, telemetry data is sent to Elastic. - If `false`, collection of telemetry data is disabled. +`telemetry.optIn`:: *Default: true* If `true`, telemetry data is sent to Elastic. + If `false`, collection of telemetry data is disabled. To enable telemetry and prevent users from disabling it, set `telemetry.allowChangingOptInStatus` to `false` and `telemetry.optIn` to `true`. From 27befa278f90bbf7f327a4eb757e10d77555af97 Mon Sep 17 00:00:00 2001 From: KOTungseth Date: Wed, 4 Dec 2019 16:44:40 -0600 Subject: [PATCH 2/5] Changes from Larry --- docs/api/spaces-management/post.asciidoc | 1 - docs/api/using-api.asciidoc | 29 +++++++++++++++++++++--- docs/setup/settings.asciidoc | 5 +++- 3 files changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/api/spaces-management/post.asciidoc b/docs/api/spaces-management/post.asciidoc index 8226a999f21f9..4d4627e98899e 100644 --- a/docs/api/spaces-management/post.asciidoc +++ b/docs/api/spaces-management/post.asciidoc @@ -33,7 +33,6 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi `color`:: (Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name. -NOTE: The hexadecimal color code must include only lowercase letters. `imageUrl`:: (Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images. diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc index 93f8bf1dfb4ee..9d2ca4400defa 100644 --- a/docs/api/using-api.asciidoc +++ b/docs/api/using-api.asciidoc @@ -38,12 +38,35 @@ curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?das [[api-request-headers]] === Request headers -For all non whitelisted APIs, you must use a header. For information on how to whitelist APIs, refer to the <> documentation. +For all non whitelisted APIs, you must use a header. {kib} APIs support the following headers: `kbn-xsrf: true`:: - By default, {kib} requires the `kbn-xsrf` header for all API interactions. + By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios: + +* The request includes `GET` or `HEAD` + +* The path is whitelisted using the <> setting + +* XSRF protections are disabled using the `server.xsrf.disableProtection` setting `Content-Type: application/json`:: - {kib} APIs use JSON for the request and response bodies. To interact with the APIs, configure the `Content-Type` accordingly. + {kib} APIs use JSON for requests and responses. To make an API call, configure the `Content-Type` accordingly. + +Request header example: + +[source,sh] +-- +curl -X POST \ + http://localhost:5601/api/spaces/space \ + -H 'Content-Type: application/json' \ + -H 'kbn-xsrf: true' \ + -d '{ + "id": "sales", + "name": "Sales", + "description": "This is your Sales Space!", + "disabledFeatures": [] +} +' +-- diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index e0aebaa3fabb9..8e81fbb5060be 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -316,7 +316,10 @@ all http requests to https over the port configured as `server.port`. `server.ssl.supportedProtocols:`:: *Default: TLSv1.1, TLSv1.2* An array of supported protocols with versions. Valid protocols: `TLSv1`, `TLSv1.1`, `TLSv1.2` -`server.xsrf.whitelist:`:: Definition. +`server.xsrf.whitelist:`:: It is not recommended to disable protections for +arbitrary API endpoints. Instead, supply the `kbn-xsrf` header. There are some +scenarios where whitelisting is required, however, such as +<>. `status.allowAnonymous:`:: *Default: false* If authentication is enabled, setting this to `true` enables unauthenticated users to access the Kibana From c192e664349a1622e7edefdfe25353df3b17c6f3 Mon Sep 17 00:00:00 2001 From: Kaarina Tungseth Date: Mon, 9 Dec 2019 11:20:49 -0600 Subject: [PATCH 3/5] Update docs/api/using-api.asciidoc Co-Authored-By: Larry Gregory --- docs/api/using-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc index 9d2ca4400defa..13034f487aa83 100644 --- a/docs/api/using-api.asciidoc +++ b/docs/api/using-api.asciidoc @@ -45,7 +45,7 @@ For all non whitelisted APIs, you must use a header. `kbn-xsrf: true`:: By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios: -* The request includes `GET` or `HEAD` +* The API endpoint uses the `GET` or `HEAD` methods * The path is whitelisted using the <> setting From 0f0291bdf9c8a86e277234707ac515850b544872 Mon Sep 17 00:00:00 2001 From: KOTungseth Date: Mon, 9 Dec 2019 11:57:40 -0600 Subject: [PATCH 4/5] Comments from Larry --- docs/api/using-api.asciidoc | 6 ++---- docs/setup/settings.asciidoc | 7 +++++++ 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc index 9d2ca4400defa..b367c8925d8a4 100644 --- a/docs/api/using-api.asciidoc +++ b/docs/api/using-api.asciidoc @@ -38,9 +38,7 @@ curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?das [[api-request-headers]] === Request headers -For all non whitelisted APIs, you must use a header. - -{kib} APIs support the following headers: +For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsrf` and `Content-Type` headers. `kbn-xsrf: true`:: By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios: @@ -52,7 +50,7 @@ For all non whitelisted APIs, you must use a header. * XSRF protections are disabled using the `server.xsrf.disableProtection` setting `Content-Type: application/json`:: - {kib} APIs use JSON for requests and responses. To make an API call, configure the `Content-Type` accordingly. + Applicable only when you send a payload in the API request. {kib} APIs use JSON for requests and responses. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. Request header example: diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index 8e81fbb5060be..f2559b3035175 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -320,6 +320,13 @@ supported protocols with versions. Valid protocols: `TLSv1`, `TLSv1.1`, `TLSv1.2 arbitrary API endpoints. Instead, supply the `kbn-xsrf` header. There are some scenarios where whitelisting is required, however, such as <>. +The `server.xsrf.whitelist` setting requires the following format: + +[source,text] + +---- +*Default: [ ]* An array of API endpoints which should be exempt from Cross-Site Request Forgery ("XSRF") protections. +---- `status.allowAnonymous:`:: *Default: false* If authentication is enabled, setting this to `true` enables unauthenticated users to access the Kibana From ef523d6e8f2f0282ec478f6fb1aa984958e34de1 Mon Sep 17 00:00:00 2001 From: KOTungseth Date: Mon, 9 Dec 2019 12:05:54 -0600 Subject: [PATCH 5/5] Comment from Larry --- docs/api/using-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc index b367c8925d8a4..fe99824fcdefa 100644 --- a/docs/api/using-api.asciidoc +++ b/docs/api/using-api.asciidoc @@ -50,7 +50,7 @@ For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsr * XSRF protections are disabled using the `server.xsrf.disableProtection` setting `Content-Type: application/json`:: - Applicable only when you send a payload in the API request. {kib} APIs use JSON for requests and responses. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. + Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. Request header example: