Using Kibana with Shield
editUsing Kibana with Shield
editKibana users have to log in when Shield is installed on your cluster. You configure Shield roles for your Kibana users to control what data those users can access. You also need to configure credentials for the Kibana server so the requests it submits to Elasticsearch on the user’s behalf can be authenticated.
To prevent user passwords from being sent in the clear, you must configure Kibana to encrypt communications between the browser and the Kibana server. If are encrypting traffic to and from the nodes in your Elasticsearch cluster, you must also configure Kibana to connect to Elasticsearch via HTTPS.
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.
To use Kibana 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 indices. The required privileges are specified in the kibana4_server role provided in the default Shieldroles.yml
file.-
Create a user account for the Kibana server and assign it the
kibana4_server
role. For example, submit the following request to create a nativekibana-server
user:curl -u es_admin -XPOST 'http://localhost:9200/_shield/user/kibana-server' -d '{"password" : "changeme", "roles" : [ "kibana4_server"]}'
If you are using an LDAP or Active Directory 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 inconfig/shield/role_mapping.yml
. For example, the following snippet assigns thekibana4_server
role to an LDAP or Active Directory user namedkibana-server
:kibana_server: - "cn=kibana-server,cn=applications,dc=example,dc=com"
-
Specify the credentials for your Kibana server user in the Kibana configuration file,
/config/kibana.yml
.elasticsearch.username: "kibana4-server" elasticsearch.password: "changeme"
-
-
Derive Kibana user roles from the example
my_kibana_user
user role and add them toroles.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. Users also need access to thekibana-devnull
index. The examplemy_kibana_user
role grants read access to the indices that match thelogstash-*
pattern and full access to the.kibana
index, which is required.You can define as many different roles for your Kibana users as you need.
For example, the following
my_kibana_user
role only allows users to discover and visualize data in thelogstash-*
indices. -
Assign the appropriate roles to your Kibana users or groups of users:
-
If you’re using the
native
realm, you can assign roles using the User Management API. For example, the following creates a user namedjacknich
and assigns it thekibana_monitoring
role:POST /_shield/user/jacknich { "password" : "t0pS3cr3t", "roles" : [ "kibana_monitoring" ] }
-
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 thekibana_monitoring
role to the group namedadmins
and the user named Jack Nicholson:kibana_monitoring: - "cn=admins,dc=example,dc=com" - "cn=Jack Nicholson,dc=example,dc=com"
-
-
Configure Kibana to encrypt communications between the browser and the Kibana server:
-
Generate a server certificate for Kibana. You must either set the certificate’s
subjectAltName
to the hostname, fully-qualified domain name (FQDN), or IP address of the Kibana server, or set the CN to the Kibana server’s hostname or FQDN. Using the server’s IP address as the CN does not work. -
Set the
server.ssl.key
andserver.ssl.cert
properties inkibana.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
.You must enable SSL encryption between the browser and the Kibana server to use Kibana with Shield. If Shield is configured to encrypt connections to Elasticsearch, you must also configure Kibana to connect to Elasticsearch via HTTPS.
-
Generate a server certificate for Kibana. You must either set the certificate’s
-
If you have enabled SSL encryption in Shield, configure Kibana to connect to Elasticsearch via HTTPS:
-
Specify the HTTPS protocol in the
elasticsearch.url
setting in the Kibana configuration file,kibana.yml
:elasticsearch.url: "https://<your_elasticsearch_host>.com:9200"
-
If you are using your own CA to sign certificates for Elasticsearch, set the
elasticsearch.ssl.ca
setting inkibana.yml
to specify the location of the PEM file.elasticsearch.ssl.ca: /path/to/your/cacert.pem
-
-
Install the Shield plugin into Kibana. The Shield plugin secures user sessions and enables users to log in and out of Kibana. To install the Shield plugin:
-
Run the following command in your Kibana installation directory to install the Shield plugin.
bin/kibana plugin --install kibana/shield/latest
To perform an offline install, download the Shield plugin from http://download.elastic.co/kibana/shield/shield-2.4.5.tar.gz (sha1) and run
bin/kibana plugin --install shield --url file:///path/to/file/shield-2.4.1.tar.gz
-
Set the
shield.encryptionKey
property in thekibana.yml
configuration file. You can use any text string of 32 characters or more as the encryption key.shield.encryptionKey: "something_at_least_32_characters"
-
To change the default session duration, set the
shield.sessionTimeout
property in thekibana.yml
configuration file. By default, sessions expire after 30 minutes. The timeout is specified in milliseconds. For example, set the timeout to 600000 to expire sessions after 10 minutes:shield.sessionTimeout: 600000
-
-
Restart Kibana and verify that you can sign in as a user. If you are running Kibana locally, go to
https://localhost:5601
and enter the credentials for a user you’ve assigned a Kibana user role. For example, you could log in as thejacknich
user created in step 3.This must be a user who has been assigned a role derived from the example
my_kibana_user
user role. Kibana server credentials should only be used internally by the Kibana server. Thekibana4_server
role doesn’t grant permission to access user indices.
Shield UI Settings
edit-
shield.encryptionKey
- An arbitrary string of 32 characters or more to use as the encryption key. Required.
-
shield.sessionTimeout
- Sets the session duration. Defaults to 1800000 ms (30 minutes).
-
shield.skipSslCheck
-
Advanced setting. Set to
true
to enable Kibana to start ifserver.ssl.cert
andserver.ssl.key
are not specified inkibana.yml
. This should only be used if SSL is configured outside of Kibana—for example, you are routing requests through a load balancer or proxy. You must still connect to the Kibana server via HTTPS when using the Shield UI plugin. If you attempt to access Kibana via HTTP, you’ll be stuck at the login screen indefinitely. Defaults tofalse
.
Default Kibana Server Role
editA default role for the Kibana server is provided in roles.yml
.
kibana4_server: cluster: - monitor indices: - names: '.kibana*' privileges: - all - names: '.reporting-*' privileges: - all