Security Settings

API Authentication

Engine authenticates API requests using either Basic Auth or Bearer tokens. 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).

API Credentials

To get started with the V2 API, you can add Basic Auth credentials to the ApiBasicSystemAccounts property in the RusticiEngineSettings.configRusticiEngineSettings.properties file. The value for this setting should be a newline-delimited list of username/password pairs in the format of username:password.

Of course, passwords residing in a configuration file isn't always desirable, and credentials set in the ApiBasicSystemAccounts property have access to every API endpoint. To create credentials that persist in the database with narrower functionality, use the admin tool or make a POST to the /appManagement/credentials endpoint.

For example, to create an API account with the ability to create and delete registrations for a specific tenant and course, the POST body would contain scoping properties and resemble the below example.

{
  "name": "eLearnersUnite-Registrations",
  "permissions": {
    "scopes": [
      "write:registration",
      "delete:registration"
    ],
    "tenantName": "eLearnersUnite",
    "courseId": "acb74ebb-74b3-48e1-8c5d-587b5da01374"
  }
}

Whether you create a credential with the admin tool or API, the response will include the new credential's user name and password.

{
    "id": "RfKr3qtxveuCW7b9wXs",
    "secret": "IbyJLCRYWw55qf2q3tE"
}

If you wanted to remove the ApiBasicSystemAccounts property from your RusticiEngineSettings.configRusticiEngineSettings.properties file entirely, create a credential with an empty scopes array. This account will have the equivalent 'root' access of an ApiBasicSystemAccounts credential.

{
  "name": "system-admin",
  "permissions": {
    "scopes": [
    ]
  }
}

The complete list of scopes can be viewed in either the admin tool or by accessing the /about endpoint. They are also included with a short description in the table below:

Certain scopes are used only for LTI 1.3 launch and should not be used manually. These scopes and their uses are described in the table below:

Token Authentication

If interfacing with Engine primarily through a user-facing, front-end application, consider authenticating these API calls using short-lived bearer tokens.

Obtain a scoped token serverside by making a POST to /appManagement/token. The scoping syntax is similar to creating a scoped API credential, but the request body also includes an 'expiry' name/value pair to specify when the token expires.

{
  "permissions": {
    "scopes": [
      "write:registration",
      "delete:registration"
    ],
    "tenantName": "eLearnersUnite",
    "courseId": "6b384cd4-82a9-475d-baa1-3a2b25104920",
  },
  "expiry": "2020-04-27T19:50:15.212Z"
}

This will return a URL-safe token that you can send back to the client.

{
    "result": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1ODgwMTcwMTUsInNjb3BlcyI6WyJ3cml0ZTpjb3Vyc2UiXSwidGVuYW50IjoiZGVmYXVsdCIsImNvdXJzZSI6Ik15Q291cnNlSWQxMjMifQ.WE-OSa9cLGQxPwSNunxSNyrld-Ji4sQsC7d7kBXbuCw"
}

The client making the API request specified in the scope can then use the token for Bearer Token authenication instead of Basic Auth. This method will allow your client application to make API requests without exposing your API credentials.

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), set PreviousEncryptionPassword 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 /appManagement/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:

• Copy the current value of EncryptionPassword to PreviousEncryptionPassword (and the current value of Encryptor to PreviousEncryptor, if it is provided and it is changing).
• Set EncryptionPassword to the new password (and Encryptor to the new encryption algorithm if relevant).
• Enumerate all tenants used by Engine, and for each tenant POST to /appManagement/configuration/updateEncryptedSettings.
• Remove the PreviousEncryptionPassword (and PreviousEncryptor) setting after that process has finished.

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 may be shown decrypted when returned via the API if the includeSecretSettings query parameter is used.

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.

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.