[[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 <>. [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. In order to set these passwords, the `elastic` user must have its password bootstrapped. To bootstrap the password, please read <> below. Once the `elastic` user has its password bootstrapped, this user can be used to <>. .{security} Built-in Users |======== | Name | Description | `elastic` | A built-in _superuser_. See <>. | `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 <>. 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]] ==== Bootstrap Elastic Password The `elastic` user can have its password bootstrapped by placing a password in the keystore of at least one node. At startup, that node will pull the password out of the keystore and set the `elastic` password to that value. The password will only be set if the `elastic` user password has not already been set. 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. Specifically, the setting for the bootstrap password is "bootstrap.password". If the keystore has not been created before, it must be created first. [source,shell] -------------------------------------------------- bin/elasticsearch-keystore create bin/elasticsearch-keystore add "bootstrap.password" -------------------------------------------------- After running the "add" command, you will be prompted to enter your password. The bootstrap password is only intended to be a transient password used to help you set all the built-in user passwords. As the password will remain accessible in the keystore on the machine, the `elastic` user's password should be changed to a different password when you . [float] [[set-built-in-user-passwords]] ==== Set Built-in User Passwords [IMPORTANT] ============================================================================= You must set the passwords for all built-in users. You can update passwords from the *Management > Users* UI in Kibana, using the setup-passwords tool, or with the security user api. The setup-passwords tool is a command line tool that is provided to assist with setup. When it is run, it will use the `elastic` user bootstrap password to execute api requests that will change the passwords of the `elastic`, `kibana`, and `logstash_system` users. In "auto" mode the passwords will be generated randomly and printed to the console. [source,shell] -------------------------------------------------- bin/x-pack/setup-passwords auto -------------------------------------------------- There is also an "interactive" mode that will prompt you to manually enter passwords. [source,shell] -------------------------------------------------- bin/x-pack/setup-passwords interactive -------------------------------------------------- If the node is not listening at "http://localhost:9200", you will need to pass the url parameter to tell the tool where to submit the requests. [source,shell] -------------------------------------------------- bin/x-pack/setup-passwords auto -u "http://localhost:9201" -------------------------------------------------- The {ref}/security-api-users.html#security-api-reset-user-password[Reset Password API] can also be used to change the passwords manually. [source,js] --------------------------------------------------------------------- PUT _xpack/security/user/elastic/_password { "password": "elasticpassword" } --------------------------------------------------------------------- // CONSOLE [source,js] --------------------------------------------------------------------- PUT _xpack/security/user/kibana/_password { "password": "kibanapassword" } --------------------------------------------------------------------- // CONSOLE [source,js] --------------------------------------------------------------------- PUT _xpack/security/user/logstash_system/_password { "password": "logstashpassword" } --------------------------------------------------------------------- // CONSOLE Once the `kibana` user password is reset, you need to update the Kibana 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]] ==== Disable 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. ============================================================================= [float] [[internal-users]] === Internal Users {security} has two _internal_ users (`_system` and `_xpack`) that are responsible for the operations that take place inside an Elasticsearch 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 <>. === 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 <>. _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 <>. _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 <>. _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 <>. _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 <>. {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 <>. 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. 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 <>. 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/custom-realm.asciidoc[] include::authentication/user-cache.asciidoc[]