diff --git a/docs/api-keys.asciidoc b/docs/api-keys.asciidoc new file mode 100644 index 00000000000..fe06a7a8494 --- /dev/null +++ b/docs/api-keys.asciidoc @@ -0,0 +1,149 @@ +[role="xpack"] +[[beats-api-keys]] +== Grant access using API keys + +Instead of using usernames and passwords, you can use API keys to grant +access to {es} resources. You can set API keys to expire at a certain time, +and you can explicitly invalidate them. Any user with the `manage_api_key` +or `manage_own_api_key` cluster privilege can create API keys. + +{beatname_uc} instances typically send both collected data and monitoring +information to {es}. If you are sending both to the same cluster, you can use the same +API key. For different clusters, you need to use an API key per cluster. + +NOTE: For security reasons, we recommend using a unique API key per {beatname_uc} instance. +You can create as many API keys per user as necessary. + +[float] +[[beats-api-key-publish]] +=== Create an API key for writing events + +In {kib}, navigate to **Stack Management** > **API keys** and click **Create API key**. + +[role="screenshot"] +image::images/server-api-key-create.png[API key creation] + +Enter a name for your API key and select **Restrict privileges**. +In the role descriptors box, assign the appropriate privileges to the new API key. For example: + +[source,json,subs="attributes,callouts"] +---- +{ + "{beat_default_index_prefix}_writer": { + "index": [ + { + "names": ["{beat_default_index_prefix}-*"], + "privileges": ["create_index", "create_doc"] + }, + { + "names": ["{beat_default_index_prefix}-*sourcemap"], + "privileges": ["read"] + }, + ] + } +} +---- + +NOTE: This example only provides privileges for **writing data**. +See <> for additional privileges and information. + +To set an expiration date for the API key, select **Expire after time** +and input the lifetime of the API key in days. + +Click **Create API key**. In the dropdown, switch to **Beats** and copy the API key. + +You can now use this API key in your +{beatname_lc}.yml+ configuration file: + +["source","yml",subs="attributes"] +-------------------- +output.elasticsearch: + api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1> +-------------------- +<1> Format is `id:api_key` (as shown in the Beats dropdown) + +[float] +[[beats-api-key-monitor]] +=== Create an API key for monitoring + +In {kib}, navigate to **Stack Management** > **API keys** and click **Create API key**. + +[role="screenshot"] +image::images/server-api-key-create.png[API key creation] + +Enter a name for your API key and select **Restrict privileges**. +In the role descriptors box, assign the appropriate privileges to the new API key. +For example: + +[source,json,subs="attributes,callouts"] +---- +{ + "{beat_default_index_prefix}_monitoring": { + "index": [ + { + "names": [".monitoring-beats-*"], + "privileges": ["create_index", "create_doc"] + } + ] + } +} +---- + +NOTE: This example only provides privileges for **publishing monitoring data**. +See <> for additional privileges and information. + +To set an expiration date for the API key, select **Expire after time** +and input the lifetime of the API key in days. + +Click **Create API key**. In the dropdown, switch to **Beats** and copy the API key. + +You can now use this API key in your +{beatname_lc}.yml+ configuration file like this: + +["source","yml",subs="attributes"] +-------------------- +monitoring.elasticsearch: + api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1> +-------------------- +<1> Format is `id:api_key` (as shown in the Beats dropdown) + +[float] +[[beats-api-key-es]] +=== Create an API key with {es} APIs + +You can also use {es}'s {ref}/security-api-create-api-key.html[Create API key API] to create a new API key. +For example: + +[source,console,subs="attributes,callouts"] +------------------------------------------------------------ +POST /_security/api_key +{ + "name": "{beat_default_index_prefix}_host001", <1> + "role_descriptors": { + "{beat_default_index_prefix}_writer": { <2> + "index": [ + { + "names": ["{beat_default_index_prefix}-*"], + "privileges": ["create_index", "create_doc"] + }, + { + "names": ["{beat_default_index_prefix}-*sourcemap"], + "privileges": ["read"] + }, + ] + } + } +} +------------------------------------------------------------ +<1> Name of the API key +<2> Granted privileges, see <> + +See the {ref}/security-api-create-api-key.html[Create API key] reference for more information. + +[[learn-more-api-keys]] +[float] +=== Learn more about API keys + +See the {es} API key documentation for more information: + +* {ref}/security-api-create-api-key.html[Create API key] +* {ref}/security-api-get-api-key.html[Get API key information] +* {ref}/security-api-invalidate-api-key.html[Invalidate API key] diff --git a/docs/copied-from-beats/docs/security/api-keys.asciidoc b/docs/copied-from-beats/docs/security/api-keys.asciidoc deleted file mode 100644 index aa397ff5fee..00000000000 --- a/docs/copied-from-beats/docs/security/api-keys.asciidoc +++ /dev/null @@ -1,127 +0,0 @@ -[role="xpack"] -[[beats-api-keys]] -== Grant access using API keys - -Instead of using usernames and passwords, you can use API keys to grant -access to {es} resources. You can set API keys to expire at a certain time, -and you can explicitly invalidate them. Any user with the `manage_api_key` -or `manage_own_api_key` cluster privilege can create API keys. - -{beatname_uc} instances typically send both collected data and monitoring -information to {es}. If you are sending both to the same cluster, you can use the same -API key. For different clusters, you need to use an API key per cluster. - -NOTE: For security reasons, we recommend using a unique API key per {beatname_uc} instance. -You can create as many API keys per user as necessary. - -IMPORTANT: Review <> before creating API keys for {beatname_uc}. - -[float] -[[beats-api-key-publish]] -=== Create an API key for publishing -To create an API key to use for writing data to {es}, use the -{ref}/security-api-create-api-key.html[Create API key API], for example: - -[source,console,subs="attributes,callouts"] ------------------------------------------------------------- -POST /_security/api_key -{ - "name": "{beat_default_index_prefix}_host001", <1> - "role_descriptors": { - "{beat_default_index_prefix}_writer": { <2> - "cluster": ["monitor", "read_ilm"], - "index": [ - { - "names": ["{beat_default_index_prefix}-*"], - "privileges": ["view_index_metadata", "create_doc"] - } - ] - } - } -} ------------------------------------------------------------- -<1> Name of the API key -<2> Granted privileges, see <> - -NOTE: See <> for the list of privileges required to publish events. - -The return value will look something like this: - -[source,console-result,subs="attributes,callouts"] --------------------------------------------------- -{ - "id":"TiNAGG4BaaMdaH1tRfuU", <1> - "name":"{beat_default_index_prefix}_host001", - "api_key":"KnR6yE41RrSowb0kQ0HWoA" <2> -} --------------------------------------------------- -<1> Unique id for this API key -<2> Generated API key - -You can now use this API key in your +{beatname_lc}.yml+ configuration file like this: -["source","yaml"] --------------------- -output.elasticsearch: - api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1> --------------------- -<1> Format is `id:api_key` (as returned by {ref}/security-api-create-api-key.html[Create API key]) - -[float] -[[beats-api-key-monitor]] -=== Create an API key for monitoring -To create an API key to use for sending monitoring data to {es}, use the -{ref}/security-api-create-api-key.html[Create API key API], for example: - -[source,console,subs="attributes,callouts"] ------------------------------------------------------------- -POST /_security/api_key -{ - "name": "{beat_default_index_prefix}_host001", <1> - "role_descriptors": { - "{beat_default_index_prefix}_monitoring": { <2> - "cluster": ["monitor"], - "index": [ - { - "names": [".monitoring-beats-*"], - "privileges": ["create_index", "create"] - } - ] - } - } -} ------------------------------------------------------------- -<1> Name of the API key -<2> Granted privileges, see <> - -NOTE: See <> for the list of privileges required to send monitoring data. - -The return value will look something like this: - -[source,console-result,subs="attributes,callouts"] --------------------------------------------------- -{ - "id":"TiNAGG4BaaMdaH1tRfuU", <1> - "name":"{beat_default_index_prefix}_host001", - "api_key":"KnR6yE41RrSowb0kQ0HWoA" <2> -} --------------------------------------------------- -<1> Unique id for this API key -<2> Generated API key - -You can now use this API key in your +{beatname_lc}.yml+ configuration file like this: -["source","yml",subs="attributes"] --------------------- -monitoring.elasticsearch: - api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1> --------------------- -<1> Format is `id:api_key` (as returned by {ref}/security-api-create-api-key.html[Create API key]) - -[[learn-more-api-keys]] -[float] -=== Learn more about API keys - -See the {es} API key documentation for more information: - -* {ref}/security-api-create-api-key.html[Create API key] -* {ref}/security-api-get-api-key.html[Get API key information] -* {ref}/security-api-invalidate-api-key.html[Invalidate API key] diff --git a/docs/copied-from-beats/docs/shared-securing-beat.asciidoc b/docs/copied-from-beats/docs/shared-securing-beat.asciidoc index e1c47d91f2c..e9889c89e16 100644 --- a/docs/copied-from-beats/docs/shared-securing-beat.asciidoc +++ b/docs/copied-from-beats/docs/shared-securing-beat.asciidoc @@ -44,18 +44,19 @@ endif::[] -- -// APM privileges ifdef::apm-server[] +// APM privileges include::{docdir}/feature-roles.asciidoc[] +// APM API keys +include::{docdir}/api-keys.asciidoc[] endif::[] -// Beat privileges ifndef::apm-server[] +// Beat privileges include::./security/users.asciidoc[] -endif::[] - -// API Keys +// Beat API keys include::./security/api-keys.asciidoc[] +endif::[] // APM Agent security ifdef::apm-server[] diff --git a/docs/images/api-key-copy.png b/docs/images/api-key-copy.png new file mode 100644 index 00000000000..d47fc7cd2de Binary files /dev/null and b/docs/images/api-key-copy.png differ diff --git a/docs/images/api-key-create.png b/docs/images/api-key-create.png new file mode 100644 index 00000000000..1aee7e75baf Binary files /dev/null and b/docs/images/api-key-create.png differ diff --git a/docs/images/server-api-key-create.png b/docs/images/server-api-key-create.png new file mode 100644 index 00000000000..d21c440b19a Binary files /dev/null and b/docs/images/server-api-key-create.png differ diff --git a/docs/secure-communication-agents.asciidoc b/docs/secure-communication-agents.asciidoc index 840416d3b9e..de959d6ead2 100644 --- a/docs/secure-communication-agents.asciidoc +++ b/docs/secure-communication-agents.asciidoc @@ -30,30 +30,35 @@ include::./ssl-input.asciidoc[] [[api-key]] === API keys -You can configure API keys to authorize requests to the APM Server. - NOTE: API keys are sent as plain-text, so they only provide security when used in combination with <>. +They are not applicable for agents running on clients, like the RUM agent, +as there is no way to prevent them from being publicly exposed. -By enabling `apm-server.auth.api_key.enabled: true`, you ensure that only agents with a valid API Key -are able to successfully use APM Server's API (except for RUM endpoints). +Configure API keys to authorize requests to the APM Server. +To enable API key authorization, set `apm-server.auth.api_key.enabled` to `true`. -To secure the communication between APM Agents and the APM Server with API keys: +There are multiple, unique privileges you can assign to each API key. +API keys can have one or more of these privileges: -. Make sure <> is enabled -. <> -. <> -. <> +* *Agent configuration* (`config_agent:read`): Required for agents to read +{kibana-ref}/agent-configuration.html[Agent configuration remotely]. +* *Ingest* (`event:write`): Required for ingesting Agent events. +* *Sourcemap* (`sourcemap:write`): Required for <>. -NOTE: API Keys are not applicable for the RUM Agent, -as there is no way to prevent them from being publicly exposed. +To secure the communication between APM Agents and the APM Server with API keys, +make sure <> is enabled, then complete these steps: + +. <> +. <> +. <> [[configure-api-key]] [float] === Enable and configure API keys -API keys are disabled by default. You can change this, and additional settings, -in the `apm-server.auth.api_key` section of the +{beatname_lc}.yml+ configuration file. +API keys are disabled by default. Enable and configure this feature in the `apm-server.auth.api_key` +section of the +{beatname_lc}.yml+ configuration file. At a minimum, you must enable API keys, and should set a limit on the number of unique API keys that APM Server allows per minute. @@ -72,35 +77,95 @@ All other configuration options are described in <>. [[create-api-key]] [float] -=== Create and validate an API key +=== Create an API key + +[role="screenshot"] +image::images/api-key-create.png[API key creation] + +In {kib}, navigate to **Stack Management** > **API keys** and click **Create API key**. + +Enter a name for your API key and select **Restrict privileges**. +In the role descriptors box, copy and paste the following JSON. +This example creates an API key with privileges for ingesting APM events, +reading agent central configuration, uploading a sourcemap: + +[source,json] +---- +{ + "apm": { + "applications": [ + { + "application": "apm", + "privileges": ["sourcemap:write", "event:write", "config_agent:read"], <1> + "resources": ["*"] + } + ] + } +} +---- +<1> This example adds all three API privileges to the new API key. +Privileges are described <>. Remove any privileges that you do not need. + +To set an expiration date for the API key, select **Expire after time** +and input the lifetime of the API key in days. + +Click **Create API key** and then copy the Base64 encoded API key. +You will need this for the next step, and you will not be able to view it again. + +[role="screenshot"] +image::images/api-key-copy.png[API key copy base64] + +[[set-api-key]] +[float] +=== Set the API key in your APM agents + +You can now apply your newly created API keys in the configuration of each of your APM agents. +See the relevant agent documentation for additional information: + +// Not relevant for RUM and iOS +* *Go agent*: {apm-go-ref}/configuration.html#config-api-key[`ELASTIC_APM_API_KEY`] +* *.NET agent*: {apm-dotnet-ref}/config-reporter.html#config-api-key[`ApiKey`] +* *Java agent*: {apm-java-ref}/config-reporter.html#config-api-key[`api_key`] +* *Node.js agent*: {apm-node-ref}/configuration.html#api-key[`apiKey`] +* *PHP agent*: {apm-php-ref-v}/configuration-reference.html#config-api-key[`api_key`] +* *Python agent*: {apm-py-ref}/configuration.html#config-api-key[`api_key`] +* *Ruby agent*: {apm-ruby-ref}/configuration.html#config-api-key[`api_key`] + +[[configure-api-key-alternative]] +[float] +=== Alternate API key creation methods + +API keys can also be created and validated outside of Kibana: + +* <> +* <> + +[[create-api-key-workflow-apm-server]] +[float] +==== APM Server API key workflow APM Server provides a command line interface for creating, retrieving, invalidating, and verifying API keys. -Keys created using this method can only be used for Agent/Server communication. +Keys created using this method can only be used for communication with APM Server. [[create-api-key-subcommands]] [float] -==== `apikey` subcommands +===== `apikey` subcommands include::{libbeat-dir}/command-reference.asciidoc[tag=apikey-subcommands] [[create-api-key-privileges]] [float] -==== Privileges +===== Privileges -There are three unique privileges you can assign to each API keys. If privileges are not specified at creation time, the created key will have all privileges. -* *Agent configuration*: Required for agents to read -{kibana-ref}/agent-configuration.html[Agent configuration remotely]. -`--agent-config` gives the `config_agent:read` privilege to the created key. -* *Ingest*: Required for ingesting Agent events. -`--ingest` gives the `event:write` privilege to the created key. -* *Sourcemap*: Required for <>. -`--sourcemap` gives the `sourcemap:write` privilege to the created key. +* `--agent-config` grants the `config_agent:read` privilege +* `--ingest` grants the `event:write` privilege +* `--sourcemap` grants the `sourcemap:write` privilege [[create-api-key-workflow]] [float] -==== API key workflow example +===== Create an API key Create an API key with the `create` subcommand. @@ -163,9 +228,9 @@ A full list of `apikey` subcommands and flags is available in the <