Using Kibana with Shield

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Using Kibana with Shield

Shield supports both Kibana 3 and Kibana 4.0 and later. To set things up, you need to update your Kibana configuration and define and assign roles for your Kibana users in Shield. If you’re using Kibana 3, you also need to enable cross-origin resource sharing (CORS) in Elasticsearch. If you’re using Kibana 4, you need to configure credentials for the Kibana server. The following sections provide step-by-step instructions for using Kibana 3 and Kibana 4 with Shield.

With Shield installed, if you load a Kibana dashboard that accesses data in an index that you are not authorized to view, you get an error that indicates the index does not exist. Kibana and Shield do not currently provide a way to control which users can load which dashboards.

Using Kibana 3 with Shield

edit

Kibana users have to authenticate when your cluster has Shield installed. You configure Shield roles for your Kibana users to control what data those users can access. In addition, you can encrypt communications between the browser and Elasticsearch.

To use Kibana 3 with Shield:

Configure Kibana to use credentials when communicating with Elasticsearch. To do this, set withCredentials to true in the elasticsearch property in Kibana’s config.js file:
```
elasticsearch: {server: "http://YOUR_ELASTICSEARCH_SERVER:9200", withCredentials: true}
```
If SSL encryption is enabled in Shield, specify the HTTPS protocol in the Elasticsearch URL rather than HTTP.

Enable CORS in Elasticsearch and allow credentialed requests. To do this, set the following properties in elasticsearch.yml on each node in your cluster and restart the nodes:

http.cors.enabled: true 
http.cors.allow-origin: "https://MYHOST:MYPORT" 
http.cors.allow-credentials: true

	Enables CORS. For more information, see HTTP in the Elasticsearch Reference.
	Specifies the webserver you are using for Kibana. Note that you must explicitly specify your server’s protocol, hostname, and port—you cannot simply specify a wildcard `*` when using credentialed requests.
	Sends authentication headers to the browser.

If you are using a source build of Kibana 3, you might encounter authentication errors when trying to connect to Kibana 3 after deploying Shield and configuring the http.cors.allow-credentials property. If you do, simply clear your browser’s cache and reconnect.

Derive Kibana 3 user roles from the default kibana3 user role and add them to roles.yml to control which indices your Kibana users can access. Kibana users need access to the indices that they will be working with and the kibana-int index where their dashboards are stored. The default kibana3 role grants read access to all indices and full access to the kibana-int index.

We strongly recommend creating custom kibana3 user roles to limit access to specific indices according to your organization’s goals and policies. You can define as many different roles for your Kibana users as you need.

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
```
For example, the following kibana3_monitoring role only allows users to build dashboards using data in the logstash-* indices.
```
kibana3_monitoring:
  cluster:
      - cluster:monitor/nodes/info 
  indices:
    'logstash-*':
      - indices:admin/mappings/fields/get
      - indices:admin/validate/query
      - indices:data/read/search
      - indices:data/read/msearch
      - indices:admin/get
    '.kibana-int': 
      - indices:data/read/get
      - indices:data/read/search
      - indices:data/write/delete
      - indices:data/write/index
      - create_index
```
Kibana 3 uses the cluster permission to access the /_nodes endpoint to check the node version.

All Kibana users need access to the kibana-int index.
Assign the appropriate roles to your Kibana users or groups of users:
- If you’re using the default esusers realm, you can assign roles when you add a user, or modify the role assignments with the roles command. For example, the following command creates a user named jacknich and assigns the kibana3_monitoring role:
```
esusers useradd jacknich -r kibana3_monitoring -p password
```
- If you are using an LDAP or Active Directory realm, you can either assign roles on a per user basis, or assign roles to groups of users. By default, role mappings are stored in config/shield/role_mapping.yml. For example, the following snippet assigns the kibana3_monitoring role to the group named admins and the user named Jack Nicholson:
```
kibana3_monitoring:
  - "cn=admins,dc=example,dc=com"
  - "cn=Jack Nicholson,dc=example,dc=com"
```
- If you are using a PKI realm, you assign roles on a per user basis in the role mapping file. For example, the following snippet assigns the kibana3_monitoring role to the users named Jack Nicholson and `Robert De Niro.
```
kibana3_monitoring:
  - "cn=Jack Nicholson,ou=example,o=com"
  - "cn=Robert De Niro,ou=example,o=com"
```
If you have enabled SSL encryption in Shield and are using your own Certificate Authority (CA) to sign certificates for your nodes, configure your browser or operating system to trust your CA. When you access 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 CA that signed the node’s certificate. Consult your local IT professional for information about the recommended procedure for adding trusted CAs in your organization.
Access Kibana 3 from your browser and verify that you can sign in as a user. For example, you could log in as the jacknich user created in step 4.

Using Kibana 4 with Shield

edit

Kibana users have to authenticate when your cluster has Shield installed. You configure Shield roles for your Kibana users to control what data those users can access. Kibana 4 runs a webserver that makes requests to Elasticsearch on the client’s behalf, so you also need to configure credentials for the Kibana server so those requests can be authenticated. In addition, you can encrypt communications between the Kibana server and Elasticsearch.

To use Kibana 4 with Shield:

Configure credentials for the Kibana server. The Kibana server needs access to the cluster monitoring APIs and the .kibana index. The server does not need access to user indexes. The required privileges are specified in the kibana4_server role provided in the default Shield roles.yml file.
1. Create a user account for the Kibana server and assign it the kibana4_server role. For example, if you’re using the default esusers realm, you can create a kibana-server user with the useradd command:
```
esusers useradd kibana4-server -r kibana4_server -p password
```
  If you are using an LDAP, Active Directory, or PKI realm, you need to create a user for the Kibana server and map the user’s distinguished name to the kibana4_server role in the Shield role mapping file. By default, role mappings are stored in config/shield/role_mapping.yml. For example, the following snippet assigns the kibana4_server role to an LDAP or Active Directory user named kibana-server:
```
kibana4_server:
  - "cn=kibana-server,cn=applications,dc=example,dc=com"
```
  For PKI realms, you specify the user’s common name, organizational unit, and organization:
```
kibana4_server:
  - "cn=kibana-server,ou=example,o=com"
```
2. Specify the credentials for your Kibana server user in the Kibana configuration file, /config/kibana.yml.
```
elasticsearch.username: kibana4-server
elasticsearch.password: password
```
Derive Kibana 4 user roles from the default kibana4 user role and add them to roles.yml to control which indices your Kibana users can access. 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. The default kibana4 role grants read access to all indices and full access to the .kibana index.

We strongly recommend creating custom kibana4 user roles to limit access to specific indices according to your organization’s goals and policies. You can define as many different roles for your Kibana 4 users as you need.

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
```
For example, the following my_kibana_user role only allows users to discover and visualize data in the logstash-* indices.
```
my_kibana_user:
  cluster:
      - cluster:monitor/nodes/info
      - cluster:monitor/health
  indices:
    'logstash-*':
      - indices:admin/mappings/fields/get
      - indices:admin/validate/query
      - indices:data/read/search
      - indices:data/read/msearch
      - indices:admin/get
    '.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
```
All Kibana users need access to the .kibana index.
Assign the appropriate roles to your Kibana users or groups of users:
- If you’re using the default esusers realm, you can assign roles when you add a user, or modify the role assignments with the roles command. For example, the following command creates a user named jacknich and assigns the kibana4_monitoring role:
```
esusers useradd jacknich -r kibana4_monitoring -p password
```
- If you are using an LDAP or Active Directory realm, you can either assign roles on a per user basis, or assign roles to groups of users. By default, role mappings are stored in config/shield/role_mapping.yml. For example, the following snippet assigns the kibana4_monitoring role to the group named admins and the user named Jack Nicholson:
```
kibana4_monitoring:
  - "cn=admins,dc=example,dc=com"
  - "cn=Jack Nicholson,dc=example,dc=com"
```
- If you are using a PKI realm, you assign roles on a per user basis in the role mapping file. For example, the following snippet assigns the kibana4_monitoring role to the users named Jack Nicholson and Robert De Niro.
```
kibana4_monitoring:
  - "cn=Jack Nicholson,ou=example,o=com"
  - "cn=Robert De Niro,ou=example,o=com"
```
If you have enabled SSL encryption in Shield, configure Kibana 4 to connect to Elasticsearch via HTTPS. To do this:
1. Specify the HTTPS protocol in the elasticsearch.url setting in the Kibana configuration file, kibana.yml:
```
elasticsearch.url: "https://<your_elasticsearch_host>.com:9200"
```
2. If you are using your own CA to sign certificates for Elasticsearch, set the elasticsearch.ssl.ca setting in kibana.yml to specify the location of the PEM file.
```
elasticsearch.ssl.ca: /path/to/your/cacert.pem
```
Configure Kibana 4 to encrypt communications between the browser and the Kibana server. To do this, configure the server.ssl.key and server.ssl.cert properties in kibana.yml:
```
server.ssl.key: /path/to/your/server.key
server.ssl.cert: /path/to/your/server.crt
```
Once you enable SSL encryption between the browser and the Kibana server, access Kibana via HTTPS. For example, https://localhost:5601.

Enabling browser encryption is required to prevent passing user credentials in the clear.
Restart Kibana and verify that you can sign in as a user. If you are running Kibana locally, go to localhost:5601 and enter the credentials for a user you’ve assigned a Kibana user role. For example, you could log in as the jacknich user created in step 3.

Sign in as a Kibana user—the Kibana server credentials should only be used internally by the Kibana server. The kibana4_server role doesn’t grant permission to create the .kibana index or access user indices.

Default Roles for Kibana

edit

Default roles for Kibana 3 and Kibana 4 are provided in roles.yml.

The default user roles grant 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.

Kibana 3 User Role.

kibana3:
  cluster: cluster:monitor/nodes/info
  indices:
    '*': indices:data/read/search, indices:data/read/get, indices:admin/get
    'kibana-int': indices:data/read/search, indices:data/read/get, indices:data/write/delete, indices:data/write/index, create_index

Kibana 4 User Role.

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
      - indices:admin/get
    '.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
      - indices:admin/create

Kibana 4 Server Role.

kibana4_server:
  cluster:
      - cluster:monitor/nodes/info
      - cluster:monitor/health
  indices:
    '.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

« Using Marvel with Shield Managing Your License »

	Kibana 3 uses the cluster permission to access the `/_nodes` endpoint to check the node version.
	All Kibana users need access to the `kibana-int` index.