Bring elasticsearch_and_kibana_auth back from the dead (chef#2253)

Signed-off-by: IanMadd <[email protected]>

Author: IanMadd

chef_master/source/elasticsearch_and_kibana_auth.rst

@@ -0,0 +1,84 @@
+=====================================================
+Authentication for Elasticsearch and Kibana
+=====================================================
+`[edit on GitHub] <https://github.com/chef/chef-web-docs/blob/master/chef_master/source/elasticsearch_and_kibana_auth.rst>`__
+
+.. meta:: 
+    :robots: noindex 
+
+.. tag chef_automate_mark
+
+.. image:: ../../images/a2_docs_banner.svg
+   :target: https://automate.chef.io/docs
+
+.. end_tag
+
+.. tag EOL_a1
+
+.. danger:: This documentation applies to a `deprecated product </versions.html#deprecated-products-and-versions>`__. Chef Automate includes newer out-of-the-box compliance profiles, an improved compliance scanner with total cloud scanning functionality, better visualizations, role-based access control and many other features. Chef Automate is included as part of the Workflow license agreement and is `available via subscription <https://www.chef.io/pricing/>`_.
+
+.. end_tag
+
+Node data in Chef Automate is stored in `Elasticsearch <https://www.elastic.co/products/elasticsearch>`__ and viewable in the Chef Automate UI as well as `Kibana <https://www.elastic.co/products/kibana>`__. Access to Chef Automate's Elasticsearch and Kibana is protected by the same authentication used by the Chef Automate user interface. Elasticsearch authentication is enabled by default.
+
+.. tag kibana_note
+
+.. note:: As of Chef Automate 1.6.87, Kibana is no longer enabled by default. To enable it, see the `Kibana setup documentation <https://www.elastic.co/guide/en/kibana/current/setup.html>`_. In prior versions of Chef Automate, Kibana and its authentication are enabled by default.
+
+.. end_tag
+
+How It Works
+============
+
+* User logs into the Chef Automate UI normally.
+* Chef Automate stores information about the user's session in browser local storage as well as a browser cookie.
+* If authentication is enabled for Elasticsearch or Kibana, Chef Automate's web server will look for the session cookie and validate the session is valid and active.
+   * If the session is valid and active, the request is permitted.
+   * If the session is invalid, or if no session information is present, the server returns a ``401 Unauthorized`` message.
+
+
+Accessing Elasticsearch with Authentication - Node Visibility UI
+=================================================================
+
+The Automate node visibility UI performs a number of queries to Elasticsearch in order to present the node visibility data. The Chef Automate server will validate each of the Elasticsearch requests with the session cookie information as described in the **How It Works** section above.
+
+
+Accessing Elasticsearch with Authentication - API/CLI
+=====================================================
+
+If you wish to access Elasticsearch via your Chef Automate server via a CLI tool (such as ``curl``) or an API client (such as `elasticsearch-ruby <https://github.com/elastic/elasticsearch-ruby>`__), you must pass three additional HTTP headers in your requests for your request to be properly authenticated:
+
+* ``chef-delivery-user``: the Chef Automate username for whom a token has been generated
+* ``chef-delivery-token``: a valid token generated for the user
+* ``chef-delivery-enterprise``: the Chef Automate enterprise name. This is the string after the ``/e/`` in your Chef Automate URLs.
+    * Example: if your Workflow dashboard URL is ``https://my-automate-server.mycompany.biz/e/coolcompany/#/dashboard``, your enterprise is ``coolcompany``
+
+To generate a token, use the ``delivery token`` command of the `Delivery CLI </delivery_cli.html>`__.
+
+For example, to pass the required headers using curl:
+
+.. code-block:: bash
+
+   curl https://my-automate-server.mycompany.biz/elasticsearch/_cat/indices -H "chef-delivery-user: myuser" -H "chef-delivery-enterprise: coolcompany" -H "chef-delivery-token: s00pers33krett0ken"
+
+
+Accessing Kibana with Authentication
+====================================
+
+Your browser must have a valid cookie containing a valid token before access to Kibana will be permitted. If you encounter a "401 Unauthorized" error message, follow these steps:
+
+* Log into the Chef Automate UI normally.
+* Change your browser URI to ``/kibana``.
+   * Example: ``https://my-automate-server.mycompany.biz/kibana``
+
+
+Configuration
+=============
+
+.. warning:: It is strongly recommended that authentication to Elasticsearch and Kibana remain enabled at all times. Without authentication, any user with network access to your Automate server will be able to view any available Visibility data.
+
+If you wish to disable authentication for either Kibana or Elasticsearch, you may use the following configuration parameters in your ``/etc/delivery/delivery.rb`` configuration file:
+
+* ``elasticsearch['enable_auth']``: If ``true``, a valid user/enterprise/token must be supplied in a cookie or in HTTP headers for the request to be accepted and passed to Elasticsearch. If ``false``, all Elasticsearch queries are permitted without authentication. Default: ``true``
+
+* ``kibana['enable_auth']``: If ``true``, a valid user/enterprise/token must be supplied in a cookie or in HTTP headers for access to be granted to the Kibana UI. If ``false``, all Kibana access is permitted without authentication. Default: ``true``

chef_master/source/index.rst

@@ -556,6 +556,7 @@ Addenda
    dsl_delivery
    dsl_handler
    dsl_recipe
+   elasticsearch_and_kibana_auth
    environment_variables
    environments
    errors