diff --git a/docs/apm/api.asciidoc b/docs/apm/api.asciidoc index 3e4b515e009d..7411f37d3c69 100644 --- a/docs/apm/api.asciidoc +++ b/docs/apm/api.asciidoc @@ -11,6 +11,12 @@ Some APM app features are provided via a REST API: * <> * <> +[float] +[[apm-api-example]] +=== Using the APIs + +Users interacting with APM APIs must have <>. +In addition, there are request headers to be aware of, like `kbn-xsrf: true`, and `Content-Type: applicaton/json`. Here's an example CURL request that adds an annotation to the APM app: [source,curl] @@ -32,16 +38,8 @@ curl -X POST \ }' ---- -For more information, the Kibana <> provides information on how to use Kibana APIs, -like required request headers and authentication options. - -// AGENT CONFIG API -// GET --> Feature (APM) Read -// CREATE/EDIT/DELETE --> Feature (APM) All - -// ANNOTATION API -// Feature (APM) All -// Index: `observability-annotations`. Privileges: `create_index`, `create_doc`, `manage`, and `read`. +The Kibana <> provides additional information on how to use Kibana APIs, +required request headers, and token-based authentication options. //// ******************************************************* @@ -61,6 +59,8 @@ The following Agent configuration APIs are available: * <> to list all Agent configurations. * <> to search for an Agent configuration. +See <> for information on the privileges required to use this API endpoint. + //// ******************************************************* //// @@ -327,6 +327,8 @@ The following APIs are available: By default, annotations are stored in a newly created `observability-annotations` index. The name of this index can be changed in your `config.yml` by editing `xpack.observability.annotations.index`. +See <> for information on the privileges required to use this API endpoint. + //// ******************************************************* //// diff --git a/docs/apm/apm-app-users.asciidoc b/docs/apm/apm-app-users.asciidoc new file mode 100644 index 000000000000..442a07d27972 --- /dev/null +++ b/docs/apm/apm-app-users.asciidoc @@ -0,0 +1,256 @@ +[role="xpack"] +[[apm-app-users]] +== APM app users and privileges + +:beat_default_index_prefix: apm +:beat_kib_app: APM app +:annotation_index: `observability-annotations` + +++++ +Users and privileges +++++ + +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. + +{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a +subset of the privileges needed by APM 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: + +* **Elasticsearch cluster privileges**: Manage the actions a user can perform against your cluster. +* **Elasticsearch index privileges**: Control access to the data in specific indices your cluster. +* **Kibana space privileges**: Grant users write or read access to features and apps within Kibana. + +//// +*********************************** *********************************** +//// + +[role="xpack"] +[[apm-app-reader]] +=== APM reader user + +++++ +Create an APM reader user +++++ + +[[apm-app-reader-full]] +==== Full APM reader + +APM reader users typically need to view the APM app, dashboards, and visualizations that contain APM data. +These users might also need to create and edit dashboards, visualizations, and machine learning jobs. + +. Assign the following built-in roles: ++ +[options="header"] +|==== +|Role | Purpose + +|`kibana_admin` +|Grants access to all features in Kibana. + +|`apm_user` +|Grants the privileges required for APM users on +{beat_default_index_prefix}*+ indices + +|`machine_learning_admin` +|Grants the privileges required to create, update, and view machine learning jobs +|==== + +[[apm-app-reader-partial]] +==== Partial APM reader + +In some instances, you may wish to restrict certain Kibana apps that a user has access to. + +. Assign the following built in roles: ++ +[options="header"] +|==== +|Role | Purpose +|`apm_user` +|Grants the privileges required for APM users on +{beat_default_index_prefix}*+ indices +|==== + +. Assign space privileges to any Kibana space that the user needs access to. +Here are two examples: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +| `Read` or `All` on the {beat_kib_app} +| Allow the use of the the {beat_kib_app} + +| Spaces +| `Read` or `All` on Dashboards, Visualize, and Discover +| Allow the user to view, edit, and create dashboards, as well as browse data. +|==== + +. Finally, assign the following role if a user needs to enable and edit machine learning features: ++ +[options="header"] +|==== +|Role | Purpose + +|`machine_learning_admin` +|Grants the privileges required to create, update, and view machine learning jobs +|==== + +//// +*********************************** *********************************** +//// + +[role="xpack"] +[[apm-app-central-config-user]] +=== APM app central config user + +++++ +Create a central config user +++++ + +[[apm-app-central-config-manager]] +==== Central configuration manager + +Central configuration users need to be able to view, create, update, and delete Agent configurations. + +. Assign the following built-in roles: ++ +[options="header"] +|==== +|Role | Purpose + +|`apm_user` +|Grants the privileges required for APM users on +{beat_default_index_prefix}*+ indices +|==== + +. Assign the following Kibana space privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +|`All` on {beat_kib_app} +|Allow full use of the {beat_kib_app} +|==== + +[[apm-app-central-config-reader]] +==== Central configuration reader + +In some instances, you may wish to create a user that can only read central configurations, +but not create, update, or delete them. + +. Assign the following built-in roles: ++ +[options="header"] +|==== +|Role | Purpose +|`apm_user` +|Grants the privileges required for APM users on +{beat_default_index_prefix}*+ indices +|==== + +. Assign the following Kibana space privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +|`read` on the {beat_kib_app} +|Allow read access to the {beat_kib_app} +|==== + +[[apm-app-central-config-api]] +==== Central configuration API + +See <>. + +//// +*********************************** *********************************** +//// + +[role="xpack"] +[[apm-app-api-user]] +=== APM app API user + +++++ +Create an API user +++++ + +[[apm-app-api-config-manager]] +==== Central configuration API + +Users can list, search, create, update, and delete central configurations via the APM app API. + +. Assign the following Kibana space privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +|`all` on the {beat_kib_app} +|Allow all access to the {beat_kib_app} +|==== + +[[apm-app-api-config-reader]] +==== Central configuration API reader + +Sometimes a user only needs to list and search central configurations via the APM app API. + +. Assign the following Kibana space privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +|`read` on the {beat_kib_app} +|Allow read access to the {beat_kib_app} +|==== + +[[apm-app-api-annotation-manager]] +==== Annotation API + +Users can use the annotation API to create annotations on their APM data. + +. Create a new role, named something like `annotation_role`, +and assign the following privileges: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +|Index +|`manage` on +{annotation_index}+ index +|Check if the +{annotation_index}+ index exists + +|Index +|`read` on +{annotation_index}+ index +|Read the +{annotation_index}+ index + +|Index +|`create_index` on +{annotation_index}+ index +|Create the +{annotation_index}+ index + +|Index +|`create_doc` on +{annotation_index}+ index +|Create new annotations in the +{annotation_index}+ index +|==== + +. Assign the `annotation_role` created previously, +and the following Kibana space privileges to any annotation API users: ++ +[options="header"] +|==== +|Type | Privilege | Purpose + +| Spaces +|`all` on the {beat_kib_app} +|Allow all access to the {beat_kib_app} +|==== + +//LEARN MORE +//Learn more about <>. diff --git a/docs/apm/index.asciidoc b/docs/apm/index.asciidoc index 4f0bd20d10a1..1eff4f578af9 100644 --- a/docs/apm/index.asciidoc +++ b/docs/apm/index.asciidoc @@ -38,6 +38,8 @@ include::getting-started.asciidoc[] include::how-to-guides.asciidoc[] +include::apm-app-users.asciidoc[] + include::settings.asciidoc[] include::api.asciidoc[]