API 密钥

Elastic Stack

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

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

• 代理配置 (config_agent:read)：代理远程读取 代理配置时需要。
• 采集 (event:write)：采集代理事件时需要。

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

1. 启用 API 密钥
2. 创建 API 密钥用户
3. 在 Kibana 中创建 API 密钥
4. 在 APM 代理中设置 API 密钥

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

API 密钥只能拥有与创建它们的用户相同或更低的访问权限。

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

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

Fleet 管理或 APM Server 二进制文件

使用超级用户帐户或在上一步中创建的角色，在 Kibana 的主菜单中找到 Applications，或使用 全局搜索字段。 转到 Settings → Agent keys。 输入 API 密钥的名称，然后选择至少一个权限。

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

单击 Create APM Agent key 并复制 Base64 编码的 API 密钥。 您将在下一步中需要此密钥，并且您将无法再次查看它。

×

Elastic Cloud Serverless

创建新 API 密钥

1. 在您的 Elastic Observability Serverless 项目中，转到任何 Applications 页面。
2. 单击 Settings。
3. 选择 Agent keys 选项卡。
4. 单击 Create APM agent key。
5. 命名密钥并为其分配权限。
6. 单击 Create APM agent key。
7. 立即复制密钥。 您将无法再次看到它。 API 密钥不会过期。

查看项目的全部 API 密钥

1. 展开 Project settings。
2. 选择 Management。
3. 选择 API keys。

您现在可以在每个 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

Elastic Stack Serverless 不可用

也可以在 Kibana 外部创建和验证 API 密钥

• APM Server API 密钥工作流程
• Elasticsearch API 密钥工作流程

此 API 创建方法仅适用于 APM Server 二进制文件。

APM Server 提供了一个命令行界面，用于创建、检索、失效和验证 API 密钥。 使用此方法创建的密钥只能用于与 APM Server 通信。

create

使用指定的权限创建 API 密钥。 没有必需的标志。

请求创建 API 密钥的用户需要具有 APM Server 使用的 APM 权限。 默认情况下，超级用户具有这些权限。

info

查询 API 密钥。 需要 --id 或 --name。

invalidate

使 API 密钥失效。 需要 --id 或 --name。

verify

检查凭据字符串是否具有给定的权限。 需要 --credentials。

如果在创建时未指定权限，则创建的密钥将具有所有权限。

• --agent-config 授予 config_agent:read 权限
• --ingest 授予 event:write 权限
• --sourcemap 授予 sourcemap:write 权限

使用 create 子命令创建一个 API 密钥。

以下示例创建一个 name 为 java-001 的 API 密钥，并授予“代理配置”和“采集”权限。

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

响应将类似于这样

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

您应始终在创建 API 密钥后验证其权限。 可以使用 verify 子命令完成验证。

以下示例验证 java-001 API 密钥是否具有“代理配置”和“采集”权限。

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

如果 API 密钥具有请求的权限，则响应将类似于这样

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

要使 API 密钥失效，请使用 invalidate 子命令。 由于 Elasticsearch 缓存，执行此子命令与生效之间可能存在延迟。

以下示例使 java-001 API 密钥失效。

apm-server apikey invalidate --name java-001

响应将类似于这样

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

完整的 apikey 子命令和标志列表可在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": ["*"]
        }
      ]
    }
  }
}

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

响应将类似于这样

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