« APM 代理 TLS 通信 密钥令牌 »
Elastic 文档 ›Elastic 可观测性 [8.16] ›应用和服务监控 ›应用性能监控 (APM) ›安全地使用 APM ›与 APM 代理的安全通信

API 密钥

编辑
API 密钥
编辑

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

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

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

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

要使用 API 密钥保护 APM 代理和 APM 服务器之间的通信，请确保启用了TLS，然后完成以下步骤

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

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

在 Kibana 中创建 API 密钥用户编辑

API 密钥只能具有与创建它们的用户的访问权限相同或更低的访问权限。您可以创建一个具有最低必需权限的角色，而不是使用超级用户帐户创建 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 密钥的用户。

在“应用”UI 中创建 API 密钥编辑

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

使用超级用户帐户或具有上一步骤中创建的角色的用户，在 Kibana 中，在主菜单中找到应用，或使用全局搜索字段。转到设置 → 代理密钥。输入 API 密钥的名称，并至少选择一项权限。

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

单击创建 APM 代理密钥并复制 Base64 编码的 API 密钥。下一步需要此密钥，您将无法再次查看它。

Applications UI API key
在您的 APM 代理中设置 API 密钥编辑

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

其他 API 密钥创建方法编辑

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

APM 服务器 API 密钥工作流程编辑

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

在 8.6.0 版本中已弃用。

用户应通过 Kibana 或 Elasticsearch REST API 创建 API 密钥

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

apikey 子命令编辑
创建

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

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

展开以获取有关将这些权限分配给其他用户的更多信息

要创建具有创建和管理 API 密钥所需权限的 APM 服务器用户

  1. 创建一个名为apm_api_key之类的API 密钥角色，它具有以下cluster级权限

    权限 用途

    manage_own_api_key

    允许 APM 服务器创建、检索和使 API 密钥无效

  2. 根据API 密钥角色的用途，还分配相应的apm应用级权限

    • 要接收代理配置，请分配config_agent:read。
    • 要摄取代理数据，请分配event:write。
    • 要上传源映射，请分配sourcemap:write。
信息
查询 API 密钥。需要--id或--name。
使无效
使 API 密钥无效。需要--id或--name。
验证
检查凭据字符串是否具有给定的权限。需要--credentials。
权限编辑

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

  • --agent-config授予config_agent:read权限
  • --ingest授予event:write权限
  • --sourcemap授予sourcemap:write权限
创建 API 密钥编辑

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

以下示例创建一个名为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-001API 密钥是否具有“代理配置”和“摄取”权限。

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-001API 密钥无效。

apm-server apikey invalidate --name java-001

响应将类似于：

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

apikey子命令和标志的完整列表可在API 密钥命令参考中找到。

Elasticsearch 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 服务器通信）是 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
« APM 代理 TLS 通信 密钥令牌 »