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 your credentials using Engine's REST API. You can PUT a JSON object containing an array of the credentials you wish to create/update to /xapi/credentials/. 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": "",
  "info": "",
  "secret": "",
  "isEnabled": true,
  "auth": {
    "xapiCredentialAuthType": "BASICAUTH"
  },
  "permissionsLevel": {
    "xapiCredentialPermissionsLevel": "USER"
  }
  • id - The identifier of this credential (also, the OAuth consumer key)
  • 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, 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.

xAPI Authorization Callback

Engine can use a callback URL to validate calls into the xAPI endpoint. To configure this, you need to use the setting LrsAuthCallbackUrl in you Engine settings file. Also pay note to related settings LrsAuthCallbackMaxCacheSize, LrsAuthCacheSecondsSuccess and LrsAuthCacheSecondsFailure.

Once configured the calling system should hit the xAPI endpoint with a basic auth header consisting of the username/password that it wishes the callback URL to authenticate. The body of the request that is sent to the callback URL will be in this format:

{
    "username": "<username supplied in basic auth header>",
    "password": "<password supplied in basic auth header>"
}

The callback URL implementation must authenticate the credentials and ascertain the xAPI permissions level for the credentials before returning that information in the following format:

{
    "verified": true, 
    "permission": "READONLY", 
    "expireTimeInSeconds": 600, 
    "invalidateEntireCache": false
}

Key:

  • verified - required field. Values: true/false. Return true if the username/password authenticated, false if it didn't.
  • permission - required field. Values: NONE/USER/ROOT/READONLY/WRITEONLY. The xAPI permissions level granted to the credentials.
  • expireTimeInSeconds - optional field. Value: integer. Specifies the number of seconds to cache this authentication. Subsequent, matching, calls to the xAPI endpoint in Engine will not result in calling the callback URL until the object expires. Will use LrsAuthCacheSecondsSuccess setting if not supplied.
  • invalidateEntireCache - optional field. Values: true/false. If this flag is set to true the entire auth callback cache in ScormEngine will be invalidated when processing this callback.

results matching ""

    No results matching ""