Key Rotation in WSO2 Identity server

Signature and Encryption are the two basic methods used in secure transactions. Especially in the case of tokens where most of the OAuth tokens are bearer tokens, we need to focus more on security. Self-signed tokens are comparatively the safest token a party can issue to another. Their security depends on the signature they carry. However, if the key that used to sign the token is compromised, then the token will become insecure. Thus changing keys is important. This commonly known as “key rotation”.

Key rotation helps to make the signing safer and versatile. In this article, I 'll explain the basics of key rotation and how we can perform a key rotation in wso2 Identity server

What is Key Rotation?

Key Rotation is the term used to denote the change of new Keypair for signing and encryption. Whenever we perform a key rotation we must make sure that we keep the old key for a certain period in order to validate our signature for the old tokens which already have been issued.

Why do we need to perform Key Rotation?

The main two reasons for key rotation are

1. Security Concerns: It is recommended to change your keypair four times a year ie quarterly. This is considered a regular rotation. If the key pair is compromised we need to change it immediately and this kind of rotations are considered as Ad-hoc rotations. By rotating the key frequently we prevent it from being compromised and reduce the risk of the compromised key is being used. Rotation also helps us to introduce much stronger keys.
2. Maintenance concerns: Due to government regulations or policies we may have to change the keys eg certain length of keys are not allowed some countries. If the certificates expired we have to rotate those keys.

Other than this nowadays key rotation has become a common practice. It has moved from the status of the selling point to a necessary feature that all should have.

Before performing a key rotation in the Identity server let see the keystore structure in WSO2 IS.

In your identity server, you can have three different keystore like above. Here

1. Primary Keystore → Used in signing and encrypting tokens
2. Secondary Keystore → Used in SSL
3. Internal Keystore → Encrypts internal critical data

The key rotation should be performed mainly in (primary)Keystore. As we are trying to make our tokens more secure this is the keystore we need to concentrate more. This needs more frequent rotations as well as ad-hoc rotation even if we had a slight suspicion.

Then we can perform a key rotation in secondary keystore which is taking part in SSL handshakes. We don’t need a regular rotation here but if there is suspicion we need to perform the key rotation immediately. Otherwise, all our transactions can be monitored and manipulated by malicious groups.

It is not recommended to perform a key rotation in internal keystore. This key is used to encrypt almost all the internal critical data. Thus rotating this without proper guidance will lead to undecryptable data as well as loss in some functionalities. Even with proper guidance, we have to have a larger effort to shift all the data to the new key version.

Prepare for Key Rotation

The key rotation of super tenant has become possible in IS 5.7 and upper versions. In IS5.7 a feature is introduced via an update(WSO2-CARBON-UPDATE-4.4.0–4563) which facilitates this rotation.

However, before beginning the key rotation we need to apply another update(WSO2-CARBON-UPDATE-4.4.0–4656) which re-encrypts secondary userstore password using internal keystore from primary keystore. This update does the following change

It changes the secondary user store password encryption to use internal keystore. Ideally, internal keystore should be used for encryption of internal critical data. Currently, the secondary user store passwords are encrypted using primary/external keystore which is used to sign and encrypt tokens. Thus it is preferable to switch from keystore to internal keystore for encrypting the secondary userstore password.

Otherwise, after performing a key rotation secondary user store will become inaccessible. This change is only needed in IS 5.7 and IS 5.8 future version will do them correctly.

Steps to perform key rotation

Key rotations in the super tenant is a simple process. We can perform a key rotation in three steps.

• Add the new (RSA) key pair into the keystore

Go to {is-product}/repository/resources/security and there you will find the wso2carbon.jks(this is the default wso2 keystore name if you have changed the keystore then select that keystore. The default keystore password is “wso2 carbon”

Following key-tool command will help you to add a new (RSA)key pair.

keytool -genkey -alias newKey -keyalg RSA -keysize 2048 -keystore wso2carbon.jks -storepass wso2carbon -keyalg RSA -dname “CN=localhost, O=WSO2, L=colombo, ST=west, C=LK”

• Change the primary keystore config in “carbon.xml “ with the alias and password of the new key

We can find the “carbon.xml” in {is-product}/repository/conf/carbon.xml. There Change the keyAlias in “Security/KeyStore” XPath to the new alias

• Now restart the IS server

Now all the token issue will be signed by the new key. We can see this new key through the management console under keystore. Please see [1] to know more about how to check this new key and JWKS endpoint

Concerns in Key rotation

• It is recommended to have 3 different keystores in WSO2 IS server. This will have less complication when we perform key rotation.
• If you don’t have separate keystore for internal keystore and primary keystore in the super tenant. We can still perform the key rotation but in “carbon.xml” we need to point the old key for internal keystore.

eg config will look like this:

here we point to the same keystore but as KeyAlias we have given the old key alias

• Currently, performing key rotation in tenants are not recommended as there is no separation of internal keystore from primary keystore in tenants.
• We need to keep the old key in the .jks keystore file and list all the keys (both old and new) at the JWKS endpoint, for a period of time, until we can delete the old key. Because there are JWT tokens issued to clients using the old signing key, and until those tokens expire, the clients can use them to make service/resource requests and the resource server/ service providers will need the OLD public key for JWT validation.
• Currently, we can only do key rotation for RSA based keypairs.

References:

[1]https://medium.com/@inthiraj1994/adding-multiple-keys-to-wso2-keystores-741ee0a699ea