99 lines
4.1 KiB
Plaintext
99 lines
4.1 KiB
Plaintext
[[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].
|