Key Rotation¶

Insights Hub signs JSON Web Tokens using keys that are regularly updated based on the 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.

You can find the valid public keys for Insights Hub operator or developer environments at: https://{tenant_name}.piam.{region}.{mindsphere_domain}/token_keys. For more information, refer to the OAuth Authorization Server documentation.

Key Rotation Processes¶

This section describes the key rotation process, which serves as a security practice that involves replacing the cryptographic keys used for signing access tokens to minimize the risk of key compromise. There are two main types of key rotation processes: hard key rotation and soft key rotation.

Hard Key Rotation¶

Hard key rotation is a process where the old key is replaced with a new key instantly. The stages of hard key rotation are as follows:

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 access token header 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 access token header indicates that the key with key ID {key_id_2} was used for signing the token.
   Access tokens must be validated using the 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 access token header indicates that the key with key ID {key_id_2} was used for signing the token.
   Access tokens must be validated using the key corresponding to key ID {key_id_2}.

Soft Key Rotation¶

Soft key rotation is a process where the new key is introduced gradually before replacing the old key. The stages of soft key rotation are as follows:

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 may be multiple keys at this stage.
   The kid claim in the access token header 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
   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 access token header indicates that the key at {key_id_1} was used for signing the token.
   Access tokens must be validated using the 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 access token header indicates that the key at {key_id_2} was used for signing the token.
   Access tokens must be validated using the 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 access token header indicates that the key at {key_id_2} was used for signing the token.
   Access tokens must be validated using the key corresponding to key ID {key_id_2}.

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:

Recommended Procedures without Downtime¶

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.

Trouble Shooting for Handling Key Rotation¶

This section provides potential workarounds if your application or API does not support the recommended key rotation methods. These workarounds help maintain security and ensure a smooth key rotation process.

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