CDRN

Inspecionar um JWKS e extrair as chaves públicas em PEM

  • Painel
  • Documentação
  • API
inspeciona um JWK Set (JSON Web Key Set) e extrai cada chave pública no formato PEM, pronta para verificar as assinaturas JWT de um fornecedor de identidade (OIDC, Auth0, Keycloak…)
Cole o conteúdo completo de um documento JWKS, por exemplo o publicado em /.well-known/jwks.json.

O que é um JWKS?

Um JWKS (JSON Web Key Set, RFC 7517) é um documento JSON que agrupa uma lista de chaves públicas sob forma estruturada. Serve para publicar as chaves que um emissor de JWT utiliza para assinar os seus tokens, para que qualquer consumidor as possa obter e verificar a assinatura dos tokens que recebe. O formato apresenta-se sempre assim: 

{
  "keys": [
    { "kty": "RSA", "kid": "abc123", "use": "sig", "alg": "RS256", "n": "...", "e": "AQAB" },
    { "kty": "EC",  "kid": "def456", "use": "sig", "alg": "ES256", "crv": "P-256", "x": "...", "y": "..." }
  ]
}

Cada entrada do array keys é uma JWK (JSON Web Key) que descreve uma chave pública: tipo de chave (kty), identificador (kid), uso previsto (use), algoritmo alvo (alg) e componentes criptográficos.

Quando se usa um JWKS?

O JWKS é a espinha dorsal das arquiteturas OAuth2 e OpenID Connect modernas. Encontrá-lo-á em vários contextos:

  • Descoberta OIDC: qualquer fornecedor OpenID Connect expõe um documento de configuração em /.well-known/openid-configuration que contém um campo jwks_uri. Nesse URL encontra-se um JWKS que lista as chaves públicas ativas.
  • Verificação de JWT: quando a sua API recebe um token assinado em RS256 ou ES256, lê o kid do header, descarrega o JWKS do emissor, encontra a chave correspondente, deriva dela a chave pública em formato PEM, e verifica a assinatura.
  • Rotação de chaves: um emissor pode publicar várias chaves simultaneamente, o que permite introduzir uma nova chave para assinar os novos tokens mantendo a antiga em serviço enquanto os tokens em circulação expiram.
  • Federações: SAML, SCIM, serviços interligados, a publicação de um JWKS evita ter de trocar manualmente certificados X.509 entre parceiros.

Campos essenciais de uma JWK

Alguns campos aparecem sistematicamente numa JWK. Esta ferramenta extrai-os e mostra-os para cada chave do JWKS analisado:

  • kid (key ID): identificador único da chave. É este valor que o header de um JWT coloca no seu campo kid para indicar que chave do JWKS deve servir para a verificação.
  • kty (key type): família criptográfica. Os dois valores dominantes são RSA (chaves RSA clássicas, utilizadas com RS256, RS384, RS512) e EC (curvas elípticas, utilizadas com ES256, ES384, ES512).
  • alg (algorithm): algoritmo de assinatura para o qual esta chave está prevista. Campo facultativo mas muitas vezes preenchido. Permite filtrar rapidamente as chaves utilizáveis para um dado JWT.
  • use: uso da chave. sig para a assinatura (caso habitual), enc para a cifragem (raro, utilizado com JWE).

Porquê converter uma JWK em PEM?

A maioria das bibliotecas criptográficas clássicas (OpenSSL, openssl_verify em PHP, crypto em Node.js, JCA em Java) aceitam as chaves públicas em formato PEM (Base64 enquadrado por -----BEGIN PUBLIC KEY-----), não diretamente em formato JWK. Converter uma JWK em PEM é, portanto, indispensável para:

  • Verificar manualmente a assinatura de um JWT a partir de um script ou ferramenta de linha de comandos (jwt, jose, step crypto).
  • Importar a chave para uma ferramenta de debug como JWT Verifier que espera uma chave PEM no seu campo "chave pública".
  • Armazenar uma chave em cache local ou num ficheiro de configuração sob uma forma universal e legível.
  • Comparar rapidamente duas chaves (o formato PEM facilita os diffs visuais).

Limites e avisos

Esta ferramenta suporta chaves públicas RSA (kty=RSA) e EC (kty=EC nas curvas P-256, P-384, P-521). Os outros tipos (OKP para Ed25519, oct para chaves simétricas) não são convertidos: são sinalizados com uma mensagem de erro por entrada, o resto do JWKS permanece legível.

  • A conversão efetua-se num único sentido: JWKS para PEM. A reconstrução de uma JWK a partir de uma chave PEM existente não é coberta por esta versão.
  • O JWKS deve ser colado tal como está sob forma de texto JSON. A obtenção automática a partir de um URL jwks_uri ou de um endpoint OIDC não é feita no lado do servidor, para evitar chamadas de saída inesperadas.
  • As chaves privadas não devem aparecer num JWKS público, e esta ferramenta extrai apenas os componentes públicos mesmo que uma chave privada estivesse presente.

Como utilizar

  1. Obtenha o JWKS do emissor que pretende inspecionar. Para um fornecedor OIDC, o endereço é geralmente https://exemplo.com/.well-known/jwks.json ou https://exemplo.com/oauth2/jwks.
  2. Copie a totalidade do documento JSON (o objeto que contém a chave keys).
  3. Cole-o na área de entrada da ferramenta e inicie a análise.
  4. Para cada chave do JWKS, a ferramenta mostra o seu kid, o seu kty, o seu alg, o seu use e a chave pública convertida em formato PEM.
  5. Clique em "copiar" para recuperar a PEM e utilizá-la num script de verificação, no nosso JWT Verifier, ou em qualquer ferramenta compatível com OpenSSL.

Perguntas frequentes

Onde encontrar o JWKS de um fornecedor OIDC?

A grande maioria dos fornecedores OpenID Connect publica um documento de descoberta em https://exemplo.com/.well-known/openid-configuration. Este JSON contém um campo jwks_uri que aponta para o JWKS efetivo. Alguns fornecedores servem diretamente o JWKS em https://exemplo.com/.well-known/jwks.json ou num endpoint OAuth2 dedicado. Descarregue o conteúdo e cole-o aqui tal como está.

Porque é que o kid é importante?

O kid (key ID) é o identificador que o header de um JWT coloca no seu próprio campo kid para indicar que chave do JWKS deve servir à verificação. Sem este identificador, o consumidor teria de tentar cada chave do JWKS, o que complica o diagnóstico em caso de erro. A presença de um kid por chave é, portanto, considerada uma boa prática, e todos os IdP sérios publicam um.

Qual a diferença entre kty=RSA e kty=EC?

RSA é a família histórica de assinaturas assimétricas, utilizada com RS256, RS384, RS512. As chaves são descritas por um módulo n e um expoente e. EC (Elliptic Curve) é mais recente e dá assinaturas mais curtas para um nível de segurança equivalente. As chaves EC são descritas por uma curva (crv = P-256, P-384 ou P-521) e duas coordenadas x e y. Esta ferramenta converte as duas famílias em PEM.

Como utilizar a PEM extraída para verificar um JWT?

Copie a PEM, depois cole-a no campo "chave pública" do nosso JWT Verifier com o JWT a validar. Também pode utilizá-la na linha de comandos com openssl dgst, em Node.js com crypto.verify, em Python com cryptography ou PyJWT, em Java com a JCA, etc. O formato PEM é universalmente reconhecido.

O meu JWKS contém uma chave Ed25519 (OKP), porque é que não é convertida?

A conversão de chaves OKP (Ed25519, Ed448, X25519, X448) requer uma lógica específica e uma codificação DER diferente da das chaves RSA e EC. Esta versão da ferramenta só suporta RSA e EC. As chaves não suportadas são sinalizadas individualmente com uma mensagem de erro, sem bloquear a análise das outras entradas do JWKS.

É possível obter o JWKS a partir de um URL em vez de o colar?

Não nesta versão. A ferramenta não realiza qualquer chamada HTTP de saída para se manter rápida e evitar atuar como proxy involuntário. Descarregue o JWKS a partir do seu navegador ou com curl https://exemplo.com/.well-known/jwks.json e cole o conteúdo no campo de entrada.

Exemplo de pedido

curl -X POST https://cdrn.fr/api/v1/tools/jwks-inspector/execute \
  -H "Content-Type: application/json" \
  -d '{"jwks":"..."}'

Esquema de entrada

Campo Tipo Obrigatório Predefinição
jwks text –

Pontos de acesso

  • GET https://cdrn.fr/api/v1/tools - lista todas as ferramentas disponíveis
  • GET https://cdrn.fr/api/v1/tools/jwks-inspector - obtém o esquema desta ferramenta
  • POST https://cdrn.fr/api/v1/tools/jwks-inspector/execute - executa esta ferramenta com um payload JSON