Aura – security

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura security and networks

Scope: Key information regarding Aura security and networks, applicable to both Aura Virtual Assistant and ATRIA

Aura Security group

In each Aura installation, we create/update rules to allow access only to the public endpoint through ports 443 from Internet.

Blob encryption

By default, the blob storage in Aura is not encrypted with our own key but, by default, Azure encrypts every resource.

You can see more info in Microsoft Azure Storage encryption documentation.

Aura Network Policies

Policy 1 - alertmanager-network-policy

Ingress

Allows pods in namespace aura-system with labels app: alertmanager to receive traffic from pods with labels networking/allow-pod-alertmanager-access: true in namespaces with labels networking/allow-namespace-alertmanager-access: true on ports TCP http and TCP cluster
- app: alertmanager
  - namespace: aura-system statefulset.apps/alertmanager
- networking/allow-pod-alertmanager-access
  - namespace: aura-$ENV deployments.apps/nginx
  - namespace: aura-system deployments.apps/prometheus-msteams
- networking/allow-namespace-alertmanager-access
  - namespace: aura-system
  - namespace: aura-$ENV

Policy 2 - elasticsearch-exporter-network-policy

Ingress

Allows pods in namespace aura-system with labels app: elasticsearch-exporter to receive traffic from pods with labels networking/allow-pod-elasticsearch-exporter-access: true in namespaces with labels networking/allow-namespace-elasticsearch-exporter-access: true on port TCP 9114
- app: elasticsearch-exporter
  - namespace: aura-system deployment.apps/elasticsearch-exporter
- networking/allow-pod-elasticsearch-exporter-access
  - namespace: aura-system statefulsets.apps/prometheus
- networking/allow-namespace-elasticsearch-exporter-access
  - namespace: aura-system

Policy 3 - elasticsearch-network-policy

Ingress

Allows pods in namespace aura-system with labels app: elasticsearch to receive traffic from all pods in namespaces with labels networking/allow-namespace-elasticsearch-access: true on ports TCP 9200 and TCP 9300
- app: elasticsearch
  - namespace: aura-system elasticsearch.k8s.elastic.co/elasticsearch
- networking/allow-namespace-elasticsearch-access
  - namespace: aura-system
  - namespace: aura-$ENV
Allows pods in namespace aura-system with labels app: elasticsearch to receive traffic from pods in the same namespace with labels networking/allow-pod-elasticsearch-access: true on ports TCP 9200 and TCP 9300
- app: elasticsearch
  - namespace: aura-system elasticsearch.k8s.elastic.co/elasticsearch
- networking/allow-pod-elasticsearch-access
  - namespace: aura-system deployments.apps/kibana-kb
  - namespace: aura-system deployments.apps/elasticsearch-exporter
  - namespace: aura-$ENV deployments.apps/nginx

Policy 4 - fluent-bit-aggregator-network-policy

Ingress

Allows pods in namespace aura-system with labels app: fluent-bit-aggregator to receive traffic from pods with labels networking/allow-pod-fluent-bit-aggregator-access: true in namespaces with labels networking/allow-namespace-fluent-bit-aggregator-access: true on port TCP http
- app: fluent-bit-aggregator
  - aura-system statefulset.apps/fluent-bit-aggregator
- networking/allow-namespace-fluent-bit-aggregator-access
  - aura-system
- networking/allow-pod-fluent-bit-aggregator-access
  - aura-system deployments.apps/azure-logger

Policy 5 - fluent-bit-network-policy

Ingress

Allows pods in namespace aura-system with labels app: fluent-bit to receive traffic from pods with labels networking/allow-pod-fluent-bit-access: true in namespaces with labels networking/allow-namespace-fluent-bit-access: true on port TCP metrics
- app: fluent-bit
  - namespace: aura-system daemonset.apps/fluent-bit
- networking/allow-namespace-fluent-bit-access
  - namespace: aura-system
- networking/allow-pod-fluent-bit-access
  - namespace: aura-system deployments.apps/azure-logger

Policy 6 - grafana-network-policy

Ingress

Allows pods in namespace aura-system with labels app: grafana to receive traffic from pods with labels networking/allow-pod-grafana-access: true in namespaces with labels networking/allow-namespace-grafana-access: true on port TCP http
- app: grafana
  - namespace: aura-system job.batch/grafana-provision
  - namespace: aura-system statefulset.apps/grafana
- networking/allow-pod-grafana-access
  - namespace: aura-$ENV deployments.apps/nginx
- networking/allow-namespace-grafana-access
  - namespace: aura-system
  - namespace: aura-$ENV

Policy 7 - kibana-network-policy

Ingress

Allows pods in namespace aura-system with labels app: kibana to receive traffic from all pods in namespaces with labels networking/allow-namespace-kibana-access: true on port TCP 5601
- app: kibana
- namespace: aura-system deployments.apps/kibana-kb
- networking/allow-namespace-kibana-access
  - namespace: aura-system
  - namespace: aura-$ENV
Allows pods in namespace aura-system with labels app: kibana to receive traffic from pods in the same namespace with labels networking/allow-pod-kibana-access: true on port TCP 5601
- app: kibana
- namespace: aura-system deployments.apps/kibana-kb
- networking/allow-namespace-kibana-access
  - namespace: aura-system deployments.apps/kibana-kb
  - namespace: aura-$ENV deployments.apps/nginx

Policy 8 - mongodb-exporter-network-policy

Ingress

Allows pods in namespace aura-system with labels app: mongodb-exporter to receive traffic from pods with labels networking/allow-pod-mongodb-exporter-access: true in namespaces with labels networking/allow-namespace-mongodb-exporter-access: true on port TCP metrics
- app: mongodb-exporter
  - namespace: aura-system deployments.apps/mongodb-exporter
- networking/allow-pod-mongodb-exporter-access
  - namespace: aura-system statefulset.apps/prometheus
- networking/allow-namespace-mongodb-exporter-access
  - namespace: aura-system

Policy 9 - mongodb-network-policy

Ingress

Allows pods in namespace aura-system with labels app: mongodb to receive traffic from pods with labels networking/allow-pod-mongodb-access: true in namespaces with labels networking/allow-namespace-mongodb-access: true on port TCP mongodb
- app: mongodb
  - namespace: aura-system deployments.apps/mongodb
  - namespace: aura-system job.batch/mongodb-provision
- networking/allow-pod-mongodb-access
  - namespace: aura-system deployments.apps/mongodb-exporter
  - namespace: aura-$ENV deployments.apps/aura-bot
  - namespace: aura-$ENV deployments.apps/aura-bridge
  - namespace: aura-$ENV deployments.apps/authentication-api
  - namespace: aura-$ENV deployments.apps/tac
- networking/allow-namespace-mongodb-access
  - namespace: aura-system
  - namespace: aura-$ENV

Policy 10 - node-exporter-network-policy

Ingress

Allows pods in namespace aura-system with labels app: node-exporter to receive traffic from pods with labels networking/allow-pod-node-exporter-access: true in namespaces with labels networking/allow-namespace-node-exporter-access: true on port TCP metrics
- app: node-exporter
  - namespace: aura-system daemonset.apps/node-exporter
- networking/allow-pod-node-exporter-access
- networking/allow-namespace-node-exporter-access
  - namespace: aura-system

Policy 11 - prometheus-msteams-network-policy

Ingress

Allows pods in namespace aura-system with labels app: prometheus-msteams to receive traffic from pods with labels networking/allow-pod-prometheus-msteams-access: true in namespaces with labels networking/allow-namespace-prometheus-msteams-access: true on port TCP http
- app: prometheus-msteams
  - namespace: aura-system deployments.apps/prometheus-msteams
- networking/allow-pod-prometheus-msteams-access
  - namespace: aura-system deployments.apps/prometheus-msteams
- networking/allow-namespace-prometheus-msteams-access
  - namespace: aura-system

Policy 12 - prometheus-network-policy

Ingress

Allows pods in namespace aura-system with labels app: prometheus to receive traffic from pods with labels networking/allow-pod-prometheus-access: true in namespaces with labels networking/allow-namespace-prometheus-access: true on ports TCP http, TCP exposed and TCP 10901
- app: prometheus
  - namespace: aura-system statefulset.apps/prometheus
- networking/allow-pod-prometheus-access
  - namespace: aura-system deployment.apps/elasticsearch-exporter
  - namespace: aura-system deployments.apps/mongodb-exporter
  - namespace: aura-system deployments.apps/thanos-querier
  - namespace: aura-$ENV deployments.apps/aura-bot
  - namespace: aura-$ENV deployments.apps/aura-bridge
  - namespace: aura-$ENV deployments.apps/nginx
  - namespace: aura-$ENV deployments.apps/context
  - namespace: aura-$ENV deployments.apps/tac
  - namespace: aura-$ENV deployments.apps/npl
- networking/allow-namespace-prometheus-access
  - namespace: aura-system
  - namespace: aura-$ENV

Policy 13 - pushgateway-network-policy

Ingress

Allows pods in namespace aura-system with labels app: pushgateway and release: pushgateway to receive traffic from all pods in namespaces with labels networking/allow-namespace-pushgateway-access: true on port TCP 9091
- app: pushgateway
  - namespace: aura-system deployment.apps/pushgateway
- networking/allow-namespace-pushgateway-access
  - namespace: aura-system
  - namespace: aura-$ENV
Allows pods in namespace aura-system with labels app: pushgateway and release: pushgateway to receive traffic from pods in the same namespace with labels networking/allow-pod-pushgateway-access: true on port TCP 9091
- app: pushgateway
  - namespace: aura-system deployment.apps/pushgateway
- networking/allow-pod-pushgateway-access
  - namespace: aura-$ENV deployments.apps/nlp-provisioning

Policy 14 - redis-network-policy

Ingress

Allows pods in namespace aura-system with labels app: redis to receive traffic from pods with labels networking/allow-pod-redis-access: true in namespaces with labels networking/allow-namespace-redis-access: true on ports TCP 6379, TCP 26379 and TCP 9121
- app: redis
  - namespace: aura-system statefulset.apps/redis
- networking/allow-pod-redis-access
  - namespace: aura-$ENV deployments.apps/context
- networking/allow-namespace-redis-access
  - namespace: aura-system
  - namespace: aura-$ENV

Policy 15 - thanos-network-policy

Ingress

Allows pods in namespace aura-system with labels app: thanos to receive traffic from pods with labels networking/allow-pod-thanos-access: true in namespaces with labels networking/allow-namespace-thanos-access: true on ports TCP 10901 and TCP 10902
- app: thanos
- networking/allow-pod-thanos-access
  - namespace: aura-system statefulset.apps/thanos-store-gateway
- networking/allow-namespace-thanos-access
  - namespace: aura-system
  - namespace: aura-$ENV

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Change the environment encryption key

Description of the process to change the encryption key without service loss

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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Generate an APIKey in Aura

Methods for the generation of an APIKey in Aura

Introduction

All Aura’s public APIs are protected using an APIKey.

The generation of an APIKey can be done using two alternative processes:

Generate an APIKey from Aura installer aurak8s
Follow the instructions in the document Create Aura APIKeys
Generate an APIKey using the aura-api-key-generator utility
- aura-api-key-generator is an Aura utility that generates encrypted APIKeys with a JSON model that will be used to validate the access to Aura’s public APIs.
- It is executed with the configuration of the chosen environment. This utility must be executed by the Operations Team and the generated APIKey must only be shared with the team involved in the integration of the corresponding API client.
- The guidelines are included in the following sections.

Generate an APIKey using the aura-api-key-generator utility

These guidelines correspond to the process that uses the aura-api-key-generator utility as a Docker image.

Prerequisites

Docker 23.0.5 or higher
Access to auraregistry.azurecr.io private docker registry.

The ENCRYPTION_KEY of the environment where the APIKey will be used:

kubectl installed in your local host.
curl installed in your local host.
jq installed in your local host.

To obtain the ENCRYPTION_KEY, just execute the following command:

# substitute {{aura-environment}} with the environment you're configuring
export AURA_ENVIRONMENT={{aura-environment}}

$ kubectl -n $AURA_ENVIRONMENT get secret aura-bot -o json | jq -r ".data.AURA_ENCRYPTION_KEY|@base64d"

YOUR-ENCRYPTION-KEY

Run the tool

Download the Docker image and run the tool by executing the following command:

# Substitute {{aura-encryption-key}} with the ENCRYPTION_KEY obtained in the previous step
$ docker run -e AURA_ENCRYPTION_KEY={{aura-encryption-key}} auraregistry.azurecr.io/aura/aura-api-key-generator:1.0.0 -v 8.3.0 -s aura-services -a kernel -m rw

Usage

> @telefonica/aura-api-key-generator@1.0.0 start
> node lib/index.js --help

process.env.CONFIG_FILE (undefined) not found or not configured, using only process.env

Usage: index -s aura-services:token -e pre -a kernel -v 8.3.0 -m rw

Utility to generate API Key to access the APIs of Aura.  Version: 1.0.0.

Options:
  -V, --version                     Output the version number
  -i, --identifier [identifier]     Unique identifier of the APIKey. Format UUID. If not provided, it will be autogenerated
  -s, --scope [scope]               Comma-separated list of strings containing the API path where this APIKey will be used. Possible values: "aura-services", "aura-services:users,aura-services:token", "aura-services:whatsapp", etc. (By default: "aura-services")
  -e, --enviroment <enviroment>     Environment where the APIKey will be used. Possible values: dev, stg, pre, pro (Choices: "dev", "stg", "pre", "pro". By default: "pro")
  -a, --authorised <client>         Name of the client that will use the APIKey. Usually one of kernel, novum, mh, mp, stb, la, etc. (By default: "kernel")
  -v, --aura-version <auraVersion>  Minimum Aura Platform version to use this APIKey. It should contain the full version of Aura. Example: 8.3.0 (default: "8.3.0")
  -m, --mode <mode>                 Type of access to the API. Possible values: r, w, rw (Choices: "r", "w", "rw". By default: "r")
  -h, --help                        Display help for command

Scope

All public Aura’s APIs are in the aura-services scope, so any APIKey generated with this scope will have access to all Aura’s APIs. But the idea is to use always the minimum scope valid for the specific usage of the client.

For example:

For those clients that are Aura channels and need to get a Direct Line token from Aura, the scope must be aura-services:token.
To configure the WhatsApp webhooks of aura-bridge in Kernel, the scope must be aura-services:whatsapp.
To configure the access from Kernel to aura-services API, the scope must be aura-services:users.
To configure the access from Kernel to aura-gateway-api in aura-services API, the scope must be aura-ai-services:messaging:write or aura-ai-services:nlp-messaging:write.

Environment

As the specific environment is configured via the ENCRYPTION_KEY, the environment parameter is only used to generate the APIKey with the correct environment name.

The environment name is used to validate the APIKey when it is used to access an API. It only contains the type of the environment: dev, stg, pre or pro.

Authorized

It should contain a human-readable name of the client that will use the APIKey. The usual values are: kernel, novum, mh, mp, stb, la, metaverse.

API Version

It contains the major version of the Aura API that the APIKey will be used.

For example, if the APIKey will be used to access the aura-services API, the API version must be 1. It must be coherent with the version of the API published in Aura’s API documentation.

Mode

It indicates the type of access to the API:

r: read-only access, it allows to access the API to execute GET operations.
w: write-only access, it allows to access the API to execute POST, PUT and DELETE operations.
rw: read-write access, it allows to access the API to execute GET, POST, PUT and DELETE operations.