How To: Change the CloudEntity Signing Certificate Algorithm

Version Affected: All

 

Overview

This article explains how to change the signing certificate algorithm for a SecureAuth CloudEntity Workspace's OAuth tokens, choosing between RSA and Elliptic Curve Digital Signature Algorithm (ECDSA).

The algorithm is set for the whole workspace by the type of its signing key, not for each client: every client in the workspace receives tokens signed with the current key's algorithm, such as ES256 for an ECDSA key or RS256 for an RSA key. A workspace cannot sign tokens with RSA for some clients and ECDSA for others. If one application needs a different algorithm from the rest, create a separate workspace with the other key type for that application.

Change the Signing Certificate Algorithm

1. Sign in to CloudEntity and, in the correct Workspace, go to OAuth > Tokens > Signing and Encryption.
2. Scroll down to Signing key rotation settings.
3. Under Manual key rotation, select Rotate key.

   

   Once you confirm the rotation, the current signing key is replaced by the next key in queue, and a new key with the algorithm you select becomes the next key in queue. Any Service Provider still using the previous signing key's public key will need to be updated.

4. In the Rotate Signing Keys dialog, under Select the token signing algorithm type, choose RSA or ECDSA for the new key.
5. Select Rotate keys to confirm.

   

6. To start signing tokens with the new algorithm, select Rotate key again, or wait for the next automatic rotation. The first rotation only places the new key in the queue, so until it becomes the Current key in use, the workspace still signs with the old algorithm.

The key that was previously Next key in queue becomes the Current key in use, and the newly created key, with the algorithm you selected, becomes the new Next key in queue.

For more information, see the SecureAuth Manage signing keys documentation.

Update Each Client to the New Algorithm

Once the new key is the current key, change every client whose ID token or JARM (JWT Secured Authorization Response Mode) signing algorithm is still set to the old algorithm. Until a client is changed, the application that receives its tokens rejects them, for example with Signed JWT rejected: Another algorithm expected, or no matching key(s) found.

SecureAuth CIAM only accepts a client algorithm that matches the workspace's current key. Saving a client that is set to the other algorithm, or promoting configuration that contains one into a workspace with the other key type, fails with an error such as:

OAuth client wants to use RS256 as id token signed response algorithm but server allows only ES256

If you see this error after rotating, check that the new key is the Current key in use, as described in step 6.

1. Go to Applications, open the client, and open its OAuth tab.
2. Set the ID Token Signing Algorithm to the new algorithm, for example RS256.
3. If the client shows a JARM Signing Algorithm, set it to the new algorithm as well.
4. Click Save, and confirm that the application accepts tokens from the client.

How Automatic Rotation Behaves

• Automatic rotation keeps the key type you last selected, so it does not change the algorithm back.
• The rotation schedule runs in Coordinated Universal Time (UTC). For example, 30 17 2 * * rotates the key at 17:30 UTC on the 2nd day of each month, not at 17:30 local time.
• The next key is published in the workspace's JSON Web Key Set (JWKS) as soon as it is placed in the queue, so applications that cache the JWKS can load the new key before it is used to sign tokens.
• Applications should fetch the JWKS again whenever they receive a token whose key ID (kid) is not in their cached copy, because SecureAuth can rotate a key at any time, for example if the key is compromised.

Special Considerations

• Rotating a signing key cannot be undone. Confirm that every Service Provider using the current signing key's public key is ready to pick up the new key before you rotate, since tokens signed with a revoked key will no longer validate.
• Services that verify tokens against a cached copy of the JWKS, such as an API gateway authorizer, can keep accepting tokens signed with a revoked key until their cache is refreshed or the tokens expire.
• Importing or promoting configuration that contains the workspace's signing keys, for example through configuration as code, replaces the active signing key. Leave the keys out of the configuration unless you intend to replace them.

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.