
[[kibana]]
=== Using Kibana with Shield

Shield supports both Kibana 3 and Kibana 4.0+ releases. The configuration required differs
between Kibana 3 and 4. Please follow the instructions below for the version of Kibana you are working with.

[float]
==== Using Kibana 3 with Shield

Shield and Kibana 3 have been tested together for recent versions of Chrome, Safari, and IE. This section describes
configuration changes and general information to ensure that the two products work together successfully for you.

Kibana 3 uses the `kibana-int` index to store saved dashboards. All users store dashboards in this index. Enable all
users to save and load dashboards from this index. When the Shield plugin is installed, users may be able to load
dashboards that access data in indices that they are not authorized to view. A user that loads such a dashboard
will receive a Kibana error stating that the disallowed index does not exist.

At the moment, there is no way to control which users can load which dashboards. We expect to address this
limitation with future versions of Shield and Kibana.

[float]
===== Configuring Kibana 3 
Kibana will need to be informed that you wish use credentials. In Kibana's `config.js` set the `elasticsearch` property:

[source,yaml]
------------------------------------
elasticsearch: {server: "http://YOUR_ELASTICSEARCH_SERVER:9200", withCredentials: true}
------------------------------------

[float]
[[cors]]
===== Enabling CORS in Elasticsearch

HTTP authentication interacts with cross-origin resource sharing (CORS). Clusters that use CORS must send authentication
headers to the browser.

In the `elasticsearch.yml` file on all nodes, add the following configuration entries:

[source,yaml]
------------------------------------
http.cors.enabled: true
http.cors.allow-origin: "https://MYHOST:MYPORT"
http.cors.allow-credentials: true
------------------------------------

Note that in `http.cors.allow-origin`, `*` is disallowed for credentialed requests. You must enter the correct
protocol, hostname and port that would normally be entered into your browser.

Restart the nodes after modifying the configuration file. This change enables Elasticsearch to send the required
`Access-Control-Allow-Credentials` header.

NOTE: To learn more about enabling CORS, see http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-http.html[Elasticsearch Reference].

[float]
===== Configuring Shield for Kibana 3

Shield includes a default <<roles,role>> for use with Kibana 3:

[source,yaml]
------------------------------------------------------------------------------------------------------------------------
kibana3:
  cluster: cluster:monitor/nodes/info
  indices:
    '*': indices:data/read/search, indices:data/read/get, indices:admin/get <1>
    'kibana-int': indices:data/read/get, indices:data/read/search, indices:data/write/delete, indices:data/write/index,
                  create_index
------------------------------------------------------------------------------------------------------------------------

<1> This line gives the Kibana 3 user read access to indices in order to search and display the data in them. To
constrain this role's access to specific indices, alter the wildcard.

Kibana 3 uses the `kibana-int` index to save and load dashboards. This role definition allows the user to manage and
use the dashboards in the `kibana-int` index.

Kibana 3 uses the cluster permission to access the `/_nodes` endpoint in order to check the node version.

Elasticsearch recommends that you create one or more roles derived from this role. These new roles will include access to
indices specified by your organization's goals and policies.

==== SSL/TLS and browsers

===== Trusting certificates
As discussed in <<securing-communications, Securing Communications>>, Shield supports adding SSL to the Elasticsearch HTTP interface.
When using Kibana, your browser verifies that the certificate received from the Elasticsearch node is trusted
before sending a request to the node. Establishing this trust requires that either your browser or operating
system trust the Certificate Authority (CA) that signed the node's certificate. To use SSL with Shield and
Kibana 3, ensure that the browser or operating system has been configured to trust this CA.

[float]
===== Configuring Your Browser to Use SSL
As discussed in <<securing-communications, Securing Communications with Encryption and IP Filtering>>, Shield supports adding SSL to the Elasticsearch HTTP interface. 
When using Kibana, your browser verifies that the certificate received from the Elasticsearch node is trusted 
before sending a request to the node. Establishing this trust requires that either your browser or operating 
system trust the Certificate Authority (CA) that signed the node's certificate. To use SSL with Shield and 
Kibana 3, ensure that the browser or operating system has been configured to trust this CA. 

The process to ensure this trust varies per organization. Some organizations will have pre-installed these CA
certificates into the operating system or the browser's local certificate store. If this is the case, you will
not need to take any further action.

Other organizations will not have pre-installed the CA certificate. Or you may have created your own CA as discussed 
in <<certificate-authority, Setting Up a Certificate Authority>>. In these cases, we recommend that you consult your local IT professional to 
determine the recommended procedure for adding trusted CAs in your organization. 

[float]
===== Working with source builds of Kibana 3

Some developers use Kibana 3 by pulling the software from our GitHub repository, and not using a built package
from our download site. If you do this, be sure to clear your browser's cache after deploying Shield and
configuring the `http.cors.allow-credentials` parameter to avoid authentication errors with most browsers.

[float]
==== Using Kibana 4 with Shield

Kibana 4 adds a server-side component that changes the integration with Shield and the steps required to configure Shield, Elasticsearch, and Kibana to work together. With Kibana 4, the browser makes requests to the Kibana 4 server, and not to Elasticsearch directly. The Kibana 4 server then makes requests to Elasticsearch on behalf of the browser. We recommend using separate roles for your users who log into Kibana and for the Kibana 4 server itself.

[float]
[[kibana4-roles]]
===== Configuring Roles for Kibana 4 Users

Kibana users need access to the indices that they will be working with and the `.kibana` index where their
saved searches, visualizations, and dashboards are stored.  Shield includes a default `kibana4` role that grants
read access to all indices and full access to the `.kibana` index.

IMPORTANT: The default Kibana 4 user role grants read access to all indices. We strongly recommend deriving
custom roles for your Kibana users that limit access to specific indices according to your organization's goals and policies.

[source,yaml]
------------------------------------------------------------------------------------------------------------------------
kibana4:
  cluster:
      - cluster:monitor/nodes/info
      - cluster:monitor/health
  indices:
    '*':
      - indices:admin/mappings/fields/get
      - indices:admin/validate/query
      - indices:data/read/search
      - indices:data/read/msearch
    '.kibana':
      - indices:admin/create
      - indices:admin/exists
      - indices:admin/mapping/put
      - indices:admin/mappings/fields/get
      - indices:admin/refresh
      - indices:admin/validate/query
      - indices:data/read/get
      - indices:data/read/mget
      - indices:data/read/search
      - indices:data/write/delete
      - indices:data/write/index
      - indices:data/write/update
      - indices:admin/create
------------------------------------------------------------------------------------------------------------------------

To constrain Kibana's access to specific indices, explicitly specify the index names in your role. When configuring a role for a Kibana user and granting access to a specific index, at a minimum the user needs the following privileges on the index:

* `indices:admin/mappings/fields/get`
* `indices:admin/validate/query`
* `indices:data/read/search`
* `indices:data/read/msearch`
* `indices:admin/get`

[float]
[[kibana4-server-role]]
===== Configuring a Role for the Kibana 4 Server

The Kibana 4 server needs access to the cluster monitoring APIs and the `.kibana` index. However, the server
does not need access to user indexes. The following `kibana4_server` role shows the privileges required
by the Kibana 4 server.

NOTE: This role is included in roles.yml by default as of Shield 1.1. If you are running an older version of Shield,
you need to add it yourself.

[source,yaml]
------------------------------------------------------------------------------------------------------------------------
kibana4_server:
  cluster:
      - cluster:monitor/nodes/info
      - cluster:monitor/health
  indices:
    '.kibana':
      - indices:admin/exists
      - indices:admin/mapping/put
      - indices:admin/mappings/fields/get
      - indices:admin/refresh
      - indices:admin/validate/query
      - indices:data/read/get
      - indices:data/read/mget
      - indices:data/read/search
      - indices:data/write/delete
      - indices:data/write/index
      - indices:data/write/update
------------------------------------------------------------------------------------------------------------------------

To configure the Kibana 4 server, you must assign this role to a user and add the user credentials to `kibana.yml`.
For more information, see http://www.elastic.co/guide/en/kibana/current/production.html#configuring-kibana-shield[Configuring Kibana to Work with Shield] in the Kibana 4 User Guide.

[float]
===== Configuring Kibana 4 to Use SSL

You should also configure Kibana 4 to use SSL encryption for both client requests and the requests the Kibana server sends to Elasticsearch. For more information, see http://www.elastic.co/guide/en/kibana/current/production.html#enabling-ssl[Enabling SSL] in the Kibana 4 User Guide.
