Rotate Keys #

While the Pragma Platform is running, you can change the keys used for token signing and verification without disrupting a user’s existing sessions or forcing them to re-authenticate.

To rotate keys update the TokenConfig under both game and social as follows:

1. Replace the jwtCurrentKeys values with the new RSA key pair.
2. Add jwtRotatedPublicKeys.
3. Under jwtRotatedPublicKeys add the previous/old public key.
   • Keys in the jwtRotatedPublicKeys list will only be used for verification and won’t be included in the token signing process.

The public and private keys under jwtCurrentKeys must be a valid RSA key pair otherwise the user will not be able to log in or get a session.

Below we’ll go through what a TokenConfig would look like before and after rotating keys:

# Initial TokenConfig 
game:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "original-RSA-public-key"
        private: "original-RSA-private-key"
social:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "original-RSA-public-key"
        private: "original-RSA-private-key"

# After first rotation 
game:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys: 
        public: "new-RSA-public-key" 
        private: "new-RSA-private-key" 
      jwtRotatedPublicKeys:
        1: "original-RSA-public-key" # previous public key
social:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "new-RSA-public-key"
        private: "new-RSA-private-key"
      jwtRotatedPublicKeys:
        1: "original-RSA-public-key" # previous public key

# After second rotation
game:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "newest-RSA-public-key"
        private: "newest-RSA-private-key"
      jwtRotatedPublicKeys:
        1: "original-RSA-public-key"
        2: "new-RSA-public-key"
social:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "newest-RSA-public-key"
        private: "newest-RSA-private-key"
      jwtRotatedPublicKeys:
        1: "original-RSA-public-key"
        2: "new-RSA-public-key"

After rotating keys, we recommend cleaning up old keys that are not in use. For example, consider a scenario where you have a token that has a lifespan of eight hours and the current key in session is public key A. You switch to public key B and rotate public key A; public key A is now used only for validation. After eight hours, you can remove public key A because all tokens signed with it have expired. Removing rotated public keys before they’ve expired will immediately invalidate any remaining old tokens.

This affects all tokens and token related behaviors. Tokens such as email verification and login queue might have different expiratation times from player tokens. Partner tokens will need to be redistributed to trusted third parties before removing the relevant public key.