Inspekcjonuj JWKS i wyodrębnij klucze publiczne w PEM

Czym jest JWKS?

JWKS (JSON Web Key Set, RFC 7517) to dokument JSON, który gromadzi listę kluczy publicznych w ustrukturyzowanej formie. Służy do publikowania kluczy, których emitent JWT używa do podpisywania swoich tokenów, aby każdy konsument mógł je pobrać i zweryfikować podpis otrzymywanych tokenów. Format zawsze wygląda tak:

{
  "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": "..." }
  ]
}

Każda pozycja tablicy keys to JWK (JSON Web Key), która opisuje klucz publiczny: typ klucza (kty), identyfikator (kid), przewidziane użycie (use), docelowy algorytm (alg) i komponenty kryptograficzne.

Kiedy używać JWKS?

JWKS to kręgosłup nowoczesnych architektur OAuth2 i OpenID Connect. Spotkasz go w kilku kontekstach:

• Odkrywanie OIDC: każdy dostawca OpenID Connect udostępnia dokument konfiguracji pod /.well-known/openid-configuration, który zawiera pole jwks_uri. Pod tym URL znajduje się JWKS z aktywnymi kluczami publicznymi.
• Weryfikacja JWT: gdy twoje API otrzymuje token podpisany w RS256 lub ES256, odczytuje kid nagłówka, pobiera JWKS emitenta, znajduje odpowiedni klucz, wydobywa z niego klucz publiczny w formacie PEM i weryfikuje podpis.
• Rotacja kluczy: emitent może równolegle publikować kilka kluczy, co pozwala wprowadzić nowy klucz do podpisywania nowych tokenów, jednocześnie zachowując stary w służbie do czasu wygaśnięcia tokenów w obiegu.
• Federacje: SAML, SCIM, połączone usługi, publikacja JWKS pozwala uniknąć ręcznej wymiany certyfikatów X.509 między partnerami.

Kluczowe pola JWK

Kilka pól systematycznie pojawia się w JWK. To narzędzie wyodrębnia je i wyświetla dla każdego klucza analizowanego JWKS:

• kid (key ID): unikalny identyfikator klucza. To ta wartość, którą nagłówek JWT umieszcza w swoim polu kid, aby wskazać, który klucz z JWKS powinien być użyty do weryfikacji.
• kty (key type): rodzina kryptograficzna. Dwie dominujące wartości to RSA (klasyczne klucze RSA, używane z RS256, RS384, RS512) i EC (krzywe eliptyczne, używane z ES256, ES384, ES512).
• alg (algorithm): algorytm podpisu, dla którego ten klucz jest przewidziany. Pole opcjonalne, ale często wypełnione. Pozwala szybko filtrować klucze przydatne dla danego JWT.
• use: użycie klucza. sig dla podpisu (zwykły przypadek), enc dla szyfrowania (rzadkie, używane z JWE).

Dlaczego konwertować JWK na PEM?

Większość klasycznych bibliotek kryptograficznych (OpenSSL, openssl_verify w PHP, crypto w Node.js, JCA w Javie) akceptuje klucze publiczne w formacie PEM (Base64 otoczony przez -----BEGIN PUBLIC KEY-----), a nie bezpośrednio w formacie JWK. Konwersja JWK na PEM jest więc niezbędna do:

• Ręcznej weryfikacji podpisu JWT ze skryptu lub narzędzia wiersza poleceń (jwt, jose, step crypto).
• Importu klucza do narzędzia debugującego, takiego jak JWT Verifier, które oczekuje klucza PEM w polu „klucz publiczny".
• Przechowywania klucza w lokalnej pamięci podręcznej lub pliku konfiguracyjnym w uniwersalnej i czytelnej formie.
• Szybkiego porównywania dwóch kluczy (format PEM ułatwia wizualne diffy).

Ograniczenia i ostrzeżenia

• Konwersja odbywa się w jednym kierunku: JWKS na PEM. Odtworzenie JWK z istniejącego klucza PEM nie jest objęte tą wersją.
• JWKS musi być wklejony bez zmian jako tekst JSON. Automatyczne pobieranie z URL jwks_uri lub endpointu OIDC nie jest wykonywane po stronie serwera, aby uniknąć nieprzewidzianych wywołań wychodzących.
• Klucze prywatne nie powinny pojawiać się w publicznym JWKS, a to narzędzie wyodrębnia tylko komponenty publiczne, nawet jeśli klucz prywatny byłby obecny.

Jak korzystać

1. Pobierz JWKS emitenta, którego chcesz zbadać. Dla dostawcy OIDC adres to zazwyczaj https://exemple.com/.well-known/jwks.json lub https://exemple.com/oauth2/jwks.
2. Skopiuj cały dokument JSON (obiekt zawierający klucz keys).
3. Wklej go w polu wprowadzania narzędzia i uruchom analizę.
4. Dla każdego klucza JWKS narzędzie wyświetla jego kid, kty, alg, use i klucz publiczny przekonwertowany na format PEM.
5. Kliknij „kopiuj", aby pobrać PEM i użyć go w skrypcie weryfikacyjnym, naszym JWT Verifier lub dowolnym narzędziu zgodnym z OpenSSL.

Najczęściej zadawane pytania

Przykładowe zapytanie

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

Schemat wejściowy

Punkty końcowe

• GET https://cdrn.fr/api/v1/tools - lista wszystkich dostępnych narzędzi
• GET https://cdrn.fr/api/v1/tools/jwks-inspector - zwraca schemat dla tego narzędzia
• POST https://cdrn.fr/api/v1/tools/jwks-inspector/execute - uruchamia to narzędzie z payloadem JSON