API keysedit
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 API keys 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:
API Keys are not applicable for the RUM Agent, as there is no way to prevent them from being publicly exposed.
Enable and configure API keysedit
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:
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 keyedit
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.
apikey
subcommandsedit
-
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. See create an API key user for required privileges.
-
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.
Privilegesedit
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 theconfig_agent:read
privilege to the created key. -
Ingest: Required for ingesting Agent events.
--ingest
gives theevent:write
privilege to the created key. -
Sourcemap: Required for uploading sourcemaps.
--sourcemap
gives thesourcemap:write
privilege to the created key.
API key workflow exampleedit
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 .... cVQ0dHoyOEIxZzU5ekMzdUFYZlc6ckg1NXpLZDVRVDZ3dnMzVWJia3hPQQ== (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 cVQ0dHoyOEIxZzU5ekMzdUFYZlc6ckg1NXpLZDVRVDZ3dnMzVWJia3hPQQ==
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.
Alternate API key workflow exampleedit
Instead of using the APM Server CLI, it is possible to create API keys using the Elasticsearch create API key API.
This example creates an API key named java-002
:
POST /_security/api_key { "name": "java-002", "expiration": "1d", "role_descriptors": { "apm": { "applications": [ { "application": "apm", "privileges": ["sourcemap:write", "event:write", "config_agent:read"], "resources": ["*"] } ] } } }
The response will look similar to this:
{ "id" : "GnrUT3QB7yZbSNxKET6d", "name" : "java-002", "expiration" : 1599153532262, "api_key" : "RhHKisTmQ1aPCHC_TPwOvw" }
The credential
string, which is what agents use to communicate with APM Server,
is a base64 encoded representation of the API key’s id:api_key
.
It can be created like this:
echo -n GnrUT3QB7yZbSNxKET6d:RhHKisTmQ1aPCHC_TPwOvw | base64
You can verify your API key has been base64-encoded correctly with the Authenticate API:
curl -H "Authorization: ApiKey R0gzRWIzUUI3eVpiU054S3pYSy06bXQyQWl4TlZUeEcyUjd4cUZDS0NlUQ==" localhost:9200/_security/_authentication
If the API key has been encoded correctly, you’ll see a response similar to the following:
{ "username":"1325298603", "roles":[], "full_name":null, "email":null, "metadata":{ "saml_nameid_format":"urn:oasis:names:tc:SAML:2.0:nameid-format:transient", "saml(http://saml.elastic-cloud.com/attributes/principal)":[ "1325298603" ], "saml_roles":[ "superuser" ], "saml_principal":[ "1325298603" ], "saml_nameid":"_7b0ab93bbdbc21d825edf7dca9879bd8d44c0be2", "saml(http://saml.elastic-cloud.com/attributes/roles)":[ "superuser" ] }, "enabled":true, "authentication_realm":{ "name":"_es_api_key", "type":"_es_api_key" }, "lookup_realm":{ "name":"_es_api_key", "type":"_es_api_key" } }
You can then use the APM Server CLI to verify that the API key has the requested privileges:
apm-server apikey verify --credentials R25yVVQzUUI3eVpiU054S0VUNmQ6UmhIS2lzVG1RMWFQQ0hDX1RQd092dw==
If the API key has the requested privileges, the response will look similar to this:
Authorized for privilege "config_agent:read"...: Yes Authorized for privilege "event:write"...: Yes Authorized for privilege "sourcemap:write"...: Yes
Set the API key in your APM Agentsedit
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:
-
Go Agent:
ELASTIC_APM_API_KEY
-
.NET Agent:
ApiKey
-
Java Agent:
api_key
-
Python Agent:
api_key
-
Ruby Agent:
api_key