OpenSearch/docs/en/security/getting-started.asciidoc

[[security-getting-started]]
== Getting Started with Security

To secure a cluster, you must install {xpack} on every node in the
cluster. Basic authentication is enabled by default--to communicate
with the cluster, you must specify a username and password.
Unless you {xpack-ref}/anonymous-access.html[enable anonymous access], all
requests that don't include a user name and password are rejected.

{security} provides a built-in `elastic` superuser you can use
to start setting things up. This `elastic` user has full access
to the cluster, including all indices and data, so the `elastic` user
does not have a password set by default.

To get started with {security}:

. <<installing-xpack, Install X-Pack>>.

. On at least one of the nodes in your cluster, set the "bootstrap.password" secure setting in the keystore.
+
--
[source,shell]
--------------------------------------------------
bin/elasticsearch-keystore create
bin/elasticsearch-keystore add "bootstrap.password"
--------------------------------------------------

--

.  Start Elasticsearch and Kibana. The Elasticsearch node with the "bootstrap.password" setting will use that
setting to set the `elastic` user password on node startup.


. Set the passwords of the built in `elastic`, `kibana`, and `logstash_system` users using the provided setup
passwords tool. In "auto" mode this tool will randomly generate passwords and print them to the console.
+
--
[source,shell]
--------------------------------------------------
bin/x-pack/setup-passwords auto
--------------------------------------------------

--

. Set up roles and users to control access to Elasticsearch and Kibana.
For example, to grant _John Doe_ full access to all indices that match
the pattern `events*` and enable him to create visualizations and dashboards
for those indices in Kibana, you could create an `events_admin` role and
and assign the role to a new `johndoe` user.
+
--
[source,shell]
----------------------------------------------------------
curl -XPOST -u elastic 'localhost:9200/_xpack/security/role/events_admin' -H "Content-Type: application/json" -d '{
  "indices" : [
    {
      "names" : [ "events*" ],
      "privileges" : [ "all" ]
    },
    {
      "names" : [ ".kibana*" ],
      "privileges" : [ "manage", "read", "index" ]
    }
  ]
}'

curl -XPOST -u elastic 'localhost:9200/_xpack/security/user/johndoe' -H "Content-Type: application/json" -d '{
  "password" : "userpassword",
  "full_name" : "John Doe",
  "email" : "john.doe@anony.mous",
  "roles" : [ "events_admin" ]
}'
----------------------------------------------------------
// NOTCONSOLE
--

[[enable-auditing]]
. Enable Auditing to keep track of attempted and successful interactions with
  your Elasticsearch cluster:
+
--
.. Add the following setting to `elasticsearch.yml` on all nodes in your cluster:
+
[source,yaml]
----------------------------
xpack.security.audit.enabled: true
----------------------------
.. Restart Elasticsearch.

By default, events are logged to a dedicated `elasticsearch-access.log` file in
`ES_HOME/logs`. You can also store the events in an Elasticsearch index for
easier analysis and control what events are logged. For more information, see
{xpack-ref}/auditing.html[Configuring Auditing].
--

[[moving-on]]
IMPORTANT:  Once you get these basic security measures in place, we strongly
            recommend that you secure communications to and from nodes by
            configuring your cluster to use {xpack-ref}/ssl-tls.html[SSL/TLS encryption].
            Nodes that do not have encryption enabled send passwords in plain
            text and will not be able to install a non-trial license that enables the use
            of {security}.

Depending on your security requirements, you might also want to:

* Integrate with {xpack-ref}/ldap-realm.html[LDAP] or {xpack-ref}/active-directory-realm.html[Active Directory],
or {xpack-ref}/pki-realm.html[require certificates] for authentication.
* Use {xpack-ref}/ip-filtering.html[IP Filtering] to allow or deny requests from particular
IP addresses or address ranges.