Document toolboxDocument toolbox

Key Rotation

Owned by Jan Åge Lavik
Last updated: 22 Nov 2023Version comment

In OpenID Connect, cryptographic keys published by the OpenID Provider (BankID) are used to ensure the authenticity and integrity of issued JWT tokens, and to encrypt sensitive data from merchant to the provider.

These keys are published in the JWKs endpoint in the JWK format. These keys may change, so make sure you keep them up-to-date (every 24 hours).

Our responsibility 

To make key management as smooth as possible:

  • we will always publish new keys before they are used
  • old keys will be available to verify tokens some time after rotating out
  • have cache-control header in JWKs endpoint with a max-age (seconds) which defines the minimum guaranteed life time of all the keys returned. 
    • Header value example: cache-control: public, max-age=23269, must-revalidate, no-transform

Your responsibility

Always verify the signatures and signing keys of Tokens issued by BankID OIDC.

When handling keys from our JWKs endpoint:

  • Cache all keys returned from jwks_uri and jwks_uri_enc, as several may be in use

  • Refresh keys at intervals, and not on every request, to avoid possible DDOS attacks when key is unknown.
  • Take advantage of the max-age value returned in cache-control header.

When validating tokens or JWTs, find key using a combination of claims kid, alg and use.

When encrypting JWTs, select key to use by kty, use and alg claims.

Rotation of Signing keys

BankID OIDC returns three use=sig keys for each algorithm. New keys will always have a different kid value than previous keys.

  1. the next key,
  2. the currently used key
  3. the previously used key. 

Cache header will have max-age set to time between rotations (minus some minutes).

When rotating, current replaces previous key, next replaces current, a new one will be introduced and the oldest one will be discarded.

Remember, the merchant is responsible to refresh keys regularly.

Rotation of Encryption keys

BankID OIDC will for each algorithm offered, return one use=enc key. New keys will always have different "kid" value than previous keys.

Cache header will have max-age set to time between rotations (minus some minutes).

When rotating, BankID OIDC will remember the old key used until next key rotation, but we will also introduce a new key. The new key will be used as soon as created.