Como verificar um token Web JSON - Amazon Cognito

Como verificar um token Web JSON

Essas etapas descrevem como verificar um JSON web token (JWT) do grupo de usuários.

Pré-requisitos

Sua biblioteca, o SDK ou o framework de software podem processar as tarefas nesta seção. Por exemplo, os SDKs do Amazon Cognito fornecem processamento e gerenciamento de tokens do grupo de usuários no lado do cliente. Da mesma forma, o Mobile SDK para iOS e o Mobile SDK para Android atualizarão automaticamente seus tokens de ID e de acesso se forem atendidas duas condições: deverá estar presente um token de atualização válido (não expirado) e os tokens de ID e de acesso deverão ter um tempo de validade mínimo restante de cinco minutos. Para obter informações sobre SDKs e um código de exemplo para JavaScript, Android e iOS, consulte SDKs para grupo de usuários do Amazon Cognito.

Muitas bibliotecas estão disponíveis para decodificação e verificação de um JSON Web Token (JWT). Se você precisar processar tokens manualmente para o processamento da API no lado do servidor ou se estiver usando outras linguagens de programação, essas bibliotecas poderão ajudar. Consulte a OpenID foundation list of libraries for working with JWT tokens (Lista básica de bibliotecas da OpenID para trabalhar com tokens JWT).

Etapa 1: confirmar a estrutura do JWT

Um JSON Web Token (JWT) inclui três seções:

  1. Cabeçalho

  2. Carga útil

  3. Assinatura

11111111111.22222222222.33333333333

Essas seções são codificadas como strings base64url e são separadas por caracteres de ponto (.). Se o JWT não for compatível com essa estrutura, considere-o não válido e não o aceite.

Etapa 2: validar a assinatura do JWT

A assinatura JWT é uma combinação com hash do cabeçalho e da carga útil. O Amazon Cognito gera dois pares de chaves criptográficas RSA para cada grupo de usuários. Uma das chaves privadas é usada para assinar o token.

Para verificar a assinatura de um token JWT

  1. Decodifique o token de ID.

    Você pode usar o AWS Lambda para decodificar JWTs do grupo de usuários. Para obter mais informações, consulte Decode and verify Amazon Cognito JWT tokens using AWS Lambda (Decodificar e verificar tokens JWT do Amazon Cognito usando o AWS Lambda).

    A OpenID Foundation também mantém uma lista de bibliotecas para trabalhar com tokens JWT.

  2. Compare o ID de chave local (kid) com o kid público.

    1. Faça download e armazene o JSON Web Key (JWK) público correspondente para seu grupo de usuários. Ele está disponível como parte de um JSON Web Key Set (JWKS). Você pode localizá-lo construindo o seguinte URL para seu ambiente:

      https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json

      Para mais informações sobre JWK e conjuntos de JWK, consulte JSON Web key (JWK).

      nota

      Baixar e armazenar o JWK para seu grupo de usuários é uma etapa única antes que as operações da API da Web possam processar tokens. Depois de fazer isso, você pode executar as etapas a seguir cada vez que os tokens de ID ou de acesso forem usados com suas operações de API da Web.

      Este é um exemplo de arquivo jwks.json:

      { "keys": [{ "kid": "1234example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "1234567890", "use": "sig" }, { "kid": "5678example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "987654321", "use": "sig" }] }
      ID da chave (kid)

      O kid é uma dica que indica qual foi a chave usada para proteger a JSON web signature (JWS) do token.

      Algoritmo (alg)

      O parâmetro de cabeçalho alg representa o algoritmo criptográfico usado para proteger o token de ID. Os grupos de usuários utilizam um algoritmo criptográfico RS256, que é uma assinatura RSA com SHA-256. Para mais informações sobre RSA, consulte Criptografia RSA.

      Tipo de chave (kty)

      O parâmetro kty identifica o algoritmo criptográfico usado pela família com a chave, como “RSA”, neste exemplo.

      Expoente RSA (e)

      O parâmetro e contém o valor de expoente da chave pública RSA. Ele é representado como um valor codificado como Base64urlUInt.

      Modulus (n) RSA

      O parâmetro n contém o valor de modulus da chave pública RSA. Ele é representado como um valor codificado como Base64urlUInt.

      Usar o use

      O parâmetro use descreve o uso pretendido da chave pública. Neste exemplo, o use valor sig representa assinatura.

    2. Pesquise a chave da Web JSON pública de um kid que corresponda ao kid do JWT.

  3. Use uma biblioteca de JWT, como a biblioteca aws-jwt-verify no GitHub, para comparar a assinatura do emissor com a assinatura no token. A assinatura do emissor é derivada da chave pública (o módulo RSA "n") do kid em jwks.json que corresponde ao token kid. Talvez seja necessário converter a JWK em formato PEM primeiro. Esse exemplo a seguir adota o JWT e a JWK, e usa a biblioteca Node.js, jsonwebtoken, para verificar a assinatura do JWT:

    Node.js
    var jwt = require('jsonwebtoken'); var jwkToPem = require('jwk-to-pem'); var pem = jwkToPem(jwk); jwt.verify(token, pem, { algorithms: ['RS256'] }, function(err, decodedToken) { });

Etapa 3: verificar as declarações

Para verificar alegações JWT

  1. Verifique se o token não expirou.

  2. A declaração aud em um token de ID e a declaração client_id em um token de acesso devem corresponder ao ID do cliente de aplicação criado no grupo de usuários do Amazon Cognito.

  3. A solicitação de emissor (iss) deve corresponder ao seu grupo de usuários. Por exemplo, um grupo de usuários criado na região us-east-1 terá o seguinte valor de iss:

    https://cognito-idp.us-east-1.amazonaws.com/<userpoolID>.

  4. Verifique a alegação token_use.

    • Se você estiver aceitando apenas o token de acesso nas APIs da Web, o valor do token terá de ser access.

    • Se estiver usando apenas o token de ID, o valor dele precisa ser id.

    • Se estiver usando os tokens de ID e acesso, a alegação token_use deverá ser id ou access.

Você já pode aceitar as alegações dentro do token.