A newer version is available. For the latest information, see the current release documentation.
« Secure communication with APM Agents api_key.* configuration options »
Elastic Docs › ›Secure APM Server ›Secure communication with APM Agents

API keys

edit

API keys

edit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

You can configure an API key to authorize requests to the APM Server. API keys are sent as plain-text, so they only provide security when used in combination with SSL/TLS. By enabling apm-server.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).

To secure the communication between APM Agents and the APM Server with API keys:

  1. Enable SSL/TLS
  2. Enable and configure API keys
  3. Create an API key with APM Server
  4. Set the API key in your APM Agents

API Keys are not applicable for the RUM Agent, as there is no way to prevent them from being publicly exposed.

Enable SSL/TLS communication

edit

To enable SSL/TLS, you need to enable SSL and provide both a private key and a certificate issued by a certificate authority (CA). You can then specify the path to those files in your configuration properties. This will make APM Server serve HTTPS requests instead of HTTP.

Here’s a basic APM Server SSL config with secure communication enabled:

apm-server.ssl.enabled: true
apm-server.ssl.key: "/etc/pki/key.pem"
apm-server.ssl.certificate: "/etc/pki/apm-server.pem"

A full list of configuration options is available in SSL input settings.

Enable and configure API keys

edit

API keys are disabled by default. You can change this, and additional settings, in the apm-server.api_key section of the apm-server.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. Here’s an example apm-server.api_key config using 50 unique API keys:

apm-server.api_key.enabled: true 
apm-server.api_key.limit: 50

Enables API keys

Restricts the number of unique API keys that Elasticsearch allows each minute. This value should be the number of unique API keys configured in your monitored services.

All other configuration options are described in api_key.* configuration options.

Create and validate an API key

edit

APM Server provides a command line interface for creating API keys. Keys created using this method can only be used for Agent/Server communication. The user that creates the API key will need to have the privileges they wish to give to the API key.

apikey subcommands

edit
create

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. Create a role that is then assigned to the user:

PUT /_security/role/apm-privileges {
	"applications": [{
	  "application": "apm",
	  "privileges": ["sourcemap:write", "event:write", "config_agent:read"],
	  "resources": ["*"]
	}]
}
info
Query API Key(s). --id or --name required.
invalidate
Invalidate API Key(s). --id or --name required.
verify
Check if a credentials string has the given privilege(s). --credentials required.

Privileges

edit

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 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 uploading sourcemaps. --sourcemap gives the sourcemap:write privilege to the created key.

API key example workflow

edit

Create an API key with the create subcommand.

The following example creates an API key with a name of java-001, and gives the "agent configuration" and "ingest" privileges.

apm-server apikey create --ingest --agent-config --name java-001

The response will look similar to this:

Name ........... java-001
Expiration ..... never
Id ............. qT4tz28B1g59zC3uAXfW
API Key ........ rH55zKd5QT6wvs3UbbkxOA (won't be shown again)
Credentials .... cVQ0dHoyOEIxZzVDZ3dnMzVWJia3hPQQ== (won't be shown again)

You should always verify the privileges of an API key after creating it. Verification can be done using the verify subcommand.

The following example verifies that the java-001 API key has the "agent configuration" and "ingest" privileges.

apm-server apikey verify --agent-config --ingest --credentials cVQ0dHoyOEIxZzVDZ3dnMzVWJia3hPQQ==

If the API key has the requested privileges, the response will look similar to this:

Authorized for privilege "event:write"...:          Yes
Authorized for privilege "config_agent:read"...:    Yes

To invalidate an API key, use the invalidate subcommand. Due to Elasticsearch caching, there may be a delay between when this subcommand is executed and when it takes effect.

The following example invalidates the java-001 API key.

apm-server apikey invalidate --name java-001

The response will look similar to this:

Invalidated keys ... qT4tz28B1g59zC3uAXfW
Error count ........ 0

A full list of apikey subcommands and flags is available in the API key command reference.

Set the API key in your APM Agents

edit

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:

« Secure communication with APM Agents api_key.* configuration options »