ApsaraMQ for MQTT は、トークンベースの認証をサポートしており、メッセージングリソースへのクライアントアクセスを制御します。このトピックでは、トークンを使用した接続パラメーターの設定方法、切断せずにトークンを更新する方法、およびトークンの有効期限切れと無効化通知の処理方法について説明します。
認証フロー
トークンベースの認証は、次のシーケンスに従います：
アプリケーションが ApsaraMQ for MQTT のトークンサービスにトークンをリクエストし、リソースと権限タイプ (読み取り、書き込み、またはその両方) を指定します。
MQTT クライアントは、CONNECT パケットの
UsernameおよびPasswordフィールドにトークンデータを含めてブローカーに接続します。ブローカーはトークンを検証し、指定されたリソースへのアクセスを許可します。
セッション中、クライアントはシステムトピックにパブリッシュすることでトークンを更新でき、ブローカーはトークンの有効期限切れまたは無効化に関する通知をプッシュします。
トークンタイプ
各 ApsaraMQ for MQTT クライアントは、タイプごとに 1 つのトークンを保持でき、同時に 1 つ以上のタイプを使用できます。
| タイプ識別子 | 権限 | 説明 |
|---|---|---|
| R | 読み取り専用 | 指定されたリソースに対する読み取り権限を付与します |
| W | 書き込み専用 | 指定されたリソースに対する書き込み権限を付与します |
| RW | 読み取り/書き込み | 指定されたリソースに対する読み取りと書き込みの両方の権限を付与します |
接続パラメーター
トークンベースの認証で接続するには、MQTT CONNECT パケットの Username および Password フィールドを次のように設定します。
Username
フォーマット： Token|<AccessKey ID>|<Instance ID>
| コンポーネント | 説明 |
|---|---|
Token | リテラル文字列 Token。トークンベースの認証モードを示します |
<AccessKey ID> | ご利用の Alibaba Cloud AccessKey ID |
<Instance ID> | ご利用の ApsaraMQ for MQTT インスタンス ID |
例：
クライアント ID GID_Test@@@0001、インスタンス ID mqtt-xxxxx、および AccessKey ID YYYYY のクライアントの場合：
Token|YYYYY|mqtt-xxxxxPassword
フォーマット： トークンのタイプと内容のペアを縦棒 (|) で連結します。複数のトークンタイプを任意の順序で指定できます。
例：
単一トークン： クライアントが読み取り専用トークン
123を保持している場合、Password を次のように設定します：R|123複数トークン： クライアントが読み取り専用トークン
123と書き込み専用トークンabcdを保持している場合、Password を次のように設定します：R|123|W|abcd
Password フィールド内のすべてのトークンは有効である必要があります。いずれかのトークンが無効な場合、ブローカーは接続を拒否することがあります。
切断せずにトークンを更新
デフォルトでは、トークンをローテーションするには、クライアントを切断し、新しいトークンで再接続する必要があります。切断を避けるには、トークン更新メッセージをシステムトピック $SYS/uploadToken にパブリッシュします。ブローカーは接続を切断せずに、セッション内のトークンを置き換えます。
更新手順
新しいトークンコンテンツを含む JSON メッセージを
$SYS/uploadTokenにパブリッシュします。パブリッシュまたはサブスクライブ操作を実行する前に、PUBACK 応答を待ちます。クライアントが待たずに処理を進めると、ブローカーは古いトークンで認証を試み、認証失敗と切断を引き起こす可能性があります。
次回の再接続時にクライアントが新しいトークンを使用するように、ローカルのトークン設定を更新します。
メッセージフォーマット
トピック： $SYS/uploadToken
ペイロード： 以下のフィールドを含む JSON 文字列：
| パラメーター | タイプ | 必須 | 説明 |
|---|---|---|---|
| token | String | はい | 新しいトークン文字列 |
| type | String | はい | トークンタイプ：R、W、または RW。無効なタイプは権限検証エラーを引き起こします。 |
ペイロードの例：
{
"token": "<your-token-string>",
"type": "RW"
}応答： 標準の PUBACK メッセージ。
トークンの更新が成功した後は、必ずローカルのトークン設定を更新してください。そうしないと、クライアントは次回の再接続時に古いトークンデータを使用する可能性があります。
トークン有効期限切れの通知
ApsaraMQ for MQTT ブローカーは、システムトピック $SYS/tokenExpireNotice を通じてクライアントに有効期限切れの警告をプッシュします。サブスクリプションは不要で、ブローカーはこれらの通知を直接配信します。
トピック： $SYS/tokenExpireNotice
ペイロード： 以下のフィールドを含む JSON 文字列：
| パラメーター | タイプ | 説明 |
|---|---|---|
| expireTime | Long | トークンの有効期限時刻 (ミリ秒単位の UNIX タイムスタンプ) |
| type | String | トークンタイプ：R、W、または RW |
通知の動作
ブローカーは通常、トークンの有効期限が切れる約 5 分前に通知を送信します。
配信は保証されません。トークンのライフサイクル管理をこれらの通知のみに依存しないでください。
通知を受け取ったら、メッセージングの失敗を避けるために、速やかに新しいトークンをリクエストして更新してください。
トークン無効化の通知
ブローカーがトークン検証エラーを検出すると、システムトピック $SYS/tokenInvalidNotice を通じてクライアントにエラー通知をプッシュし、その後クライアントを切断します。サブスクリプションは不要です。
トピック： $SYS/tokenInvalidNotice
ペイロード： 以下のフィールドを含む JSON 文字列：
| パラメーター | タイプ | 説明 |
|---|---|---|
| code | int | トークン検証失敗のタイプを識別するエラーコード |
| type | String | トークンタイプ：R、W、または RW |
エラーコード
| コード | 説明 |
|---|---|
| 1 | トークンが偽造されており、解析できません |
| 2 | トークンの有効期限が切れています |
| 3 | トークンが取り消されています |
| 4 | リソースとトークンが一致しません |
| 5 | 権限タイプとトークンが一致しません |
| 8 | 署名が無効です |
| -1 | アカウントの権限が無効です |
切断の動作
ブローカーがトークン検証エラーを検出した場合：
認証が失敗します。
ブローカーはエラーコードを
$SYS/tokenInvalidNoticeを通じてクライアントにプッシュします。ブローカーはクライアントを切断します。
再接続する前に、エラーコードを使用して根本原因を特定し、修正措置を講じてください。
ベストプラクティス
短命なトークンを使用する。 トークン漏洩の影響を限定するために、トークンに妥当な有効期間を設定します。
TLS を有効にする。 クライアント接続を暗号化して、送信中のトークン傍受を防ぎます。
有効期限切れに事前対応する。 配信が保証されないため、ブローカーの有効期限切れ通知のみに依存するのではなく、クライアントにトークン更新ロジックを実装します。
認証情報を安全に保管する。 AccessKey ID をアプリケーションにハードコーディングするのではなく、環境変数やシークレットマネージャーから取得します。
ローカルとブローカーのトークンを同期させる。
$SYS/uploadTokenを通じてトークンを更新した後は、再接続時に古いトークンが使用されるのを防ぐために、必ずローカルの設定を更新します。