Introduction
In the previous blog, we learned how to use custom token-based SSO. In a custom token-based SSO integration, the external application generates an encrypted token containing user details such as username, organization, roles, and profile attributes. Helical Insight decrypts and validates this token to establish the user’s session.
Both applications must use the same encryption key, which should be treated as a sensitive secret and stored securely.
Key rotation is the process of replacing an existing encryption key with a new one periodically or whenever a security risk arises. Starting with Helical Insight version 7.0.1.278 RC1, the SSO encryption key can be configured independently using the sso.cipherKey property in the project.properties file.
This allows administrators to change the encryption key without affecting existing user records. Ensure that the new key is updated in both Helical Insight and all external applications generating SSO tokens. Also, plan the transition carefully, as tokens encrypted with the previous key may no longer work after the change.
Operational Consideration: The new key must be coordinated across Helical Insight and every application or service that generates SSO tokens. During the changeover, ensure both sides are updated in a controlled manner and that new tokens are generated with the new key. Tokens encrypted with the previous key may no longer be decryptable after the change, so plan the rollout around active integrations and token lifetimes.
1. SSO Encryption Key Rotation
In earlier versions, rotation of the SSO encryption key was not supported due to dependencies in the existing implementation.
Starting from Helical Insight version 7.0.1.278 RC1, the SSO encryption key is configured separately using the following property:
sso.cipherKey
This allows the SSO encryption key to be changed without affecting existing Helical Insight users.
2. Steps to Rotate the SSO Encryption Key
Follow these steps to update the SSO encryption key:
-
Step 1: Open the Configuration File
Navigate to the following location:
...../hi-ee/WEB-INF/classes/project.properties -
Step 2: Locate the Property
Open the project.properties file and find the following property:
sso.cipherKey -
Step 3: Update the Key
Set sso.cipherKey to your new 16-character encryption key.
Example:
sso.cipherKey=1234567890ABCDEF -
Step 4: Save the File
Save the changes made to the project.properties file.
-
Step 5: Restart Helical Insight
Restart the Helical Insight application for the new encryption key to take effect.
-
Step 6: Update the Token Generator
Update your SSO token-generating application with the same new encryption key. Both Helical Insight and the token-generating application must use the same key.
3. Important Note
Existing Helical Insight users do not need to be recreated or modified. The key rotation only applies to the SSO token encryption and decryption mechanism. Existing users remain unchanged.
4. Summary
The following table summarizes the important configuration details for SSO encryption key rotation in Helical Insight:
| Configuration | Details |
|---|---|
| Helical Insight Version | 7.0.1.278 RC1 |
| Configuration Property | sso.cipherKey |
| Key Length | 16 characters |
| Application Restart | Required |
| Token Generator Update | Use the same new encryption key |
| Existing Users | No changes required |
