|
| 1 | +[role="xpack"] |
| 2 | +[testenv="enterprise"] |
| 3 | +[[configure-operator-privileges]] |
| 4 | +=== Configure operator privileges |
| 5 | + |
| 6 | +include::operator-privileges-designed-for-note.asciidoc[] |
| 7 | + |
| 8 | +Before you can use operator privileges, you must |
| 9 | +<<enable-operator-privileges, enable the feature>> on all nodes in the cluster |
| 10 | +and <<designate-operator-users,designate operator users>>. |
| 11 | + |
| 12 | +[[enable-operator-privileges]] |
| 13 | +==== Enable operator privileges |
| 14 | + |
| 15 | +In order to use the operator privileges feature, it must be enabled explicitly |
| 16 | +on each node in the cluster. Add the following setting in each |
| 17 | +`elasticsearch.yml` file: |
| 18 | + |
| 19 | +[source,yaml] |
| 20 | +---------------------------- |
| 21 | +xpack.security.operator_privileges.enabled: true |
| 22 | +---------------------------- |
| 23 | + |
| 24 | +If the node is already running before you make this change, you must restart |
| 25 | +the node for the feature to take effect. |
| 26 | + |
| 27 | +WARNING: The feature needs to be either enabled or disabled consistently across |
| 28 | +all nodes in a cluster. Otherwise, you can get inconsistent behaviour depending |
| 29 | +on which node first receives a request and which node executes it. |
| 30 | + |
| 31 | +When operator privileges are enabled on a cluster, |
| 32 | +<<operator-only-functionality,specific functionalities>> are restricted and can |
| 33 | +be executed only by users who have been explicitly designated as operator users. |
| 34 | +If a regular user attempts to execute these functionalities (even if they have |
| 35 | +the `superuser` role), a security exception occurs. |
| 36 | + |
| 37 | +[[designate-operator-users]] |
| 38 | +==== Designate operator users |
| 39 | + |
| 40 | +Operator users are just normal {es} users with special rights to perform |
| 41 | +operator-only functionalities. They are specified in an `operator_users.yml` |
| 42 | +file, which is located in the config directory (as defined by the `ES_PATH_CONF` |
| 43 | +environment variable). Similar to |
| 44 | +<<file-realm-configuration,other security config files>>, the |
| 45 | +`operator_users.yml` file is local to a node and does not apply globally to the |
| 46 | +cluster. This means, in most cases, the same file should be distributed or |
| 47 | +copied to all nodes in a cluster. |
| 48 | + |
| 49 | +The `operator_users.yml` file defines a set of criteria that an authenticating |
| 50 | +user must match to be considered as an operator user. The following snippet |
| 51 | +shows an example of such a file: |
| 52 | + |
| 53 | +[source,yaml] |
| 54 | +----------------------------------- |
| 55 | +operator: <1> |
| 56 | + - usernames: ["system_agent_1","system_agent_2"] <2> |
| 57 | + realm_type: "file" <3> |
| 58 | + auth_type: "realm" <4> |
| 59 | +----------------------------------- |
| 60 | +<1> A fixed value of `operator` signals the beginning of the definition. |
| 61 | +<2> A list of user names allowed for operator users. This field is mandatory. |
| 62 | +<3> The type of the authenticating realm allowed for operator users. The default |
| 63 | +and only acceptable value is <<file-realm,`file`>>. |
| 64 | +<4> The authentication type allowed for operator users. The default and only |
| 65 | +acceptable value is `realm`. |
| 66 | + |
| 67 | +You must specify at least the `usernames` field. If no other fields are |
| 68 | +specified, their default values are used. All fields must be matched for a user |
| 69 | +to be qualified as an operator user. You can also specify multiple groups of |
| 70 | +criteria. This is currently not very useful since this feature does not yet |
| 71 | +support other realms or authentication types. |
| 72 | + |
| 73 | +There are also two implicit rules that affect which users are operator users: |
| 74 | + |
| 75 | +1. If the authenticating user <<run-as-privilege,runs as>> another user, neither |
| 76 | +of them are considered to be operator users. |
| 77 | +2. All <<internal-users>> are implicitly operator users. |
| 78 | + |
| 79 | +IMPORTANT: After a user is designated as an operator user, they are still |
| 80 | +subject to regular <<authorization,RBAC user authorization>> checks. That is to |
| 81 | +say, in addition to specifying that a user is an operator user, you must also |
| 82 | +grant them the necessary {es} roles to perform their tasks. Consequently, it is |
| 83 | +entirely possible that an operator user can encounter an "access denied" error |
| 84 | +and fail to perform certain actions due to RBAC check failures. In short, an |
| 85 | +operator user is *not* automatically a `superuser`. |
0 commit comments