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.

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
- Zorg dat elke applicatie die een certificaat handmatig vastlegt de Next-sleutel vertrouwt.
- Gebruik Rotate key. Nieuwe tokens worden nu met de nieuwe sleutel ondertekend; oudere tokens blijven geldig.
- 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.