honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOC] Miscellaneous security doc updates (elastic/x-pack-elasticsearch#1908) 

- Document refresh interval for role mapping files
- Fix obsolete shield reference in transport profile example 
- Clarify that AD & PKI don't support run_as
- Fix logstash conf examples
- Clarify interaction of SSL settings and PKI realm settings
- Document PKI DN format, and recommend use of pki_dn metadata
- Provide more details about action.auto_create_index during setup

Original commit: elastic/x-pack-elasticsearch@49ddb12a7e
This commit is contained in:
Tim Vernum 2017-07-07 13:33:35 +10:00 committed by GitHub
parent b636dcc366
commit c5012ac6e8
7 changed files with 108 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/en/installing-xes.asciidoc
View File

@ -82,7 +82,10 @@ Continue with installation? [y/N]y
----------------------------------------------------------
--
. If you have disabled automatic index creation in {es}, configure
. {xpack} will try to automatically create a number of indices within {es}.
By default, {es} is configured to allow automatic index creation, and no
additional steps are required. However, if you have disabled automatic index
creation in {es}, you must configure
{ref}/docs-index_.html#index-creation[`action.auto_create_index`] in
`elasticsearch.yml` to allow {xpack} to create the following indices:
+
@ -92,6 +95,16 @@ Continue with installation? [y/N]y
action.auto_create_index: .security,.monitoring*,.watches,.triggered_watches,.watcher-history*,.ml*
-----------------------------------------------------------
--
+
[IMPORTANT]
=============================================================================
If you are using https://www.elastic.co/products/logstash[Logstash]
or https://www.elastic.co/products/beats[Beats] then you will most likely
require additional index names in your `action.auto_create_index` setting, and
the exact value will depend on your local configuration. If you are unsure of
the correct value for your environment, you may consider setting the value to
`*` which will allow automatic creation of all indices.
=============================================================================
. Start {es}.
+

103
docs/en/security/authentication/pki-realm.asciidoc
View File

@ -65,11 +65,40 @@ xpack:
username_pattern: "EMAILADDRESS=(.*?)(?:,|$)"
------------------------------------------------------------
+
You can also specify which truststore to use for authentication. This is useful
when the SSL/TLS layer trusts clients with certificates that are signed by a
different CA than the one that signs your users' certificates. To specify the
location of the truststore, specify the `truststore.path` option:
+
. Restart Elasticsearch.
[[pki-ssl-config]]
==== PKI and SSL Settings
The PKI realm relies on the SSL settings of the node's network interface
(transport or http). The realm can be configured to be more restrictive than
the underlying network connection - that is, it is possible to configure the
node such that some connections are accepted by the network interface but then
fail to be authenticated by the PKI realm. However the reverse is not possible
- the PKI realm cannot authenticate a connection that has been refused by the
network interface.
In particular this means:
* The transport or http interface must request client certificates by setting
`client_authentication` to `optional` or `required`.
* The interface must _trust_ the certificate that is presented by the client
by configuring either the `truststore` or `certificate_authorities` paths,
or by setting `verification_mode` to `none`.
* The _protocols_ supported by the interface must be compatible with those
used by the client.
The relevant network interface (transport or http) must be configured to trust
any certificate that is to be used within the PKI realm. However it possible to
configure the PKI realm to trust only a _subset_ of the certificates accepted
by the network interface.
This is useful when the SSL/TLS layer trusts clients with certificates that are
signed by a different CA than the one that signs your users' certificates.
To configure the PKI realm with its own truststore, specify the
`truststore.path` option as below:
[source, yaml]
------------------------------------------------------------
xpack:
@ -83,35 +112,41 @@ xpack:
password: "x-pack-test-password"
------------------------------------------------------------
. Restart Elasticsearch.
The `certificate_authorities` option may be used as an alternative to the
`truststore.path` setting.
[[pki-settings]]
===== PKI Realm Settings
[cols="4,^3,10"]
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type. Must be set to `pki`.
| `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.
Enables you to disable a realm without removing its
configuration. Defaults to `true`.
| `username_pattern` | no | Specifies the regular expression pattern used to extract
the username from the certificate DN. The first match
group is used as the username. Defaults to `CN=(.*?)(?:,\|$)`.
| `truststore.path` | no | The path to the truststore. Defaults to the path
defined by {ref}/security-settings.html#ssl-tls-settings[SSL/TLS settings].
| `truststore.password` | no/yes | Specifies the password for the truststore. Must be
provided if `truststore.path` is set.
| `truststore.algorithm` | no | Specifies the algorithm used for the truststore.
Defaults to `SunX509`.
| `files.role_mapping` | no | Specifies the <<security-files-location,location>>
for the <<pki-role-mapping, YAML role mapping configuration file>>.
Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`.
| Setting | Required | Description
| `type` | yes | Indicates the realm type. Must be set to `pki`.
| `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.
Enables you to disable a realm without removing its
configuration. Defaults to `true`.
| `username_pattern` | no | Specifies the regular expression pattern used to extract
the username from the certificate DN. The first match
group is used as the username. Defaults to `CN=(.*?)(?:,\|$)`.
| `certificate_authorities` | no | List of paths to the PEM encoded certificate files
that should be trusted.
This setting may not be used with `truststore.path`.
| `truststore.path` | no | The path to the truststore. Defaults to the path
defined by {ref}/security-settings.html#ssl-tls-settings[SSL/TLS settings].
This setting may not be used with `certificate_authorities`.
| `truststore.password` | no/yes | Specifies the password for the truststore. Must be
provided if `truststore.path` is set.
| `truststore.algorithm` | no | Specifies the algorithm used for the truststore.
Defaults to `SunX509`.
| `files.role_mapping` | no | Specifies the <<security-files-location,location>>
for the <<pki-role-mapping, YAML role mapping configuration file>>.
Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`.
|=======================
[[assigning-roles-pki]]
@ -151,4 +186,16 @@ user: <1>
<1> The name of a role.
<2> The distinguished name (DN) of a PKI user.
The disinguished name for a PKI user follows X.500 naming conventions which
place the most specific fields (like `cn` or `uid`) at the beginning of the
name, and the most general fields (like `o` or `dc`) at the end of the name.
Some tools, such as _openssl_, may print out the subject name in a different
format.
One way that you can determine the correct DN for a certificate is to use the
{ref}/security-api-authenticate.html[authenticate API] (use the relevant PKI
certificate as the means of authentication) and inspect the metadata field in
the result. The user's distinguished name will be populated under the `pki_dn`
key. You can also use the authenticate API to validate your role mapping.
For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.

6
docs/en/security/authorization/mapping-roles.asciidoc
View File

@ -258,6 +258,12 @@ are values. The mappings can have a many-to-many relationship. When you map role
to groups, the roles of a user in that group are the combination of the roles
assigned to that group and the roles assigned to that user.
By default, {security} checks role mapping files for changes every 5 seconds.
You can change this default behavior by changing the
`resource.reload.interval.high` setting in the `elasticsearch.yml` file
(as this is a common setting in Elasticsearch, changing its value may effect
other schedules in the system).
==== Realm Specific Details
[float]
[[ldap-role-mapping]]

6
docs/en/security/authorization/run-as-privilege.asciidoc
View File

@ -8,8 +8,10 @@ users, you can use the _run as_ mechanism to restrict data access according to
To "run as" (impersonate) another user, you must be able to retrieve the user from
the realm you use to authenticate. Both the internal `native` and `file` realms
support this out of the box. The LDAP realm however must be configured to enable
user search. For more information, see <<ldap-user-search, Configuring an LDAP Realm with User Search>>.
support this out of the box. The LDAP realm however must be configured to run in
_user search_ mode. For more information, see
<<ldap-user-search, Configuring an LDAP Realm with User Search>>.
The Active Directory and PKI realms do not support "run as".
To submit requests on behalf of other users, you need to have the `run_as`
permission. For example, the following role grants permission to submit request

2
docs/en/security/securing-communications/separating-node-client-traffic.asciidoc
View File

@ -13,7 +13,7 @@ to `elasticsearch.yml`:
--------------------------------------------------
transport.profiles.client: <1>
port: 9500-9600 <2>
shield:
xpack.security:
type: client <3>
--------------------------------------------------
<1> `client` is the name of this example profile

5
docs/en/security/tribe-clients-integrations/logstash.asciidoc
View File

@ -74,21 +74,26 @@ plugins in your Logstash `.conf` file. For example:
[source,js]
--------------------------------------------------
input {
elasticsearch {
...
user => logstash_internal
password => x-pack-test-password
}
}
filter {
elasticsearch {
...
user => logstash_internal
password => x-pack-test-password
}
}
output {
elasticsearch {
...
user => logstash_internal
password => x-pack-test-password
}
}
--------------------------------------------------
[float]

2
docs/en/settings/security-settings.asciidoc
View File

@ -494,10 +494,12 @@ Defaults to `CN=(.*?)(?:,\|$)`
`certificate_authorities`::
List of PEM certificate files that should be used to authenticate a
user's certificate as trusted. Defaults to the trusted certificates configured for SSL.
See the {xpack-ref}/pki-realm.html#pki-ssl-config[SSL settings] section of the PKI realm documentation for more information.
This setting may not be used with `truststore.path`.
`truststore.path`::
The path of a truststore to use. Defaults to the trusted certificates configured for SSL.
See the {xpack-ref}/pki-realm.html#pki-ssl-config[SSL settings] section of the PKI realm documentation for more information.
This setting may not be used with `certificate_authorities`.
`truststore.password`::