# 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ć.

[Image: 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:

| Status | Rola |
|---|---|
| **Następny w kolejce** | Publikowany z wyprzedzeniem, aby aplikacje znały go już wtedy, gdy zaczyna podpisywać. |
| **Obecnie używany** | Podpisuje każdy token wystawiany teraz. |
| **Poprzednio używany** | Podpisywał 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.

| Akcja | Co się dzieje | Wpływ na istniejące tokeny |
|---|---|---|
| **Rotate key** | Klucz *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 key** | Rotuje jak wyżej i natychmiast unieważnia poprzedni klucz. | Tokeny z `kid` poprzedniego klucza **przestają przechodzić weryfikację**. |
| **Revoke key** | Unieważ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](https://dts-identity.com/pl/docs/integrations/applications.md).
