トークンベース認証におけるクライアント関連操作 - ApsaraMQ for MQTT

このトピックでは、ApsaraMQ for MQTT クライアントがトークンベース認証モードでトークンをアップロードおよび更新する方法、またトークンの有効期限切れと無効性に関する通知をリッスンする方法について説明します。

トークンベース認証モードでの Message Queue for MQTT クライアント接続のパラメーターを設定する

Message Queue for MQTT は 3 つのトークンタイプをサポートしています。各 Message Queue for MQTT クライアントは、タイプごとに最大 1 つのトークンを申請でき、必要に応じて 1 つ以上のタイプを申請して使用できます。次の表に、トークンタイプを示します。

タイプ識別子	説明
R	指定されたリソースに対する読み取り権限のみを持つ読み取り専用トークン。
W	指定されたリソースに対する書き込み権限のみを持つ書き込み専用トークン。
RW	指定されたリソースに対する読み取りおよび書き込み権限を持つ読み取り/書き込みトークン。

トークンベース認証モードでの Message Queue for MQTT クライアント接続には、次のパラメーターが設定されます。

ユーザー名
ユーザー名パラメーターは、認証モード、AccessKey ID、およびインスタンス ID で構成され、これらは縦棒（|）で区切られます。認証モードは、トークンベース認証モードではトークンです。
例
クライアント ID が GID_Test@@@0001 の Message Queue for MQTT クライアントがインスタンス ID mqtt-xxxxx と AccessKey ID YYYYY を使用する場合、この Message Queue for MQTT クライアントを接続するためのユーザー名パラメーターは Token|YYYYY|mqtt-xxxxx に設定する必要があります。
パスワード:
パスワードパラメーターは、Message Queue for MQTT クライアントが使用するトークンの内容を示します。パラメーター値は、トークンタイプとトークンコンテンツによって縦棒（|）で接続されたすべてのトークンを順番に連結した完全な文字列です。異なるタイプのトークンは、特定の順序で連結されません。
例 1: Message Queue for MQTT クライアントが文字列形式で読み取り専用トークン 123 のみを持つ場合、パスワードパラメーターは R|123 に設定する必要があります。
例 2: Message Queue for MQTT クライアントが 2 つのトークンタイプ（読み取り専用トークンとして 123、書き込み専用トークンとして abcd）を持つ場合、パスワードパラメーターは R|123|W|abcd に設定する必要があります。
説明 Message Queue for MQTT クライアント接続のトークンパラメーターが上記のルールに基づいて設定され、すべてのトークンが有効であることを確認してください。一部のトークンが無効な場合、Message Queue for MQTT ブローカーはトークン設定が無効であると判断する場合があります。

クライアントのトークンを更新する

通常の場合、Message Queue for MQTT クライアントのトークンを更新するには、Message Queue for MQTT クライアントを切断してから、新しいトークンを使用して Message Queue for MQTT クライアントを接続します。トークンの更新中にクライアントの切断を回避するには、トークン更新の操作を呼び出すことで、Message Queue for MQTT ブローカーセッションのトークンデータを置き換えることができます。

トークンの更新中、Message Queue for MQTT クライアントは事前定義されたシステムトピックを使用して特別なメッセージを送信し、新しいトークンコンテンツを Message Queue for MQTT ブローカーに更新します。 Message Queue for MQTT クライアントは、トークンの更新とともにローカルのトークン構成が更新されることを確認する必要があります。そうしないと、次回の接続初期化中に古いトークンデータが使用される可能性があります。

トークンの更新に使用されるトピック: $SYS/uploadToken
コンテンツ: JSONString

コンテンツの説明

パラメーター	タイプ	説明
token	String	トークンベース認証が使用されている場合、Message Queue for MQTT クライアントはトークン文字列をアップロードする必要があります。
type	String	トークンタイプ。W、R、または RW で、3 つの権限タイプに対応します。 Message Queue for MQTT クライアントは、最大 3 つのタイプのトークンを持つことができます。無効なトークンタイプは、権限検証エラーになる可能性があります。

戻り値
一般的な PubAck メッセージが返されます。 Message Queue for MQTT クライアントは、パブリッシュまたはサブスクライブ操作の前に応答を待つ必要があります。そうしないと、Message Queue for MQTT ブローカーは認証に古いトークンデータを使用し続け、認証エラーと切断が発生する可能性があります。

トークンの有効期限切れ間近の通知をリッスンする（サブスクリプション不要）

サービスのデバッグと監視を容易にするため、Message Queue for MQTT ブローカーはシステムトピックを使用して Message Queue for MQTT クライアントに通知をプッシュし、まもなく期限切れになるトークンをクライアントに通知します。 Message Queue for MQTT クライアントは、このような通知をリッスンして、トークンがまもなく期限切れになるかどうかを判断できます。

受信トピック: $SYS/tokenExpireNotice
コンテンツ: JSONString

コンテンツの説明

パラメーター	タイプ	説明
expireTime	Long	トークンの有効期限。タイムスタンプ形式で、ミリ秒単位の精度です。 Message Queue for MQTT クライアントは通常、5 分前にトークンの有効期限が通知されます。ただし、Message Queue for MQTT ブローカーは、常に通知が送信されることを保証するものではありません。
type	String	クライアントによってアップロードされたトークンのタイプ。W、R、または RW で、3 つの権限タイプに対応します。

レスポンス
Message Queue for MQTT クライアントは、トークンの有効期限切れ間近の通知を受信した後、メッセージングの失敗を回避するために、できるだけ早く新しいトークンを申請する必要があります。

無効なトークンに関する通知をリッスンする（サブスクリプション不要）

サービスのデバッグと監視を容易にするため、Message Queue for MQTT ブローカーはシステムトピックを使用して Message Queue for MQTT クライアントに通知をプッシュし、トークンベース認証エラーをクライアントに通知します。 Message Queue for MQTT クライアントは、このような通知をリッスンして、トークンの不一致やその他の権限エラーを検出できます。

受信トピック: $SYS/tokenInvalidNotice
コンテンツ: JSONString

コンテンツの説明

パラメーター	タイプ	説明
code	int	トークン検証エラーのタイプ。
type	String	クライアントによってアップロードされたトークンのタイプ。W、R、または RW で、3 つの権限タイプに対応します。

レスポンス

Message Queue for MQTT ブローカーがトークン検証エラーを検出した場合、認証に失敗し、Message Queue for MQTT ブローカーは Message Queue for MQTT クライアントを積極的に切断します。 Message Queue for MQTT ブローカーは、Message Queue for MQTT クライアントを切断する前に、エラーコードを Message Queue for MQTT クライアントにプッシュします。 Message Queue for MQTT クライアントは、エラーコードに基づいて原因を特定できます。

タイプコード	エラースタイプ
1	トークンが偽造されており、解析できません。
2	トークンの有効期限が切れています。
3	トークンが失効しています。
4	リソースとトークンが一致しません。
5	権限タイプとトークンが一致しません。
8	署名が無効です。
-1	アカウント権限が無効です。