Tokeny sieciowe JSON (JWT)

Tink obsługuje generowanie i weryfikowanie tokenów JWT, które są powszechnie stosowanym standardem w internecie. Implementacja tokena JWT w Tink zapewnia podzbiór standardu JWT zdefiniowanego w RFC 7519, który zespół Tink uważa za bezpieczny w użyciu i który dobrze pasuje do biblioteki Tink.

Tink nie obsługuje części standardu, które są rzadko używane lub trudne do prawidłowego zastosowania. Ograniczenia są następujące:

• Tink obsługuje tylko format JWS Compact Serialization. JWS JSON Serialization i JWE nie są obsługiwane.
• Usługa Tink nie obsługuje wartości None w nagłówku alg.
• Tink obsługuje tylko nagłówki typ, alg i kid. Pozostałe nagłówki nie są obsługiwane.
• Tink nie zezwala na analizowanie tokenów przed zweryfikowaniem podpisu lub kodu MAC.

Podpisy JWT

Jeśli tokeny są generowane i weryfikowane przez różne podmioty, użyj kluczy asymetrycznych z funkcjami JwtPublicKeySign i JwtPublicKeyVerify. Klucz prywatny służy do generowania tokenów, a klucz publiczny – do ich weryfikacji. Algorytmy obsługiwane przez te elementy pierwotne to: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384 i PS512.

Wybierz typ klucza

Podpisy JWT używają innych typów kluczy niż zwykłe podpisy cyfrowe w Tink. Jest to konieczne, ponieważ niektóre metadane (np. alg i kid) muszą być przechowywane z kluczem.

W większości przypadków zalecamy używanie JWT_ES256. Tokeny wygenerowane za pomocą tego typu klucza zawsze mają nagłówek kid. Jeśli wolisz nieco krótsze tokeny bez nagłówka kid, wybierz typ klucza JWT_ES256_RAW. Listę wszystkich obsługiwanych typów kluczy znajdziesz w sekcji Obsługiwane typy kluczy.

Dystrybucja publicznego zbioru kluczy

Tink umożliwia konwertowanie publicznych zestawów kluczy do formatu zestawów JWK zdefiniowanego w dokumencie RFC 7517 i z tego formatu, który jest obsługiwany przez większość bibliotek JWT.

Uwaga: format serializacji zestawu kluczy JSON Tink nie jest zestawem JWK i inne biblioteki prawdopodobnie nie będą w stanie go odczytać.

Tink nie obsługuje eksportowania publicznych kluczy JWT w żadnym innym formacie. Wynika to z faktu, że inne formaty nie zawierają metadanych alg i kid, które są używane w procesie weryfikacji. Z tego powodu korzystanie z nich jest bardziej podatne na błędy i może utrudniać rotację kluczy.

Zalecamy nie tylko jednorazowe udostępnienie zestawu kluczy publicznych, ale też zapewnienie możliwości automatycznej aktualizacji tego zestawu. (W przeciwnym razie rotacja do nowego klucza jest bardzo trudna). Często odbywa się to przez opublikowanie publicznego zestawu kluczy pod zaufanym i bezpiecznym adresem URL. Serwer, który weryfikuje tokeny, musi okresowo ponownie pobierać zestaw kluczy publicznych z tego adresu URL, np. raz dziennie. Aby zmienić klucz, nowy klucz publiczny musi zostać dodany do zbioru kluczy publicznych co najmniej dzień przed użyciem go do podpisywania tokenów. W przeciwnym razie nowe tokeny podpisane nowym kluczem prywatnym będą odrzucane przez serwery, które nadal używają starego zestawu kluczy publicznych.

Uwaga: niektóre implementacje ponownie pobierają klucz publiczny, gdy tylko otrzymają token z nieznanym nagłówkiem kid. W Tink nie można zaimplementować tej logiki, ponieważ token nie jest analizowany przed weryfikacją. Nie zalecamy tego, ponieważ może to spowodować wiele dodatkowych żądań do adresu URL zestawu kluczy, jeśli zostaną wysłane złośliwe tokeny z losowymi nagłówkami kid.

JWT MAC

Tink obsługuje też tokeny JWT z kluczami symetrycznymi z obiektem podstawowym JwtMac. Używaj tego typu tylko wtedy, gdy tokeny są generowane i weryfikowane przez ten sam podmiot. Algorytmy obsługiwane przez ten element to HS256, HS384 i HS512.

Wybierz typ klucza

Typy kluczy MAC JWT różnią się od zwykłych typów kluczy MAC. W większości przypadków zalecamy używanie JWT_HS256.

Przykłady użycia

Więcej informacji znajdziesz w sekcji Chcę tworzyć i weryfikować tokeny JWT.