Key Rotation¶
MindSphere 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 MindSphere operator or developer tenants 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¶
MindSphere may use both hard and soft key rotation processes. This section describes the stages of each process.
Hard Key Rotation¶
- Initial State
Thetoken_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).
Thekid
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}
. - New Key is Available and Used
Thetoken_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.
Thekid
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}
. - Old Key is Removed
Thetoken_keys
endpoint returns an array of public keys containing only one public key with key ID{key_id_2}
.
Thekid
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¶
- Initial State
Thetoken_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.
Thekid
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}
. - New Key is Available
Thetoken_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.
Thekid
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}
. - New Key is Used
Thetoken_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.
Thekid
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}
. - Old Key is Removed
Thetoken_keys
endpoint returns an array of public keys containing only one public key with key ID{key_id_2}
.
Thekid
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.
Recommended Procedure without Downtime¶
- Bootstrap the key set for token validation
Load the initial set of public keys from thetoken_keys
endpoint during start-up. - 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 thetoken_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. |
Any questions left?
Except where otherwise noted, content on this site is licensed under the Development License Agreement.