通过专用终结点注册ADF自托管集成运行时遇InvalidGatewayKey错误

环境配置 #

• Azure数据工厂（ADF）在托管专用网络中运行AutoResolver Azure IR，已配置多个托管专用终结点连接KeyVault、存储账户、函数应用等Azure服务，该部分运行正常
• ADF已禁用公网访问
• 为ADF配置了2个专用终结点（PE）：子类型分别为factory和portal
• 本地服务器安装了SHIR，通过CLI可将ADF的FQDN正确解析至虚拟网络子网中的专用终结点IP

问题现象 #

尝试注册SHIR时出现InvalidGatewayKey错误，具体错误信息：

Failed to get service token from ADF service with key IR@61[redacted]f6@[redacted]-df-shared@ServiceEndpoint=[redacted]-df-shared.[region-redacted].datafactory.azure.net@****************** and time cost is: 0.1606498 seconds, the error code is: InvalidGatewayKey, activityId is: e14a4ef0-f581-4396-bae8-f2a3d680435b and detailed error message is Processed HTTP request failed. .

• 启用ADF公网访问时，SHIR可正常注册；禁用公网访问后，SHIR无法与ADF通信
• 网络团队确认未拦截SHIR服务器到专用终结点地址的出站流量

排查结果 #

运行ADF排查工具后，确认：

1. DNS解析成功，ADF的FQDN正确指向专用终结点IP
2. 可正常获取ADF服务端点证书
3. 最终身份验证失败，完整排查日志如下：

DNS resolve
0.006s
Result: Success
Documentation: https://go.microsoft.com/fwlink/?linkid=2166762
[UTC 2/26/2025 4:12:21 AM] DNS resolve: [redacted]-df-shared.[region-redacted].datafactory.azure.net
[UTC 2/26/2025 4:12:21 AM] GetHostEntry([redacted]-df-shared.[region-redacted].datafactory.azure.net) returns:
[UTC 2/26/2025 4:12:21 AM]     [first-two-octets-redacted].12.8
 
Get service endpoint certificate
0.110s
Result: Success
Documentation: https://go.microsoft.com/fwlink/?linkid=2166762
[UTC 2/26/2025 4:12:21 AM] Get service endpoint certificate information: https://[redacted]-df-shared.[region-redacted].datafactory.azure.net/
[UTC 2/26/2025 4:12:21 AM] Get certificate Hash: C9[redacted]D3
 
Connect to cloud service endpoint
0.169s
Result: Failed
Error Message: Failed to get service token from ADF service with key IR@61[redacted]f6@[redacted]-df-shared@ServiceEndpoint=[redacted]-df-shared.[region-redacted].datafactory.azure.net@****************** and time cost is: 0.1606498 seconds, the error code is: InvalidGatewayKey, activityId is: e14a4ef0-f581-4396-bae8-f2a3d680435b and detailed error message is Processed HTTP request failed. .
Parameters:
Endpoint: https://[redacted]-df-shared.[region-redacted].datafactory.azure.net/
Documentation: https://go.microsoft.com/fwlink/?linkid=2166762
[UTC 2/26/2025 4:12:21 AM] Connecting to cloud service endpoint: https://[redacted]-df-shared.[region-redacted].datafactory.azure.net/
{
  "ClassName": "Microsoft.DataTransfer.DIAgentClient.HostServiceException",
  "Message": "Failed to get service token from ADF service with key IR@61[redacted]f6@[redacted]-df-shared@ServiceEndpoint=[redacted]-df-shared.[region-redacted].datafactory.azure.net@****************** and time cost is: 0.1606498 seconds, the error code is: InvalidGatewayKey, activityId is: e14a4ef0-f581-4396-bae8-f2a3d680435b and detailed error message is Processed HTTP request failed.\r\n.",
  "Data": {
    "ErrorCode": 15
  },
  "InnerException": null,
  "HelpURL": null,
  "StackTraceString": "   at Microsoft.DataTransfer.DiagnosticTool.ServiceFrontendDomainConnectionSuite.d__8.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at Microsoft.DataTransfer.DiagnosticTool.DiagnosticRunner.d__8.MoveNext()",
  "RemoteStackTraceString": null,
  "RemoteStackIndex": 0,
  "ExceptionMethod": "8\nMoveNext\nMicrosoft.DataTransfer.DiagnosticTool, Version=5.48.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35\nMicrosoft.DataTransfer.DiagnosticTool.ServiceFrontendDomainConnectionSuite+d__8\nVoid MoveNext()",
  "HResult": -2146233088,
  "Source": "Microsoft.DataTransfer.DiagnosticTool",
  "WatsonBuckets": null
}

解决方向 #

• 确认专用终结点覆盖SHIR通信路径：检查ADF的factory子类型专用终结点，确保其关联的服务端点覆盖SHIR与ADF通信的所有必要路径，无遗漏。
• 验证流量路由正确性：在SHIR服务器上使用tracert或Test-NetConnection测试到ADF专用终结点IP的连通性，确认数据包未被转发到公网，确实到达目标子网。
• 检查ADF网络ACL规则：ADF禁用公网访问后，需确保专用终结点所在子网以及SHIR服务器的IP范围被添加到ADF的入站允许列表中。
• 重新生成注册密钥：删除ADF中未注册成功的SHIR实例，重新生成注册密钥后再次尝试注册，排除密钥过期或格式异常问题。
• 更新SHIR版本：将SHIR升级至最新版本，确保与ADF服务版本兼容，避免旧版本在禁用公网环境中的通信缺陷。
• 确认专用DNS配置完整性：如果使用Azure专用DNS区域，检查是否已正确关联到虚拟网络，且区域中包含ADF所有必要的DNS记录（包括子域名条目）。

内容的提问来源于stack exchange，提问作者Sepster