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.

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.

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.

results matching ""

    No results matching ""