[[native-realm]]
=== Native User Authentication

The easiest way to manage and authenticate users is with the internal `native`
realm. You can use the REST APIs or Kibana to add and remove users, assign user roles, and
manage user passwords.

[[native-realm-configuration]]
[float]
==== Configuring a Native Realm

The native realm is added to the realm chain by default. You don't need to
explicitly configure a native realm to manage users through the REST APIs.


IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
realms you specify are used for authentication. To use the
`native` realm as a fallback, you must include it in the realm chain.

You can, however, configure options for the `native` realm in the
`xpack.security.authc.realms` namespace in `elasticsearch.yml`. Explicitly
configuring a native realm enables you to set the order in which it appears in
the realm chain, temporary disable the realm, and control its cache options.

To configure a native realm:

. Add a realm configuration of type `native` to `elasticsearch.yml` under the
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm
`type` to `native`. If you are configuring multiple realms, you should also
explicitly set the `order` attribute. See <<native-settings, Native Realm Settings>>
for all of the options you can set for the `native` realm.
+
For example, the following snippet shows a `native` realm configuration that
sets the `order` to zero so the realm is checked first:
+
[source, yaml]
------------------------------------------------------------
xpack:
  security:
    authc:
      realms:
        native1:
          type: native
          order: 0
------------------------------------------------------------

. Restart Elasticsearch.

[[native-settings]]
.Native Realm Settings
[cols="4,^3,10"]
|=======================
| Setting             | Required  | Description

| `type`              | yes       | Indicates the realm type. Must be set to `native`.

| `order`             | no        | Indicates the priority of this realm within
                                    the realm chain. Realms with a lower order
                                    are consulted first. Although not required,
                                    we recommend explicitly setting this value
                                    when you configure multiple realms. Defaults
                                    to `Integer.MAX_VALUE`.

| `enabled`           | no        | Indicates whether this realm is enabled or
                                    disabled. When set to `false`, the realm is
                                    not added to the realm chain and therefore
                                    is inactive. Defaults to `true`.

| `cache.ttl`         | no        | Specifies the time-to-live for cached user
                                    entries. A user's credentials are cached for
                                    this period of time. Specify the time period
                                    using the standard Elasticsearch
                                    {ref}/common-options.html#time-units[time units].
                                    Defaults to `20m`.

| `cache.max_users`   | no        | Specifies the maximum number of user entries
                                    that can be cached at any given time. Defaults
                                    to 100,000.

| `cache.hash_algo`   | no        | Specifies the hashing algorithm that is used
                                    for the cached user credentials. See
                                    <<cache-hash-algo, Cache hash algorithms>>
                                    for the possible values. (Expert Setting)
|=======================


[[managing-native-users]]
==== Managing Native Users

{security} enables you to easily manage users in {kib} on the 
*Management / Security / Users* page. 

Alternatively, you can manage users through the `user` API. For more 
information and examples, see {ref}/security-api-users.html[User Management APIs].

[[migrating-from-file]]
NOTE: To migrate file-based users to the `native` realm, use the
{ref}/migrate-tool.html[migrate tool].