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:

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:

Supported secrets stores

Three types of secrets stores are currently supported by Collections:

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:

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 implicitly 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.