Backstage项目中Azure认证失败的排查与解决方案

问题背景

在Backstage 1.3.6版本中，当使用Azure认证插件时，开发人员遇到了一个典型的认证失败问题。该问题表现为：在本地开发环境中Azure认证工作正常，但在部署到OpenShift生产环境后，认证流程会失败并返回错误信息。

错误现象

系统在认证过程中抛出了以下关键错误：

Received a plugin token where the source 'auth' plugin unexpectedly does not have a JWKS endpoint.

以及底层错误：

fetch failed

这表明Backstage的后端服务在尝试验证JWT令牌时，无法从认证服务获取JWKS(JSON Web Key Set)端点信息，导致认证流程中断。

技术原理分析

Backstage的认证流程依赖于JWT令牌验证机制。当用户通过Azure AD认证后，系统会：

1. 前端获取ID Token
2. 后端验证该Token的有效性
3. 后端需要从认证服务获取JWKS公钥来验证Token签名
4. 验证通过后建立会话

在这个过程中，关键的技术点包括：

• JWKS端点：用于提供验证JWT签名所需的公钥
• 服务发现机制：后端服务需要能够定位到认证服务的地址
• 网络通信：后端服务需要能够访问认证服务的JWKS端点

问题根源

经过深入分析，发现问题出在代理配置上。在OpenShift环境中，由于存在企业级网络代理，导致：

1. 后端服务无法直接访问外部网络
2. 默认的ProxyAgent实现不兼容当前环境
3. JWKS端点请求被代理拦截或失败

解决方案

针对这一问题，我们采用了以下解决方案：

1. 替换默认的代理实现
2. 使用EnvHttpProxyAgent替代原有的ProxyAgent
3. 确保代理配置能够正确处理HTTPS请求

具体实现方式是在后端服务的初始化代码中加入：

setGlobalDispatcher(new EnvHttpProxyAgent());

实施建议

对于在类似企业环境中部署Backstage的开发人员，建议：

1. 环境检查：确认生产环境的网络代理要求
2. 代理兼容性测试：在部署前测试各种代理方案
3. 日志监控：启用详细的网络请求日志，便于排查连接问题
4. 版本验证：确保使用的Backstage版本与插件版本兼容

总结

Backstage在企业环境中的部署经常会遇到网络代理相关的挑战，特别是在需要与外部认证服务(如Azure AD)交互时。通过正确配置网络代理实现，可以解决大部分因环境限制导致的认证问题。本文提供的解决方案已在生产环境中验证有效，可供类似场景参考。

对于更复杂的企业环境，可能还需要考虑额外的网络策略配置或服务网格集成，以确保Backstage各组件间的通信不受限制。