Securitas Direct API集成中的JWT令牌验证问题解析

Securitas Direct API集成中的JWT令牌验证问题解析

securitas-direct-new-api This repository contains the new securitas direct API that can be integrated in Home Assistant 项目地址: https://gitcode.com/gh_mirrors/se/securitas-direct-new-api

问题背景

在使用Securitas Direct New API集成时，部分用户遇到了JWT令牌验证失败的问题。典型错误表现为"Invalid token type"和"Failed to decode authentication token None"的错误信息。这种情况通常发生在用户尝试重新配置集成或使用新创建的账户时。

错误现象分析

当用户尝试通过Home Assistant配置Securitas Direct集成时，系统会在2FA验证后抛出以下异常：

1. JWT解码错误："Invalid token type. Token must be a <class 'bytes'>"
2. 认证错误："Failed to decode authentication token None"

从调试日志中可以看到，API响应中的hash字段为null：

{
  "data": {
    "xSLoginToken": {
      "__typename": "XSLoginToken",
      "res": "OK",
      "msg": "Utilisateur correctement validé",
      "hash": null,
      "refreshToken": null,
      "legals": false,
      "changePassword": true,
      "needDeviceAuthorization": null,
      "mainUser": false
    }
  }
}

根本原因

经过深入分析，发现这个问题主要与账户状态有关：

1. 新账户未完全激活：当用户创建专用账户用于API集成时，虽然账户已创建，但可能未完成Securitas系统的完整验证流程。

2. 账户类型限制：日志显示"mainUser":false表明使用的是次级账户，这类账户可能需要额外的验证步骤。

3. 密码重置要求：系统返回"changePassword":true提示，表明账户需要先完成密码修改流程。

解决方案

要解决此问题，需要完成以下步骤：

1. 使用主账户登录：首先尝试使用主账户而非次级账户进行集成配置。

2. 完成账户激活：

   • 使用新创建的专用账户登录Securitas官方网站
   • 完成账户的最终设置流程
   • 按要求修改初始密码
   • 完成2FA验证
   • 重新登录确认账户状态

3. 验证账户状态：确保API响应中的hash字段不再为null。

技术建议

对于开发者而言，可以考虑以下改进：

1. 增强错误处理：当检测到"changePassword":true或"mainUser":false时，提供更明确的错误提示。

2. 账户状态检查：在集成配置流程中加入账户状态验证步骤。

3. 日志增强：建议用户启用调试日志以便更好地诊断问题：

logger:
  default: error
  logs:
    custom_components.securitas: debug

总结

Securitas Direct API集成中的JWT令牌验证问题往往源于账户状态而非代码本身。通过确保账户完全激活并完成所有必要的验证步骤，大多数情况下可以解决此类认证问题。对于开发者而言，增强错误提示和状态检查可以显著改善用户体验。

securitas-direct-new-api This repository contains the new securitas direct API that can be integrated in Home Assistant 项目地址: https://gitcode.com/gh_mirrors/se/securitas-direct-new-api