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 à court terme entre les appareils et les ponts MQTT ou HTTP. Cette page décrit les exigences pour Cloud IoT Core concernant le contenu du jeton JWT.
Cloud IoT Core ne nécessite pas de méthode de génération de jetons spécifique. Une bonne collection de bibliothèques clientes d'assistance est disponible sur JWT.io.
Lors de la création d'un client MQTT, le 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 comportent trois sections: un 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 UTF-8 octets, 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 JWT Cloud IoT Core pour un projet donné. Après avoir créé le JWT, vous pouvez vous connecter au pont MQTT ou HTTP pour publier des messages depuis un appareil.
C++
Go
Java
Node.js
Python
En-tête JWT
L'en-tête JWT comprend deux champs qui indiquent l'algorithme de signature et le type de jeton. Ces deux champs sont obligatoires et chaque champ ne comporte qu'une seule valeur. Cloud IoT Core est compatible avec les algorithmes de signature suivants:
- JWT
RS256(RSASSA-PKCS1-v1_5 avec SHA-256 RFC 7518 sec 3.3). Cela est exprimé au formatRS256dans le champalgde l'en-tête JWT. - JWT
ES256(ECDSA à l'aide de P-256 et SHA-256 RFC 7518 s 3.4), défini dans OpenSSL comme courbe prime256v1. Cela est exprimé au formatES256dans le champalgde l'en-tête JWT.
En plus de 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 du jeton JWT contient un ensemble de revendications. Elle 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 sa durée de vie. Comme l'en-tête JWT, l'ensemble de revendications JWT est un objet JSON et est utilisé dans le calcul de la signature.
Revendications obligatoires
Cloud IoT Core nécessite 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 |
("Émis à"): horodatage de la création du jeton, exprimé en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. Le serveur peut signaler une erreur si cet horodatage est trop antérieur dans le passé ou à l'avenir (en tenant compte d'un décalage de 10 minutes). |
exp |
("Expiration"): horodatage de la validité du jeton, 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 avec décalage.
|
aud |
("Audience"): il doit s'agir d'une chaîne unique contenant l'ID du projet cloud où l'appareil est enregistré. Si la requête de connexion ne correspond pas à cet ID de projet, l'authentification sera refusée sans analyse supplémentaire. |
La revendication nbf("Pas avant") 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 du jeton JWT
La spécification JSON Web Signature (JWS) guide la mécanique de génération de la signature pour le JWT. L'entrée de la signature correspond au 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 (un fichier rsa_private.pem, par exemple) à 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 montre un 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 indiqué dans les revendications obligatoires, les jetons ont des dates d'expiration. Si un appareil est connecté via MQTT et que son jeton expire, il 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.