mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 18:51:07 -04:00
f2017fef81
# Backport This will backport the following commits from `main` to `7.17`: - [[docs] Fix wrong example and highlight Kibana API (#124347)](https://github.com/elastic/kibana/pull/124347) <!--- Backport version: 8.9.7 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Toby Sutor","email":"55087308+toby-sutor@users.noreply.github.com"},"sourceCommit":{"committedDate":"2022-12-20T15:42:15Z","message":"[docs] Fix wrong example and highlight Kibana API (#124347)\n\nThe current example contains invalid characters and does not work. Furthermore does it incorrectly point towards the Elasticsearch API instead of the Kibana API. Both is addressed in this change.\r\n\r\nCo-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>","sha":"53e42eb6339aace91c5111bdb910dec8f9dacf5e","branchLabelMapping":{"^v8.7.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","v8.0.0","release_note:skip","docs","v7.14.0","auto-backport","v7.15.0","v7.16.0","v8.1.0","v7.17.0","v8.2.0"],"number":124347,"url":"https://github.com/elastic/kibana/pull/124347","mergeCommit":{"message":"[docs] Fix wrong example and highlight Kibana API (#124347)\n\nThe current example contains invalid characters and does not work. Furthermore does it incorrectly point towards the Elasticsearch API instead of the Kibana API. Both is addressed in this change.\r\n\r\nCo-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>","sha":"53e42eb6339aace91c5111bdb910dec8f9dacf5e"}},"sourceBranch":"main","suggestedTargetBranches":["8.0","7.14","7.15","7.16","8.1","7.17","8.2"],"targetPullRequestStates":[{"branch":"8.0","label":"v8.0.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"7.14","label":"v7.14.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"7.15","label":"v7.15.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"7.16","label":"v7.16.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.1","label":"v8.1.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"7.17","label":"v7.17.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.2","label":"v8.2.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT--> Co-authored-by: Toby Sutor <55087308+toby-sutor@users.noreply.github.com>
279 lines
11 KiB
Text
279 lines
11 KiB
Text
[role="xpack"]
|
|
[[secure-reporting]]
|
|
== Configure reporting in {kib}
|
|
|
|
++++
|
|
<titleabbrev>Configure reporting</titleabbrev>
|
|
++++
|
|
|
|
For security, you grant users access to the {report-features} and secure the reporting endpoints
|
|
with TLS/SSL encryption. Additionally, you can install graphical packages into the operating system
|
|
to enable the {kib} server to have screenshotting capabilities.
|
|
|
|
* <<install-reporting-packages>>
|
|
* <<grant-user-access>>
|
|
* <<reporting-roles-user-api>>
|
|
* <<grant-user-access-basic>>
|
|
* <<grant-user-access-external-provider>>
|
|
* <<securing-reporting>>
|
|
|
|
[float]
|
|
[[install-reporting-packages]]
|
|
=== Install the reporting packages
|
|
|
|
Make sure the {kib} server operating system has the appropriate packages installed for the distribution.
|
|
|
|
If you are using CentOS/RHEL systems, install the following packages:
|
|
|
|
* `ipa-gothic-fonts`
|
|
* `xorg-x11-fonts-100dpi`
|
|
* `xorg-x11-fonts-75dpi`
|
|
* `xorg-x11-utils`
|
|
* `xorg-x11-fonts-cyrillic`
|
|
* `xorg-x11-fonts-Type1`
|
|
* `xorg-x11-fonts-misc`
|
|
* `fontconfig`
|
|
* `freetype`
|
|
|
|
If you are using Ubuntu/Debian systems, install the following packages:
|
|
|
|
* `fonts-liberation`
|
|
* `libfontconfig1`
|
|
* `libnss3`
|
|
|
|
The reporting plugin has a built-in utility to check for common issues, such as missing dependencies. See
|
|
<<reporting-diagnostics>> for more information.
|
|
|
|
[float]
|
|
[[grant-user-access]]
|
|
=== Grant users access to reporting
|
|
When security is enabled, you grant users access to {report-features} with <<kibana-privileges, {kib} application privileges>>, which allow you to create custom roles that control the spaces and applications where users generate reports.
|
|
|
|
. Enable application privileges in Reporting. To enable, turn off the default user access control features in `kibana.yml`:
|
|
+
|
|
[source,yaml]
|
|
------------------------------------
|
|
xpack.reporting.roles.enabled: false
|
|
------------------------------------
|
|
+
|
|
NOTE: If you use the default settings, you can still create a custom role that grants reporting privileges. The default role is `reporting_user`. This behavior is being deprecated and does not allow application-level access controls for {report-features}, and does not allow API keys or authentication tokens to authorize report generation. Refer to <<reporting-advanced-settings, reporting security settings>> for information and caveats about the deprecated access control features.
|
|
|
|
. Create the reporting role.
|
|
|
|
.. Open the main menu, then click *Stack Management*.
|
|
|
|
.. Click *Roles > Create role*.
|
|
|
|
. Specify the role settings.
|
|
|
|
.. Enter the *Role name*. For example, `custom_reporting_user`.
|
|
|
|
.. Specify the *Indices* and *Privileges*.
|
|
+
|
|
Access to data is an index-level privilege. For each index that contains the data you want to include in reports, add a line, then give each index `read` and `view_index_metadata` privileges.
|
|
+
|
|
For more information, refer to {ref}/security-privileges.html[Security privileges].
|
|
|
|
. Add the {kib} privileges.
|
|
|
|
.. Click *Add Kibana privilege*.
|
|
|
|
.. Select one or more *Spaces*.
|
|
|
|
.. Click *Customize*, then click *Analytics*.
|
|
|
|
.. For each application, select *All*, or to customize the privileges, select *Read* and *Customize sub-feature privileges*.
|
|
+
|
|
NOTE: If you have a Basic license, sub-feature privileges are unavailable. For details, check out <<grant-user-access-basic>>.
|
|
[role="screenshot"]
|
|
image::user/reporting/images/kibana-privileges-with-reporting.png["Kibana privileges with Reporting options, Gold or higher license"]
|
|
+
|
|
NOTE: If the *Reporting* options for application features are unavailable, and the cluster license is higher than Basic, contact your administrator, or <<reporting-advanced-settings,check that `xpack.reporting.roles.enabled` is set to `false` in kibana.yml>>.
|
|
|
|
.. Click *Add {kib} privilege*.
|
|
|
|
. Click *Create role*.
|
|
|
|
. Assign the reporting role to a user.
|
|
|
|
.. Open the main menu, then click *Stack Management*.
|
|
|
|
.. Click *Users*, then click the user you want to assign the reporting role to.
|
|
|
|
.. From the *Roles* dropdown, select *custom_reporting_user*.
|
|
|
|
.. Click *Update user*.
|
|
|
|
Granting the privilege to generate reports also grants the user the privilege to view their reports in *Stack Management > Reporting*. Users can only access their own reports.
|
|
|
|
[float]
|
|
[[reporting-roles-user-api]]
|
|
==== Grant access with the role API
|
|
With <<grant-user-access, {kib} application privileges>> enabled in Reporting, you can also use the {ref}/security-api-put-role.html[role API] to grant access to the {report-features}, using *All* privileges, or sub-feature privileges.
|
|
|
|
NOTE: this [API request](https://www.elastic.co/guide/en/kibana/current/role-management-api-put.html) needs to be executed against the Kibana API endpoint
|
|
[source, sh]
|
|
---------------------------------------------------------------
|
|
POST <kibana host>:<port>/api/_security/role/custom_reporting_user
|
|
{
|
|
"elasticsearch": {
|
|
"cluster": [],
|
|
"indices": [],
|
|
"run_as": []
|
|
},
|
|
"kibana": [{
|
|
"spaces": ["*"],
|
|
"base": [],
|
|
"feature": {
|
|
"dashboard": ["generate_report", <1>
|
|
"download_csv_report"], <2>
|
|
"discover": ["generate_report"], <3>
|
|
"canvas": ["generate_report"], <4>
|
|
"visualize": ["generate_report"] <5>
|
|
}
|
|
}]
|
|
}
|
|
---------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
<1> Grants access to generate PNG and PDF reports in *Dashboard*.
|
|
<2> Grants access to download CSV files from saved search panels in *Dashboard*.
|
|
<3> Grants access to generate CSV reports from saved searches in *Discover*.
|
|
<4> Grants access to generate PDF reports in *Canvas*.
|
|
<5> Grants access to generate PNG and PDF reports in *Visualize Library*.
|
|
|
|
[float]
|
|
[[grant-user-access-basic]]
|
|
=== Grant users access with a Basic license
|
|
|
|
With a Basic license, you can grant users access with custom roles to {report-features} with <<kibana-privileges, {kib} application privileges>>. However, with a Basic license, sub-feature privileges are unavailable. <<grant-user-access,Create a role>>, then select *All* privileges for the applications where users can create reports.
|
|
|
|
[role="screenshot"]
|
|
image::user/reporting/images/kibana-privileges-with-reporting-basic.png["Kibana privileges with Reporting options, Basic license"]
|
|
|
|
With a Basic license, sub-feature application privileges are unavailable, but you can use the {ref}/security-api-put-role.html[role API] to grant access to CSV {report-features}:
|
|
|
|
[source, sh]
|
|
---------------------------------------------------------------
|
|
PUT localhost:5601/api/security/role/custom_reporting_user
|
|
{
|
|
"elasticsearch": { "cluster": [], "indices": [], "run_as": [] },
|
|
"kibana": [
|
|
{
|
|
"base": [],
|
|
"feature": {
|
|
"dashboard": [ "all" ], <1>
|
|
"discover": [ "all" ], <2>
|
|
},
|
|
"spaces": [ "*" ]
|
|
}
|
|
],
|
|
"metadata": {} // optional
|
|
}
|
|
---------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
<1> Grants access to generate CSV reports from saved searches in *Discover*.
|
|
<2> Grants access to download CSV reports from saved search panels in *Dashboard*.
|
|
|
|
[float]
|
|
[[grant-user-access-external-provider]]
|
|
==== Grant access using an external provider
|
|
|
|
If you are using an external identity provider, such as LDAP or Active Directory, you can assign roles to individual users or groups of users. Role mappings are configured in {ref}/mapping-roles.html[`config/role_mapping.yml`].
|
|
|
|
For example, assign the `kibana_admin` and `reporting_user` roles to the Bill Murray user:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------------------------------------
|
|
kibana_admin:
|
|
- "cn=Bill Murray,dc=example,dc=com"
|
|
reporting_user:
|
|
- "cn=Bill Murray,dc=example,dc=com"
|
|
--------------------------------------------------------------------------------
|
|
|
|
[float]
|
|
==== Grant access with a custom index
|
|
|
|
If you are using a custom index, the `xpack.reporting.index` setting must begin with `.reporting-*`. The default {kib} system user has `all` privileges against the `.reporting-*` pattern of indices.
|
|
|
|
If you use a different pattern for the `xpack.reporting.index` setting, you must create a custom `kibana_system` user with appropriate access to the index.
|
|
|
|
NOTE: In the next major version of Kibana, granting access with a custom index is unsupported.
|
|
|
|
. Create the reporting role.
|
|
|
|
.. Open the main menu, then click *Stack Management*.
|
|
|
|
.. Click *Roles > Create role*.
|
|
|
|
. Specify the role settings.
|
|
|
|
.. Enter the *Role name*. For example, `custom-reporting-user`.
|
|
|
|
.. From the *Indices* dropdown, select the custom index.
|
|
|
|
.. From the *Privileges* dropdown, select *all*.
|
|
|
|
.. Click *Add Kibana privilege*.
|
|
|
|
.. Select one or more *Spaces* that you want to grant reporting privileges to.
|
|
|
|
.. Click *Customize*, then click *Analytics*.
|
|
|
|
.. Next to each application you want to grant reporting privileges to, click *All*.
|
|
|
|
.. Click *Add {kib} privilege*, then click *Create role*.
|
|
|
|
. Assign the reporting role to a user.
|
|
|
|
.. Open the main menu, then click *Stack Management*.
|
|
|
|
.. Click *Users*, then click the user you want to assign the reporting role to.
|
|
|
|
.. From the *Roles* dropdown, select *kibana_system* and *custom-reporting-user*.
|
|
|
|
.. Click *Update user*.
|
|
|
|
. Configure {kib} to use the new account.
|
|
+
|
|
[source,js]
|
|
--------------------------------------------------------------------------------
|
|
elasticsearch.username: 'custom_kibana_system'
|
|
--------------------------------------------------------------------------------
|
|
|
|
[float]
|
|
[[securing-reporting]]
|
|
=== Secure the reporting endpoints
|
|
|
|
To automatically generate reports with {watcher}, you must configure {watcher} to trust the {kib} server certificate.
|
|
|
|
. Enable {stack-security-features} on your {es} cluster. For more information, see {ref}/security-getting-started.html[Getting started with security].
|
|
|
|
. Configure TLS/SSL encryption for the {kib} server. For more information, see <<configuring-tls>>.
|
|
|
|
. Specify the {kib} server CA certificate chain in `elasticsearch.yml`:
|
|
+
|
|
--
|
|
If you are using your own CA to sign the {kib} server certificate, then you need to specify the CA certificate chain in {es} to properly establish trust in TLS connections between {watcher} and {kib}. If your CA certificate chain is contained in a PKCS #12 trust store, specify it like so:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------------------------------------
|
|
xpack.http.ssl.truststore.path: "/path/to/your/truststore.p12"
|
|
xpack.http.ssl.truststore.type: "PKCS12"
|
|
xpack.http.ssl.truststore.password: "optional decryption password"
|
|
--------------------------------------------------------------------------------
|
|
|
|
Otherwise, if your CA certificate chain is in PEM format, specify it like so:
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------------------------------------
|
|
xpack.http.ssl.certificate_authorities: ["/path/to/your/cacert1.pem", "/path/to/your/cacert2.pem"]
|
|
--------------------------------------------------------------------------------
|
|
|
|
For more information, see {ref}/notification-settings.html#ssl-notification-settings[the {watcher} HTTP TLS/SSL Settings].
|
|
--
|
|
|
|
. Add one or more users who have access to the {report-features}.
|
|
+
|
|
Once you've enabled SSL for {kib}, all requests to the reporting endpoints must include valid credentials.
|