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 de 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'aide est disponible 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: 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 au format 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 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 accepte les algorithmes de signature suivants:
- JWT
RS256(RSASSA-PKCS1-v1_5 avec la norme SHA-256 RFC 7518 s 3.3) Cela est exprimé sous la formeRS256dans le champalgde l'en-tête JWT. - JWT
ES256(ECDSA utilisant P-256 et SHA-256 RFC 7518 s 3.4), défini dans OpenSSL comme la courbe prime256v1. Cela est exprimé sous la formeES256dans 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. 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
Les champs de revendication réservés suivants sont requis pour Cloud IoT Core. Ils peuvent apparaître dans n'importe quel ordre dans l'ensemble de revendications.
| Nom | Description |
|---|---|
iat |
("Émis à"): horodatage de 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 loin dans le passé ou le futur (ce qui permet un décalage de 10 minutes). |
exp |
("Expiration"): horodatage d'expiration 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 + décalage.
|
aud |
("Audience"): il doit s'agir d'une chaîne unique contenant l'ID de projet cloud dans lequel l'appareil est enregistré. Si la demande 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 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 base64url et une clé secrète (par exemple, 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 jeton 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 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.