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}.

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}.

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.

Recommended Procedure 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 method for key rotation.

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