kibana/docs/apm/apm-app-users.asciidoc

[role="xpack"]
[[apm-app-users]]
== APM app users and privileges

:beat_default_index_prefix: apm
:annotation_index: observability-annotations

++++
<titleabbrev>Users and privileges</titleabbrev>
++++

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 feature privileges**: Grant users write or read access to features and apps within Kibana.

Select your use-case to get started:

* <<apm-app-reader>>
* <<apm-app-annotation-user-create>>
* <<apm-app-central-config-user>>
* <<apm-app-api-user>>

////
***********************************  ***********************************
////

[role="xpack"]
[[apm-app-reader]]
=== APM reader user

++++
<titleabbrev>Create an APM reader user</titleabbrev>
++++

APM reader users typically need to view the APM app and dashboards and visualizations that use APM data.
These users might also need to create and edit dashboards, visualizations, and machine learning jobs.

[[apm-app-reader-full]]
==== APM reader

To create an APM reader user:

. Create a new role, named something like `read-apm`, and assign the following privileges:
+
--
include::./tab-widgets/apm-app-reader/widget.asciidoc[]
--
+
TIP: Using the deprecated APM Server binaries?
Add the privileges under the **Classic APM indices** tab above.

. Assign the `read-apm` role created in the previous step, and the following built-in roles to
any APM reader users:
+
[options="header"]
|====
|Role | Purpose

|`kibana_admin`
|Grants access to all features in Kibana.

|`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.

. Create a new role, named something like `read-apm-partial`, and assign the following privileges:
+
--
include::./tab-widgets/apm-app-reader/widget.asciidoc[]
--
+
TIP: Using the deprecated APM Server binaries?
Add the privileges under the **Classic APM indices** tab above.

. Assign feature privileges to any Kibana feature that the user needs access to.
Here are two examples:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Kibana
| `Read` or `All` on the {beat_kib_app} feature
| Allow the use of the the {beat_kib_app} apps

| Kibana
| `Read` or `All` on Dashboards 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-annotation-user-create]]
=== APM app annotation user

++++
<titleabbrev>Create an annotation user</titleabbrev>
++++

NOTE: By default, the `apm_user` built-in role provides access to Observability annotations.
You only need to create an annotation user if the default annotation index
defined in <<apm-settings-kb,`xpack.observability.annotations.index`>> has been customized.

[[apm-app-annotation-user]]
==== Annotation user

View deployment annotations in the APM app.

. Create a new role, named something like `annotation_user`,
and assign the following privileges:
+
[options="header"]
|====
|Type | Privilege | Purpose

|Index
|`read` on +\{ANNOTATION_INDEX\}+^1^
|Read-only access to the observability annotation index

|Index
|`view_index_metadata` on +\{ANNOTATION_INDEX\}+^1^
|Read-only access to observability annotation index metadata
|====
+
^1^ +\{ANNOTATION_INDEX\}+ should be the index name you've defined in
<<apm-settings-kb,`xpack.observability.annotations.index`>>.

. Assign the `annotation_user` created previously, and the roles and privileges necessary to create
a <<apm-app-reader-full,full>> or <<apm-app-reader-partial,partial>> APM reader to any users that need to view annotations in the APM app

[[apm-app-annotation-api]]
==== Annotation API

See <<apm-app-api-user>>.

////
***********************************  ***********************************
////

[role="xpack"]
[[apm-app-central-config-user]]
=== APM app central config user

++++
<titleabbrev>Create a central config user</titleabbrev>
++++

[[apm-app-central-config-manager]]
==== Central configuration manager

Central configuration users need to be able to view, create, update, and delete Agent configurations.

. Create a new role, named something like `central-config-manager`, and assign the following privileges:
+
--
include::./tab-widgets/central-config-users/widget.asciidoc[]
--
+
TIP: Using the deprecated APM Server binaries?
Add the privileges under the **Classic APM indices** tab above.

. Assign the `central-config-manager` role created in the previous step,
and the following Kibana feature privileges to anyone who needs to manage central configurations:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Kibana
|`All` on the {beat_kib_app} feature
|Allow full use of the {beat_kib_app} apps
|====

[[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.

. Create a new role, named something like `central-config-reader`, and assign the following privileges:
+
--
include::./tab-widgets/central-config-users/widget.asciidoc[]
--
+
TIP: Using the deprecated APM Server binaries?
Add the privileges under the **Classic APM indices** tab above.

. Assign the `central-config-reader` role created in the previous step,
and the following Kibana feature privileges to anyone who needs to read central configurations:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Kibana
|`read` on the {beat_kib_app} feature
|Allow read access to the {beat_kib_app} apps
|====

[[apm-app-central-config-api]]
==== Central configuration API

See <<apm-app-api-user>>.

////
***********************************  ***********************************
////

[role="xpack"]
[[apm-app-api-user]]
=== APM app API user

++++
<titleabbrev>Create an API user</titleabbrev>
++++

[[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 feature privileges:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Kibana
|`all` on the {beat_kib_app} feature
|Allow all access to the {beat_kib_app} apps
|====

[[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 feature privileges:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Kibana
|`read` on the {beat_kib_app} feature
|Allow read access to the {beat_kib_app} apps
|====

[[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 feature privileges to any annotation API users:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Kibana
|`all` on the {beat_kib_app} feature
|Allow all access to the {beat_kib_app} apps
|====

//LEARN MORE
//Learn more about <<kibana-feature-privileges,feature privileges>>.