共用方式為

設定 MQTT 代理程式驗證

  • 發行項

重要

此頁面包含使用 Kubernetes 部署指令清單來管理 Azure IoT Operations 元件的指示，其處於預覽狀態。 這項功能隨附 數個限制，不應用於生產工作負載。

請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

MQTT 訊息代理程式支援用戶端的多個驗證方法，而且您可以將每個接聽程式埠設定為使用 BrokerAuthentication 資源有自己的驗證設定。 如需可用設定的清單，請參閱 訊息代理程式驗證 API 參考。

下列規則適用於 BrokerListener 與 BrokerAuthentication 資源之間的關聯性：

  • 每個 BrokerListener 可以有多個連接埠。 每個埠都可以連結至 BrokerAuthentication 資源。
  • 每個 BrokerAuthentication 都可以一次支援多個驗證方法。
  • 未連結 BrokerAuthentication 資源的埠已停用驗證。

若要將 BrokerListener 埠連結至 BrokerAuthentication 資源，請在 BrokerListener 資源的設定中ports指定 authenticationRef 字段。 若要深入瞭解，請參閱 BrokerListener 資源。

預設 BrokerAuthentication 資源

Azure IoT 作業會部署名為 連結的預設 BrokerAuthentication 資源，並在命名空間中azure-iot-operations鏈接預設接聽default程式。 其設定為只使用 Kubernetes 服務帳戶令牌進行 驗證。

重要

Azure IoT 作業中的元件必須有預設 BrokerAuthentication 資源中的服務帳戶令牌 （SAT） 驗證方法才能正常運作。 避免更新或刪除預設 BrokerAuthentication 資源。

  1. 在 Azure 入口網站 中，流覽至您的IoT作業實例。

  2. 在 [Azure IoT 作業資源] 底下，選取 [MQTT 訊息代理程式]。

  3. 選取 [驗證] 索引標籤。

  4. 從驗證原則清單中，選取 預設 原則名稱。

    使用 Azure 入口網站 檢視預設 MQTT 訊息代理程式驗證原則的螢幕快照。

若要新增驗證方法，請選取 [新增方法]。

驗證流程

指定驗證方法的順序會決定 MQTT 訊息代理程式驗證用戶端的方式。 MQTT 訊息代理程式會嘗試使用第一個指定的方法驗證客戶端的認證，並逐一查看指定的方法，直到找到相符專案或到達結尾為止。

針對每個方法，MQTT 代理程式會先檢查用戶端的認證是否與該方法相關。 例如，SAT 驗證需要以 K8S-SAT 開頭的使用者名稱，而 X.509 驗證需要用戶端憑證。 如果用戶端的認證相關，MQTT 代理程式會驗證其是否有效。 如需詳細資訊，請參閱設定驗證方法一節。

針對自訂驗證，MQTT 代理程式會將與自訂驗證伺服器的通訊失敗視為認證不相關。 如果無法連線到自定義驗證伺服器，此行為可讓 MQTT 訊息代理程式回復至其他方法。

驗證流程在下列狀況下結束：

  • 其中一個條件為 True:
    • 用戶端的認證與其中一種方法相關且有效。
    • 用戶端的認證與任何方法無關。
    • 用戶端的認證與其中一種方法相關但無效。
  • MQTT 代理程式會根據驗證流程的結果，授與或拒絕對用戶端的存取權。

例如：

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthentication
metadata: 
  name: default
  namespace: azure-iot-operations
spec:
  authenticationMethods:
    - method: Custom
      customSettings:
        # ...
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        # ...

先前的範例指定自訂和 SAT。 當用戶端連線時，MQTT 訊息代理程式會嘗試使用自定義順序中的指定方法來驗證客戶端，然後是 SAT。

  1. MQTT 代理程式會檢查用戶端的認證對自訂驗證是否有效。 由於自訂驗證仰賴外部伺服器來判斷認證的有效性，因此訊息代理程式會考慮與自訂驗證相關的所有認證，並將其轉送至自訂驗證伺服器。
  2. 如果自訂驗證伺服器回應 Pass 或 Fail 結果，驗證流程就會結束。 不過，如果自訂驗證伺服器無法使用，則 MQTT 代理程式會回復為其餘的指定方法，而 SAT 則為下一個。
  3. MQTT 代理程式會嘗試將認證驗證為 SAT 認證。

如果自定義驗證伺服器無法使用，且所有後續方法都判斷所提供的認證不相關，則訊息代理程式會拒絕客戶端連線。

設定驗證方法

您可以新增驗證方法，例如 X.509、SAT 或自定義至驗證原則。

若要將驗證方法新增至原則：

  1. 在 Azure 入口網站 中，流覽至您的IoT作業實例。

  2. 在 [Azure IoT 作業資源] 底下，選取 [MQTT 訊息代理程式]。

  3. 選取 [驗證] 索引標籤。

  4. 選擇現有的驗證原則或建立新的驗證原則。

  5. 選取 [新增方法] 以新增方法。

  6. 從下拉式清單中選擇方法類型，然後選取 [ 新增詳細數據 ] 以設定方法。

    使用 Azure 入口網站 新增 MQTT 訊息代理程式驗證原則方法的螢幕快照。

若要深入瞭解每個驗證選項，請參閱每個方法的後續各節。

如需設定 Azure 金鑰保存庫 和啟用工作負載身分識別來啟用安全設定的詳細資訊，請參閱在 Azure IoT 作業部署中啟用安全設定。

X.509

在 X.509 驗證中，MQTT 訊息代理程式會使用受信任的 CA 憑證來驗證客戶端憑證。 用戶端會提供此 CA 中根目錄的憑證，讓 MQTT 訊息代理程式進行驗證。 支援 EC 和 RSA 金鑰，但鏈結中的所有憑證都必須使用相同的金鑰演算法。 由於 X.509 依賴 TLS 用戶端憑證，因此必須使用 X.509 驗證來啟用埠的 TLS。

若要匯入可用來驗證客戶端憑證的跟證書，請將憑證 PEM 儲存在 ConfigMap 中。 例如：

kubectl create configmap client-ca --from-file=client_ca.pem -n azure-iot-operations

在此範例中，CA 憑證會匯入金鑰 client_ca.pem底下。 MQTT 訊息代理程式信任 ConfigMap 中的所有 CA 憑證，因此密鑰的名稱可以是任何專案。

若要檢查根 CA 憑證是否已正確匯入，請執行 kubectl describe configmap。 結果會顯示 PEM 憑證檔案的相同 base64 編碼方式。

kubectl describe configmap client-ca -n azure-iot-operations

Name:         client-ca
Namespace:    azure-iot-operations

Data
====
client_ca.pem:
----
-----BEGIN CERTIFICATE-----
<Certificate>
-----END CERTIFICATE-----


BinaryData
====

匯入信任的 CA 憑證之後，將它新增為 BrokerAuthentication 資源中連結至已啟用 TLS 的接聽程式埠的其中一個驗證方法，以啟用 X.509 用戶端驗證。

授權的憑證屬性

您可以在 BrokerAuthentication 資源中指定 X.509 屬性，以根據其憑證屬性來授權用戶端。 屬性定義於 authorizationAttributes 欄位中。

  1. 在 Azure 入口網站 中，流覽至您的IoT作業實例。

  2. 在 [Azure IoT 作業資源] 底下，選取 [MQTT 訊息代理程式]。

  3. 選取 [驗證] 索引標籤。

  4. 選擇現有的驗證原則或建立新的驗證原則。

  5. 選取 [新增方法] 以新增方法。

  6. 從下拉式清單中選擇方法類型 X.509 ，然後選取 [ 新增詳細數據 ] 以設定方法。

    使用 Azure 入口網站 設定 MQTT 訊息代理程式 X.509 驗證方法的螢幕快照。

在此範例中，每一個具有具有辨別名稱 CN = Contoso Root CA Cert, OU = Engineering, C = US 之根 CA 所簽發憑證的用戶端，或具有辨別名稱 CN = Contoso Intermediate CA 的中繼 CA 都會接收列出的屬性。 此外，智慧型風扇用戶端憑證會接收其專屬的屬性。

屬性的比對一律從分葉用戶端憑證開始，然後沿著鏈結進行。 屬性指派會在最初相符項目之後停止。 在上一個範例中，即使 smart-fan 有中繼憑證 CN = Contoso Intermediate CA，它也不會取得相關聯的屬性。

您可以使用具有這些屬性的 X.509 憑證將授權規則套用至用戶端。 若要深入瞭解，請參閱 授權使用 X.509 驗證的用戶端。

使用 X.509 用戶端憑證將 mosquitto 用戶端連線到 MQTT 代理程式

像 mosquitto 這樣的用戶端需要兩個檔案，才能使用 TLS 和 X.509 用戶端驗證連線到 MQTT 訊息代理程式。

  • --cert 參數指定用戶端憑證 PEM 檔案。 此檔案也應該包含任何中繼憑證，以協助 MQTT 訊息代理程式建置完整的憑證鏈結。
  • --key 參數指定用戶端私密金鑰 PEM 檔案。

如果 MQTT 訊息代理程式使用自我簽署的 CA 憑證發出其 TLS 伺服器證書， --cafile 則需要 參數。 此檔案包含MOSquitto用戶端在透過TLS連線時用來驗證訊息代理程式伺服器證書的CA憑證。 如果 MQTT 訊息代理程式伺服器證書的簽發者是系統根存放區的一部分（例如已知的公用 CA）， --cafile 則可以省略 參數。

例如：

mosquitto_pub -q 1 -t hello -d -V mqttv5 -m world -i thermostat \
-h "<BROKER_HOST>" \
--cert thermostat_cert.pem \
--key thermostat_key.pem \
--cafile ca.pem

了解 MQTT 代理程式 X.509 用戶端驗證流程

X.509 用戶端驗證流程圖。

以下是客戶端驗證的步驟：

  1. 當 X.509 用戶端驗證開啟時，連線客戶端必須出示客戶端憑證和任何中繼憑證，讓 MQTT 訊息代理程式建置跟在其其中一個設定的信任憑證的憑證鏈結。
  2. 負載平衡器會將通訊導向至其中一個前端訊息代理程式。
  3. 一旦前端訊息代理程式收到用戶端憑證，它會嘗試建置根在其中一個已設定憑證的憑證鏈結。 如果前端訊息代理程式已成功建置鏈結並驗證呈現的鏈結，則會完成 TLS 交握。 線上客戶端能夠透過 TLS 通道將 MQTT 封包傳送至前端。
  4. TLS 通道已開啟，但用戶端驗證或授權尚未完成。
  5. 用戶端接著會將 CONNECT 封包傳送至 MQTT 代理程式。
  6. CONNECT 封包會再次路由傳送至前端。
  7. 前端會收集到目前為止呈現的所有用戶端認證，例如使用者名稱和密碼欄位、CONNECT 封包中的驗證資料，以及 TLS 交握期間呈現的用戶端憑證鏈結。
  8. 前端會將這些憑證傳送至驗證服務。 驗證服務會再次檢查憑證鏈結，並收集鏈結中所有憑證的主體名稱。
  9. 驗證服務會使用其設定的授權規則，來判斷連線用戶端具有哪些屬性。 這些屬性會決定用戶端可執行哪些作業，包括 CONNECT 封包本身。
  10. 驗證服務會將決策傳回給前端訊息代理程式。
  11. 前端訊息代理程式知道用戶端屬性，以及它是否允許連線。 如果是，則 MQTT 連線已完成，而且用戶端可以繼續傳送和接收由其授權規則決定的 MQTT 封包。

Kubernetes 服務帳戶權杖

Kubernetes 服務帳戶權杖 (SAT) 是與 Kubernetes 服務帳戶相關聯的 JSON Web 權杖。 用戶端向 MQTT 代理程式出示 SAT，以自行驗證。

MQTT 代理程式會使用繫結服務帳戶權杖，這些權杖詳述於GKE 使用者應該要知道關於 Kubernetes 新服務帳戶權杖的事項文章中。 以下是文章的特殊功能：

在 Kubernetes 1.13 中啟動，並成為 1.21 的預設格式，繫結權杖可解決舊版權杖所有受到限制的功能，還有更多功能：

  • 權杖本身更難竊取和濫用：其為時間繫結、對象繫結和物件系結。
  • 它們採用標準化格式：OpenID Connect (IDC)，具有完整 OIDC 探索，服務供應商會更容易接受。
  • 它們會使用新的 Kubelet 投影磁碟區類型，更安全地散發到 Pod。

訊息代理程式會使用 Kubernetes 權杖檢閱 API 來驗證權杖。 啟用 Kubernetes TokenRequestProjection 功能以指定 audiences （預設值自 1.21 起）。 如果未啟用此功能，就無法使用 SAT。

建立服務帳戶

若要建立 SAT，請先建立服務帳戶。 下列命令會建立名為 mqtt-client 的服務帳戶。

kubectl create serviceaccount mqtt-client -n azure-iot-operations

新增授權的屬性

透過 SAT 進行驗證的用戶端可以選擇性地為其服務帳戶加上批注，以搭配授權原則使用。 若要深入了解，請參閱授權使用 Kubernetes 服務帳戶權杖的用戶端。

啟用服務帳戶權杖 (SAT) 驗證

authenticationMethods修改 BrokerAuthentication 資源中的設定，以指定ServiceAccountToken為有效的驗證方法。 audiences 會指定權杖的有效物件清單。 選擇可識別 MQTT 代理程式服務的唯一值。 您必須指定至少一個對象，且所有 SAT 都必須符合其中一個指定的對象。

  1. 在 Azure 入口網站 中，流覽至您的IoT作業實例。
  2. 在 [Azure IoT 作業資源] 底下，選取 [MQTT 訊息代理程式]。
  3. 選取 [驗證] 索引標籤。
  4. 選擇現有的驗證原則或建立新的驗證原則。
  5. 選取 [新增方法] 以新增方法。
  6. 從下拉式清單中選擇 [Kubernetes SAT] 方法，然後選取 [新增詳細數據] 以設定方法。

使用 Azure 入口網站 設定 MQTT 訊息代理程式 SAT 驗證方法的螢幕快照。

測試 SAT 驗證

SAT 驗證會使用 MQTT v5 增強式驗證欄位。 客戶端必須將增強的驗證方法設定為 ， K8S-SAT 並將增強的驗證數據設定為令牌。

例如，使用 mosquitto （一些為簡潔而省略的欄位）：

mosquitto_pub ... -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data <TOKEN>

<TOKEN>以下是服務帳戶令牌。 若要取得測試權杖，請執行：

kubectl create token <SERVICE_ACCOUNT> -n azure-iot-operations --audience <AUDIENCE>

<SERVICE_ACCOUNT>以下是您建立的服務帳戶名稱，也是 <AUDIENCE> BrokerAuthentication 資源中設定的其中一個物件。

如需如何設定 Kubernetes Pod 以使用 SAT 驗證的範例，請參閱 連線到叢集內的預設接聽程式。

在 Pod 組態中serviceAccountName，中的 欄位必須符合與所使用令牌相關聯的服務帳戶，而且serviceAccountToken.audience欄位必須是 BrokerAuthentication 資源中設定的audiences其中一個。

重新整理服務帳戶權杖

服務帳戶權杖在有限的時間內有效，並使用 expirationSeconds 進行設定。 不過，Kubernetes 會在權杖到期之前自動重新整理。 權杖會在背景重新整理，用戶端不需要執行任何其他動作，即可再次擷取權杖。

例如，如果用戶端是使用掛接為磁碟區的權杖的 Pod，例如在測試 SAT 驗證範例中，則會在相同的路徑 /var/run/secrets/tokens/broker-sat 取得最新的權杖。 進行新的連線時，用戶端可以擷取最新的權杖，並使用它進行驗證。 用戶端也應該有一個機制，藉由擷取最新的權杖並重試連線，來處理 MQTT 的未授權錯誤。

自訂驗證

使用自訂驗證，將用戶端驗證延伸至提供的驗證方法之外。 服務可以是任何項目，但只要服務遵守 API，即視為插入式。

當用戶端連線到 MQTT 訊息代理程式並啟用自訂驗證時，MQTT 訊息代理程式會將客戶端認證驗證委派給具有 HTTPS 要求的自定義驗證伺服器，以及客戶端呈現的所有認證。 自訂驗證伺服器會使用用戶端的授權屬性來回應用戶端的核准或拒絕。

建立自訂驗證服務

自訂驗證伺服器會與 MQTT 代理程式分開實作和部署。

GitHub 提供範例自訂驗證伺服器和指示。 使用此範例做為範本，以及實作您自己的自訂驗證邏輯的起點。

API

MQTT 代理程式與自訂驗證伺服器之間的 API 遵循自訂驗證的 API 規格。 GitHub 提供 OpenAPI 規格。

需要具有 TLS 加密的 HTTPS

MQTT 代理程式會將包含敏感性用戶端認證的要求傳送至自訂驗證伺服器。 若要保護這些認證，MQTT 代理程式與自訂驗證伺服器之間的通訊必須使用 TLS 加密。

自訂驗證伺服器必須出示伺服器證書，而 MQTT 代理程式必須具有受信任的根 CA 憑證，才能驗證伺服器憑證。 或者，自訂驗證伺服器可能需要 MQTT 代理程式來呈現用戶端憑證以自行驗證。

啟用接聽程式的自訂驗證

authenticationMethods修改 BrokerAuthentication 資源中的設定，以指定Custom為有效的驗證方法。 然後，指定與自定驗證伺服器通訊所需的參數。

此範例顯示所有可能的參數。 所需的確切參數取決於每個自訂伺服器的需求。

spec:
  authenticationMethods:
    - method: Custom
      customSettings:
        # Endpoint for custom authentication requests. Required.
        endpoint: https://auth-server-template
        # Optional CA certificate for validating the custom authentication server's certificate.
        caCertConfigMap: custom-auth-ca
        # Authentication between MQTT broker with the custom authentication server.
        # The broker may present X.509 credentials or no credentials to the server.
        auth:
          x509:
            secretRef: custom-auth-client-cert
            namespace: azure-iot-operations
        # Optional additional HTTP headers that the broker will send to the
        # custom authentication server.
        headers:
          header_key: header_value

停用驗證

若要進行測試，您可以停用訊息代理程式接聽程式埠的驗證。 不建議針對生產環境停用驗證。

  1. 在 Azure 入口網站 中，流覽至您的IoT作業實例。
  2. 在 [Azure IoT 作業資源] 底下，選取 [MQTT 訊息代理程式]。
  3. 從清單中選取您要編輯的訊息代理程式接聽程式。
  4. 在您要停用驗證的埠上，選取 [驗證] 下拉式清單中的 [無 ]。

認證到期后用戶端中斷連線

MQTT 代理程式會在用戶端的認證過期時將用戶端中斷連線。 在認證過期後中斷連線的做法適用於所有連線到 MQTT 代理程式前端的用戶端，包括：

  • 使用 SAT 進行驗證的用戶端會在其 SAT 過期時中斷連線
  • 使用 X.509 進行驗證的用戶端會在用戶端憑證過期時中斷連線
  • 使用自訂驗證來進行驗證的用戶端會根據自訂驗證伺服器所傳回的過期時間來中斷連線。

在中斷連線時，用戶端的網路連線會關閉。 用戶端不會收到 MQTT DISCONNECT 封包，但代理程式會記錄其將用戶端中斷連線的訊息。

使用 SAT 和自訂驗證來進行驗證的 MQTT v5 用戶端可以在初始認證過期前，使用新的認證重新驗證。 X.509 用戶端無法重新驗證，而且必須重新建立連線，因為驗證是在 TLS 層完成。

用戶端可以藉由傳送 MQTT v5 AUTH 封包來重新驗證， 原因為 ReAuth。

SAT 用戶端會傳送具有 method: K8S-SAT、data: <token> 欄位的 AUTH 用戶端。 自訂驗證用戶端會按照自訂驗證伺服器的要求來設定方法和資料欄位。

成功重新驗證後，便會使用新認證的過期時間來更新用戶端的認證過期時間，而代理程式則會回應「Success AUTH」封包。 由於暫時性問題而導致驗證失敗，例如無法使用自定義驗證伺服器，導致訊息代理程序回應 ContinueAuthentication AUTH 封包。 用戶端可以稍後再試一次。 其他驗證失敗則會導致代理程式傳送 DISCONNECT 封包，並關閉用戶端的網路連線。

相關內容