Skip to content

Key Rotation

Insights Hub signs JSON Web Tokens using keys which are regularly updated in accordance with best practices for security. Thus, any application or API that validates access tokens must regularly update the set of public keys it uses for signature validation.

Valid public keys for Insights Hub operator or developer environments are available at: https://{tenant_name}.piam.{region}.{mindsphere_domain}/token_keys. For further details refer to the OAuth Authorization Server documentation.

Key Rotation Processes

It is possible to use both hard and soft key rotation processes. This section describes the stages of each process.

Hard Key Rotation

  1. Initial State
    The token_keys endpoint returns an array of public keys containing only one public key, e.g, a key with key ID (kid) {key_id_1} (value may differ).
    The kid claim in the header of the access token indicates that the key with key ID {key_id_1} was used for signing the token.
    Access tokens must be validated using the key corresponding to key ID {key_id_1}.
  2. New Key is Available and Used
    The token_keys endpoint returns an array of public keys containing two public keys with key IDs {key_id_1} and {key_id_2} (values may differ). The new key is instantly used to sign new tokens.
    The kid claim in the header of the access token indicates that the key with key ID {key_id_2} was used for signing the token.
    Access tokens must be validated using key corresponding to key ID {key_id_2}.
  3. Old Key is Removed
    The token_keys endpoint returns an array of public keys containing only one public key with key ID {key_id_2}.
    The kid claim in the header of the access token indicates that the key with key ID {key_id_2} was used for signing the token.
    Access tokens must be validated using key corresponding to key ID {key_id_2}.

Note

When evaluating the kid claim of the access token, make sure to treat the information as coming from an untrusted source. Applications should sanitize the received value to avoid introducing attack vectors like SQL injection vulnerabilities.

Soft Key Rotation

  1. Initial State
    The token_keys endpoint returns an array of public keys containing only one public key, e.g, a key with key ID (kid) {key_id_1} (value may differ). There might be multiple keys at this stage.
    The kid claim in the header of the access token indicates that the key with key ID {key_id_1} was used for signing the token.
    Access tokens must be validated using key corresponding to key ID {key_id_1}.
  2. New Key is Available
    The token_keys endpoint returns an array of public keys containing two public keys with key IDs {key_id_1} and {key_id_2} (values may differ). The new key is not used to sign new tokens yet.
    The kid claim in the header of the access token indicates that the key at {key_id_1} was used for signing the token.
    Access tokens must be validated using key corresponding to key ID {key_id_1}.
  3. New Key is Used
    The token_keys endpoint returns an array of public keys containing two public keys (as in the line above). The new key is used to sign new tokens.
    The kid claim in the header of the access token indicates that the key at {key_id_2} was used for signing the token.
    Access tokens must be validated using key corresponding to key ID {key_id_2}.
  4. Old Key is Removed
    The token_keys endpoint returns an array of public keys containing only one public key with key ID {key_id_2}.
    The kid claim in the header of the access token indicates that the key at {key_id_2} was used for signing the token.
    Access tokens must be validated using key corresponding to key ID {key_id_2}.

Note

When evaluating the kid claim of the access token, make sure to treat the information as coming from an untrusted source. Applications should sanitize the received value to avoid introducing attack vectors like SQL injection vulnerabilities.

Handling Key Rotation

Hard key rotation and soft key rotation require services to regularly check for new key sets. Soft key rotation admits some transition time, as new key sets are announced before they are used.

Hard and soft key rotations can be handled using the following procedure. Note that you could instead use a library for validating JSON Web Tokens, refer to e.g. https://jwt.io.

  1. Bootstrap the key set for token validation
    Load the initial set of public keys from the token_keys endpoint during start-up.
  2. Dynamically check for new keys during token validation
    Check whether the access token has been signed with a known key ID while validating an access token.
    If the key ID is unknown and the set of public keys has not recently been updated, request an update from the token_keys endpoint. Use the updated key set for token validation thereafter.

Note

The access rate for the token_keys endpoint may be limited in the future.

Trouble Shooting for Handling Key Rotation

This section provides potential workarounds if your application or API does not support the recommended method for key rotation.

Note

Ensure that key_id_1 and key_id_2 are not mixed up during implementation.

Problem Potential Workaround
It (the application or API) does not validate access tokens. None required.
It only downloads the key set during start up. Trigger a restart after a key rotation to get the latest key set.
It loads the public key set from configuration. Update the configuration with the latest key set after a key rotation and activate the configuration, e.g. by re-starting the application.
It uses a hard-coded public key or key set. If the application supports updating/overwriting the key or key set via configuration, refer to the option in the line above.
Otherwise, change and re-validate the implementation.
It downloads the key set, but cannot handle multiple keys provided from the token_keys endpoint. Change and re-validate the implementation.
It cannot handle receiving tokens signed with a newly introduced key (not yet known to the application). If the key set is downloaded from the token_keys endpoint or provided as configuration parameter, see options in the lines above.
Otherwise, change and re-validate the implementation.
It ignores the kid claim when validating the token's signature. Change and re-validate the implementation.

Last update: April 4, 2023

Except where otherwise noted, content on this site is licensed under the Development License Agreement.