ZimaOSには現在、文書化されたOpenAPIがあります。ただし、/v1/users/loginを呼び出して返されたアクセストークンを再利用する2024年当時の方法は、永続的なAPIキーシステムではなく、セッション認証の手法として扱うべきです。IceWhaleは、そのスレッドで永続トークンには対応していないと明言しています。
現在のOpenAPIドキュメントは、個人用アクセストークンのUIではなく、生成されたクライアントとサービスエンドポイントを中心に説明しています。Home Assistantなどの自動化では、認証をローカルに保ち、ログインエンドポイントを公開せず、セッショントークンの期限切れ時に再認証できるようインテグレーションを設計してください。
現在のOpenAPI仕様を使用する
現在のZimaOS OpenAPIガイドでは、IceWhaleのOpenAPIリポジトリを開発者に案内し、ストレージなどのサービス向けに生成されたクライアントを紹介しています。
過去のログインエンドポイントはアクセストークンを返していた
元のスレッドでは、ユーザーが/v1/users/loginに認証情報をPOSTし、レスポンスにアクセストークンが含まれていることを確認しました。その後、IceWhaleは永続トークンには対応していないと説明しました。
一時トークンを永久にハードコードしない
セッショントークンは、ログインやセキュリティ設定の変更によって期限切れになったり無効化されたりする可能性があります。認証情報または更新済みのセッション状態を安全に保存し、認証エラーを明示的に処理してください。
APIは信頼できるネットワーク内に保つ
内部のZimaOS APIエンドポイントをポートフォワーディングでパブリックインターネットに公開しないでください。まずLAN、VPN、またはZimaClientのプライベートネットワーク経由でサーバーに接続してください。
ログインAPIを使って開発する前に、古いZimaOSビルドを更新する
ZimaOSでは、/v1/users/loginに影響する重大な認証バイパスの問題が1.5.0までのバージョンに存在し、1.5.3で修正されました。必ず現行の安定版を対象に開発してください。
ZimaOSログインセキュリティアドバイザリには、そのセキュリティ境界が記載されています。
Home Assistantでは最小権限を使用する
温度、CPU、電力、ディスクのメトリクスを収集する場合は、インテグレーションに必要なデータだけを要求してください。絶対に必要でない限り、ユーザー、ストレージ、システム設定も変更できる自動化は構築しないでください。
APIバージョンの変更を想定する
現在のガイドでは、/v2/local_storageのようなバージョン付きサービスパスが参照されています。2024年当時のすべてのエンドポイントが今後も推奨インターフェースであり続けるとは限りません。現在のOpenAPIスキーマからクライアントを生成または更新してください。
プライベートアクセスガイドでは、より安全なネットワークモデルを説明しています。
401レスポンスには再認証で対応する
堅牢なインテグレーションでは、HTTP 401またはセッション期限切れのレスポンスを、同じトークンで繰り返し再試行するのではなく、新しいセッションを取得する合図として扱うべきです。ログイン障害によってリクエストが無限ループしないよう、回数を制限した再試行処理を追加してください。
トークンをログに記録しない
Home Assistantのデバッグログ、シェル履歴、スクリーンショット、Gitリポジトリは、トークンが漏えいしやすい場所です。診断情報を公開する前に、認証ヘッダーとJSON形式のログインレスポンスをマスキングしてください。
依存するAPIコントラクトを固定する
インテグレーションで生成されたOpenAPIクライアントを使用する場合は、スキーマとバージョンをコードと一緒に管理し、再生成する前に上流の変更を確認してください。これにより、エンドポイントやレスポンス形式が変更された際に、自動化がひそかに壊れるのではなく、変更を明確に把握できます。
よくある質問
ZimaOSでは永続的なAPIトークンを生成できますか？
IceWhaleの元の回答では、永続トークンには対応していないとされており、現在公開されているドキュメントにも個人用アクセストークンのUIは記載されていません。
以前のアクセストークンはどのように取得したのですか？
フォーラムのユーザーは、/v1/users/loginへのPOSTが成功した後に取得しました。
APIをインターネットに公開すべきですか？
いいえ。信頼できるプライベートネットワーク内に保ち、現在サポートされている認証フローを使用してください。
Home Assistantのインテグレーションを構築できますか？
はい。ただし、トークンの期限切れ、APIバージョンの変更、最小権限アクセスを考慮して設計してください。
