Skip to content

Commit

Permalink
[DOCS] Adds native realm security settings (#30186)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lcawl
lcawl committed Apr 27, 2018
1 parent 286844b commit 7b2f43d
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 68 deletions.
43 changes: 5 additions & 38 deletions x-pack/docs/en/security/authentication/native-realm.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
[[native-realm]]
=== Native User Authentication
=== 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
==== 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.
Expand Down Expand Up @@ -47,45 +47,12 @@ xpack:
. 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)
|=======================
==== Native realm settings

See {ref}/ref-native-settings.html[Native Realm Settings].

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

{security} enables you to easily manage users in {kib} on the
*Management / Security / Users* page.
Expand Down
82 changes: 52 additions & 30 deletions x-pack/docs/en/settings/security-settings.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
[role="xpack"]
[[security-settings]]
=== Security Settings in Elasticsearch
=== Security settings in {es}
++++
<titleabbrev>Security Settings</titleabbrev>
<titleabbrev>Security settings</titleabbrev>
++++

By default, {security} is disabled when you have a basic or trial license. To
Expand All @@ -23,14 +23,14 @@ For more information about creating and updating the {es} keystore, see

[float]
[[general-security-settings]]
==== General Security Settings
==== General security settings
`xpack.security.enabled`::
Set to `true` to enable {security} on the node. +
+
If set to `false`, which is the default value for basic and trial licenses,
{security} is disabled. It also affects all {kib} instances that connect to this
{es} instance; you do not need to disable {security} in those `kibana.yml` files.
For more information about disabling {security} in specific {kib} instances, see {kibana-ref}/security-settings-kb.html[{kib} Security Settings].
For more information about disabling {security} in specific {kib} instances, see {kibana-ref}/security-settings-kb.html[{kib} security settings].

`xpack.security.hide_settings`::
A comma-separated list of settings that are omitted from the results of the
Expand All @@ -42,16 +42,16 @@ sensitive nature of the information.

[float]
[[password-security-settings]]
==== Default Password Security Settings
==== Default password security settings
`xpack.security.authc.accept_default_password`::
In `elasticsearch.yml`, set this to `false` to disable support for the default "changeme" password.

[float]
[[anonymous-access-settings]]
==== Anonymous Access Settings

For more information, see {xpack-ref}/anonymous-access.html[
Enabling Anonymous Access].
==== Anonymous access settings
You can configure the following anonymous access settings in
`elasticsearch.yml`. For more information, see {xpack-ref}/anonymous-access.html[
Enabling anonymous access].

`xpack.security.authc.anonymous.username`::
The username (principal) of the anonymous user. Defaults to `_es_anonymous_user`.
Expand All @@ -69,20 +69,20 @@ access. Defaults to `true`.

[float]
[[field-document-security-settings]]
==== Document and Field Level Security Settings
==== Document and field level security settings

You can set the following document and field level security
settings in `elasticsearch.yml`. For more information, see
{xpack-ref}/field-and-document-access-control.html[Setting Up Document and Field
Level Security].
{xpack-ref}/field-and-document-access-control.html[Setting up document and field
level security].

`xpack.security.dls_fls.enabled`::
Set to `false` to prevent document and field level security
from being configured. Defaults to `true`.

[float]
[[token-service-settings]]
==== Token Service Settings
==== Token service settings

`xpack.security.authc.token.enabled`::
Set to `false` to disable the built-in token service. Defaults to `true` unless
Expand All @@ -102,7 +102,7 @@ The length of time that a token is valid for. By default this value is `20m` or

[float]
[[realm-settings]]
==== Realm Settings
==== Realm settings

You configure realm settings in the `xpack.security.authc.realms`
namespace in `elasticsearch.yml`. For example:
Expand All @@ -129,10 +129,11 @@ xpack.security.authc.realms:
----------------------------------------

The valid settings vary depending on the realm type. For more
information, see {xpack-ref}/setting-up-authentication.html[Setting Up Authentication].
information, see {xpack-ref}/setting-up-authentication.html[Setting up authentication].

[float]
===== Settings Valid for All Realms
[[ref-realm-settings]]
===== Settings valid for all realms

`type`::
The type of the realm: `native, `ldap`, `active_directory`, `pki`, or `file`. Required.
Expand All @@ -146,10 +147,31 @@ recommended when you configure multiple realms. Defaults to `Integer.MAX_VALUE`.
Indicates whether a realm is enabled. You can use this setting to disable a
realm without removing its configuration information. Defaults to `true`.

[[ref-native-settings]]
[float]
===== Native realm settings

For a native realm, the `type` must be set to `native`. In addition to the
<<ref-realm-settings,settings that are valid for all realms>>, you can specify
the following optional settings:

`cache.ttl`:: The time-to-live for cached user entries. User credentials are
cached for this period of time. Specify the time period using the standard
{es} <<time-units,time units>>. Defaults to `20m`.

`cache.max_users`:: The maximum number of user entries that can live in the
cache at any given time. Defaults to 100,000.

`cache.hash_algo`:: (Expert Setting) The hashing algorithm that is used for the
in-memory cached user credentials. For possible values, see
{xpack-ref}/controlling-user-cache.html[Cache hash algorithms]. Defaults to
`ssha256`.


[[ref-users-settings]]

[float]
===== File Realm Settings
===== File realm settings

`cache.ttl`::
The time-to-live for cached user entries--user credentials are cached for
Expand All @@ -168,7 +190,7 @@ all possible values. Defaults to `ssha256`.

[[ref-ldap-settings]]
[float]
===== LDAP Realm Settings
===== LDAP realm settings

`url`::
An LDAP URL in the format `ldap[s]://<server>:<port>`. Required.
Expand Down Expand Up @@ -399,7 +421,7 @@ table for all possible values). Defaults to `ssha256`.

[[ref-ad-settings]]
[float]
===== Active Directory Realm Settings
===== Active Directory realm settings

`url`::
A URL in the format `ldap[s]://<server>:<port>`. Defaults to `ldap://<domain_name>:389`.
Expand Down Expand Up @@ -611,7 +633,7 @@ the in-memory cached user credentials (see {xpack-ref}/controlling-user-cache.ht

[[ref-pki-settings]]
[float]
===== PKI Realm Settings
===== PKI realm settings

`username_pattern`::
The regular expression pattern used to extract the username from the
Expand Down Expand Up @@ -657,7 +679,7 @@ Defaults to `100000`.

[[ref-saml-settings]]
[float]
===== SAML Realm Settings
===== SAML realm settings

`idp.entity_id`::
The Entity ID of the SAML Identity Provider
Expand Down Expand Up @@ -922,11 +944,11 @@ cipher suites that should be supported.

[float]
[[ssl-tls-settings]]
==== Default TLS/SSL Settings
==== Default TLS/SSL settings

You can configure the following TLS/SSL settings in
`elasticsearch.yml`. For more information, see
{xpack-ref}/encrypting-communications.html[Encrypting Communications]. These settings will be used
{xpack-ref}/encrypting-communications.html[Encrypting communications]. These settings will be used
for all of {xpack} unless they have been overridden by more specific
settings such as those for HTTP or Transport.

Expand Down Expand Up @@ -969,7 +991,7 @@ Jurisdiction Policy Files_ has been installed, the default value also includes `

[float]
[[tls-ssl-key-settings]]
===== Default TLS/SSL Key and Trusted Certificate Settings
===== Default TLS/SSL key and trusted certificate settings

The following settings are used to specify a private key, certificate, and the
trusted certificates that should be used when communicating over an SSL/TLS connection.
Expand All @@ -979,7 +1001,7 @@ trusted along with the certificate(s) from the <<tls-ssl-key-settings, key setti
for connections that require client authentication or when acting as a SSL enabled server.

[float]
===== PEM Encoded Files
===== PEM encoded files

When using PEM encoded files, use the following settings:

Expand All @@ -1002,7 +1024,7 @@ that will be presented to clients when they connect.
List of paths to the PEM encoded certificate files that should be trusted.

[float]
===== Java Keystore Files
===== Java keystore files

When using Java keystore files (JKS), which contain the private key, certificate
and certificates that should be trusted, use the following settings:
Expand Down Expand Up @@ -1033,7 +1055,7 @@ Password to the truststore.
Password to the truststore.

[float]
===== PKCS#12 Files
===== PKCS#12 files

When using PKCS#12 container files (`.p12` or `.pfx`), which contain the
private key, certificate, and certificates that should be trusted, use
Expand Down Expand Up @@ -1090,7 +1112,7 @@ include::ssl-settings.asciidoc[]

[[ssl-tls-profile-settings]]
[float]
===== Transport Profile TLS/SSL Settings
===== Transport profile TLS/SSL settings

The same settings that are available for the <<transport-tls-ssl-settings, default transport>>
are also available for each transport profile. By default, the settings for a
Expand All @@ -1105,9 +1127,9 @@ setting, this would be `transport.profiles.$PROFILE.xpack.security.ssl.key`.

[float]
[[ip-filtering-settings]]
==== IP Filtering Settings
==== IP filtering settings

You can configure the following settings for {xpack-ref}/ip-filtering.html[IP filtering]:
You can configure the following settings for {xpack-ref}/ip-filtering.html[IP filtering].

`xpack.security.transport.filter.allow`::
List of IP addresses to allow.
Expand Down

0 comments on commit 7b2f43d

Please sign in to comment.