Merge pull request #120 from apache/UNOMI-225-es7-auth-ssl-documentation
UNOMI-225: add documentation on ES7 authentication and ssl support
diff --git a/manual/src/main/asciidoc/configuration.adoc b/manual/src/main/asciidoc/configuration.adoc
index f193b20..e191fa8 100644
--- a/manual/src/main/asciidoc/configuration.adoc
+++ b/manual/src/main/asciidoc/configuration.adoc
@@ -402,68 +402,48 @@
or the user/password you have setup to protect the system if you have changed it. You can find the list of Apache Unomi
shell commands in the "Shell commands" section of the documentation.
-==== ElasticSearch X-Pack Support
+==== ElasticSearch authentication and security
-It is now possible to use X-Pack to connect to ElasticSearch. However, for licensing reasons this is not provided out
-of the box. Here is the procedure to install X-Pack with Apache Unomi:
+With ElasticSearch 7, it's possible to secure the access to your data. (https://www.elastic.co/guide/en/elasticsearch/reference/7.5/secure-cluster.html[https://www.elastic.co/guide/en/elasticsearch/reference/7.5/secure-cluster.html])
-===== Important !
+Depending on your ElasticSearch license you may need to install Kibana and enable xpack security: https://www.elastic.co/guide/en/elasticsearch/reference/7.5/configuring-security.html[https://www.elastic.co/guide/en/elasticsearch/reference/7.5/configuring-security.html]
-Do not start Unomi directly with unomi:start, perform the following steps below first !
+===== User authentication !
-===== Installation steps
+If your ElasticSearch have been configured to be only accessible by authenticated users (https://www.elastic.co/guide/en/elasticsearch/reference/7.5/setting-up-authentication.html[https://www.elastic.co/guide/en/elasticsearch/reference/7.5/setting-up-authentication.html])
-. Create a directory for all the JARs that you will download, we will call it XPACK_JARS_DIRECTORY
-. Download https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/5.6.3/x-pack-transport-5.6.3.jar[https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/5.6.3/x-pack-transport-5.6.3.jar] to XPACK_JARS_DIRECTORY
-. Download https://artifacts.elastic.co/maven/org/elasticsearch/plugin/x-pack-api/5.6.3/x-pack-api-5.6.3.jar[https://artifacts.elastic.co/maven/org/elasticsearch/plugin/x-pack-api/5.6.3/x-pack-api-5.6.3.jar] to XPACK_JARS_DIRECTORY
-. Download http://central.maven.org/maven2/com/unboundid/unboundid-ldapsdk/3.2.0/unboundid-ldapsdk-3.2.0.jar[http://central.maven.org/maven2/com/unboundid/unboundid-ldapsdk/3.2.0/unboundid-ldapsdk-3.2.0.jar] to XPACK_JARS_DIRECTORY
-. Download http://central.maven.org/maven2/org/bouncycastle/bcpkix-jdk15on/1.55/bcpkix-jdk15on-1.55.jar[http://central.maven.org/maven2/org/bouncycastle/bcpkix-jdk15on/1.55/bcpkix-jdk15on-1.55.jar] to XPACK_JARS_DIRECTORY
-. Download http://central.maven.org/maven2/org/bouncycastle/bcprov-jdk15on/1.55/bcprov-jdk15on-1.55.jar[http://central.maven.org/maven2/org/bouncycastle/bcprov-jdk15on/1.55/bcprov-jdk15on-1.55.jar] to XPACK_JARS_DIRECTORY
-. Download http://central.maven.org/maven2/com/sun/mail/javax.mail/1.5.3/javax.mail-1.5.3.jar[http://central.maven.org/maven2/com/sun/mail/javax.mail/1.5.3/javax.mail-1.5.3.jar] to XPACK_JARS_DIRECTORY
-.
-
-Edit etc/org.apache.unomi.persistence.elasticsearch.cfg to add the following settings:
+Just edit `etc/org.apache.unomi.persistence.elasticsearch.cfg` to add the following settings:
[source]
----
-transportClientClassName=org.elasticsearch.xpack.client.PreBuiltXPackTransportClient
-transportClientJarDirectory=XPACK_JARS_DIRECTORY
-transportClientProperties=xpack.security.user=elastic:changeme
+username=USER
+password=PASSWORD
----
-You can setup more properties (for example for SSL/TLS support) by seperating the properties with commas,
-as in the following example:
+===== SSL communication
+
+By default Unomi will communicate with ElasticSearch using `http`
+but you can configure your ElasticSearch server(s) to allow encrypted request using `https`.
+
+You can follow this documentation to enable SSL on your ElasticSearch server(s):
+
+* https://www.elastic.co/guide/en/elasticsearch/reference/7.5/ssl-tls.html[Full documentation]
+* https://www.elastic.co/guide/en/elasticsearch/reference/7.5/configuring-tls.html#node-certificates[Configure certificates]
+* https://www.elastic.co/guide/en/elasticsearch/reference/7.5/configuring-tls.html#tls-http[Encrypt HTTP communications]
+
+If your ElasticSearch is correctly configure to encrypt communications on `https`:
+
+Just edit `etc/org.apache.unomi.persistence.elasticsearch.cfg` to add the following settings:
[source]
----
-transportClientProperties=xpack.security.user=elastic:changeme,xpack.ssl.key=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.key,xpack.ssl.certificate=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.crt,xpack.ssl.certificate_authorities=/home/user/elasticsearch-5.6.3/config/x-pack/ca/ca.crt,xpack.security.transport.ssl.enabled=true
+sslEnable=true
----
-.
-
-Launch Karaf and launch unomi using the command from the shell :
+By default, certificates will have to be configured on the Apache Unomi server to be able to trust the identity
+of the ElasticSearch server(s). But if you need to trust all certificates automatically, you can use this setting:
[source]
----
-unomi:start
+sslTrustAllCertificates=true
----
-
-Alternatively you could edit the configuration directly from the Karaf shell using the following commands:
-
-[source]
-----
-config:edit org.apache.unomi.persistence.elasticsearch
-config:property-set transportClientClassName org.elasticsearch.xpack.client.PreBuiltXPackTransportClient
-config:property-set transportClientJarDirectory XPACK_JARS_DIRECTORY
-config:property-set transportClientProperties xpack.security.user=elastic:changeme
-config:update
-unomi:start
-----
-
-You can setup more properties (for example for SSL/TLS support) by seperating the properties with commas,
-as in the following example:
-
-[source]
-----
-config:property-set transportClientProperties xpack.security.user=elastic:changeme,xpack.ssl.key=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.key,xpack.ssl.certificate=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.crt,xpack.ssl.certificate_authorities=/home/user/elasticsearch-5.6.3/config/x-pack/ca/ca.crt,xpack.security.transport.ssl.enabled=true
-----
\ No newline at end of file
