Skip to Content

Klucze podpisywania

Przeglądaj, rotuj i unieważniaj klucze podpisujące tokeny OIDC i SAML oraz poznaj znaczenie rotacji dla podłączonych aplikacji.

Platforma podpisuje wystawiane przez siebie tokeny, czyli tokeny ID i tokeny dostępu OIDC oraz asercje OAuth/OIDC, prywatnym kluczem podpisywania. Podłączone aplikacje weryfikują te podpisy względem pasującego klucza publicznego, który platforma publikuje w swoim punkcie końcowym JWKS (/.well-known/jwks). Karta Klucze podpisywania pozwala te klucze przeglądać, rotować i unieważniać.

Karta Klucze podpisywania w ustawieniach systemowych

Cykl życia klucza

Prześledź drogę tokenu: przy wystawieniu jest podpisywany kluczem bieżącym i nosi w nagłówku identyfikator tego klucza (kid). Aplikacja odczytuje kid, wyszukuje klucz w opublikowanym zestawie kluczy i weryfikuje podpis. Zestaw kluczy zawiera najwyżej trzy klucze: ten, który będzie podpisywał jako następny, ten, który podpisuje teraz, oraz ten, który podpisywał do ostatniej rotacji. Dopóki klucz znajduje się w zestawie, tokeny z jego kid przechodzą weryfikację; klucz unieważniony opuszcza zestaw, a jego tokeny od tej chwili jej nie przechodzą.

Karta Klucze podpisywania pokazuje te trzy klucze wraz z ich statusem:

StatusRola
Następny w kolejcePublikowany z wyprzedzeniem, aby aplikacje znały go już wtedy, gdy zaczyna podpisywać.
Obecnie używanyPodpisuje każdy token wystawiany teraz.
Poprzednio używanyPodpisywał do ostatniej rotacji. Nadal jest w zestawie kluczy, więc tokeny z jego kid przechodzą weryfikację, dopóki go nie unieważnisz.

Każdy klucz jest identyfikowany przez Identyfikator klucza (kid), po którym aplikacje wybierają właściwy klucz publiczny przy weryfikacji tokenu. Odznaka obok identyfikatora klucza pokazuje długość klucza w bitach. Nowo generowane klucze to RSA 3072-bitowe; starsze klucze 2048-bitowe pozostają ważne do weryfikacji i wraz z kolejnymi rotacjami są zastępowane mocniejszą długością.

Przeglądanie i eksportowanie klucza

Dla dowolnego klucza z listy otwórz menu akcji, aby:

  • Skopiuj certyfikat podpisywania, aby skopiować certyfikat podpisywania do schowka.
  • Pokaż certyfikat podpisywania, aby wyświetlić szczegóły certyfikatu.
  • Pobierz certyfikat podpisywania, aby pobrać certyfikat jako plik .pem.

Przydaje się to wtedy, gdy aplikacja potrzebuje certyfikatu skonfigurowanego ręcznie, a nie pobieranego z punktu końcowego JWKS.

Dlaczego rotacja ma znaczenie

Regularna rotacja kluczy podpisywania ogranicza szkody, gdyby klucz kiedykolwiek został skompromitowany, i jest częstym wymaganiem zgodności. Ile pracy kosztuje rotacja, zależy od tego, w jaki sposób dana aplikacja poznała klucz:

  • Service Providerowi SAML albo WS-Federation, który ufa jednemu przypiętemu certyfikatowi, trzeba przekazać certyfikat klucza Następny w kolejce przed rotacją; w przeciwnym razie jego weryfikacja podpisu po zmianie się nie powiedzie.
  • Aplikacja OIDC z ręcznie skonfigurowanym kluczem wymaga takiego samego przygotowania.
  • Aplikacja pobierająca zestaw kluczy z punktu końcowego JWKS przejmuje nowy klucz sama, ponieważ punkt końcowy publikuje klucz publiczny następny, bieżący i poprzedni. Dla tych aplikacji rotacja odbywa się bez przestoju.

Uwaga: Rotacja dotyczy aplikacji OIDC i OAuth. Po rotacji może upłynąć około 30 sekund, zanim zmiana zacznie w pełni obowiązywać.

Rotacja i unieważnianie

Akcje znajdziesz w sekcji Działania destrukcyjne na dole strony. Każda z nich wymaga potwierdzenia.

AkcjaCo się dziejeWpływ na istniejące tokeny
Rotate keyKlucz Następny w kolejce staje się Obecnie używany; dotychczasowy bieżący klucz staje się Poprzednio używany. Jeśli poprzedni klucz już istniał, zostaje unieważniony i przechodzi na listę unieważnień.Weryfikacja już wystawionych tokenów trwa dalej; poprzedni klucz pozostaje w zestawie kluczy.
Rotate & revoke keyRotuje jak wyżej i natychmiast unieważnia poprzedni klucz.Tokeny z kid poprzedniego klucza przestają przechodzić weryfikację.
Revoke keyUnieważnia klucz Poprzednio używany bez rotacji.Tokeny z kid tego klucza przestają przechodzić weryfikację.

Trzy najnowsze unieważnienia pozostają na liście wraz z datą, na potrzeby audytu.

Zalecana kolejność

  1. Upewnij się, że każda aplikacja z ręcznie przypiętym certyfikatem uznaje za zaufany klucz Następny w kolejce.
  2. Użyj Rotate key. Nowe tokeny są teraz podpisywane nowym kluczem; starsze tokeny pozostają ważne.
  3. Gdy masz pewność, że żadna aplikacja nie polega już na poprzednim kluczu, unieważnij go.

Z Rotate & revoke key korzystaj tylko wtedy, gdy wcześniej wystawione tokeny muszą natychmiast stracić ważność, na przykład po podejrzeniu kompromitacji klucza.

Ostrożnie: Unieważnienie klucza, na którym aplikacje wciąż polegają, zepsuje ich weryfikację tokenów. Najpierw przeprowadź rotację, potwierdź, że aplikacje się przestawiły, i dopiero potem unieważniaj.

Klucze centralne a certyfikat podpisywania dla pojedynczej aplikacji

Klucze podpisywania pojawiają się w dwóch miejscach i nie są tym samym:

  • Centralne klucze podpisywania z tej strony podpisują każdy token ID i token dostępu OIDC wystawiany przez platformę oraz, domyślnie, tworzone przez nią Assertions SAML/WS-Federation. Rotacja tutaj dotyczy wszystkich aplikacji, które ufają publikowanym kluczom platformy.
  • Certyfikat podpisywania dla pojedynczej aplikacji można zamiast tego skonfigurować na konkretnej aplikacji SAML albo WS-Federation, gdy dany Service Provider oczekuje zaufania jednemu określonemu certyfikatowi, a nie centralnemu kluczowi platformy.

Jeśli Service Provider zgłasza błąd podpisu, najpierw ustal, któremu kluczowi ma ufać: centralnemu kluczowi publikowanemu w punkcie końcowym JWKS czy certyfikatowi przypiętemu do tej jednej aplikacji. To, gdzie ustawia się poświadczenia aplikacji, opisuje strona Integracje → Aplikacje.

Na tej stronie