Change the environment encryption key

Introduction

This document describes how to change the encryption key of the Aura environments without service loss. The encryption key in Aura has three main usages:

• Generation and validation of the service APIKeys.
• Encryption of the secrets stored in the channels configuration settings.
• Encryption of temporary params shared with other systems to validate an incoming request. For instance, when authenticating a user using the “Redirect authentication” of Kernel IdP, to be able to validate the incoming request with the user data in the authentication callback, via the state field, which is encrypted by Aura Bot and sent as query param to the authentication callback of Aura.

The mechanism proposed allows to validate APIKeys encrypted with several keys, whilst the servers use just the active encryption key for the rest of the functionalities.

Further information regarding how to configure the new encryption in the installer can be found in the deployment documentation.

Requirements

• Docker and python3 installed in your local machine
  • Also Nodejs20 if want to try the snippet to generate the encryption keys.
• Access to the Aura installer
• Access to the config.yml of your environment

Procedure

⚠️ It is important to do this change only during the installation of a new release of Aura, to avoid problems in the encryption of the channels collection and to let the installer generate automatically all the internal APIKeys.

• Generate a 32 character encryption key. The length is mandatory because of the encryption algorithm being used. The following snippet contains an example of how to generate it using Nodejs:

const crypto = require('crypto');
const key = crypto.randomBytes(16).toString('hex');
console.log(key);

• Encrypt it using ansible-vault:

ansible-vault encrypt_string 'old-encryptionkey,new-encryptionkey' --name 'aura_encryption_key'
New Vault password: 
Confirm New Vault password: 
Encryption successful
aura_encryption_key: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          62393736616536336262613333313866366365396361643930653535633564636430343530303637
          3866643931653739343164303662376439316630633538620a663031306265613162353633323565
          33376662626162663431616132353436366431383064663131643363653636346336343433303637
          3666333534656439390a656132306236336337383761323166666430633463303461316561363632
          65396530323635323363316362343437623065353232339343731643031653961336137343664366
          162386564636561313532633662383366383364653362663530653563623362303164653137653039
          663430356237366439663238346130656432303737

• Configure it in the config.yml of your environment:

vim config.yml
...
aura_encryption_key: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          62393736616536336262613333313866366365396361643930653535633564636430343530303637
          3866643931653739343164303662376439316630633538620a663031306265613162353633323565
          33376662626162663431616132353436366431383064663131643363653636346336343433303637
          3666333534656439390a656132306236336337383761323166666430633463303461316561363632
          65396530323635323363316362343437623065353232339343731643031653961336137343664366
          162386564636561313532633662383366383364653362663530653563623362303164653137653039
          663430356237366439663238346130656432303737
...

• Now, the installer can be launched. The default encryption key is going to be new-encryptionkey.
  • The installer will generate all the internally used APIKeys, such as the one provided in the configuration of the services stored in the environment variable as AURA_AUTHORIZATION_HEADER.
• Generate the new APIKeys for all the consumers of Aura’s APIs, using the tool of the installer to do it, following the instructions in generate APIKey section, the APIKeys are going to be created directly with the default one.
• The APIKeys to be created depend on the environment, but take into account the following notes to update them all:
  • The APIKey is used by all the channels accessing Aura via DirectLine, a new one per channel should be generated.
  • The APIKey is used in the following webhooks or Aura APIs configured in Telefónica Kernel:
    • WhatsApp webhooks
    • Deployment of aura-services API
    • Deployment of aura-aiservices API
• Once all the channels and Kernel configurations are changed to use the brand-new APIKeys, the environment configuration can be changed to count only with the default one.
• To do the change from release to release, at least the encryption key of the latest deployment and the new one should be configured.