Secured key storage

Typically, secrets or keys for connecting to the Customer's bot framework provider are configured on the VoiceAI Connect in plain text. To improve security, the secrets and keys can be stored securely on third-party, secure-storage applications.

Cache of secrets objects:

To reduce the number of repeated requests to the third-party, secure-storage, a cache manager is enabled.

The secrets are cached for 10 minutes.

Microsoft Azure key vault

If the customer is using Microsoft's Azure Key Vault to securely store its secret keys, the secrets can be configured on the VoiceAI Connect using Azure Key Vault URLs (instead of plain text). Therefore, the secrets are not exposed to potential attackers.

When the credential is required for accessing the bot framework resources, VoiceAI Connect uses the URL to access and authenticate with the Key Vault. For more information on Azure's Key Vault, see Azure's documentation.

How to use it?

Before you can configure the secret on VoiceAI Connect, you need to add the plain-text credential to Azure's Key Vault. You then need to generate a URL (HTTPS) for the credential, and use this URL ('Secret Identifier' field) as the value for the credentialsAzureSecrets bot parameter (described below). Thus, the credential is not shown in the VoiceAI Connect configuration file; only a URL to the Key Vault.

{
  "name": "sample-bot",
  "displayName": "Sample bot",
  "provider": "my-provider",
  "credentialsAzureSecrets": {
    "botSecret": "https://keyvault-name.vault.azure.net/secrets/MY-SECRET/VERSION"
  }
}

{
  "name": "my_google",
  "type": "google",
  "projectId": "my-project",
  "credentialsAzureSecrets": {
    "privateKey": "https://keyvault-name.vault.azure.net/secrets/MY-SECRET/VERSION"
  },
  "credentials": {
    "clientEmail": "service@my-project.iam.gserviceaccount.com"
  }
}

HashiCorp Vault

HashiCorp Vault is a tool for securely accessing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, or certificates. Vault provides a unified interface to any secret, while providing tight access control and recording a detailed audit log.

Vault encrypts the secrets prior to writing them to persistent storage, so gaining access to the raw storage isn't enough to access your secrets.

Authentication to Vault can be done by user/password or by App Role method (service token). An AppRole represents a set of Vault policies and login constraints that must be met to receive a token with those policies. The scope can be as narrow or broad as desired. An AppRole can be created for a particular machine, or even a particular user on that machine, or a service spread across machines. The credentials required for successful login depend upon the constraints set on the AppRole associated with the credentials. For more information, see Vault AppRole documentation.

The credentials are configured in environment variables, in the file .env:

• For user/password: VAULT_USER and VAULT_PASS

• For AppRole: VAULT_ROLE_ID and VAULT_SECRET_ID

The VoiceAI Connect uses API to retrieve the secret at the specified location:

Configuration is done using the credentialsVault bot parameter.

Since secrets are in key-value form, the input should also contain the key inside the object. It is specified by a pound (#) followed by the name, for example, #key. The value is configured using the following format:

http[s]://<URL>[:port]/v1/<secret-engine>/data/<secret-name>[?version=<version>][#field]

If the object contains only a single key-value, the field can be omitted (and value part will be used).

For example:

"credentialsVault": {
  "privateKey": "https://VAULT_URL:8200/v1/my-kv/data/google-prov#privateKey"
}

{
  "name": "sample-bot",
  "displayName": "Sample bot",
  "provider": "my-provider",
  "credentialsVault": {
    "privateKey": "https://VAULT_URL:8200/v1/my-kv/data/google-prov#privateKey"
  }
}

{
  "name": "my_google",
  "type": "google",
  "projectId": "my-project",
  "credentialsVault": {
    "privateKey": "https://VAULT_URL:8200/v1/my-kv/data/google-prov#privateKey"
  },
  "credentials": {
    "clientEmail": "service@my-project.iam.gserviceaccount.com"
  }
}

If you are using Vault namespace, set the VAULT_NAMESPACE variable in the file .env.

AWS Secrets Manager

AWS Secrets Manager is a tool for securely accessing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, or certificates. AWS Secrets Manager can be used to store secrets of any provider or bot (e.g., Google, RasaBot).

Cache of secrets objects:

To reduce the number of repeated requests to the third-party secure-storage, the secrets are cached for 10 minutes.

IAM Role:

The user must create a new IAM role and relevant policy and attach it together. (i.e., attach the IAM role to the ec2 Instances, where the session manager is centered in AWS).

Secret and Access keys:

To authenticate AWS via Secret key and Access key, the values must be defined as environment variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Match Pattern for secret ARN:

Since secrets are in key-value form, the input should also contain the key inside the secretARN. It is specified by a pound followed by the name of the key (e.g., #foo).

The value is configured using the following format:

arn:aws:secretsmanager:<aws-region>:<account-id>:secret:<secretName>[-SixRandomCharacters][#field]

Note:
if the format is not matched, relevant error will be displayed.
If the object contains only a single key-value, the field can be omitted.

Using AWS-SDK for client secrets manager to retrieve secrets:

Note: Before the configuration in VoiceAI Connect, the keys need to be stored in AWS Secret Manager Service, so the secret ARN can be generated and use the secret ARN as the value for the credentialsAwsSecrets provider or bot parameter (described below). The credential is not shown in the VoiceAI Connect configuration file or in the UI; only the secret ARN to the Secrets Manager Service.

Example 1: Using the botSecret parameter in the bot:

{
  "name": "sample-bot",
  "displayName": "Sample bot",
  "provider": "my-provider",
  "credentialsAwsSecrets": {
    "botSecret": "arn:aws:secretsmanager:AWSREGION:ACCOUNTID:secret:SECRETNAME-SIXRANDOMCHARACHTERS#privateKey"
  }
}

Example 2: Using the ‘key’ parameter in the provider:

{
  "name": "sample-provider",
  "type": "provider-type",
  "region": "my-region",
  "credentialsAwsSecrets": {
    "key": "arn:aws:secretsmanager:AWSREGION:ACCOUNTID:secret:SECRETNAME-SIXRANDOMCHARACHTERS#privateKey"
  }
}

Note: Using the credentials, credentialsAzureSecrets, credentialsVault and credentialsAwsSecrets parameters in the same provider or bot configuration is allowed as long as they use different keys in both parameters. For example:

{
  "name": "my_google",
  "type": "google",
  "credentialsVault": {
    "privateKey": "https://VAULT_URL:8200/v1/my-kv/data/google-prov#privateKey"
  },
  " credentialsAwsSecrets": {
    "clientEmail": "arn:aws:secretsmanager:AWSREGION:ACCOUNTID:secret:SECRETNAME-SIXRANDOMCHARACHTERS#privateKey"
  }
}