# Ondertekeningssleutels

De sleutels die OIDC- en SAML-tokens ondertekenen bekijken, roteren en intrekken, en begrijpen waarom rotatie belangrijk is voor aangesloten applicaties.

Het platform ondertekent de tokens die het uitgeeft, dus OIDC ID-tokens en access tokens plus OAuth-/OIDC-assertions, met een private ondertekeningssleutel. Aangesloten applicaties controleren die handtekeningen tegen de bijbehorende publieke sleutel, die het platform publiceert op zijn JWKS-endpoint (`/.well-known/jwks`). Op het tabblad **Ondertekeningssleutels** kunt u deze sleutels inspecteren, roteren en intrekken.

[Image: Het tabblad Ondertekeningssleutels in de systeeminstellingen]

## Levenscyclus van een sleutel

Volg een token: bij de uitgifte wordt het met de huidige sleutel ondertekend en draagt het de identificatie van die sleutel (`kid`) in de header. De applicatie leest de `kid`, zoekt de sleutel op in de gepubliceerde sleutelset en controleert de handtekening. De sleutelset bevat maximaal drie sleutels: de sleutel die als volgende gaat ondertekenen, de sleutel die nu ondertekent en de sleutel die tot de laatste rotatie ondertekende. Zolang een sleutel in de set staat, zijn tokens met die `kid` te verifiëren; een ingetrokken sleutel verlaat de set en zijn tokens mislukken vanaf dat moment.

Het tabblad **Ondertekeningssleutels** toont deze drie sleutels met hun status:

| Status | Rol |
|---|---|
| **Next** | Wordt vooraf gepubliceerd, zodat applicaties hem al kennen wanneer hij begint te ondertekenen. |
| **Current** | Ondertekent elk token dat nu wordt uitgegeven. |
| **Previous** | Ondertekende tot de laatste rotatie. Staat nog in de sleutelset, zodat tokens met die `kid` te verifiëren blijven totdat u hem intrekt. |

Elke sleutel wordt geïdentificeerd door een **Sleutel-ID** (kid), waarmee applicaties bij het controleren van een token de juiste publieke sleutel kiezen. Een badge naast de sleutel-ID toont de sleutellengte in bits. Nieuw gegenereerde sleutels zijn RSA met 3072 bits; oudere sleutels van 2048 bits blijven geldig voor verificatie en worden bij elke rotatie door de sterkere lengte vervangen.

## Een sleutel bekijken en exporteren

Voor elke sleutel in de lijst opent u het actiemenu om:

- het ondertekeningscertificaat met **Copy** naar het klembord te kopiëren,
- de certificaatgegevens met **View** te bekijken,
- het certificaat met **Download** als `.pem`-bestand te downloaden.

Dat is nuttig wanneer een applicatie het certificaat handmatig geconfigureerd nodig heeft in plaats van het op te halen bij het JWKS-endpoint.

## Waarom rotatie belangrijk is

Ondertekeningssleutels regelmatig roteren beperkt de schade als een sleutel ooit gecompromitteerd raakt, en is een gangbare compliance-eis. Hoeveel werk een rotatie kost, hangt ervan af hoe elke applicatie de sleutel heeft gekregen:

- Een SAML- of WS-Federation-Service Provider die één vastgelegd certificaat vertrouwt, moet het certificaat van de **Next**-sleutel krijgen *voordat* u roteert, anders mislukt zijn handtekeningcontrole na de wijziging.
- Een OIDC-applicatie met een handmatig geconfigureerde sleutel vraagt dezelfde voorbereiding.
- Een applicatie die de sleutelset bij het JWKS-endpoint ophaalt, neemt de nieuwe sleutel zelf over, omdat het endpoint de volgende, de huidige en de vorige publieke sleutel publiceert. Voor die applicaties **verloopt de rotatie zonder downtime**.

> **Opmerking:** De rotatie raakt OIDC- en OAuth-applicaties. Na een rotatie kan het tot ongeveer 30 seconden duren voordat de wijziging volledig van kracht is.

## Roteren en intrekken

De acties staan onder **Destructieve acties** onderaan de pagina. Elke actie vraagt om een bevestiging.

| Actie | Wat er gebeurt | Effect op bestaande tokens |
|---|---|---|
| **Rotate key** | De *Next*-sleutel wordt *Current*; de tot dan toe huidige sleutel wordt *Previous*. Bestond er al een Previous-sleutel, dan wordt die ingetrokken en gaat hij naar de intrekkingslijst. | Al uitgegeven tokens blijven te verifiëren; de Previous-sleutel **blijft in de sleutelset**. |
| **Rotate & revoke key** | Roteert zoals hierboven en trekt de Previous-sleutel meteen in. | Tokens met de `kid` van de Previous-sleutel **zijn niet meer te verifiëren**. |
| **Revoke key** | Trekt de *Previous*-sleutel in zonder te roteren. | Tokens met de `kid` van die sleutel **zijn niet meer te verifiëren**. |

De drie meest recente intrekkingen blijven met hun datum vermeld, voor auditdoeleinden.

### Aanbevolen volgorde

1. Zorg dat elke applicatie die een certificaat handmatig vastlegt de **Next**-sleutel vertrouwt.
2. Gebruik **Rotate key**. Nieuwe tokens worden nu met de nieuwe sleutel ondertekend; oudere tokens blijven geldig.
3. Zodra u er zeker van bent dat geen enkele applicatie nog op de Previous-sleutel steunt, **trekt** u die in.

Gebruik **Rotate & revoke key** alleen wanneer eerder uitgegeven tokens onmiddellijk ongeldig moeten worden, bijvoorbeeld na een vermoedelijke sleutelcompromittering.

> **Let op:** Het intrekken van een sleutel waarop applicaties nog steunen breekt hun tokencontrole. Roteer eerst, stel vast dat de applicaties zijn overgestapt en trek de sleutel pas daarna in.

## Centrale sleutels versus een ondertekeningscertificaat per applicatie

Ondertekeningssleutels duiken op twee plaatsen op, en ze zijn niet hetzelfde:

- **De centrale ondertekeningssleutels op deze pagina** ondertekenen elk OIDC ID-token en access token dat het platform uitgeeft, en standaard ook de SAML-/WS-Federation-Assertions die het aanmaakt. Een rotatie hier raakt alle applicaties die de gepubliceerde sleutels van het platform vertrouwen.
- **Een ondertekeningscertificaat per applicatie** kan in plaats daarvan op een afzonderlijke SAML- of WS-Federation-applicatie worden geconfigureerd, wanneer die Service Provider één specifiek certificaat moet vertrouwen in plaats van de centrale sleutel van het platform.

Meldt een Service Provider een handtekeningfout, stel dan eerst vast welke sleutel hij vertrouwt: de centrale sleutel die op het JWKS-endpoint wordt gepubliceerd, of een certificaat dat op precies die ene applicatie is vastgelegd. Waar de credentials van een applicatie worden ingesteld, leest u in [Integraties → Applicaties](https://dts-identity.com/nl/docs/integrations/applications.md).
