From b5818d5964d00fe6cd5ffe177c6363c0b797d23e Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 22 Aug 2024 16:59:05 -0500 Subject: [PATCH 01/17] initial attempt --- .../observability/apm/feature-roles.asciidoc | 208 +++++++++++------- 1 file changed, 133 insertions(+), 75 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index d1acdac6bc..e01962da20 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -10,7 +10,7 @@ NOTE: This documentation only applies to the APM Server binary. Use role-based access control or API keys to grant APM Server users access to secured resources. * <> -* <>. +* <> After privileged users have been created, use authentication to connect to a secured Elastic cluster. @@ -33,19 +33,34 @@ Firewall rules are recommended to ensure only authorized systems can connect. [[apm-feature-roles]] === Feature roles -You can use role-based access control to grant users access to secured -resources. The roles that you set up depend on your organization's security -requirements and the minimum privileges required to use specific features. +It's recommended that you only grant users the minimum privileges required to use specific features. One approach to managing access on a feature-by-feature basis is to create several feature-related _roles_ and assign one or more of these roles to each _user or group_ based on which features the user needs to access. -Typically, you need to create the following separate roles: +[TIP] +==== +A _role_ identifies a set of permissions that translate to privileges on resources. You can associate a _user or group_ with an arbitrary number of roles. The total set of permissions that a user has is defined by the union of the permissions in all its roles. +==== -* <>: To publish events collected by APM Server. -* <>: One for sending monitoring -information, and another for viewing it. -* <>: To create and manage API keys. -* <>: To view -APM Agent central configurations. -* <>: To read RUM source maps. +Below are some common tasks that users in your organization might need to do and links to more information on creating roles that provides access to the right resources: + +* <>: +Allows a user to view APM Agent central configurations, which is *required* when +<> is enabled (it is enabled by default). +* <>: +Allows a user to publish events collected by APM Server. +* <>: Allows a user to do one or both of these: +** Publish monitoring data +** View monitoring data +* <>: Allow a user to create and manage API keys. +* <>: Allows a user to read RUM source maps. + +// Is "deployment" the right word? +.Example: Assigning multiple roles to a user +***** +For example, if you have a user in your organization who needs to be able to _____ in a deployment where +central configuration management hasn't been explicitly disabled, you would need to associate the user with +two of the roles listed above: <> +and <>. +***** {es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a subset of the privileges needed by APM users. @@ -62,17 +77,74 @@ In general, there are three types of privileges you'll work with: *********************************** *********************************** //// +[[apm-privileges-agent-central-config]] +=== Allow users to access APM Agent central configuration + +++++ +Create a _central config_ role +++++ + +[IMPORTANT] +==== +The privileges included in this role are *required* for all users when <> is enabled (it is enabled by default). +==== + +[[apm-privileges-agent-central-config-server]] +APM Server acts as a proxy between your APM agents and the APM UI. +The APM UI communicates any changed settings to APM Server so that your agents only need to poll the Server +to determine which central configuration settings have changed. + +To grant an APM Server user with the required privileges for managing central configuration in {es} without {kib}, +assign the user the following privileges: + +[options="header"] +|==== +|Type | Privilege | Purpose + +| Index +|`read` on `.apm-agent-configuration` index, `allow_restricted_indices: true` +|Allow APM Server to manage central configurations in {es} +|==== + +The above privileges should be sufficient for APM agent central configuration to work properly +as long as APM Server communicates with {es} successfully. +If it fails, it may fallback to read agent central configuration via {kib} if configured, +which requires the following privileges: + +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +|`Read` on APM UI +|Allow APM Server to manage central configurations via the APM UI +|==== + +TIP: Looking for privileges and roles needed to use central configuration from the APM UI or APM UI API? +See <>. + +//// +*********************************** *********************************** +*********************************** *********************************** +//// + [[apm-privileges-to-publish-events]] -=== Grant privileges and roles needed for writing events +=== Create a writer role ++++ -Create a _writer_ user +Create a _writer_ role ++++ APM users that publish events to {es} need privileges to write to APM data streams. -[float] -==== General writer role +// tag::central-config-note[] +[NOTE] +==== +*In most cases, users will need to be assigned the* <> *in addition to this role.* + +You do _not_ need the _Central configuration management_ role if central configuration management has been explicitly disabled in the APM UI. +==== +// end::central-config-note[] To grant an APM user the required privileges for writing events to {es}: @@ -93,8 +165,12 @@ that has the following privileges: |==== . Assign the *general writer role* to users who need to publish APM data. +. Assign <> to users as needed. -. If <> is enabled, create a separate <>. +[NOTE] +==== +If <> is enabled, create a separate <>. +==== //// *********************************** *********************************** @@ -102,10 +178,10 @@ that has the following privileges: //// [[apm-privileges-to-publish-monitoring]] -=== Grant privileges and roles needed for monitoring +=== Create a monitoring role ++++ -Create a _monitoring_ user +Create a _monitoring_ role ++++ {es-security-features} provides built-in users and roles for publishing and viewing monitoring data. @@ -121,6 +197,8 @@ depend on the method used to collect that data. [[apm-privileges-to-publish-monitoring-write]] ==== Publish monitoring data +include::feature-roles.asciidoc[tag=central-config-note] + [IMPORTANT] ==== **{ecloud} users:** This section does not apply to our @@ -133,8 +211,14 @@ Monitoring on {ecloud} is enabled by clicking the *Enable* button in the *Monito ===== Internal collection If you're using <> to -collect metrics about APM Server, {security-features} provides -the +apm_system+ {ref}/built-in-users.html[built-in user] and +collect metrics about APM Server, you can either: + +* Use the built-in `apm_system` user or role +* Create a custom role + +*Use a built-in user or role* + +{security-features} provides the +apm_system+ {ref}/built-in-users.html[built-in user] and +apm_system+ {ref}/built-in-roles.html[built-in role] to send monitoring information. You can use the built-in user, if it's available in your environment, or create a user who has the built-in role assigned, @@ -144,7 +228,9 @@ information. If you use the built-in +apm_system+ user, make sure you set the password before using it. -If you don't use the +apm_system+ user: +*Create a custom role* + +If you don't use the +apm_system+ user, you can create a custom role: -- . Create a *monitoring role*, called something like @@ -164,6 +250,7 @@ If you don't use the +apm_system+ user: |==== + . Assign the *monitoring role* to users who need to write monitoring data to {es}. +. Assign <> to users as needed. -- [float] @@ -176,7 +263,14 @@ See <> for complete details on setting up {metricbeat} collection. If you're <> to collect -metrics about APM Server, {security-features} provides the `remote_monitoring_user` +metrics about APM Server, you can either: + +* Use the built-in `remote_monitoring_user` user or role +* Create a custom user + +*Use a built-in user or role* + +{security-features} provides the `remote_monitoring_user` {ref}/built-in-users.html[built-in user], and the `remote_monitoring_collector` and `remote_monitoring_agent` {ref}/built-in-roles.html[built-in roles] for collecting and sending monitoring information. You can use the built-in user, if @@ -186,7 +280,9 @@ needed to collect and send monitoring information. If you use the built-in `remote_monitoring_user` user, make sure you set the password before using it. -If you don't use the `remote_monitoring_user` user: +*Create a custom user* + +If you don't use the `remote_monitoring_user` user, you can create a custom user: -- . Create a *monitoring user* on the production cluster who will collect and send monitoring @@ -202,6 +298,8 @@ information. Assign the following roles to the *monitoring user*: |`remote_monitoring_agent` |Send monitoring data to the monitoring cluster |==== + +. Assign <> to the *monitoring user* as needed. -- [float] @@ -236,6 +334,7 @@ need to view monitoring data for APM Server: |`monitoring_user` |Grants access to monitoring indices for APM Server |==== +. Assign <> to users as needed. //// *********************************** *********************************** @@ -243,13 +342,16 @@ need to view monitoring data for APM Server: //// [[apm-privileges-api-key]] -=== Grant privileges and roles needed for API key management +=== Create an API key role ++++ -Create an _API key_ user +Create an _API key_ role ++++ You can configure <> to authorize requests to APM Server. + +include::feature-roles.asciidoc[tag=central-config-note] + To create an APM Server user with the required privileges for creating and managing API keys: . Create an **API key role**, called something like `apm_api_key`, @@ -269,9 +371,9 @@ also assign the appropriate `apm` application-level privileges: * To **receive Agent configuration**, assign `config_agent:read`. * To **ingest agent data**, assign `event:write`. * To **upload source maps**, assign `sourcemap:write`. - . Assign the **API key role** to users that need to create and manage API keys. Users with this role can only create API keys that have the same or lower access rights. +. Assign <> to users as needed. [float] [[apm-privileges-api-key-example]] @@ -310,63 +412,19 @@ PUT _security/role/apm_api_key <1> *********************************** *********************************** //// -[[apm-privileges-agent-central-config]] -=== Grant privileges and roles needed for APM Agent central configuration - -++++ -Create a _central config_ user -++++ - -[float] -[[apm-privileges-agent-central-config-server]] -==== APM Server agent central configuration management - -APM Server acts as a proxy between your APM agents and the APM UI. -The APM UI communicates any changed settings to APM Server so that your agents only need to poll the Server -to determine which central configuration settings have changed. - -To grant an APM Server user with the required privileges for managing central configuration in {es} without {kib}, -assign the user the following privileges: - -[options="header"] -|==== -|Type | Privilege | Purpose - -| Index -|`read` on `.apm-agent-configuration` index, `allow_restricted_indices: true` -|Allow APM Server to manage central configurations in {es} -|==== - -The above privileges should be sufficient for APM agent central configuration to work properly -as long as APM Server communicates with {es} successfully. -If it fails, it may fallback to read agent central configuration via {kib} if configured, -which requires the following privileges: - -[options="header"] -|==== -|Type | Privilege | Purpose - -| Spaces -|`Read` on APM UI -|Allow APM Server to manage central configurations via the APM UI -|==== - -TIP: Looking for privileges and roles needed to use central configuration from the APM UI or APM UI API? -See <>. - [[apm-privileges-rum-source-map]] -=== Grant privileges and roles needed for reading source maps +=== Create a source map role ++++ -Create a _source map_ user +Create a _source map_ role ++++ -[float] [[apm-privileges-rum-source-mapping]] -==== APM Server RUM source mapping If <> is enabled, additional privileges are required to read source maps. +include::feature-roles.asciidoc[tag=central-config-note] + To grant an APM Server user with the required privileges for reading RUM source maps from {es} directly without {kib}, assign the user the following privileges: From c2eb01bca0d4e1c114e803b6a79639f1262869c5 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 23 Aug 2024 08:37:48 -0500 Subject: [PATCH 02/17] restructure --- .../observability/apm/feature-roles.asciidoc | 100 +++++++----------- 1 file changed, 41 insertions(+), 59 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index e01962da20..94c99c4f9c 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -9,7 +9,7 @@ NOTE: This documentation only applies to the APM Server binary. Use role-based access control or API keys to grant APM Server users access to secured resources. -* <> +* <> * <> After privileged users have been created, use authentication to connect to a secured Elastic cluster. @@ -29,9 +29,12 @@ APM Server exposes an HTTP endpoint, and as with anything that opens ports on yo you should be careful about who can connect to it. Firewall rules are recommended to ensure only authorized systems can connect. -[float] [[apm-feature-roles]] -=== Feature roles +=== Create and assign feature roles to users + +++++ +Use feature roles +++++ It's recommended that you only grant users the minimum privileges required to use specific features. One approach to managing access on a feature-by-feature basis is to create several feature-related _roles_ and assign one or more of these roles to each _user or group_ based on which features the user needs to access. @@ -47,19 +50,21 @@ Allows a user to view APM Agent central configurations, which is *required* when <> is enabled (it is enabled by default). * <>: Allows a user to publish events collected by APM Server. -* <>: Allows a user to do one or both of these: -** Publish monitoring data -** View monitoring data +* <>: Allows a user to publish monitoring data, +view monitoring data, or both. * <>: Allow a user to create and manage API keys. * <>: Allows a user to read RUM source maps. // Is "deployment" the right word? .Example: Assigning multiple roles to a user ***** -For example, if you have a user in your organization who needs to be able to _____ in a deployment where -central configuration management hasn't been explicitly disabled, you would need to associate the user with -two of the roles listed above: <> -and <>. +For example, if you have a user in your organization who needs to be able to in a deployment where +central configuration management is enabled and <> is enabled, +you would need to assign three of the roles listed above to the user: + +* <> +* <> +* <> ***** {es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a @@ -77,16 +82,14 @@ In general, there are three types of privileges you'll work with: *********************************** *********************************** //// +[float] [[apm-privileges-agent-central-config]] -=== Allow users to access APM Agent central configuration - -++++ -Create a _central config_ role -++++ +=== Create a _central config_ role +[[apm-central-config-role-note]] [IMPORTANT] ==== -The privileges included in this role are *required* for all users when <> is enabled (it is enabled by default). +The privileges included in this role are *required* for all users when <> is enabled (it is enabled by default). You do _not_ need the _Central configuration management_ role only if central configuration management has been explicitly disabled in the APM UI. ==== [[apm-privileges-agent-central-config-server]] @@ -128,24 +131,11 @@ See <>. *********************************** *********************************** //// +[float] [[apm-privileges-to-publish-events]] -=== Create a writer role - -++++ -Create a _writer_ role -++++ +=== Create a _writer_ role APM users that publish events to {es} need privileges to write to APM data streams. - -// tag::central-config-note[] -[NOTE] -==== -*In most cases, users will need to be assigned the* <> *in addition to this role.* - -You do _not_ need the _Central configuration management_ role if central configuration management has been explicitly disabled in the APM UI. -==== -// end::central-config-note[] - To grant an APM user the required privileges for writing events to {es}: . Create a *general writer role*, called something like `apm_writer`, @@ -165,7 +155,8 @@ that has the following privileges: |==== . Assign the *general writer role* to users who need to publish APM data. -. Assign <> to users as needed. +. Assign <> to users as needed +(including the _Central configuration management role_, which is <>). [NOTE] ==== @@ -177,12 +168,9 @@ If <> is enabled, create a separate *********************************** *********************************** //// +[float] [[apm-privileges-to-publish-monitoring]] -=== Create a monitoring role - -++++ -Create a _monitoring_ role -++++ +=== Create a _monitoring_ role {es-security-features} provides built-in users and roles for publishing and viewing monitoring data. The privileges and roles needed to publish monitoring data @@ -197,8 +185,6 @@ depend on the method used to collect that data. [[apm-privileges-to-publish-monitoring-write]] ==== Publish monitoring data -include::feature-roles.asciidoc[tag=central-config-note] - [IMPORTANT] ==== **{ecloud} users:** This section does not apply to our @@ -250,7 +236,8 @@ If you don't use the +apm_system+ user, you can create a custom role: |==== + . Assign the *monitoring role* to users who need to write monitoring data to {es}. -. Assign <> to users as needed. +. Assign <> to users as needed +(including the _Central configuration management role_, which is <>). -- [float] @@ -299,7 +286,8 @@ information. Assign the following roles to the *monitoring user*: |Send monitoring data to the monitoring cluster |==== -. Assign <> to the *monitoring user* as needed. +. Assign <> to the *monitoring user* as needed +(including the _Central configuration management role_, which is <>). -- [float] @@ -334,24 +322,20 @@ need to view monitoring data for APM Server: |`monitoring_user` |Grants access to monitoring indices for APM Server |==== -. Assign <> to users as needed. +. Assign <> to users as needed +(including the _Central configuration management role_, which is <>). //// *********************************** *********************************** *********************************** *********************************** //// +[float] [[apm-privileges-api-key]] -=== Create an API key role - -++++ -Create an _API key_ role -++++ +=== Create an _API key_ role You can configure <> to authorize requests to APM Server. -include::feature-roles.asciidoc[tag=central-config-note] - To create an APM Server user with the required privileges for creating and managing API keys: . Create an **API key role**, called something like `apm_api_key`, @@ -373,11 +357,12 @@ also assign the appropriate `apm` application-level privileges: * To **upload source maps**, assign `sourcemap:write`. . Assign the **API key role** to users that need to create and manage API keys. Users with this role can only create API keys that have the same or lower access rights. -. Assign <> to users as needed. +. Assign <> to users as needed +(including the _Central configuration management role_, which is <>). [float] [[apm-privileges-api-key-example]] -=== Example API key role +==== Example API key role The following example assigns the required cluster privileges, and the ingest agent data `apm` API key application privileges to a role named `apm_api_key`: @@ -412,19 +397,13 @@ PUT _security/role/apm_api_key <1> *********************************** *********************************** //// +[float] [[apm-privileges-rum-source-map]] -=== Create a source map role - -++++ -Create a _source map_ role -++++ +=== Create a _source map_ role [[apm-privileges-rum-source-mapping]] - If <> is enabled, additional privileges are required to read source maps. -include::feature-roles.asciidoc[tag=central-config-note] - To grant an APM Server user with the required privileges for reading RUM source maps from {es} directly without {kib}, assign the user the following privileges: @@ -437,6 +416,9 @@ assign the user the following privileges: |Allow APM Server to read RUM source maps from {es} |==== +Then assign <> to users as needed +(including the _Central configuration management role_, which is <>). + The above privileges should be sufficient for RUM source mapping to work properly as long as APM Server communicates with {es} successfully. If it fails, it may fallback to read source maps via {kib} if configured, From ed83d71d9a9b707f50e5972a5c2970272d6cb530 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 23 Aug 2024 09:25:58 -0500 Subject: [PATCH 03/17] fix build --- docs/en/apm-server/redirects.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/en/apm-server/redirects.asciidoc b/docs/en/apm-server/redirects.asciidoc index 986593cbb4..235cde598e 100644 --- a/docs/en/apm-server/redirects.asciidoc +++ b/docs/en/apm-server/redirects.asciidoc @@ -1114,35 +1114,35 @@ Refer to {observability-guide}/apm-secure-comms-stack.html[With the Elastic Stac {move-notice} -Refer to {observability-guide}/apm-privileges-to-publish-events.html[Create a _writer_ user]. +Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-to-publish-events[Create a _writer_ user]. [role="exclude",id="privileges-to-publish-monitoring"] === Create a _monitoring_ user {move-notice} -Refer to {observability-guide}/apm-privileges-to-publish-monitoring.html[Create a _monitoring_ user]. +Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-to-publish-monitoring[Create a _monitoring_ user]. [role="exclude",id="privileges-api-key"] === Create an _API key_ user {move-notice} -Refer to {observability-guide}/apm-privileges-api-key.html[Create an _API key_ user]. +Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-api-key[Create an _API key_ user]. [role="exclude",id="privileges-agent-central-config"] === Create a _central config_ user {move-notice} -Refer to {observability-guide}/apm-privileges-agent-central-config.html[Create a _central config_ user]. +Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-agent-central-config[Create a _central config_ user]. [role="exclude",id="privileges-rum-source-map"] === Create a _source map_ user {move-notice} -Refer to {observability-guide}/apm-privileges-rum-source-map.html[Create a _source map_ user]. +Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-rum-source-map[Create a _source map_ user]. [role="exclude",id="beats-api-keys"] === Grant access using API keys From 671382f87bafc7ddaf177853354badb0d7f46045 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 28 Aug 2024 17:25:05 -0500 Subject: [PATCH 04/17] address initial feedback --- .../observability/apm/feature-roles.asciidoc | 148 +++++++++++------- 1 file changed, 90 insertions(+), 58 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index 94c99c4f9c..a0d53e90f3 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -45,25 +45,23 @@ A _role_ identifies a set of permissions that translate to privileges on resourc Below are some common tasks that users in your organization might need to do and links to more information on creating roles that provides access to the right resources: +* <>: +Allows a user to publish events collected by APM Server, which is *required* to write to {es}. * <>: Allows a user to view APM Agent central configurations, which is *required* when <> is enabled (it is enabled by default). -* <>: -Allows a user to publish events collected by APM Server. * <>: Allows a user to publish monitoring data, view monitoring data, or both. -* <>: Allow a user to create and manage API keys. +* <>: Allows a user to create and manage API keys. * <>: Allows a user to read RUM source maps. -// Is "deployment" the right word? .Example: Assigning multiple roles to a user ***** -For example, if you have a user in your organization who needs to be able to in a deployment where -central configuration management is enabled and <> is enabled, -you would need to assign three of the roles listed above to the user: +For example, if you use agent central configuration to manage APM agents and you use RUM source mapping, +and you want to create a user who can , you would need to assign these three roles to the user: -* <> * <> +* <> * <> ***** @@ -82,6 +80,52 @@ In general, there are three types of privileges you'll work with: *********************************** *********************************** //// +[float] +[[apm-privileges-to-publish-events]] +=== Create a _writer_ role + + +APM users that publish events to {es} _must_ privileges to write to APM data streams. + +// Not sure if I captured this accurately... +[NOTE] +==== +This is not needed if APM Server doesn't write to {es} directly. +Instead, another configured {es} role will need to be passed to +<>. +==== + +To grant an APM user the required privileges for writing events to {es}: + +. Create a *general writer role*, called something like `apm_writer`, +that has the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`auto_configure` on `traces-apm*`, `logs-apm*`, and `metrics-apm*` indices +|Permits auto-creation of indices and data streams + +|Index +|`create_doc` on `traces-apm*`, `logs-apm*`, and `metrics-apm*` indices +|Write events into {es} +|==== + +. Assign the *general writer role* to users who need to publish APM data. + +[NOTE] +==== +Assign <> to users as needed including the +_Central configuration management role_, which is <>. +==== + +//// +*********************************** *********************************** +*********************************** *********************************** +//// + [float] [[apm-privileges-agent-central-config]] === Create a _central config_ role @@ -123,46 +167,15 @@ which requires the following privileges: |Allow APM Server to manage central configurations via the APM UI |==== -TIP: Looking for privileges and roles needed to use central configuration from the APM UI or APM UI API? -See <>. - -//// -*********************************** *********************************** -*********************************** *********************************** -//// - -[float] -[[apm-privileges-to-publish-events]] -=== Create a _writer_ role - -APM users that publish events to {es} need privileges to write to APM data streams. -To grant an APM user the required privileges for writing events to {es}: - -. Create a *general writer role*, called something like `apm_writer`, -that has the following privileges: -+ -[options="header"] -|==== -|Type | Privilege | Purpose - -|Index -|`auto_configure` on `traces-apm*`, `logs-apm*`, and `metrics-apm*` indices -|Permits auto-creation of indices and data streams - -|Index -|`create_doc` on `traces-apm*`, `logs-apm*`, and `metrics-apm*` indices -|Write events into {es} -|==== - -. Assign the *general writer role* to users who need to publish APM data. -. Assign <> to users as needed -(including the _Central configuration management role_, which is <>). - [NOTE] ==== -If <> is enabled, create a separate <>. +Assign <> to users as needed including the +_Writer role_, which is <>. ==== +TIP: Looking for privileges and roles needed to use central configuration from the APM UI or APM UI API? +See <>. + //// *********************************** *********************************** *********************************** *********************************** @@ -218,7 +231,6 @@ make sure you set the password before using it. If you don't use the +apm_system+ user, you can create a custom role: --- . Create a *monitoring role*, called something like +apm_monitoring_writer+, that has the following privileges: + @@ -236,9 +248,13 @@ If you don't use the +apm_system+ user, you can create a custom role: |==== + . Assign the *monitoring role* to users who need to write monitoring data to {es}. -. Assign <> to users as needed -(including the _Central configuration management role_, which is <>). --- + +[NOTE] +==== +Assign <> to users as needed including the +<> and <>, +both of which are required in most cases. +==== [float] [[apm-privileges-to-publish-monitoring-metricbeat]] @@ -271,7 +287,6 @@ make sure you set the password before using it. If you don't use the `remote_monitoring_user` user, you can create a custom user: --- . Create a *monitoring user* on the production cluster who will collect and send monitoring information. Assign the following roles to the *monitoring user*: + @@ -286,9 +301,12 @@ information. Assign the following roles to the *monitoring user*: |Send monitoring data to the monitoring cluster |==== -. Assign <> to the *monitoring user* as needed -(including the _Central configuration management role_, which is <>). --- +[NOTE] +==== +Assign <> to users as needed including the +<> and <>, +both of which are required in most cases. +==== [float] [[apm-privileges-to-publish-monitoring-view]] @@ -322,8 +340,13 @@ need to view monitoring data for APM Server: |`monitoring_user` |Grants access to monitoring indices for APM Server |==== -. Assign <> to users as needed -(including the _Central configuration management role_, which is <>). + +[NOTE] +==== +Assign <> to users as needed including the +<> and <>, +both of which are required in most cases. +==== //// *********************************** *********************************** @@ -357,8 +380,13 @@ also assign the appropriate `apm` application-level privileges: * To **upload source maps**, assign `sourcemap:write`. . Assign the **API key role** to users that need to create and manage API keys. Users with this role can only create API keys that have the same or lower access rights. -. Assign <> to users as needed -(including the _Central configuration management role_, which is <>). + +[NOTE] +==== +Assign <> to users as needed including the +<> and <>, +both of which are required in most cases. +==== [float] [[apm-privileges-api-key-example]] @@ -416,8 +444,12 @@ assign the user the following privileges: |Allow APM Server to read RUM source maps from {es} |==== -Then assign <> to users as needed -(including the _Central configuration management role_, which is <>). +[NOTE] +==== +Assign <> to users as needed including the +<> and <>, +both of which are required in most cases. +==== The above privileges should be sufficient for RUM source mapping to work properly as long as APM Server communicates with {es} successfully. From 90e213ee91deec9a916cf83ad8f045a882d2ebd3 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 20 Sep 2024 13:05:21 -0500 Subject: [PATCH 05/17] deprecate api key role --- .../apm/command-reference.asciidoc | 33 ++++++++- .../observability/apm/feature-roles.asciidoc | 73 ------------------- docs/en/observability/redirects.asciidoc | 7 +- 3 files changed, 35 insertions(+), 78 deletions(-) diff --git a/docs/en/observability/apm/command-reference.asciidoc b/docs/en/observability/apm/command-reference.asciidoc index 45e65e570d..b85c346fd6 100644 --- a/docs/en/observability/apm/command-reference.asciidoc +++ b/docs/en/observability/apm/command-reference.asciidoc @@ -2,7 +2,7 @@ :deploy-command-short-desc: Deploys the specified function to your serverless environment -:apikey-command-short-desc: Manage API Keys for communication between APM agents and server. +:apikey-command-short-desc: Manage API Keys for communication between APM agents and server ifndef::serverless[] :export-command-short-desc: Exports the configuration, index template, or {ilm-init} policy to stdout @@ -57,7 +57,9 @@ more information, see https://www.elastic.co/subscriptions and [options="header"] |======================= |Commands | -|<> |{apikey-command-short-desc}. +|<> a| {apikey-command-short-desc}. + +deprecated::[8.6.0, Users should create API Keys through {kib} or the {es} REST API. See <>.] |<> |{export-command-short-desc}. |<> |{help-command-short-desc}. ifndef::serverless[] @@ -101,8 +103,31 @@ apm-server apikey SUBCOMMAND [FLAGS] Create an API Key with the specified privilege(s). No required flags. + The user requesting to create an API Key needs to have APM privileges used by the APM Server. -A superuser, by default, has these privileges. For other users, -you can create them. See <> for required privileges. +A superuser, by default, has these privileges. ++ +.*Expand for more information on assigning these privileges to other users* +[%collapsible] +==== +To create an APM Server user with the required privileges for creating and managing API keys: + +. Create an **API key role**, called something like `apm_api_key`, +that has the following `cluster` level privileges: ++ +[options="header"] +|==== +| Privilege | Purpose + +|`manage_own_api_key` +|Allow APM Server to create, retrieve, and invalidate API keys +|==== + +. Depending on what the **API key role** will be used for, +also assign the appropriate `apm` application-level privileges: ++ +* To **receive Agent configuration**, assign `config_agent:read`. +* To **ingest agent data**, assign `event:write`. +* To **upload source maps**, assign `sourcemap:write`. +==== *`info`*:: Query API Key(s). `--id` or `--name` required. diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index a0d53e90f3..fd018fe516 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -52,7 +52,6 @@ Allows a user to view APM Agent central configurations, which is *required* when <> is enabled (it is enabled by default). * <>: Allows a user to publish monitoring data, view monitoring data, or both. -* <>: Allows a user to create and manage API keys. * <>: Allows a user to read RUM source maps. .Example: Assigning multiple roles to a user @@ -348,78 +347,6 @@ Assign <> to users as needed inc both of which are required in most cases. ==== -//// -*********************************** *********************************** -*********************************** *********************************** -//// - -[float] -[[apm-privileges-api-key]] -=== Create an _API key_ role - -You can configure <> to authorize requests to APM Server. - -To create an APM Server user with the required privileges for creating and managing API keys: - -. Create an **API key role**, called something like `apm_api_key`, -that has the following `cluster` level privileges: -+ -[options="header"] -|==== -| Privilege | Purpose - -|`manage_own_api_key` -|Allow APM Server to create, retrieve, and invalidate API keys -|==== - -. Depending on what the **API key role** will be used for, -also assign the appropriate `apm` application-level privileges: -+ -* To **receive Agent configuration**, assign `config_agent:read`. -* To **ingest agent data**, assign `event:write`. -* To **upload source maps**, assign `sourcemap:write`. -. Assign the **API key role** to users that need to create and manage API keys. -Users with this role can only create API keys that have the same or lower access rights. - -[NOTE] -==== -Assign <> to users as needed including the -<> and <>, -both of which are required in most cases. -==== - -[float] -[[apm-privileges-api-key-example]] -==== Example API key role - -The following example assigns the required cluster privileges, -and the ingest agent data `apm` API key application privileges to a role named `apm_api_key`: - -[source,kibana] ----- -PUT _security/role/apm_api_key <1> -{ - "cluster": [ - "manage_own_api_key" <2> - ], - "applications": [ - { - "application": "apm", - "privileges": [ - "event:write" <3> - ], - "resources": [ - "*" - ] - } - ] -} ----- -<1> `apm_api_key` is the name of the role we're assigning these privileges to. Any name can be used. -<2> Required cluster privileges. -<3> Required for API keys that will be used to ingest agent events. - - //// *********************************** *********************************** *********************************** *********************************** diff --git a/docs/en/observability/redirects.asciidoc b/docs/en/observability/redirects.asciidoc index ca06f129e0..3319220b92 100644 --- a/docs/en/observability/redirects.asciidoc +++ b/docs/en/observability/redirects.asciidoc @@ -639,7 +639,12 @@ Refer to <>. [role="exclude",id="privileges-api-key"] === Create an _API key_ user -Refer to <>. +Refer to <>. + +[role="exclude",id="apm-privileges-api-key"] +=== Create an _API key_ user + +Refer to <>. [role="exclude",id="privileges-agent-central-config"] === Create a _central config_ user From 8cdb6cb14a795a5b711ef6c6ba1d88f166eef20c Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 20 Sep 2024 13:28:27 -0500 Subject: [PATCH 06/17] fix typo --- docs/en/observability/apm/feature-roles.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index fd018fe516..4f0ea0d154 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -54,6 +54,7 @@ Allows a user to view APM Agent central configurations, which is *required* when view monitoring data, or both. * <>: Allows a user to read RUM source maps. +// TO DO: Replace with a common task made possible by the listed roles .Example: Assigning multiple roles to a user ***** For example, if you use agent central configuration to manage APM agents and you use RUM source mapping, @@ -84,7 +85,7 @@ In general, there are three types of privileges you'll work with: === Create a _writer_ role -APM users that publish events to {es} _must_ privileges to write to APM data streams. +APM users that publish events to {es} _must_ have privileges to write to APM data streams. // Not sure if I captured this accurately... [NOTE] From 571a58ca34b28e8339ba532ebc45fbd57d2ceb97 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 20 Sep 2024 13:33:36 -0500 Subject: [PATCH 07/17] add use cases --- docs/en/observability/apm/feature-roles.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index 4f0ea0d154..7b03ab79f3 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -90,8 +90,10 @@ APM users that publish events to {es} _must_ have privileges to write to APM dat // Not sure if I captured this accurately... [NOTE] ==== -This is not needed if APM Server doesn't write to {es} directly. -Instead, another configured {es} role will need to be passed to +This is not needed when APM Server doesn't write to {es} directly. +For example, in some cases you may configure APM Server to write to another +output like Logstash, Kafka, or any another output supported by libbeat. +In these cases, another configured {es} role will need to be passed to <>. ==== From c8fb50d5ae36acc0630b7509b28f3afb687b17c1 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 20 Sep 2024 13:42:47 -0500 Subject: [PATCH 08/17] reframe what we mean by users --- .../observability/apm/feature-roles.asciidoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index 7b03ab79f3..f5c0e0928c 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -30,20 +30,20 @@ you should be careful about who can connect to it. Firewall rules are recommended to ensure only authorized systems can connect. [[apm-feature-roles]] -=== Create and assign feature roles to users +=== Create and assign feature roles to APM Server users ++++ Use feature roles ++++ -It's recommended that you only grant users the minimum privileges required to use specific features. One approach to managing access on a feature-by-feature basis is to create several feature-related _roles_ and assign one or more of these roles to each _user or group_ based on which features the user needs to access. +It's recommended that you only grant APM Server users the minimum privileges required to use specific features. One approach to managing access on a feature-by-feature basis is to create several feature-related _roles_ and assign one or more of these roles to each _user or group_ based on which features the user needs to access. [TIP] ==== A _role_ identifies a set of permissions that translate to privileges on resources. You can associate a _user or group_ with an arbitrary number of roles. The total set of permissions that a user has is defined by the union of the permissions in all its roles. ==== -Below are some common tasks that users in your organization might need to do and links to more information on creating roles that provides access to the right resources: +Below are some common tasks that APM Server users might need to do and links to more information on creating roles that provides access to the right resources: * <>: Allows a user to publish events collected by APM Server, which is *required* to write to {es}. @@ -55,10 +55,10 @@ view monitoring data, or both. * <>: Allows a user to read RUM source maps. // TO DO: Replace with a common task made possible by the listed roles -.Example: Assigning multiple roles to a user +.Example: Assigning multiple roles to an APM Server user ***** For example, if you use agent central configuration to manage APM agents and you use RUM source mapping, -and you want to create a user who can , you would need to assign these three roles to the user: +and you want to create an APM Server user who can , you would need to assign these three roles to the user: * <> * <> @@ -66,7 +66,7 @@ and you want to create a user who can , you would need to assign t ***** {es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a -subset of the privileges needed by APM users. +subset of the privileges needed by users. When possible, assign users the built-in roles to minimize the affect of future changes on your security strategy. If no built-in role is available, you can assign users the privileges needed to accomplish a specific task. In general, there are three types of privileges you'll work with: @@ -97,7 +97,7 @@ In these cases, another configured {es} role will need to be passed to <>. ==== -To grant an APM user the required privileges for writing events to {es}: +To grant an APM Server user the required privileges for writing events to {es}: . Create a *general writer role*, called something like `apm_writer`, that has the following privileges: @@ -115,7 +115,7 @@ that has the following privileges: |Write events into {es} |==== -. Assign the *general writer role* to users who need to publish APM data. +. Assign the *general writer role* to APM Server users who need to publish APM data. [NOTE] ==== @@ -249,7 +249,7 @@ If you don't use the +apm_system+ user, you can create a custom role: |Write monitoring events into {es} |==== + -. Assign the *monitoring role* to users who need to write monitoring data to {es}. +. Assign the *monitoring role* to APM Server users who need to write monitoring data to {es}. [NOTE] ==== From e0be5720b565a344ee3b31e0a58f7ac3e80a5d32 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 23 Sep 2024 14:40:33 -0500 Subject: [PATCH 09/17] fix redirect --- docs/en/apm-server/redirects.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/apm-server/redirects.asciidoc b/docs/en/apm-server/redirects.asciidoc index af0b8d896c..3a95d23c84 100644 --- a/docs/en/apm-server/redirects.asciidoc +++ b/docs/en/apm-server/redirects.asciidoc @@ -1128,7 +1128,7 @@ Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-to-publish- {move-notice} -Refer to {observability-guide}/apm-feature-roles.html#apm-privileges-api-key[Create an _API key_ user]. +Refer to {observability-guide}/apm-command-line-options.html#apm-apikey-command[`apikey` command]. [role="exclude",id="privileges-agent-central-config"] === Create a _central config_ user From 0e65820c1fdddd425fe70a8f9d7774c80c3b0d68 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 25 Sep 2024 11:55:44 -0500 Subject: [PATCH 10/17] add monitor privilege --- docs/en/observability/apm/feature-roles.asciidoc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index f5c0e0928c..d4b4f58a97 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -113,6 +113,15 @@ that has the following privileges: |Index |`create_doc` on `traces-apm*`, `logs-apm*`, and `metrics-apm*` indices |Write events into {es} + +|Cluster +|`monitor` +a|* Allows cluster UUID checks, which are performed as part of APM server startup preconditions +if {ref}/security-settings.html[Elasticsearch security] is enabled (it is enabled by default). +* Allows a license check, which is required if <> is enabled. + +NOTE: If you have explicitly disabled Elastic security _and_ you are _not_ using tail-based sampling, +this privilege may not be necessary. |==== . Assign the *general writer role* to APM Server users who need to publish APM data. From 9a2353244784e28f8805ec619daed1d6bc4de180 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 25 Sep 2024 14:14:01 -0500 Subject: [PATCH 11/17] clean up structure --- .../observability/apm/feature-roles.asciidoc | 64 ++++++++++++------- 1 file changed, 42 insertions(+), 22 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index d4b4f58a97..d404ab3db1 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -9,8 +9,29 @@ NOTE: This documentation only applies to the APM Server binary. Use role-based access control or API keys to grant APM Server users access to secured resources. -* <> -* <> +[discrete] +[[apm-secure-comms-stack-role-based]] +=== Role-based access + +{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a +subset of the privileges needed by users. +When possible, assign users the built-in roles to minimize the affect of future changes on your security strategy. + +If no built-in role is available, you can assign users the privileges needed to accomplish a specific task by +creating and assigning feature roles to users. + +<> + +[discrete] +[[apm-secure-comms-stack-api-keys]] +=== API keys + +Instead of using usernames and passwords, you can use API keys to grant access to Elasticsearch resources. You can set API keys to expire at a certain time, and you can explicitly invalidate them. + +<> + +[discrete] +=== More resources After privileged users have been created, use authentication to connect to a secured Elastic cluster. @@ -21,13 +42,13 @@ For secure communication between APM Server and APM Agents, see <> is also available. -[float] [[apm-security-overview]] -=== Security Overview - +[IMPORTANT] +==== APM Server exposes an HTTP endpoint, and as with anything that opens ports on your servers, you should be careful about who can connect to it. Firewall rules are recommended to ensure only authorized systems can connect. +==== [[apm-feature-roles]] === Create and assign feature roles to APM Server users @@ -36,14 +57,22 @@ Firewall rules are recommended to ensure only authorized systems can connect. Use feature roles ++++ -It's recommended that you only grant APM Server users the minimum privileges required to use specific features. One approach to managing access on a feature-by-feature basis is to create several feature-related _roles_ and assign one or more of these roles to each _user or group_ based on which features the user needs to access. +It's recommended that you only grant APM Server users the minimum privileges required to use specific features. +{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a subset of the privileges needed by users. +If no built-in role is available, you can manage access on a feature-by-feature basis by creating several custom feature-related _roles_ and assigning one or more of these roles to each _user or group_ based on which features they need to access. [TIP] ==== A _role_ identifies a set of permissions that translate to privileges on resources. You can associate a _user or group_ with an arbitrary number of roles. The total set of permissions that a user has is defined by the union of the permissions in all its roles. + +In general, there are three types of privileges you'll work with when creating roles: + +* **{es} cluster privileges**: Manage the actions a user can perform against your cluster. +* **{es} index privileges**: Control access to the data in specific indices your cluster. +* **{kib} space privileges**: Grant users write or read access to features and apps within {kib}. ==== -Below are some common tasks that APM Server users might need to do and links to more information on creating roles that provides access to the right resources: +Below are some common roles that APM Server users might need: * <>: Allows a user to publish events collected by APM Server, which is *required* to write to {es}. @@ -57,24 +86,15 @@ view monitoring data, or both. // TO DO: Replace with a common task made possible by the listed roles .Example: Assigning multiple roles to an APM Server user ***** -For example, if you use agent central configuration to manage APM agents and you use RUM source mapping, -and you want to create an APM Server user who can , you would need to assign these three roles to the user: +If you use agent central configuration to manage APM agents, you use RUM source mapping, +and you want to create an APM Server user who can , +you would need to assign these three roles to the user: * <> * <> * <> ***** -{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a -subset of the privileges needed by users. -When possible, assign users the built-in roles to minimize the affect of future changes on your security strategy. -If no built-in role is available, you can assign users the privileges needed to accomplish a specific task. -In general, there are three types of privileges you'll work with: - -* **{es} cluster privileges**: Manage the actions a user can perform against your cluster. -* **{es} index privileges**: Control access to the data in specific indices your cluster. -* **{kib} space privileges**: Grant users write or read access to features and apps within {kib}. - //// *********************************** *********************************** *********************************** *********************************** @@ -223,12 +243,12 @@ Monitoring on {ecloud} is enabled by clicking the *Enable* button in the *Monito If you're using <> to collect metrics about APM Server, you can either: -* Use the built-in `apm_system` user or role +* Use the built-in `apm_system` user or role * Create a custom role *Use a built-in user or role* -{security-features} provides the +apm_system+ {ref}/built-in-users.html[built-in user] and +{es-security-features} provides the +apm_system+ {ref}/built-in-users.html[built-in user] and +apm_system+ {ref}/built-in-roles.html[built-in role] to send monitoring information. You can use the built-in user, if it's available in your environment, or create a user who has the built-in role assigned, @@ -284,7 +304,7 @@ metrics about APM Server, you can either: *Use a built-in user or role* -{security-features} provides the `remote_monitoring_user` +{es-security-features} provides the `remote_monitoring_user` {ref}/built-in-users.html[built-in user], and the `remote_monitoring_collector` and `remote_monitoring_agent` {ref}/built-in-roles.html[built-in roles] for collecting and sending monitoring information. You can use the built-in user, if From 21ed2002b1ce64a729ba58583be5ed6b7b412bca Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 2 Oct 2024 16:01:42 -0500 Subject: [PATCH 12/17] Update docs/en/observability/apm/feature-roles.asciidoc Co-authored-by: Edoardo Tenani <526307+endorama@users.noreply.github.com> --- docs/en/observability/apm/feature-roles.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index d404ab3db1..4d3bb63ed6 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -113,7 +113,7 @@ APM users that publish events to {es} _must_ have privileges to write to APM dat This is not needed when APM Server doesn't write to {es} directly. For example, in some cases you may configure APM Server to write to another output like Logstash, Kafka, or any another output supported by libbeat. -In these cases, another configured {es} role will need to be passed to +In these cases, different authentication credentials will need to be passed to <>. ==== From 10ba5c902f251504be1007eadaed8293a711b151 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 3 Oct 2024 10:03:36 -0500 Subject: [PATCH 13/17] update docs/en/observability/apm/feature-roles.asciidoc --- docs/en/observability/apm/feature-roles.asciidoc | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index 4d3bb63ed6..64590d5d01 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -13,12 +13,8 @@ Use role-based access control or API keys to grant APM Server users access to se [[apm-secure-comms-stack-role-based]] === Role-based access -{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a -subset of the privileges needed by users. -When possible, assign users the built-in roles to minimize the affect of future changes on your security strategy. - -If no built-in role is available, you can assign users the privileges needed to accomplish a specific task by -creating and assigning feature roles to users. +Manage access on a feature-by-feature basis by creating several custom feature-related roles and assigning +one or more of these roles to each APM Server user based on which features they need to access. <> From 03fbafd444bf6aab054a28d95ff4458307fb4fc4 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 3 Oct 2024 10:05:57 -0500 Subject: [PATCH 14/17] Update feature-roles.asciidoc --- docs/en/observability/apm/feature-roles.asciidoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index 64590d5d01..cefa3c1f3a 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -53,9 +53,7 @@ Firewall rules are recommended to ensure only authorized systems can connect. Use feature roles ++++ -It's recommended that you only grant APM Server users the minimum privileges required to use specific features. -{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a subset of the privileges needed by users. -If no built-in role is available, you can manage access on a feature-by-feature basis by creating several custom feature-related _roles_ and assigning one or more of these roles to each _user or group_ based on which features they need to access. +Manage access on a feature-by-feature basis by creating several custom feature-related _roles_ and assigning one or more of these roles to each _user or group_ based on which features they need to access. [TIP] ==== @@ -424,4 +422,4 @@ See <> for more details. // Create an _APM API key_ user // ++++ -// CONTENT \ No newline at end of file +// CONTENT From 9ba0f02671ca63b32b6f8948748569ea4e0d348a Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 3 Oct 2024 13:52:17 -0500 Subject: [PATCH 15/17] update docs/en/observability/apm/feature-roles.asciidoc --- docs/en/observability/apm/feature-roles.asciidoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index cefa3c1f3a..f62ebbe4a6 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -77,16 +77,15 @@ Allows a user to view APM Agent central configurations, which is *required* when view monitoring data, or both. * <>: Allows a user to read RUM source maps. -// TO DO: Replace with a common task made possible by the listed roles .Example: Assigning multiple roles to an APM Server user ***** -If you use agent central configuration to manage APM agents, you use RUM source mapping, -and you want to create an APM Server user who can , -you would need to assign these three roles to the user: +If you want to create an APM Server user who can use the Elastic APM Real User Monitoring (RUM) +JavaScript Agent to ingest data from a frontend application and you use central configuration +to manage APM agents, you would need to assign these three roles to the user: * <> * <> -* <> +* <> ***** //// From d3f19ba15c84096a2c189dc4868b04126fe4b626 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 4 Oct 2024 08:28:58 -0500 Subject: [PATCH 16/17] use roles api in central config section --- .../observability/apm/feature-roles.asciidoc | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/en/observability/apm/feature-roles.asciidoc b/docs/en/observability/apm/feature-roles.asciidoc index f62ebbe4a6..f4ba0fc40a 100644 --- a/docs/en/observability/apm/feature-roles.asciidoc +++ b/docs/en/observability/apm/feature-roles.asciidoc @@ -165,17 +165,23 @@ APM Server acts as a proxy between your APM agents and the APM UI. The APM UI communicates any changed settings to APM Server so that your agents only need to poll the Server to determine which central configuration settings have changed. -To grant an APM Server user with the required privileges for managing central configuration in {es} without {kib}, -assign the user the following privileges: - -[options="header"] -|==== -|Type | Privilege | Purpose - -| Index -|`read` on `.apm-agent-configuration` index, `allow_restricted_indices: true` -|Allow APM Server to manage central configurations in {es} -|==== +To create a role with the required privileges for managing central configuration in {es} without {kib}, +you must to use the {ref}/security-api-put-role.html[Roles API] (the required privileges can't be assigned to a role in Kibana): + +[source,console] +---- +POST /_security/role/apm_agentcfg +{ + "description": "Allow APM Server to manage central configurations in Elasticsearch.", + "indices": [ + { + "names": [".apm-agent-configuration"], + "privileges": ["read"], + "allow_restricted_indices": true + } + ] +} +---- The above privileges should be sufficient for APM agent central configuration to work properly as long as APM Server communicates with {es} successfully. From 72c3693d60e9b82c33ce0dfd0339df901cd96d77 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 7 Oct 2024 15:12:19 -0500 Subject: [PATCH 17/17] apply suggestions from code review Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com> --- .../elastic-stack/feature-roles.asciidoc | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/en/observability/apm/security/elastic-stack/feature-roles.asciidoc b/docs/en/observability/apm/security/elastic-stack/feature-roles.asciidoc index 974a9ebfed..1e33fac6b1 100644 --- a/docs/en/observability/apm/security/elastic-stack/feature-roles.asciidoc +++ b/docs/en/observability/apm/security/elastic-stack/feature-roles.asciidoc @@ -9,16 +9,16 @@ Manage access on a feature-by-feature basis by creating several custom feature-r [TIP] ==== -A _role_ identifies a set of permissions that translate to privileges on resources. You can associate a _user or group_ with an arbitrary number of roles. The total set of permissions that a user has is defined by the union of the permissions in all its roles. +A _role_ identifies a set of permissions that translates to privileges on resources. You can associate a _user or group_ with an arbitrary number of roles. The total set of permissions that a user has is defined by the union of the permissions in all its roles. In general, there are three types of privileges you'll work with when creating roles: * **{es} cluster privileges**: Manage the actions a user can perform against your cluster. -* **{es} index privileges**: Control access to the data in specific indices your cluster. +* **{es} index privileges**: Control access to the data in specific indices of your cluster. * **{kib} space privileges**: Grant users write or read access to features and apps within {kib}. ==== -Below are some common roles that APM Server users might need: +The following are common roles that APM Server users might need: * <>: Allows a user to publish events collected by APM Server, which is *required* to write to {es}. @@ -56,7 +56,7 @@ APM users that publish events to {es} _must_ have privileges to write to APM dat ==== This is not needed when APM Server doesn't write to {es} directly. For example, in some cases you may configure APM Server to write to another -output like Logstash, Kafka, or any another output supported by libbeat. +output like Logstash, Kafka, or any other output supported by libbeat. In these cases, different authentication credentials will need to be passed to <>. ==== @@ -103,12 +103,12 @@ _Central configuration management role_, which is <> is enabled (it is enabled by default). You do _not_ need the _Central configuration management_ role only if central configuration management has been explicitly disabled in the APM UI. +The privileges included in this role are *required* for all users when <> is enabled (it is enabled by default). You need this role unless central configuration management has been explicitly disabled in the APM UI. ==== [[apm-privileges-agent-central-config-server]] @@ -117,7 +117,7 @@ The APM UI communicates any changed settings to APM Server so that your agents o to determine which central configuration settings have changed. To create a role with the required privileges for managing central configuration in {es} without {kib}, -you must to use the {ref}/security-api-put-role.html[Roles API] (the required privileges can't be assigned to a role in Kibana): +you must use the {ref}/security-api-put-role.html[Roles API] (the required privileges can't be assigned to a role in Kibana): [source,console] ---- @@ -134,9 +134,9 @@ POST /_security/role/apm_agentcfg } ---- -The above privileges should be sufficient for APM agent central configuration to work properly +The previous privileges should be sufficient for APM agent central configuration to work properly as long as APM Server communicates with {es} successfully. -If it fails, it may fallback to read agent central configuration via {kib} if configured, +If it fails, it may fallback to read agent central configuration through {kib} if configured, which requires the following privileges: [options="header"] @@ -164,7 +164,7 @@ See <>. [float] [[apm-privileges-to-publish-monitoring]] -=== Create a _monitoring_ role +== Create a _monitoring_ role {es-security-features} provides built-in users and roles for publishing and viewing monitoring data. The privileges and roles needed to publish monitoring data @@ -177,7 +177,7 @@ depend on the method used to collect that data. [float] [[apm-privileges-to-publish-monitoring-write]] -== Publish monitoring data +=== Publish monitoring data [IMPORTANT] ==== @@ -188,10 +188,10 @@ Monitoring on {ecloud} is enabled by clicking the *Enable* button in the *Monito [float] [[apm-privileges-to-publish-monitoring-internal]] -=== Internal collection +==== Internal collection If you're using <> to -collect metrics about APM Server, you can either: +collect metrics about APM Server, either: * Use the built-in `apm_system` user or role * Create a custom role @@ -201,7 +201,7 @@ collect metrics about APM Server, you can either: {es-security-features} provides the +apm_system+ {ref}/built-in-users.html[built-in user] and +apm_system+ {ref}/built-in-roles.html[built-in role] to send monitoring information. You can use the built-in user, if it's available in your -environment, or create a user who has the built-in role assigned, +environment, create a user who has the built-in role assigned, or create a user and manually assign the privileges needed to send monitoring information. @@ -239,7 +239,7 @@ both of which are required in most cases. [float] [[apm-privileges-to-publish-monitoring-metricbeat]] -=== {metricbeat} collection +==== {metricbeat} collection NOTE: When using {metricbeat} to collect metrics, no roles or users need to be created with APM Server. @@ -360,8 +360,8 @@ Assign <> to users as needed inc both of which are required in most cases. ==== -The above privileges should be sufficient for RUM source mapping to work properly +The previous privileges should be sufficient for RUM source mapping to work properly as long as APM Server communicates with {es} successfully. -If it fails, it may fallback to read source maps via {kib} if configured, +If it fails, it may fallback to read source maps through {kib} if configured, which requires additional {kib} privileges. See <> for more details. \ No newline at end of file