OpenSearch/docs/en/security/authentication/native-realm.asciidoc

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].