Zur Authentifizierung bei Cloud IoT Core muss jedes Gerät ein JSON Web Token (JWT, RFC 7519) vorbereiten. JWTs werden für die kurzlebige Authentifizierung zwischen Geräten und den MQTT- oder HTTP-Brücken verwendet. Auf dieser Seite werden die Cloud IoT Core-Anforderungen für den Inhalt des JWT beschrieben.
Für Cloud IoT Core ist keine bestimmte Methode zur Tokengenerierung erforderlich. Eine gute Sammlung von Hilfsclient-Bibliotheken finden Sie auf JWT.io.
Beim Erstellen eines MQTT-Clients muss das JWT im Feld password
der Nachricht CONNECT
übergeben werden. Beim Herstellen einer Verbindung über HTTP muss ein JWT im Header jeder HTTP-Anfrage enthalten sein.
JWTs erstellen
JWTs bestehen aus drei Abschnitten: einem Header, einer Nutzlast (mit einem Anforderungssatz) und einer Signatur. Der Header und die Nutzlast sind JSON-Objekte, die in UTF-8-Byte serialisiert und dann mit base64url-Codierung codiert werden.
Der Header, die Nutzlast und die Signatur des JWT werden mit Punkten (.
) verkettet. Daher hat ein JWT in der Regel die folgende Form:
{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}
Im folgenden Beispiel wird gezeigt, wie Sie ein Cloud IoT Core-JWT für ein bestimmtes Projekt erstellen. Nachdem Sie das JWT erstellt haben, können Sie eine Verbindung zur MQTT- oder HTTP-Bridge herstellen, um Nachrichten von einem Gerät zu veröffentlichen.
C++
Go
Java
Node.js
Python
JWT-Header
Der JWT-Header besteht aus zwei Feldern, die den Signaturalgorithmus und den Tokentyp angeben. Beide Felder sind obligatorisch und jedes Feld hat nur einen Wert. Cloud IoT Core unterstützt die folgenden Signaturalgorithmen:
- JWT
RS256
(RSASSA-PKCS1-v1_5 mit SHA-256 RFC 7518 sec 3.3). Dies wird alsRS256
im Feldalg
im JWT-Header ausgedrückt. - JWT
ES256
(ECDSA mit P-256 und SHA-256 RFC 7518 sec 3.4) ist in OpenSSL als die Kurve prime256v1 definiert. Dies wird alsES256
im Feldalg
im JWT-Header ausgedrückt.
Zusätzlich zum Signaturalgorithmus müssen Sie das JWT-Tokenformat angeben.
Die JSON-Darstellung des Headers sieht so aus:
Für RSA-Schlüssel:
{ "alg": "RS256", "typ": "JWT" }
Für Elliptische-Kurven-Schlüssel:
{ "alg": "ES256", "typ": "JWT" }
Der im Header angegebene Algorithmus muss mit mindestens einem der für das Gerät registrierten öffentlichen Schlüssel übereinstimmen.
JWT-Anforderungen
Die JWT-Nutzlast enthält eine Reihe von Anforderungen und wird mit den asymmetrischen Schlüsseln signiert. Der JWT-Anforderungssatz enthält Informationen zum JWT, z. B. das Ziel des Tokens, den Aussteller, den Zeitpunkt der Ausstellung des Tokens und/oder die Lebensdauer des Tokens. Wie der JWT-Header ist auch der JWT-Anforderungssatz ein JSON-Objekt, das zur Berechnung der Signatur verwendet wird.
Erforderliche Ansprüche
Cloud IoT Core erfordert die folgenden reservierten Anforderungsfelder. Sie können in beliebiger Reihenfolge im Anforderungssatz angezeigt werden.
Name | Beschreibung |
---|---|
iat |
("Ausgegeben am"): Der Zeitstempel, zu dem das Token erstellt wurde, angegeben in Sekunden seit 00:00:00 UTC, 1. Januar 1970. Der Server meldet möglicherweise einen Fehler, wenn dieser Zeitstempel zu weit in der Vergangenheit oder in der Zukunft liegt (erlaubt eine Abweichung von 10 Minuten). |
exp |
("Ablauf"): Der Zeitstempel, ab wann das Token nicht mehr gültig ist, angegeben als Sekunden seit 00:00:00 UTC, 1. Januar 1970. Die maximale Lebensdauer eines Tokens beträgt 24 Stunden + Abweichung.
|
aud |
("Zielgruppe"): Dies muss ein einzelner String sein, der die Cloud-Projekt-ID enthält, unter der das Gerät registriert ist. Wenn die Verbindungsanfrage nicht mit dieser Projekt-ID übereinstimmt, wird die Authentifizierung ohne weitere Analyse abgelehnt. |
Die Anforderung nbf
("Not before") wird ignoriert und ist nicht erforderlich.
Im Folgenden finden Sie eine JSON-Darstellung der erforderlichen reservierten Felder in einem Anforderungssatz des Cloud IoT Core-JWT:
{ "aud": "my-project", "iat": 1509654401, "exp": 1612893233 }
JWT-Signatur
Die Spezifikation JSON-Websignatur (JWS) regelt, wie die Signatur für das JWT erzeugt wird. Die Eingabe für die Signatur ist das Byte-Array des folgenden Inhalts:
{Base64url encoded header}.{Base64url encoded claim set}
Zur Berechnung der Signatur signieren Sie den base64url-codierten Header, den base64-url-codierten Anforderungssatz und einen geheimen Schlüssel (z. B. eine rsa_private.pem
-Datei) mit dem im Header definierten Algorithmus. Die Signatur ist dann base64url-codiert und das Ergebnis ist das JWT. Das folgende Beispiel zeigt ein JWT vor der base64url-Codierung:
{"alg": "RS256", "typ": "JWT"}.{"aud": "my-project", "iat": 1509654401, "exp": 1612893233}.[signature bytes]
Nach der endgültigen Codierung sieht das JWT so aus:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteS1wcm9qZWN0IiwiZXhwIjoxNTA5NjUwODAxLCJpYXQiOjE1MDk2NTQ0MDF9.F4iKO0R0wvHkpCcQoyrYttdGxE5FLAgDhbTJQLEHIBPsbL2WkLxXB9IGbDESn9rE7oxn89PJFRtcLn7kJwvdQkQcsPxn2RQorvDAnvAi1w3k8gpxYWo2DYJlnsi7mxXDqSUCNm1UCLRCW68ssYJxYLSg7B1xGMgDADGyYPaIx1EdN4dDbh-WeDyLLa7a8iWVBXdbmy1H3fEuiAyxiZpk2ll7DcQ6ryyMrU2XadwEr9PDqbLe5SrlaJsQbFi8RIdlQJSo_DZGOoAlA5bYTDYXb-skm7qvoaH5uMtOUb0rjijYuuxhNZvZDaBerEaxgmmlO0nQgtn12KVKjmKlisG79Q
JWTs aktualisieren
Wie unter Erforderliche Anforderungen beschrieben, haben Tokens ein Ablaufdatum. Wenn ein Gerät über MQTT verbunden ist und dessen Token abläuft, wird die Verbindung zu Cloud IoT Core automatisch getrennt. Sie können verhindern, dass das Gerät die Verbindung unterbricht. Aktualisieren Sie dazu das Token automatisch. Die folgenden Beispiele veranschaulichen, wie geprüft wird, ob ein Token abgelaufen ist, und wie, falls dies der Fall ist, die Verbindung mit einem neuen Token wiederhergestellt wird, ohne das Gerät zu trennen.