General topics: using the secrets store for secure e-mailing

Using the secrets store for secure e-mailing

If your SMTP server is secured via TLS/SSL and Collections users need to be able to send e-mails, e.g. by using the Collections scheduling service as an SDI server, you'll need way to authenticate the Collections connection to the SMTP server.

To begin with, mark the User secure connection option (available from 1.13.1.6603) on the Application authentication tab in your Collections application properties to have the SMTP client (Collections) create a TLS/SSL connection to the SMTP server, to enable secure connections for e-mails sent through SMTP. This setting is compatible with Collections 1.19 and up.

Since the connection needs to be authenticated via user credentials (user name and password) other than the IIS application pool identity credentials, you'll have to use a so-called secrets store to securely store these credentials in, for Collections to use when a connection must be made for the currently logged-in user.
The secret store is a user-specific per-server secure store for sensitive information, such as his or her user credentials (so each user has its own secrets store). The behaviour of the store is determined by a configuration file and values in the vault of the secret store can only be set via the secrets.exe command-line utility.

This secrets store functionality is available from Collections 1.19. It consists of:

•

a secretsconfig.json configuration file that will automatically have been created already in the \App_Data folder of your Collections IIS application (when running it as a web application), while otherwise the file will be located in the same folder as the application's binary files. You'll have to configure it to point it to the desired secret store;

•	a Secrets.exe command-line utility located in the \bin sub folder of your Collections IIS application, to (initially create and later) manage the settings and secrets in the secrets store;

•

an encrypted vault file (a filled-in, encrypted copy of secretsconfig.json, renamed to secrets.json in the users appdata folder, containing the actual set up configuration and secrets. Only a local file secret store will contain secrets (instead of the remote AWS or the Azure Key Vault, the other supported secrets stores).

The secret store configuration file

As mentioned, a secretsconfig.json configuration file will automatically have been created already (by Collections or any other Axiell software using the secrets store) in the \App_Data folder of your Collections IIS application (when running it as a web application), while otherwise the file will be located in the same folder as the application's binary files. You'll have to configure it to point it to the desired secret store and vault using Secrets.exe. The format of the configuration file is as follows:

{
"Type": "LocalFile",
"DefaultSection": "Sql",
"Enabled": false,
"Path": null,
"VaultName": "42v9f13e-9e83-4472-817e-3905d01235e4",
"SecretName": "secrets.json",
"Encrypted": true,
"PollPeriod": 0,
"Template": {
"EmailCredentials": {
"UserName": "string",
"Password": "password"
}
}
}

The settings, to be made using Secrets.exe, are the following:

Setting	Default value	Description
Type	LocalFile	Type of the secrets store (see the paragraph below for more information about these types): LocalFile – Local file AWS - Amazon Web Services (untested) AzureKeyVault – Azure Key Vault (untested)
Enabled	false	Set to true or false. When the configuration file is first created, the secret store is empty and this has been set to false. There is no need to change this value manually. Setting any value for the other settings using the secrets.exe utility will enable the secret store (and will automatically set this option to true).
Path	null	For LocalFile this is an optional base path. If not specified the default will be the Windows user's %APPDATA%\.axiell folder.
VaultName	Generated GUID	Name of the vault, which is specific to the provider. The first time this is created, it will be a GUID.
SecretName	secrets.json	The name of the secret in the store where all the secrets for the application are saved to. For the local file, this is the file name. For other providers this will be a configured area within the vault.
Encrypted	true	For LocalFile, this setting determines whether to encrypt the key store. Normally you set it to true but for debugging purposes it can be set to false temporarily, so that you can read the edited configuration file in a text editor.
PollPeriod		Poll period in milliseconds for Collections or other software to check the secret store for changed values. If 0, then no polling occurs. For LocalFile, this value is ignored because the settings are automatically refreshed when the configuration file is modified.

Supported secrets stores

Three types of secrets stores are currently supported by Collections:

•

LocalFile - A local file secrets store is an encrypted file, by default located at %APPDATA%\.axiell\<VaultName>\<SecretName>. The Path can optionally be set to a different folder to use instead of %APPDATA%\.axiell. The VaultName GUID was generated automatically. The SecretName is the file name of the encrypted JSON file where all the actual secrets for the application will be stored.

•

AWS - For the Amazon Web Services secrets store, use the Amazon Secrets Manager to manage the actual secrets. The VaultName in the configuration corresponds to the region and will need to be changed to match your setup. The SecretName is the name of the secret in the secrets manager where all secrets for the application will be stored.

•

AzureKeyVault - For the Microsoft Azure Key Vault secrets store, use the Azure Key Vault to manage the actual secrets. The VaultName in the configuration corresponds to https://{VaultName}.vault.azure.net. The SecretName is the name of the secret in the secrets manager where all secrets for the application will be stored.

The secrets management utility (Secrets.exe)

Open a command-line window (as administrator) and run* Secrets.exe followed by the desired arguments to edit the configuration file and manage secrets (the latter for LocalFile only). This utility must be run under the same account as that which owns the IIS application pool: the encryption keys belong to the current user, so therefore, if you run the application pool as a specific user, the secrets utility has to be run as that user; otherwise, Collections will not be able to pick up the file or decrypt it. The syntax is as follows (leave out all brackets):

secrets <command> [<key>] [<value>]

The possible commands are:

Command	Key	Value	Description
List	[all]		List all the current secrets, including deleted ones. Some stores don’t delete the secrets, they just set them to empty. Note that it doesn't matter if you specify the key all behind List or not.
Set	[key]	<value>	Set the supplied key
Get	[key]		Get the supplied key
Delete	[key]		Delete the supplied setting.
Settings			Show the path to the current settings file and the settings.
Edit			Open the configuration file in a text editor, to pre-edit it maybe if no secrets store was created with it yet.
Template			List the known keys (not the values) under the Template node. The available keys will depend on the Collections configurations on that server. This feature has to be supported by the application and the application will need to be run first once in order to generate the base configuration file. This can result in, for example: Using: C:\inetpub\wwwroot\Collections\App_Data\secrets.json EmailCredentials:UserName EmailCredentials:Password

Settings are hierarchical with a colon being used as a separator.

Examples:

Secrets list

Secrets template

Secrets set EmailCredentials:UserName erik

* If the ability to run executables from the \inetpub folder is prohibited, you can run Secrets.exe from a different folder too. Just copy the relevant Axiell files somewhere else. The bare minimum files to copy across from the \bin folder are: Axiell.dll, Axiell.Security.Secrets.dll, CommandLine.dll, Microsoft.Extensions.Configuration.Abstractions.dll, Newtonsoft.Json.dll and Secrets.exe. When you run Secrets.exe from this other location, you must specify an extra parameters at the end of the command-line to Secrets.exe, to point to the \bin folder of the Axiell application, e.g.:

-d "c:\inetpub\wwwroot\Collections\bin"

It’s also possible that the Windows security permissions that are set on the .exe file will persist into the new folder. In which case, you could extract the required files from the AxiellCollections.zip file that is used to deploy to the server.

Secrets in Collections

All secrets are prefixed with the ID of the Application source in settings.xml. (In multi-tenant environments this is the individual ID of an application, not "Multi", because we can't assume that each tenant will use the same SMTP authentication, especially if those tenants are separate organisations.)

So for the usual configuration of:

<SessionManager Id="SQL" …

The keys will start with SQL:

The reason for this is that there is only one secrets file per user. The file is partitioned so that multiple instances of Collections can have different secrets – all within the same file.

You never have to add this prefix explicitly when you set a key.