Authentication

Engine supports multiple ways to authenticate a request to your LRS. In accordance with the xAPI spec, both OAuth1.0a and Basic Auth can be used for accessing the LRS within Engine. The Basic Auth credentials can be set in your Engine config, and you can use the API to configure both Basic Auth and OAuth credentials. Alongside both of those credential systems, there is also an xAPI authorization callback system that be configured.

Basic Auth

Engine has a setting called xAPIBasicAccounts that can be configured with the credentials that should be allowed access to your LRS. The format of each credential should be username:password:role, and multiple credentials can be supplied by separating the definitions with a new line. The role property has a few different values that can be used to limit the permissions that the credential has:

• user : This is the most common permission level. It allows the account to assert any statement and to read only those statements they have asserted or play some role in
• read-only : This credential is allowed to read all statements and state documents, but it cannot not write anything. This would be an appropriate permission to give an application meant to report on the entire contents of your LRS.
• write-only : A credential with write-only permissions is allowed to assert any statement and store any xAPI document, but it cannot read anything out of your LRS. If you were to have another LRS forward its statements to yours, then this would be a good permission level to use.
• root : This permission level allows a credential to read and write any statement or xAPI document. Obviously, anyone with this kind of access would have a lot of power over your xAPI data. Use this permission level judiciously.

Here's an example configuration:

<add key="xApiBasicAccounts" value="
    xapi_user_1:password_1:user
    xapi_user_2:password_2:read-only
    xapi_user_3:password_3:write-only
" />

<entry key="xAPIBasicAccounts">
    xapi_user_1:password_1:user
    xapi_user_2:password_2:read-only
    xapi_user_3:password_3:write-only
</entry>

Using the API

To avoid storing your xAPI credentials in a config file, you can also set up tenant-specific credentials using Engine's REST API. You can PUT a JSON object containing the credentials you wish to create/update to /xapi/credentials/{credentialId}. Unlike the ones defined with the xAPIBasicAccounts setting, credentials created with the REST API will only authenticate against the tenant specified in the EngineTenantName request header. Additionally, if you specify the ID of a credential that is already in use, then that credential will be updated. Otherwise, a new credential will be created.

Here is an example of the JSON object that you would send, followed by an explanation of the properties:

{
  "id": "",
  "name": "Example Credentials",
  "info": "https://mydomain.com/credentialInfo/xyz",
  "secret": "mysuperSecretPassword",
  "isEnabled": true,
  "auth": {
    "xapiCredentialAuthType": "BASICAUTH"
  },
  "permissionsLevel": {
    "xapiCredentialPermissionsLevel": "USER"
  }

• id - The identifier of this credential. For OAuth credentials, the value will be the consumer key, and for Basic Auth credentials, the value will be used as the username.
• name - The name of the credential that you are creating. Name it something that helps you remember what the credential is used for.
• info - An optional property. If provided, it should be a URL that resolves to information about the credential. For example, if a credential is being created for a web app, you could set info to the URL that the web app is being hosted on.
• secret - Usage varies depending on which credential auth type you have chosen. For OAuth credentials, the value will be the consumer secret of the new credential, and for Basic Auth credentials, the value will be used as the password.
• isEnabled - Controls whether or not this credential can be used.
• xapiCredentialAuthType - Possible values are OAUTH or BASICAUTH and determines the type of authentication the credential is used for.
• xapiCredentialPermissionsLevel - Possible values of USER, ROOT, READONLY, and WRITEONLY, which all correspond to their respective definitions found in the Basic Auth Credentials section above.

Note: You can also make a POST request to the /xapi/credentials endpoint. With that request, you do NOT specify an id for the credential, and instead one is generated for you. The newly generated id will be returned in the result property of the response.

xAPI Authorization Exchange Webhook

There may be times when you want to authenticate applications to access the LRS in Engine where the default basic auth credentials created through the above methods is not flexible enough. Maybe you want to assign the 3rd part a credential that then you validate yourself. This is where the XapiGetAuthority exchange webhook can come into play.

With this subscription created, whenever a request comes into the LRS we will send a request to your configured endpoint with a payload that contains the Authorization header from the incoming request.

Your endpoint must then validate the credentials and return to us the permissions this credential should have in the LRS. It should also return the account id for the credential, as we'll use this in building the Actor object to use as the authority on the statements.

If your endpoint returns a verified of false, or the request returns an error status code, Engine will reject the request to the LRS as being unauthenicated.

Please see the general Webhooks section and the exchange definition for complete details on the payload you'll receive from Engine and what is expected in your response.

Note to Upgrading Customers

Engine's previous implementation of this functionality that used the LrsAuthCallbackUrl will still operate as normal, so you can continue to use it for now. However, it will be removed in a future Engine version, so you should plan to migrate to using the new webhook as a replacement.