From a906844f5a3fae74b59b269272c42799f632cdfb Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Wed, 10 Mar 2021 16:20:05 +1100 Subject: [PATCH] Documentation for operator privileges (#68964) Add documentation for operator privilegs. The docs cover features delivered by phase 1 (#65256) and 2 (#66684). Co-authored-by: Tim Vernum Co-authored-by: lcawl Co-authored-by: Adam Locke --- x-pack/docs/en/security/index.asciidoc | 2 + .../configure-operator-privileges.asciidoc | 85 +++++++++++++++++++ .../operator-privileges/index.asciidoc | 28 ++++++ .../operator-only-functionality.asciidoc | 40 +++++++++ ...perator-only-snapshot-and-restore.asciidoc | 41 +++++++++ ...ator-privileges-designed-for-note.asciidoc | 4 + 6 files changed, 200 insertions(+) create mode 100644 x-pack/docs/en/security/operator-privileges/configure-operator-privileges.asciidoc create mode 100644 x-pack/docs/en/security/operator-privileges/index.asciidoc create mode 100644 x-pack/docs/en/security/operator-privileges/operator-only-functionality.asciidoc create mode 100644 x-pack/docs/en/security/operator-privileges/operator-only-snapshot-and-restore.asciidoc create mode 100644 x-pack/docs/en/security/operator-privileges/operator-privileges-designed-for-note.asciidoc diff --git a/x-pack/docs/en/security/index.asciidoc b/x-pack/docs/en/security/index.asciidoc index 64a28e366bc3b..da8dfbe476ae9 100644 --- a/x-pack/docs/en/security/index.asciidoc +++ b/x-pack/docs/en/security/index.asciidoc @@ -18,6 +18,7 @@ IP filtering, and auditing. * <> * <> * <> +* <> * <> * <> * <> @@ -33,6 +34,7 @@ include::auditing/index.asciidoc[] include::securing-communications/index.asciidoc[] include::using-ip-filtering.asciidoc[] include::ccs-clients-integrations/index.asciidoc[] +include::operator-privileges/index.asciidoc[] include::get-started-security.asciidoc[] include::securing-communications/tutorial-tls-intro.asciidoc[] include::troubleshooting.asciidoc[] diff --git a/x-pack/docs/en/security/operator-privileges/configure-operator-privileges.asciidoc b/x-pack/docs/en/security/operator-privileges/configure-operator-privileges.asciidoc new file mode 100644 index 0000000000000..1e1b1b77629ae --- /dev/null +++ b/x-pack/docs/en/security/operator-privileges/configure-operator-privileges.asciidoc @@ -0,0 +1,85 @@ +[role="xpack"] +[testenv="enterprise"] +[[configure-operator-privileges]] +=== Configure operator privileges + +include::operator-privileges-designed-for-note.asciidoc[] + +Before you can use operator privileges, you must +<> on all nodes in the cluster +and <>. + +[[enable-operator-privileges]] +==== Enable operator privileges + +In order to use the operator privileges feature, it must be enabled explicitly +on each node in the cluster. Add the following setting in each +`elasticsearch.yml` file: + +[source,yaml] +---------------------------- +xpack.security.operator_privileges.enabled: true +---------------------------- + +If the node is already running before you make this change, you must restart +the node for the feature to take effect. + +WARNING: The feature needs to be either enabled or disabled consistently across +all nodes in a cluster. Otherwise, you can get inconsistent behaviour depending +on which node first receives a request and which node executes it. + +When operator privileges are enabled on a cluster, +<> are restricted and can +be executed only by users who have been explicitly designated as operator users. +If a regular user attempts to execute these functionalities (even if they have +the `superuser` role), a security exception occurs. + +[[designate-operator-users]] +==== Designate operator users + +Operator users are just normal {es} users with special rights to perform +operator-only functionalities. They are specified in an `operator_users.yml` +file, which is located in the config directory (as defined by the `ES_PATH_CONF` +environment variable). Similar to +<>, the +`operator_users.yml` file is local to a node and does not apply globally to the +cluster. This means, in most cases, the same file should be distributed or +copied to all nodes in a cluster. + +The `operator_users.yml` file defines a set of criteria that an authenticating +user must match to be considered as an operator user. The following snippet +shows an example of such a file: + +[source,yaml] +----------------------------------- +operator: <1> + - usernames: ["system_agent_1","system_agent_2"] <2> + realm_type: "file" <3> + auth_type: "realm" <4> +----------------------------------- +<1> A fixed value of `operator` signals the beginning of the definition. +<2> A list of user names allowed for operator users. This field is mandatory. +<3> The type of the authenticating realm allowed for operator users. The default +and only acceptable value is <>. +<4> The authentication type allowed for operator users. The default and only +acceptable value is `realm`. + +You must specify at least the `usernames` field. If no other fields are +specified, their default values are used. All fields must be matched for a user +to be qualified as an operator user. You can also specify multiple groups of +criteria. This is currently not very useful since this feature does not yet +support other realms or authentication types. + +There are also two implicit rules that affect which users are operator users: + +1. If the authenticating user <> another user, neither +of them are considered to be operator users. +2. All <> are implicitly operator users. + +IMPORTANT: After a user is designated as an operator user, they are still +subject to regular <> checks. That is to +say, in addition to specifying that a user is an operator user, you must also +grant them the necessary {es} roles to perform their tasks. Consequently, it is +entirely possible that an operator user can encounter an "access denied" error +and fail to perform certain actions due to RBAC check failures. In short, an +operator user is *not* automatically a `superuser`. diff --git a/x-pack/docs/en/security/operator-privileges/index.asciidoc b/x-pack/docs/en/security/operator-privileges/index.asciidoc new file mode 100644 index 0000000000000..f7f8b2cfe6e39 --- /dev/null +++ b/x-pack/docs/en/security/operator-privileges/index.asciidoc @@ -0,0 +1,28 @@ +[role="xpack"] +[testenv="enterprise"] +[[operator-privileges]] +== Operator privileges + +include::operator-privileges-designed-for-note.asciidoc[] + +With a typical {es} deployment, people who administer the cluster also operate +the cluster at the infrastructure level. User authorization based on +<> is effective and reliable for +this environment. However, in more managed environments, such as +{ess-trial}[{ess}], there is a distinction between the operator of the cluster +infrastructure and the administrator of the cluster. + +Operator privileges limit some functionality to operator users only. Operator +users are just regular Elasticsearch users with access to specific +<>. These +privileges are not available to cluster administrators, even if they log in as +a highly privileged user such as the `elastic` user or another user with the +superuser role. By limiting system access, operator privileges enhance the +Elasticsearch security model while safeguarding user capabilities. + + +include::configure-operator-privileges.asciidoc[] + +include::operator-only-functionality.asciidoc[] + +include::operator-only-snapshot-and-restore.asciidoc[] diff --git a/x-pack/docs/en/security/operator-privileges/operator-only-functionality.asciidoc b/x-pack/docs/en/security/operator-privileges/operator-only-functionality.asciidoc new file mode 100644 index 0000000000000..e07cf697714e0 --- /dev/null +++ b/x-pack/docs/en/security/operator-privileges/operator-only-functionality.asciidoc @@ -0,0 +1,40 @@ +[role="xpack"] +[testenv="enterprise"] +[[operator-only-functionality]] +=== Operator-only functionality + +include::operator-privileges-designed-for-note.asciidoc[] + +Operator privileges provide protection for APIs and dynamic cluster settings. +Any API or cluster setting that is protected by operator privileges is known as +_operator-only functionality_. When the operator privileges feature is enabled, +operator-only APIs can be executed only by operator users. Likewise, +operator-only settings can be updated only by operator users. The list of +operator-only APIs and dynamic cluster settings are pre-determined in the +codebase. The list may evolve in future releases but it is otherwise fixed in a +given {es} version. + +[[operator-only-apis]] +==== Operator-only APIs + +* <> +* <> +* <> +* <> +* <> +* <> + +[[operator-only-dynamic-cluster-settings]] +==== Operator-only dynamic cluster settings + +* All <> settings +* The following the dynamic <>: + - `xpack.ml.node_concurrent_job_allocations` + - `xpack.ml.max_machine_memory_percent` + - `xpack.ml.use_auto_machine_memory_percent` + - `xpack.ml.max_lazy_ml_nodes` + - `xpack.ml.process_connect_timeout` + - `xpack.ml.nightly_maintenance_requests_per_second` + - `xpack.ml.max_ml_node_size` + - `xpack.ml.enable_config_migration` + - `xpack.ml.persist_results_max_retries` diff --git a/x-pack/docs/en/security/operator-privileges/operator-only-snapshot-and-restore.asciidoc b/x-pack/docs/en/security/operator-privileges/operator-only-snapshot-and-restore.asciidoc new file mode 100644 index 0000000000000..65f70251f7193 --- /dev/null +++ b/x-pack/docs/en/security/operator-privileges/operator-only-snapshot-and-restore.asciidoc @@ -0,0 +1,41 @@ +[role="xpack"] +[testenv="enterprise"] +[[operator-only-snapshot-and-restore]] +=== Operator privileges for snapshot and restore + +include::operator-privileges-designed-for-note.asciidoc[] + +Invoking <> or updating +<> +typically results in changes in the cluster state. The cluster state can be +included in a cluster <>. Snapshots are a great way +to preserve the data of a cluster, which can later be restored to bootstrap a +new cluster, perform migration, or disaster recovery, for example. In a +traditional self-managed environment, the intention is for the restore process +to copy the entire cluster state over when requested. However, in a more +managed environment, such as {ess-trial}[{ess}], data that is associated with +<> is explicitly +managed by the infrastructure code. + +Restoring snapshot data associated with +operator-only functionality could be problematic +because: + +1. A snapshot could contain incorrect values for operator-only functionalities. +For example, the snapshot could have been taken in a different cluster where +requirements are different or the operator privileges feature is not enabled. +Restoring data associated with operator-only functionality breaks the guarantee +of operator privileges. +2. Even when the infrastructure code can correct the values immediately after +a restore, there will always be a short period of time when the cluster could be +in an inconsistent state. +3. The infrastructure code prefers to configure operator-only functionality from +a single place, that is to say, through API calls. + +Therefore, +<>, +snapshot data that is associated with any operator-only functionality is *not* +restored. + +NOTE: That information is still included when taking a snapshot so that all data +is always preserved. diff --git a/x-pack/docs/en/security/operator-privileges/operator-privileges-designed-for-note.asciidoc b/x-pack/docs/en/security/operator-privileges/operator-privileges-designed-for-note.asciidoc new file mode 100644 index 0000000000000..600badccebd6d --- /dev/null +++ b/x-pack/docs/en/security/operator-privileges/operator-privileges-designed-for-note.asciidoc @@ -0,0 +1,4 @@ +[NOTE] +The operator privileges feature is designed for indirect use by {ess-trial}[{ess}], +{ece-ref}[{ece}], and {eck-ref}[Elastic Cloud on Kubernetes]. Direct use is not +supported.