ZimaOSには現在、公式のOpenAPIが用意されていますが、2024年当時のように/v1/users/loginを呼び出して返されたアクセストークンを再利用する方法は、恒久的な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には、1.5.0以前のバージョンで/v1/users/loginに影響する重大な認証バイパスの問題があり、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バージョンの変更、最小権限でのアクセスを考慮して設計してください。
