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 <<anonymous-access, 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.

In order for the `elastic` user to be usable, its <<bootstrap-elastic-passwords,password must be bootstrapped>>
by at least one of the nodes in your cluster. The bootstrap password is intended
to be a temporary password to help you setup your cluster. The `elastic` user password
will be changed during the setup process.

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
<<auditing, 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 <<ssl-tls, SSL/TLS encryption>>.
            Nodes that do not have encryption enabled send passwords in plain
            text!

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

* Integrate with <<ldap-realm, LDAP>> or <<active-directory-realm, Active Directory>>,
or <<pki-realm, require certificates>> for authentication.
* Use <<ip-filtering, IP Filtering>> to allow or deny requests from particular
IP addresses or address ranges.