Security Settings

API Authentication

In order to keep your credentials secure we strongly recommend using TLS (https) when accessing the API, and using long random strings for both the username and password components (these should not be real user accounts, so no one should ever have to type these credentials).

Engine's API is designed to exclusively be used by your team during application development and by your application in production. It does not provide the fine grained security control you'd want for an API available to users, as any API account can perform any operation, including the creation and deletion of data. The API is not authenticated in such a way that would be safe for a user-facing application to call directly. The ability to set up multiple accounts is only relevant for the purpose of having different sets of credentials that can be revoked separately. Only use the API as an interface between your application and Engine.

Encryption

If EncryptionPassword is provided and EncryptConfigurationSettings is set to true, configuration settings with the secretString type will be encrypted when set via the API. By default, Engine will use 128-bit AES encryption with GCM as its encryption algorithm, but a custom encryption algorithm can be set via the Encryptor configuration setting.

In order to support password rotation (that is, the ability to switch to a new encryption password while still decrypting values encrypted with the old password), PreviousEncryptionPassword should be set with the current password's value before changing it. If the previous password is given and decryption of a configuration setting fails with the current password, Engine will attempt to use the previous password. To facilitate password rotation, Engine provides the /[tenant]/configuration/updateEncryptedSettings API endpoint. When that endpoint is POST-ed to, Engine will rewrite encrypted settings (and xAPI statement pipe passwords) for that tenant using the latest password. A PreviousEncryptor setting also exists if you need to change the encryption algorithm.

All in all, the password rotation process is as follows:

This rotation process does not handle package- or registration-level settings. The only such settings that are encrypted by default are the registration postback credentials. We recommend that you set those credentials at the tenant level instead of providing different credentials for each registration, to avoid needing to come up with your own process to re-write those settings when you rotate passwords.

Encrypted values are decrypted immediately after they are loaded. In particular, note that settings which are encrypted in the DB will be shown decrypted when returned via the API.

Hashing

If HashAccountPasswords is enabled, then when storing "account" configuration settings, passwords will be replaced with bcrypt password hashes before being persisted to the database. The originally specified password will not be saved anywhere, so when reading this setting through the API, only the hashed password will be seen. In order to "bootstrap" Engine so that no unhashed passwords appear in configuration files, one can do the following:

Alternatively, if you have a method of generating bcrypt hashed passwords, you can create your own password hashes and use them instead of passwords in any "accounts" configuration setting, even directly in your configuration file. We expect these to be in the modular crypt format with a prefix of 2a, 2b, or 2y.

The built-in xAPI Statement Viewer will not work if password hashing is enabled. Customers wishing to use Statement Viewer in their application are advised to download and configure the original open-source Statement Viewer.

results matching ""

    No results matching ""