企业官网建设流程全解析

Apache SkyWalking Token Authentication：基于 Token 的 Agent 与 OAP 数据信任校验机制

【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sky/skywalking

Token Authentication（Token 认证）是 Apache SkyWalking 为 Agent（探针）与 OAP（Observability Analysis Platform）服务端之间提供的一道应用层信任校验机制。本文基于 docs/en/setup/backend/backend-token-auth.md 官方文档，结合 OAP 端receiver-sharing-server模块源码与默认配置，完整讲解 Token 认证的作用、配置方法、失败排查与常见问题，帮助读者在需要校验"应用数据来源可信"的场景下正确启用该能力。

版本支持与适用场景

Token 认证自SkyWalking 7.0.0起提供支持。其典型应用场景包括：

• Agent 与 OAP 之间通过网络（而非本地回环）通信，需要确保上报数据确实来自受信任的探针；
• 多团队共享同一套 OAP 集群，希望限制数据采集来源；
• 与 TLS 配合，在不可信网络上建立"传输可信 + 数据可信"的双层防线。

在动手配置前，需要先理解一个关键定位：TLS 与 Token 认证解决的是两个不同层次的问题（详见后文 FAQ 小节）。

为什么有了 TLS 之后还需要 Token 认证？

这是理解该机制的第一性问题。两者分工如下：

官方文档的原话是：TLS 保障的是"可信网络（a trusted network）"，而 Token 认证监控的是"应用数据是否可以被信任（whether application data can be trusted）"。换句话说，TLS 只保证数据在传输途中不被偷看、不被篡改，但它无法区分"这条数据是合法 Agent 发的，还是任何能连上端口的客户端伪造的"。Token 认证恰好补上这一环：OAP 对每一个来自 Agent 的请求进行校验，只有携带正确 Token 的请求才被放行。

Token 是什么？

在 SkyWalking 当前实现中，Token 被定义为一段简单的字符串（simple string），不涉及复杂的签名或加密算法。它本质上是一个预共享密钥（Pre-Shared Key, PSK）：Agent 端与 OAP 端配置同一个字符串，OAP 在收到请求时拿请求中携带的 Token 与本地配置的 Token 做比对。

Token 仅通过字符串相等比较完成校验，从源码结构看，OAP 端核心校验逻辑位于 AuthenticationInterceptor.java：

private static final Metadata.Key<String> AUTH_HEAD_HEADER_NAME = Metadata.Key.of("Authentication", Metadata.ASCII_STRING_MARSHALLER); @Override public <REQUEST, RESPONSE> ServerCall.Listener<REQUEST> interceptCall( ServerCall<REQUEST, RESPONSE> serverCall, Metadata metadata, ServerCallHandler<REQUEST, RESPONSE> serverCallHandler) { String token = metadata.get(AUTH_HEAD_HEADER_NAME); if (expectedToken.equals(token)) { return serverCallHandler.startCall(serverCall, metadata); } else { serverCall.close(Status.PERMISSION_DENIED, new Metadata()); return listener; } }

该拦截器实现了 gRPC 的ServerInterceptor：从 gRPC 请求的元数据（Metadata）中读取名为Authentication的 Header 值，与 OAP 配置的expectedToken进行equals比较。匹配则继续调用链，不匹配则直接以PERMISSION_DENIED状态关闭调用。

配置 Token：Agent 端与 OAP 端必须成对设置

Token 的启用以 OAP 端设置为准，Agent 端需要配置相同的值才能通过校验。官方文档给出了两端各自的配置方式。

第 1 步：在 Agent 端设置 Token

在 Java Agent 的agent.config配置文件中设置：

# Authentication active is based on backend setting, see application.yml for more details. agent.authentication = ${SW_AGENT_AUTHENTICATION:xxxx}

• 配置项：agent.authentication
• 环境变量覆盖：SW_AGENT_AUTHENTICATION
• 注意：注释明确说明"认证是否生效取决于后端（OAP）设置"，即 Agent 端配置的 Token 只有在 OAP 端也开启了authentication时才有意义。

第 2 步：在 OAP 端 application.yml 中设置 Token

在 OAP 的配置文件（默认路径为oap-server/server-starter/src/main/resources/application.yml）中，找到receiver-sharing-server模块进行配置：

receiver-sharing-server: default: authentication: ${SW_AUTHENTICATION:""}

• 配置项：receiver-sharing-server.default.authentication
• 环境变量覆盖：SW_AUTHENTICATION
• 默认值：空字符串""，表示默认不启用 Token 认证。

receiver-sharing-server是 SkyWalking 的共享接收服务器模块，Trace、JVM、CLR、Profile、Meter 等各类 Agent 上报数据都通过该模块的 gRPC 端口进入 OAP。因此在此处配置的 Token 会统一作用于所有 Agent 上报通道。

环境变量方式（推荐用于容器化部署）

OAP 端也可以直接通过环境变量注入，避免直接修改 yaml 文件：

export SW_AUTHENTICATION=your-secret-token

在 Docker/K8s 部署场景下，通过环境变量注入SW_AUTHENTICATION比修改配置文件更便于统一管理与轮换。

认证失败的排查：PERMISSION_DENIED

OAP 会校验每个来自 Agent 的请求，只有 Token 与application.yml中配置一致时才放行。当 Token 不匹配时，Agent 端日志中会出现如下异常：

org.apache.skywalking.apm.dependencies.io.grpc.StatusRuntimeException: PERMISSION_DENIED

这是最典型的 Token 认证失败信号，出现该异常时按以下顺序排查：

1. 两端是否都配置了 Token：OAP 端authentication为空字符串时认证未启用；只有 OAP 端配置了非空 Token，认证才会真正生效（对应 SharingServerModuleProvider.java 中StringUtil.isNotEmpty(config.getAuthentication())的判断）；
2. 两端的 Token 值是否完全一致：Token 是字符串精确匹配，任何多余的空格、大小写差异、换行都会导致校验失败；
3. 是否通过环境变量覆盖了配置：确认SW_AGENT_AUTHENTICATION与SW_AUTHENTICATION两个环境变量没有被重复设置或设置了不一致的值；
4. 配置后是否重启了服务：OAP 的authentication在模块 prepare 阶段加载（见 SharingServerConfig.java 中的authentication字段），修改后需要重启 OAP 与 Agent 才会生效。

源码视角：Token 校验的底层调用链

结合仓库源码，可以完整还原 Token 认证在 OAP 端的实现链路：

1. 配置加载：receiver-sharing-server模块的配置类 SharingServerConfig.java 声明了authentication字段（String 类型），由application.yml注入；
2. 拦截器创建：在 SharingServerModuleProvider.java 的prepare()阶段，若配置的authentication非空，则创建AuthenticationInterceptor实例（new AuthenticationInterceptor(config.getAuthentication())）；
3. 拦截器挂载：无论是内置 gRPC 服务（GRPCHandlerRegisterImpl）还是延迟注册的ReceiverGRPCHandlerRegister，都会通过addFilter(authenticationInterceptor)将拦截器挂载到 gRPC 服务链上。addFilter的实现在 GRPCHandlerRegisterImpl.java 中，本质是server.addHandler(interceptor)，即把拦截器注册为 gRPC Server 的全局拦截器；
4. 请求校验：每个 gRPC 请求到达时，AuthenticationInterceptor.java 的interceptCall被触发，读取请求 Metadata 中AuthenticationHeader 的值并与expectedToken比对，通过则放行，否则以PERMISSION_DENIED状态拒绝。

值得注意的实现细节：拦截器持有setExpectedToken(String)方法，这意味着 OAP 支持在运行时动态更新期望的 Token 值（例如结合 动态配置 机制实现 Token 热更新），而无需重启服务。

FAQ：两个高频疑问

可以用 Token 认证替代 TLS 吗？

不建议，也不应该。官方文档明确回答：虽然技术上可行，但 Token 与 TLS 面向的都是不可信网络环境，在这种场景下TLS 的优先级更高。理由非常直接：Token 只有在 TLS 保护下才是可信的——如果 Token 通过非 TLS 网络明文传输，很容易被窃取，一旦被窃取，Token 认证就形同虚设。正确姿势是"TLS + Token 认证"组合使用：

• TLS 负责防窃听、防篡改，保证 Token 在传输过程中不被截获；
• Token 认证负责校验数据来源，防止伪造数据上报。

是否支持 ak/sk 等其他认证机制？

目前不支持。当前实现仅支持简单的 Token 字符串认证，官方文档表示欢迎社区为此功能贡献代码（例如实现 AccessKey/SecretKey 签名认证等更复杂的机制）。

安全配置建议

综合官方文档与源码实现，给出以下落地建议：

1. Token 强度：虽然 Token 仅是字符串，但生产环境应使用足够长、足够随机的字符串（建议 32 位以上随机字符），避免弱口令被暴力猜测；
2. 传输保护：务必在启用 Token 认证的同时启用 TLS（gRPC 对应配置receiver-sharing-server.default.gRPCSslEnabled及相关证书路径，见 application.yml），禁止在明文网络上单独依赖 Token；
3. 密钥管理：Token 属于敏感信息，建议通过环境变量（SW_AUTHENTICATION/SW_AGENT_AUTHENTICATION）注入，并纳入密钥管理系统，避免硬编码进代码仓库或镜像；
4. 配置同步：Agent 与 OAP 两端 Token 必须保持一致，变更 Token 时需要同步更新所有 Agent 并滚动重启，避免期间出现数据上报中断；
5. 结合动态配置：从源码结构看，AuthenticationInterceptor支持动态更新expectedToken，生产环境可借助 动态配置 能力在不停机的情况下轮换 Token。

小结

Token 认证是 SkyWalking 在"传输可信"（TLS）之外提供的"数据可信"校验层：OAP 通过 AuthenticationInterceptor 对每个 Agent 请求做字符串 Token 比对，不匹配即返回PERMISSION_DENIED。配置上只需在 Agent 端agent.config与 OAP 端application.yml成对设置相同 Token（或通过SW_AGENT_AUTHENTICATION/SW_AUTHENTICATION环境变量注入），并牢记"TLS 优先、Token 为辅"的组合原则，即可在不可信网络环境下安全地保障监控数据的来源可信。

【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址: https://gitcode.com/gh_mirrors/sky/skywalking