Elastic APM 的 API 密钥

APM Server 与托管摄取服务 (managed intake service)

在 Elastic Cloud Hosted 中，APM Server 接收来自 Elastic APM Agent 的数据并将其转换为 Elasticsearch 文档。而在 Elastic Cloud Serverless 中，实际上并没有运行 APM Server，而是由托管摄取服务 (managed intake service) 接收并转换数据。

重要提示

API 密钥是以纯文本形式发送的，因此只有在与 TLS 结合使用时才能提供安全性。

启用后，API 密钥用于授权对 APM Server 或托管接收服务的请求。API 密钥不适用于在客户端上运行的 APM 代理（如 RUM 代理），因为无法防止它们被公开暴露。

你可以为每个 API 密钥分配一个或多个唯一权限

代理配置 (config_agent:read)：代理远程读取代理配置所必需的。
摄取 (event:write)：摄取代理事件所必需的。

要使用 API 密钥保护 APM 代理与 APM Server 或托管接收服务之间的通信，请确保已启用 TLS，然后完成以下步骤

启用 API 密钥
创建一个 API 密钥用户
在 Kibana 中创建 API 密钥
在你的 APM 代理中设置 API 密钥

注意

如果你正在使用 Elastic Distribution of OpenTelemetry (EDOT) SDKs，请参考为 EDOT SDK 创建 APM 代理密钥获取有关创建和使用 API 密钥的 EDOT 特定指导。

启用 API 密钥

Fleet 管理

在 API 密钥身份验证选项中启用 API 密钥授权。你还应该对 APM Server 每分钟允许的唯一 API 密钥数量设置限制；该值应为你监控的服务中配置的唯一 API 密钥的数量。

APM Server 二进制文件

默认情况下禁用 API 密钥。在 apm-server.yml 文件的 apm-server.auth.api_key 部分中启用和配置此功能。

至少，你必须启用 API 密钥，并且应该限制 APM Server 每分钟允许的唯一 API 密钥数量。以下是一个使用 50 个唯一 API 密钥的 apm-server.auth.api_key 配置示例

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

启用 API 密钥
限制 Elasticsearch 每分钟允许的唯一 API 密钥数量。此值应为你监控的服务中配置的唯一 API 密钥的数量。

Elastic Cloud Serverless

默认情况下启用 API 密钥。

在 Kibana 中创建一个 API 密钥用户

API 密钥的访问权限只能等于或低于创建它的用户。

Fleet 管理或 APM Server 二进制文件

你可以创建一个具有最低所需权限的角色，而不是使用超级用户帐户来创建 API 密钥。

创建 APM 代理 API 密钥的用户必须至少具有 manage_own_api_key 集群权限以及希望授予的 APM 应用程序级权限。此外，当从“应用程序”UI 创建 API 密钥时，你需要适当的 Kibana 空间和功能权限。

下面的示例使用 Kibana 角色管理 API 创建一个名为 apm_agent_key_role 的角色。

		POST /_security/role/apm_agent_key_role
{
   "cluster": [ "manage_own_api_key" ],
   "applications": [
      {
         "application":"apm",
         "privileges":[
            "event:write",
            "config_agent:read"
         ],
         "resources":[ "*" ]
      },
      {
         "application":"kibana-.kibana",
         "privileges":[ "feature_apm.all" ],
         "resources":[ "space:default" ]
      }
   ]
}
		
	

此示例为默认空间分配权限。

将新创建的 apm_agent_key_role 角色分配给任何希望创建 APM 代理 API 密钥的用户。

Elastic Cloud Serverless

对于可观测性无服务器（Observability Serverless）项目，需要 Editor（编辑者）或更高角色才能创建和管理 API 密钥。要了解更多信息，请参考分配用户角色和权限。

在“应用程序”UI 中创建 API 密钥

“应用程序”UI 具有内置工作流，你可以使用它轻松创建和查看 APM 代理 API 密钥。只有在“应用程序”UI 中创建的 API 密钥才会显示在此处。

要创建 APM 代理密钥

在 Kibana 的主菜单中找到应用程序，或使用全局搜索字段。
选择任意应用程序页面。
转到设置 > 代理密钥。
选择创建 APM 代理密钥。
输入你的 API 密钥的名称。
分配至少一个权限
- 代理配置 (config_agent:read)：使用代理集中配置进行远程配置所必需的。
- 摄取 (event:write)：摄取代理事件所必需的。
选择创建 APM 代理密钥。
立即复制 API 密钥。该密钥仅显示一次。

注意

API 密钥不会过期。

例如，要创建一个可用于摄取 APM 事件并读取代理集中配置的 API 密钥，请选择 config_agent:read 和 event:write。

要查看你的 Elastic Cloud 无服务器项目的所有 API 密钥，请展开项目设置，选择管理，然后选择API 密钥。

在你的 APM 代理中设置 API 密钥

你现在可以在每个 APM 代理的配置中应用新创建的 API 密钥。有关更多信息，请参阅相关的代理文档

Android: apiKey
Go 代理: ELASTIC_APM_API_KEY
.NET 代理: ApiKey
iOS: withApiKey
Java 代理: api_key
Node.js 代理: apiKey
PHP 代理: api_key
Python 代理: api_key
Ruby 代理: api_key

替代的 API 密钥创建方法

也可以使用 Elasticsearch 创建 API 密钥 API 来创建 API 密钥。

此示例创建一个名为 java-002 的 API 密钥

		POST /_security/api_key
{
  "name": "java-002",
  "expiration": "1d",
  "role_descriptors": {
    "apm": {
      "applications": [
        {
          "application": "apm",
          "privileges": ["sourcemap:write", "event:write", "config_agent:read"],
          "resources": ["*"]
        }
      ]
    }
  }
}
		
	

API 密钥的名称
API 密钥的过期时间
任何已分配的权限

响应将类似于以下内容

		{
  "id" : "GnrUT3QB7yZbSNxKET6d",
  "name" : "java-002",
  "expiration" : 1599153532262,
  "api_key" : "RhHKisTmQ1aPCHC_TPwOvw"
}
		
	

credential 字符串（代理用于与 APM Server 通信的内容）是 API 密钥的 id:api_key 的 base64 编码表示形式。它可以这样创建

echo -n GnrUT3QB7yZbSNxKET6d:RhHKisTmQ1aPCHC_TPwOvw | base64

你可以使用身份验证 API 验证你的 API 密钥是否已正确进行 base64 编码

		curl -H "Authorization: ApiKey R0gzRWIzUUI3eVpiU054S3pYSy06bXQyQWl4TlZUeEcyUjd4cUZDS0NlUQ==" localhost:9200/_security/_authenticate
		
	

如果 API 密钥编码正确，你将看到类似于以下的响应

		{
   "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"
   }
}
		
	

然后，你可以使用 APM Server CLI 验证 API 密钥是否具有所需的权限

		apm-server apikey verify --credentials R25yVVQzUUI3eVpiU054S0VUNmQ6UmhIS2lzVG1RMWFQQ0hDX1RQd092dw==
		
	

如果 API 密钥具有所需的权限，响应将类似于此

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