docs: Update security documentation #3799
Conversation
💚 Build Succeeded
Expand to view the summary
Build stats
|
| + | ||
|
|
||
| If you use the built-in +{beat_monitoring_user}+ user, | ||
| make sure you set the password before assigning it to users that need to write monitoring data to {es}. |
There was a problem hiding this comment.
This sentence confused me a bit, as the user is not assigned to other users; how about something like If you use the built-in +{beat_monitoring_user}+ user, make sure you set the password before using it.
| {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, use the built-in roles to minimize the affect of future changes on your security strategy. | ||
| If no built-in role is available, you can create a custom user and assign |
There was a problem hiding this comment.
%s/a custom user/a custom role/
A custom user would need to be created in both cases.
|
|
||
| * **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. |
| can be performed by dedicated users with stricter privileges. | ||
|
|
||
| [float] | ||
| ===== Event writer role |
There was a problem hiding this comment.
Looking at this again, the section for Event writer roles doesn't make too much sense as it is the same privileges as the general ones. Maybe it is better to remove this section after all, and only keep the section for Sourcemap writer role as that actually needs less privileges.
| endif::apm-server[] | ||
| |Index | ||
| |`read` on +{beat_default_index_prefix}-*sourcemap+ indices | ||
| |Read sourcemaps from {es} |
There was a problem hiding this comment.
You could mention that this privilege is only required if RUM and sourcemap is enabled (apm-server.rum.enabled: true and apm-server.rum.source_mapping.enabled: true)
There was a problem hiding this comment.
I'm hesitant to add the config values here, but I've added links to each value. How does this change look to you?
| |Role | Purpose | ||
|
|
||
| |`kibana_user` | ||
| |Use the APM UI |
There was a problem hiding this comment.
The kibana_user is deprecated (sorry forgot to mention that) and should be replaced by the kibana_admin. When granting the kibana_admin one already grants all the privileges for Kibana spaces. This makes for a nice getting-started experience.
In the section below, where pointing out more fine granular privileges, please ensure to note that those can be used combined with the apm_user instead of granting the whole kibana_user/kibana_admin role.
There was a problem hiding this comment.
You did mention it, I just forgot 😨. Thanks for the reminder. Good point on the kibana_admin. I've clarified.
|
|
||
| . Assign the *writer role* to users who will index events into {es}. | ||
| [[privileges-agent-central-config-server]] | ||
| ==== APM Server central configuration management |
There was a problem hiding this comment.
Users might not be super familiar with the internals, that an APM agent retrieves the updated agent configuration via APM Server when they change it in Kibana. Therefore some explanation about this would be great, something like: When configuring central configurations for your agents in Kibana, ensure the user that you configure in APM Server to talk to Kibana has this role.
|
|
||
| To grant users the required privileges: | ||
| [[privileges-agent-central-config-kib]] | ||
| ==== Kibana central configuration management |
There was a problem hiding this comment.
Sorry for repeating myself, but this would also be a section worth moving to Kibana in the long run.
| |==== | ||
|
|
||
| [[privileges-agent-central-config-api]] | ||
| ==== Central configuration management API |
There was a problem hiding this comment.
Why is this a dedicated section and not part of the https://github.com/elastic/apm-server/pull/3799/files#diff-d57f94e88b4f7a29666f5fd313851fbfR474 section?
There was a problem hiding this comment.
Because I'm planning to move the APM app API content to the APM app docs but was just staging everything here to get it correct and see it all in one place :)
|
@simitt, I believe this is finally ready for review. Sorry it took so long 😬. I've chosen not to tackle the Metricbeat monitoring role or monitoring writer role changes in this PR. I'll examine these in a follow-up PR. |
| +{beat_monitoring_user}+ {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 privileges needed to send monitoring | ||
| information. |
There was a problem hiding this comment.
minor note: you don't touch on the beat_monitoring_user role any more. Should we change to something like:
You can use the built-in user, if it's available in your
environment, or create a user which has the built-in role assigned,
or create a user and manually assign the required privileges.
information.
docs/feature-roles.asciidoc
Outdated
| information, and another for viewing it | ||
| * <<privileges-to-publish-events,Writer role>>: To publish events collected by {beatname_uc}. | ||
| * <<privileges-agent-central-config,Central configuration management role>>: To view, create, | ||
| update, and delete APM Agent central configurations. |
There was a problem hiding this comment.
The described role can only read from APM Agent central configurations, since everything else was moved to Kibana.
# Conflicts: # docs/copied-from-beats/docs/https.asciidoc # docs/copied-from-beats/docs/security/basic-auth.asciidoc # docs/copied-from-beats/docs/security/users.asciidoc
# Conflicts: # docs/copied-from-beats/docs/https.asciidoc # docs/copied-from-beats/docs/security/basic-auth.asciidoc # docs/copied-from-beats/docs/security/users.asciidoc
Depends on elastic/beats#18594.
Motivation/summary
This PR updates the security documentation for APM Server to better explain the roles and privileges required to perform certain tasks.
Additional information, including a few follow-up tasks, is outlined in #3596 (comment).
Doc preview
http://apm-server_3799.docs-preview.app.elstc.co/diff
Related issues