OpenSearch/docs/en/security/authentication.asciidoc

[[setting-up-authentication]]
== Setting Up User Authentication

Authentication identifies an individual. To gain access to restricted resources,
a user must prove their identity, via passwords, credentials, or some other
means (typically referred to as authentication tokens).

You can use the native support for managing and authenticating users, or
integrate with external user management systems such as LDAP and Active
Directory. For information about managing native users,
see <<managing-native-users, Managing Native Users>>.

[float]
[[built-in-users]]
=== Built-in Users

{security} provides built-in user credentials to help you get up and running.
These users have a fixed set of privileges and cannot be authenticated until their
passwords have been set. The `elastic` user can be used to
<<set-built-in-user-passwords,set all of the built-in user passwords>>.

`elastic`:: A built-in _superuser_. See <<built-in-roles>>.
`kibana`:: The user Kibana uses to connect and communicate with Elasticsearch.
`logstash_system`:: The user Logstash uses when storing monitoring information in Elasticsearch.


[float]
[[built-in-user-explanation]]
==== How the Built-in Users Work
These built-in users are stored within a special `.security` index managed by
{security}.
This means that, if the password is changed, or a user is disabled, then that
change is automatically reflected on each node in the cluster. It also means
that if your `.security` index is deleted, or restored from a snapshot, then
any changes you have applied will be lost.

Although they share the same API, the built-in users are separate and distinct
from users managed by the <<native-realm, native realm>>. Disabling the native
realm will not have any effect on the built-in users. The built-in users can
be disabled individually, using the
{ref}/security-api-users.html[user management API].

[float]
[[bootstrap-elastic-passwords]]
==== The Elastic Bootstrap Password

When you install {xpack}, if the `elastic` user does not already have a password,
it uses a default bootstrap password. The bootstrap password is a transient
password that enables you to run the tools that set all the built-in user passwords.

By default, the bootstrap password is derived from a randomized `keystore.seed`
setting, which is added to the keystore when you install {xpack}. You do not need
to know or change this bootstrap password. If you have defined a
`bootstrap.password` setting in the keystore, however, that value is used instead.
For more information about interacting with the keystore, see
{ref}/secure-settings.html[Secure Settings].
////
//TBD: Is the following still true?
As the `elastic` user is stored in the native realm, the password will be
synced to all the nodes in a cluster. It is safe to bootstrap the password with
multiple nodes as long as the password is the same. If different passwords are
set with different nodes, it is unpredictable which password will be bootstrapped.
////

NOTE: After you <<set-built-in-user-passwords,set passwords for the built-in users>>,
in particular for the `elastic` user, there is no further use for the bootstrap
password.

[float]
[[set-built-in-user-passwords]]
==== Setting Built-in User Passwords

You must set the passwords for all built-in users.

The +setup-passwords+ tool is the simplest method to set the built-in users'
passwords for the first time. It uses the `elastic` user's bootstrap password to
run user management API requests. For example, you can run the command in
an "interactive" mode, which prompts you to enter new passwords for the
`elastic`, `kibana`, and `logstash_system` users:

[source,shell]
--------------------------------------------------
bin/x-pack/setup-passwords interactive
--------------------------------------------------

For more information about the command options, see
{ref}/setup-passwords.html[setup-passwords].

IMPORTANT: After you set a password for the `elastic` user, the bootstrap
password is no longer valid; you cannot run the `setup-passwords` command a
second time.

Alternatively, you can set the initial passwords for the built-in users by using
the *Management > Users* page in {kib} or the
{ref}/security-api-change-password.html[Change Password API]. These methods are
more complex. You must supply the `elastic` user and its bootstrap password to
log into {kib} or run the API. This requirement means that you cannot use the
default bootstrap password that is derived from the `keystore.seed` setting.
Instead, you must explicitly set a `bootstrap.password` setting in the keystore
before you start {es}. For example, the following command prompts you to enter a
new bootstrap password:

[source,shell]
----------------------------------------------------
bin/elasticsearch-keystore add "bootstrap.password"
----------------------------------------------------

You can then start {es} and {kib} and use the `elastic` user and bootstrap
password to log into {kib} and change the passwords. Alternatively, you can
submit Change Password API requests for each built-in user. These methods are
better suited for changing your passwords after the initial setup is complete,
since at that point the bootstrap password is no longer required.

[float]
[[add-built-in-user-passwords]]
==== Adding Built-in User Passwords To {kib} and Logstash

After the `kibana` user password is set, you need to update the {kib} server
with the new password by setting `elasticsearch.password` in the `kibana.yml`
configuration file:

[source,yaml]
-----------------------------------------------
elasticsearch.password: kibanapassword
-----------------------------------------------

The `logstash_system` user is used internally within Logstash when
monitoring is enabled for Logstash.

To enable this feature in Logstash, you need to update the Logstash
configuration with the new password by setting `xpack.monitoring.elasticsearch.password` in
the `logstash.yml` configuration file:

[source,yaml]
----------------------------------------------------------
xpack.monitoring.elasticsearch.password: logstashpassword
----------------------------------------------------------

If you have upgraded from an older version of elasticsearch/x-pack,
the `logstash_system` user may have defaulted to _disabled_ for security reasons.
Once the password has been changed, you can enable the user via the following API call:

[source,js]
---------------------------------------------------------------------
PUT _xpack/security/user/logstash_system/_enable
---------------------------------------------------------------------
// CONSOLE

[float]
[[disabling-default-password]]
==== Disabling Default Password Functionality
[IMPORTANT]
=============================================================================
This setting is deprecated. The elastic user no longer has a default password.
The password must be set before the user can be used.
See <<bootstrap-elastic-passwords>>.
=============================================================================

[float]
[[internal-users]]
=== Internal Users

{security} has three _internal_ users (`_system`, `_xpack`, and `_xpack_security`)
that are responsible for the operations that take place inside an {es} cluster.

These users are only used by requests that originate from within the cluster.
For this reason, they cannot be used to authenticate against the API and there
is no password to manage or reset.

From time-to-time you may find a reference to one of these users inside your
logs, including <<auditing, audit logs>>.

[[how-authc-works]]
=== How Authentication Works

Authentication in {security} is handled by one or more authentication services
called _realms_. A _realm_ is used to resolve and authenticate users based on
authentication tokens. {security} provides the following built-in realms:

_native_::
An internal realm where users are stored in a dedicated Elasticsearch index.
This realm supports an authentication token in the form of username and password,
and is available by default when no realms are explicitly configured. See
<<native-realm>>.

_ldap_::
A realm that uses an external LDAP server to authenticate the
users. This realm supports an authentication token in the form of username and
password, and requires explicit configuration in order to be used. See
<<ldap-realm>>.

_active_directory_::
A realm that uses an external Active Directory Server to authenticate the
users. With this realm, users are authenticated by usernames and passwords.
See <<active-directory-realm>>.

_pki_::
A realm that authenticates users using Public Key Infrastructure (PKI). This
realm works in conjunction with SSL/TLS and identifies the users through the
Distinguished Name (DN) of the client's X.509 certificates. See <<pki-realm>>.

_file_::
An internal realm where users are defined in files stored on each node in the
Elasticsearch cluster. This realm supports an authentication token in the form
of username and password, and is always available. See <<file-realm>>.

_saml_::
A realm that facilitates authentication using the SAML 2.0 Web SSO protocol.
This realm is designed to support authentication through {kib}, and is non
intended for use in the REST API.  See <<saml-realm>>.



{security} also supports custom realms. If you need to integrate with another
authentication system, you can build a custom realm plugin. For more information,
see <<custom-realms, Integrating with Other Authentication Systems>>.

Realms live within a _realm chain_. It is essentially a prioritized list of
configured realms (typically of various types). The order of the list determines
the order in which the realms will be consulted. You should make sure each
configured realm has a distinct `order` setting. In the event that two or more
realms have the same `order`, they will be processed in `name` order.
During the authentication process, {security} will consult and try to
authenticate the request one realm at a time.
Once one of the realms successfully authenticates the request, the authentication
is considered to be successful and the authenticated user will be associated
with the request (which will then proceed to the authorization phase). If a realm
cannot authenticate the request, the next in line realm in the chain will be
consulted. If all realms in the chain could not authenticate the request, the
authentication is then considered to be unsuccessful and an authentication error
will be returned (as HTTP status code `401`).

NOTE: Some systems (e.g. Active Directory) have a temporary lock-out period after
      several successive failed login attempts. If the same username exists in
      multiple realms, unintentional account lockouts are possible. For more
      information, please see <<trouble-shoot-active-directory, here>>.

The default realm chain contains the `native` and `file` realms. To explicitly,
configure a realm chain, you specify the chain in `elasticsearch.yml`. When you
configure a realm chain, only the realms you specify are used for authentication.
To use the `native` and `file` realms, you must include them in the chain.

The following snippet configures a realm chain that includes the `file` and
`native` realms, as well as two LDAP realms and an Active Directory realm.

[source,yaml]
----------------------------------------
xpack.security.authc:
  realms:

    file:
      type: file
      order: 0

    native:
      type: native
      order: 1

    ldap1:
      type: ldap
      order: 2
      enabled: false
      url: 'url_to_ldap1'
      ...

    ldap2:
      type: ldap
      order: 3
      url: 'url_to_ldap2'
      ...

    ad1:
      type: active_directory
      order: 4
      url: 'url_to_ad'
----------------------------------------

As can be seen above, each realm has a unique name that identifies it and each
realm type dictates its own set of required and optional settings. That said,
there are three settings that are common to all realms:

[cols=",^,",options="header"]
|=========
| Setting     | Required  | Description

| `type`      | true      | Identifies the type of the realm. The realm type
                            determines what other settings the realms should be
                            configured with. The type can be one of: `native`,
                            `ldap`, `active_directory`, `pki`, `file`, or in case
                            of a custom realm, the type name that identifies it.

| `order`     | false     | A numeric value representing the priority/index of
                            the realm within the realm chain. This will determine
                            the order by which the realms will be consulted
                            during authentication, with lower order being consulted
                            first.

| `enabled`   | false     | When set to `false` the realm will be disabled and
                            will not be added to the realm chain. This is useful
                            for debugging purposes as it enables you to remove
                            a realm from the chain without deleting and losing
                            its configuration.
|=========

Realm types can roughly be classified in two categories:

Internal::  Realms that are internal to Elasticsearch and don't require any
            communication with external parties. They are fully managed by
            {security}. There can only be a maximum of one configured realm
            per internal realm type. {security} provides two internal realm
            types: `native` and `file`.

External::  Realms that require interaction with parties/components external to
            Elasticsearch, typically, with enterprise grade identity management
            systems. Unlike internal realms, there can be as many external realms
            as one would like - each with its own unique name and configuration.
            {security} provides three external realm types: `ldap`,
            `active_directory` and `pki`.

include::authentication/anonymous-access.asciidoc[]

include::authentication/native-realm.asciidoc[]

include::authentication/ldap-realm.asciidoc[]

include::authentication/active-directory-realm.asciidoc[]

include::authentication/pki-realm.asciidoc[]

include::authentication/file-realm.asciidoc[]

include::authentication/saml-realm.asciidoc[]

include::authentication/custom-realm.asciidoc[]

include::authentication/user-cache.asciidoc[]

include::authentication/saml-guide.asciidoc[]