[[shield-integration]]
=== Integrating Watcher with Shield

Watcher can work alongside https://www.elastic.co/products/shield[Shield] and integrates with it.
This integation is expected to be extended in future releases.

IMPORTANT: Watcher 1.0.x requires Shield 1.2.2 or above

When the Watcher plugin is installed along side Shield, it will automatically register an internal
user - `__watcher_user`. All actions taken as part of a watch execution will be executed on behalf
of this user.

NOTE: 	The `__watcher_user` is internal to watcher. Sending executing API on behalf of that users
		outside of watcher will fail (unless you specifically add such a user to any of the
		supported realms).

In addition to that, Watcher also registers with Shield two additional cluster level privileges:

* `monitor_watcher` - grants access to watcher <<api-rest-stats, stats>> and
					  <<api-rest-get-watch, get>> APIs
* `manage_watcher` - grants access to all watcher APIs

You can use the privileges above in Shield's {shield-ref}/defining-roles.html[`roles.yml`]
file to grant roles access to the watcher APIs. The following snippet shows an example of such role
definition:

[source,yaml]
--------------------------------------------------
watcher_admin:
    cluster: manage_watcher
--------------------------------------------------

Once the relevant role was defined, adding the watcher administrator user requires the exact same
process as adding any other user to to Shield. For example, if you are using the
{shield-ref}/esusers.html[`esusers`] realm, use the `esusers`
{shield-ref}/_managing_users_in_an_esusers_realm.html[command-line tool] to add
the user:

[source,js]
--------------------------------------------------
bin/shield/esusers useradd john -r watcher_admin
--------------------------------------------------

Once added, this user will be able to call all the watcher APIs and by that manage all watches.

[float]
=== Privileges On Watcher Internal Indices

Watcher stores its data (watches and watch history records) in its own internal indices:

* `.watches` - an index that stores all the added watches
* `.watch_history-<timestamp>` - time based indices that store all the watch records

All write operations on these indices are performed internally by Watcher itself and external users
should not write directly to them. It should be considered a best practice to not grant any write
privileges on these indices to any of the Shield users.

[float]
=== Handling Sensitive Information

Sometimes a watch may hold sensitive information. For example, the user password that is configured
as part of the basic authentication in the <<input-http-auth-basic-example, `http` input>>. In
addition, some of watcher configuration may also hold sensitive data. When Shield is installed,
Watcher can utilize some of the security services it provides to better secure this type of
sensitive information.

[float]
[[shield-watch-data-encryption]]
==== Watch Data Encryption

By default, Watcher simply stores this sensitive data as part of the watch document in the
`.watches` index. This means that the password can be retrieved in plain text by executing a
document GET or any search of the available operations in elasticsearch over that index.

NOTE:   The <<api-rest-get-watch, Get Watch API>> will automatically filter out this sensitive data
		from its response.

When Shield is installed, it is possible configure watcher to use shield and encrypt this sensitive
data prior to indexing the watch. This can be done by:

* Ensuring Shield's {shield-ref}/enable-message-authentication.html[System Key] is set up
  and used
* Add the following settings in the `elasticsearch.yml` file:
+
[source,yaml]
--------------------------------------------------
watcher.shield.encrypt_sensitive_data: true
--------------------------------------------------
+
By default (when not set), the sensitive data will be index in plain text (same behaviour as when
shield is not installed)

[float]
[[shield-sensitive-data-in-conf]]
==== Sensitive Data in Configuration Files

The `elasticsearch.yml` file may also hold sensitive data. For example, the SMTP credentials that
are configured as part of the <<email-account, email accounts>>.

As for now, neither Watcher nor Shield provide a mechanism to encrypt settings in this file. It is
a best practice to ensure that access to this file is limited to the user under which the
elasticsearch instance is running.

In addition to that, When Shield is installed, these settings will be filtered out from the REST
{ref}/cluster-nodes-info.html[Nodes Info API].