Using Multiple keys in WSO2 Keystores

Keystore is a repository where private keys, certificates and symmetric keys can be stored. Ideally, a keystore should accommodate more keypairs and certificates but due to some complications earlier it was not possible to have multiple keys in WSO2 identity server. But now it is possible and we are going to see how we can add them.

Identity server can have the following keystores:

1. Primary Keystore → Used in signing and encrypting tokens
2. Secondary Keystore → Used in SSL
3. Internal Keystore → Encrypts internal critical data
4. Tenant wise keystore → Each tenant has keystore that acts primary and internal keystore for that tenant

In accordance with their use cases, it is not recommended to have multiple keys inside an internal keystore. Primary keystore is perfect for having more keys.

In this article, we will see how we can add multiple keys to primary keystore in super tenant and keystore in the tenant.

Add a new key to Primary Keystore

Follow the below steps to add a new key

1. 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 that keystore then select the new keystore).

Note: If you want to create new keystore as primary keystore then use the following command

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

This creates a keystore with name newWso2carbon and adds a key with alias “testKey”.

We can see the details of the newly created key by executing the following command

keytool -list -v -keystore newWso2carbon.jks -storepass wso2carbon

2. Add the new key into that same jks. Important please use the same password for all the keys in the keystore. This password can be different from the store password. The default password for wso2carbon.jks is “wos2carbon” and default key password used is also “wso2carbon”

Create a key with alias “newKey” and that to the keystore.

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”

use the view list command to see the entries in the keystore

keytool -list -v -keystore wso2carbon.jks -storepass wso2carbon

3. In order to make that key as the primary encrypting and signing key go to {is-product}/repository/conf/carbon.xml

4. Change the keyAlias in “Security/KeyStore” XPath to the new alias

5. Now restart the server to apply the changes.

6. Log in to the management console and go to Home → Manage → Keystores → List.

Click the view button in your keystore

The new key will be added under “Certificate of the Private Key” with its details.

Important:

• If we are going to add multiple keys and delete those key in future, it is better to keep a separate keystore for internal and external encryption. In default pack, we don’t have separation for internal and external keystore.
• Please use the single password for all the keys. This password can be different from the store password. Please add that password in carbon.xml

Add multiple keys to tenant keystore

Unlike Super tenant, we cannot directly access the tenant keystore as it in the registry. Hence whenever we want to add a new key, we have to replace the old keystore with new keystore. Since each tenant has its own keystore for better management.

Warning: Adding multiple keys to already existing tenants have some complications. So it is better to use this feature on newly created tenants.

All the keystore names are bound to their tenant name.

• Make sure that new keystore has name as “<tenant-name without .com>-com.jks”

Eg for tenant 123.com keystore is 123-com.jks

• Please add the primary key with the alias of <tenant-name> and {Important} please use the same password for all the keys in the keystore. This password can be different from store password.

Eg for tenant 123.com alias is 123.com

Follow the steps to add multiple keys to tenant keystore

1. Login into the management console.
2. Download the old keystore from Registry. To do that

a. Go to /_system/governance/repository/security/key-stores location using registry browser in the management console

b. All the keystores added to the tenant can be viewed here. (Click the Actions button then) Download the correct keystore {the keystore with the name as <tenant-name without .com>-com.jks } eg: here 123-com.jks

c. Then delete that keystore.

Note: Currently it is not possible to extract the keys from old keystore as we cannot know the keystore password(This is only true for the first time → to the keystore that is created by idenity server). The key store password for tenants are auto-generated and stored in a hash form. Without key manager in wso2 identity server, it is not possible to access it. Although there is no direct method to extract the key we downloaded the old keystore for safekeeping or to use indirect methods.

3. Now create new keystore to be added in the place of old keystore with proper naming.

If you have already replaced the default keystore created for this tenant then extract you old keys add them to this new keystore with different alias or change the alias of the old key to something and add the new key to the old keystore

Warning: if it is not created with correct naming all the normal process will get stuck. eg here we need to create keystore like this

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

Here the alias is “123.com” and keystore name is “123-com.jks”.

4. Click Home → Manage → keystores → add and upload your new keystore

After giving proper details (Location& keystore password)click next

Then type the key password and click finish.

If the credentials are given properly in Home → Manage → Keystores you can see your keystore

and when clicking view, all the key entries will be shown properly

Important:

• Tenant keystore should in the name of <tenant-name without .com>-com.jks and it should contain the primary alias as <tenant-name>.
• Use the same password for all the keys in the keystore. This password can be different from the store password.

Using JWKS endpoint to see the added multiple keys

• For super tenant go to https://<is-server-url>/oauth2/jwks
• For tenant go to https://<is-server-url>/t/<tenant-name>/oauth2/jwks Eg: for foo.com : https://localhost:9443/t/foo.com/oauth2/jwks

Before adding a new key JWKS endpoint will have only two entries in the default pack. One entry with normal “kid” and one with “algo” appended to“kid” → kid_algo

After adding a new key this keyset will become doubled.

Adding multiple keys is a basic feature in any keystore and will help in different situations like key rotation. This capability will allow us to get the full benefit of having a keystore.