Pour s'authentifier auprès de Cloud IoT Core, chaque appareil doit préparer un jeton Web JSON (JWT, RFC 7519). Les jetons JWT sont utilisés pour l'authentification de courte durée entre les appareils et les ponts MQTT ou HTTP. Cette page décrit les exigences relatives à Cloud IoT Core pour le contenu du jeton JWT.
Cloud IoT Core ne nécessite pas de méthode de génération de jetons spécifique. Vous trouverez un bon ensemble de bibliothèques clientes d'aide sur JWT.io.
Lors de la création d'un client MQTT, le jeton JWT doit être transmis dans le champ password du message CONNECT. Lors de la connexion via HTTP, un jeton JWT doit être inclus dans l'en-tête de chaque requête HTTP.
Créer des jetons JWT
Les jetons JWT sont composés de trois sections: une en-tête, une charge utile (contenant un ensemble de revendications) et une signature. L'en-tête et la charge utile sont des objets JSON, qui sont sérialisés en octets UTF-8, puis encodés en base64url.
L'en-tête, la charge utile et la signature du jeton JWT sont concaténés avec des points (.). Par conséquent, un jeton JWT se présente généralement sous la forme suivante :
{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}
L'exemple suivant montre comment créer un jeton JWT Cloud IoT Core pour un projet donné. Après avoir créé le jeton JWT, vous pouvez vous connecter au pont MQTT ou HTTP pour publier des messages à partir d'un appareil.
C++
Go
Java
Node.js
Python
En-tête JWT
L'en-tête JWT comprend deux champs indiquant l'algorithme de signature et le type de jeton. Ces deux champs sont obligatoires et ne doivent contenir qu'une seule valeur. Cloud IoT Core accepte les algorithmes de signature suivants:
- JWT
RS256(RSASSA-PKCS1-v1_5 avec SHA-256 RFC 7518 sec 3.3). Cela est exprimé parRS256dans le champalgde l'en-tête JWT. - JWT
ES256(ECDSA utilisant P-256 et SHA-256 RFC 7518 sec 3.4), défini dans OpenSSL en tant que courbe prime256v1. Cela est exprimé parES256dans le champalgde l'en-tête JWT.
Outre l'algorithme de signature, vous devez fournir le format de jeton JWT.
La représentation JSON de l'en-tête est la suivante :
Pour les clés RSA :
{ "alg": "RS256", "typ": "JWT" }
Pour les clés à courbe elliptique:
{ "alg": "ES256", "typ": "JWT" }
L'algorithme spécifié dans l'en-tête doit correspondre à au moins une des clés publiques enregistrées pour l'appareil.
Revendications JWT
La charge utile JWT contient un ensemble de revendications et est signée à l'aide des clés asymétriques. L'ensemble de revendications JWT contient des informations sur le jeton JWT, telles que la cible du jeton, l'émetteur, l'heure d'émission du jeton et/ou la durée de vie du jeton. Comme l'en-tête JWT, l'ensemble de revendications JWT est un objet JSON qui est utilisé dans le calcul de la signature.
Revendications requises
Cloud IoT Core requiert les champs de revendication réservés suivants. Ils peuvent apparaître dans n'importe quel ordre dans l'ensemble de revendications.
| Nom | Description |
|---|---|
iat |
"Issued at"): horodatage de la création du jeton, spécifié en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. Le serveur peut signaler une erreur si cet horodatage est trop éloigné dans le passé ou le futur (avec un décalage de 10 minutes). |
exp |
("Expiration"): horodatage du délai de validité du jeton spécifié, exprimé en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. La durée de vie maximale d'un jeton est de 24 heures + décalage.
|
aud |
("Audience"): il doit s'agir d'une chaîne unique contenant l'ID du projet Cloud sur lequel l'appareil est enregistré. Si la requête de connexion ne correspond pas à cet ID de projet, l'authentification sera refusée sans autre analyse. |
La revendication nbf("NotBefore") sera ignorée et n'est pas obligatoire.
Une représentation JSON des champs réservés requis dans un ensemble de revendications JWT Cloud IoT Core est présentée ci-dessous :
{
"aud": "my-project",
"iat": 1509654401,
"exp": 1612893233
}
Signature JWT
La spécification JSON Web Signature (JWS) guide la mécanique de génération de la signature pour le jeton JWT. L'entrée de la signature est le tableau d'octets du contenu suivant:
{Base64url encoded header}.{Base64url encoded claim set}
Pour calculer la signature, signez l'en-tête encodé en base64url, l'ensemble de revendications encodées en base64 et une clé secrète (telle qu'un fichier rsa_private.pem) à l'aide de l'algorithme que vous avez défini dans l'en-tête. La signature est ensuite encodée en base64url et le résultat est le JWT. L'exemple suivant présente un jeton JWT avant l'encodage base64url:
{"alg": "RS256", "typ": "JWT"}.{"aud": "my-project", "iat": 1509654401, "exp": 1612893233}.[signature bytes]
Après l'encodage final, le jeton JWT se présente comme suit :
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteS1wcm9qZWN0IiwiZXhwIjoxNTA5NjUwODAxLCJpYXQiOjE1MDk2NTQ0MDF9.F4iKO0R0wvHkpCcQoyrYttdGxE5FLAgDhbTJQLEHIBPsbL2WkLxXB9IGbDESn9rE7oxn89PJFRtcLn7kJwvdQkQcsPxn2RQorvDAnvAi1w3k8gpxYWo2DYJlnsi7mxXDqSUCNm1UCLRCW68ssYJxYLSg7B1xGMgDADGyYPaIx1EdN4dDbh-WeDyLLa7a8iWVBXdbmy1H3fEuiAyxiZpk2ll7DcQ6ryyMrU2XadwEr9PDqbLe5SrlaJsQbFi8RIdlQJSo_DZGOoAlA5bYTDYXb-skm7qvoaH5uMtOUb0rjijYuuxhNZvZDaBerEaxgmmlO0nQgtn12KVKjmKlisG79Q
Actualiser les jetons JWT
Comme décrit dans la section Revendications requises, les jetons ont des dates d'expiration. Si un appareil est connecté via MQTT et que son jeton expire, l'appareil se déconnecte automatiquement de Cloud IoT Core. Vous pouvez empêcher la déconnexion de l'appareil en actualisant automatiquement son jeton. Les exemples suivants montrent comment vérifier si un jeton a expiré et, le cas échéant, comment se reconnecter avec un nouveau jeton sans déconnecter l'appareil.