[role="xpack"]
[[secure-reporting]]
== Configure reporting in {kib}

++++
<titleabbrev>Configure reporting</titleabbrev>
++++

To enable users to manually and automatically generate reports, install the reporting packages, grant users access to the {report-features}, and secure the reporting endpoints.

[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`

If the system is missing dependencies, *Reporting* fails in a non-deterministic way. {kib} runs a self-test at server startup, and
if it encounters errors, logs them in the Console. The error message does not include
information about why Chromium failed to run. The most common error message is `Error: connect ECONNREFUSED`, which indicates
that {kib} could not connect to the Chromium process.

To troubleshoot the problem, start the {kib} server with environment variables that tell Chromium to print verbose logs. For more information, refer to <<reporting-troubleshooting-puppeteer-debug-logs>>.

[float]
[[grant-user-access]]
=== Grant users access to reporting

When security is enabled, access to the {report-features} is controlled by roles and <<kibana-privileges, privileges>>. With privileges, you can define custom roles that grant *Reporting* privileges as sub-features of {kib} applications. To grant users permission to generate reports and view their reports in *Reporting*, create and assign the reporting role.

[[reporting-app-users]]
NOTE: In 7.12.0 and earlier, you grant access to the {report-features} by assigning users the `reporting_user` role in {es}. 

. 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*.

.. Next to the applications you want to grant reporting privileges, click *All*.
+
If the *Reporting* option is unavailable, contact your administrator, or <<reporting-advanced-settings,enable the option 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*.

[float]
[[reporting-roles-user-api]]
==== Grant access with the role API
You can also use the {ref}/security-api-put-role.html[role API] to grant access to the reporting features. Grant the reporting role to users in combination with other roles that grant read access to the data in {es}, and at least read access in the applications where users can generate reports.

[source, sh]
---------------------------------------------------------------
POST /_security/role/custom_reporting_user
{
  metadata: {},
  elasticsearch: { cluster: [], indices: [], run_as: [] },
  kibana: [
    {
      base: [],
      feature: {
        dashboard: [
          'generate_report', <1>
          'download_csv_report' <2>
        ],
        discover: ['generate_report'], <3>
        canvas: ['generate_report'], <4>
        visualize: ['generate_report'], <5>
      },
      spaces: ['*'],
    }
  ]
}
---------------------------------------------------------------
// 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 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.
