Para autenticar no Cloud IoT Core, cada dispositivo precisa preparar um JSON Web Token (JWT, RFC 7519). Os JWTs são usados para autenticação de curta duração entre dispositivos e as pontes MQTT ou HTTP. Nesta página, descrevemos os requisitos do Cloud IoT Core para o conteúdo do JWT.
O Cloud IoT Core não requer um método específico de geração de tokens. Uma coleção de bibliotecas de cliente auxiliares pode ser encontrada em JWT.io.
Ao criar um cliente MQTT, o JWT precisa ser transmitido no campo password da mensagem CONNECT. Durante a conexão por HTTP, um JWT precisa ser incluído no cabeçalho de cada solicitação HTTP.
Como criar JWTs
Os JWTs são compostos de três seções: um cabeçalho, um payload (contendo um conjunto de declarações) e uma assinatura. O cabeçalho e o payload são objetos JSON, que são serializados para bytes UTF-8 e codificados com codificação base64url.
O cabeçalho, o payload e a assinatura do JWT são concatenados com pontos (.). Como resultado, um JWT geralmente tem o seguinte formato:
{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}
Veja na amostra a seguir como criar um JWT do Cloud IoT Core para um determinado projeto. Após criar o JWT, você pode se conectar à ponte MQTT ou HTTP para publicar mensagens de um dispositivo.
C++
Go
Java
Node.js
Python
Cabeçalho JWT
O cabeçalho JWT consiste em dois campos que indicam o algoritmo de assinatura e o tipo de token. Ambos os campos são obrigatórios, e cada um tem apenas um valor. O Cloud IoT Core oferece suporte aos seguintes algoritmos de assinatura:
- JWT
RS256(RSASSA-PKCS1-v1_5 usando SHA-256 RFC 7518 sec 3.3). Ele é expresso comoRS256no campoalg, no cabeçalho JWT. - JWT
ES256(ECDSA usando P-256 e SHA-256 RFC 7518 sec 3.4), definido no OpenSSL como a curva prime256v1. Ele é expresso comoES256no campoalg, no cabeçalho JWT.
Além do algoritmo de assinatura, você precisa fornecer o formato de token JWT.
A representação JSON do cabeçalho é a seguinte:
Para chaves RSA:
{ "alg": "RS256", "typ": "JWT" }
Para chaves de curva elíptica:
{ "alg": "ES256", "typ": "JWT" }
O algoritmo especificado no cabeçalho precisa corresponder a pelo menos uma das chaves públicas registradas no dispositivo.
Declarações do JWT
O payload do JWT contém um conjunto de declarações e é assinado com as chaves assimétricas. O conjunto de declarações JWT contém informações sobre o JWT, como o destino do token, o emissor, o horário em que o token foi emitido e/ou o ciclo de vida dele. Assim como o cabeçalho JWT, o conjunto de declarações JWT é um objeto JSON e é usado no cálculo da assinatura.
Reivindicações obrigatórias
O Cloud IoT Core requer os seguintes campos de declaração reservados. Elas podem aparecer em qualquer ordem no conjunto de reivindicações.
| Nome | Descrição |
|---|---|
iat |
("Emitido em"): o carimbo de data/hora em que o token foi criado, especificado como segundos desde 00:00:00 UTC, 1o de janeiro de 1970. O servidor poderá informar um erro se esse carimbo de data/hora estiver muito distante no passado ou no futuro, permitindo um desvio de 10 minutos. |
exp |
("Validade"): o carimbo de data/hora em que o token deixa de ser válido, especificado como segundos desde 00:00:00 UTC, 1o de janeiro de 1970. A vida útil máxima de um token é de 24 horas + desvio.
|
aud |
("Público"): precisa ser uma única string que contém o ID do projeto do Cloud em que o dispositivo está registrado. Se a solicitação de conexão não corresponder a este ID do projeto, a autenticação será negada sem análises adicionais. |
A declaração nbf("Não antes") será ignorada e não será obrigatória.
Veja abaixo uma representação JSON dos campos reservados obrigatórios em um conjunto de declarações JWT do Cloud IoT Core:
{
"aud": "my-project",
"iat": 1509654401,
"exp": 1612893233
}
Assinatura JWT
A especificação JSON Web Signature (JWS) orienta a mecânica de geração da assinatura para o JWT. A entrada da assinatura é a matriz de bytes do seguinte conteúdo:
{Base64url encoded header}.{Base64url encoded claim set}
Para calcular a assinatura, assine o cabeçalho codificado em base64url, o conjunto de declarações codificadas em base64-url e uma chave secreta (como um arquivo rsa_private.pem) usando o algoritmo que você definiu no cabeçalho. Em seguida, a assinatura é codificada em base64url, e o resultado é o JWT. O exemplo a seguir mostra um JWT antes da codificação em base64url:
{"alg": "RS256", "typ": "JWT"}.{"aud": "my-project", "iat": 1509654401, "exp": 1612893233}.[signature bytes]
Após a codificação final, o JWT se parece com o seguinte:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteS1wcm9qZWN0IiwiZXhwIjoxNTA5NjUwODAxLCJpYXQiOjE1MDk2NTQ0MDF9.F4iKO0R0wvHkpCcQoyrYttdGxE5FLAgDhbTJQLEHIBPsbL2WkLxXB9IGbDESn9rE7oxn89PJFRtcLn7kJwvdQkQcsPxn2RQorvDAnvAi1w3k8gpxYWo2DYJlnsi7mxXDqSUCNm1UCLRCW68ssYJxYLSg7B1xGMgDADGyYPaIx1EdN4dDbh-WeDyLLa7a8iWVBXdbmy1H3fEuiAyxiZpk2ll7DcQ6ryyMrU2XadwEr9PDqbLe5SrlaJsQbFi8RIdlQJSo_DZGOoAlA5bYTDYXb-skm7qvoaH5uMtOUb0rjijYuuxhNZvZDaBerEaxgmmlO0nQgtn12KVKjmKlisG79Q
Como atualizar JWTs
Conforme descrito nas reivindicações obrigatórias, os tokens têm datas de validade. Se um dispositivo estiver conectado por MQTT e o token expirar, o dispositivo será desconectado automaticamente do Cloud IoT Core. É possível evitar que o dispositivo seja desconectado atualizando o token automaticamente. Os exemplos a seguir mostram como verificar se um token expirou e, em caso afirmativo, como se reconectar a um novo token sem desconectar o dispositivo.