Skip to content

Step by step: Install lxHive and setup authentication for your app

Jump to bottom Edit New page
joerg edited this page Oct 27, 2018 · 20 revisions

This tutorial goes through the installation and app authorization of lxHive (0.9.x).

This tutorial uses the domain mylxhive.com and the email admin@mylxhive.com as examples. You should replace any occurrences of these with your own site name and email.

1. Installation

1.0 Prerequisites

1.1 Install lxHive code base

Browse to your htdocs directory

$ cd /home/lrs/www/

Clone repository from the web

$ git clone https://github.com/g3i/lxHive.git

Move into the cloned lxhive app root directory

$ cd lxHive

Install dependencies with composer

$ composer install

1.2 Set up Server

1.2.1 VirtualHost

Create an apache conf file.

$ sudo nano /etc/apache2/sites-available/mylxhive.com.conf

Populate the file with the following contents and then save. Remember to change the ServerAdmin and ServerName fields.

NameVirtualHost *:80

<VirtualHost *:80>
        ServerAdmin admin@mylxhive.com
        ServerName mylxhive.com

        DocumentRoot /home/lrs/www/lxHive/public

        <Directory />
                Options FollowSymLinks
                AllowOverride None
        </Directory>
        <Directory /home/lrs/www/lxHive/public>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride All
                Order allow,deny
                allow from all
        </Directory>

        ErrorLog /home/lrs/www/logs/error.log
        CustomLog /home/lrs/www/logs/access.log combined
</VirtualHost>

1.2.2 Register configuration with server

Enable the configuration

sudo a2ensite mylxhive.com.conf

Reload Apache to apply changes

$ sudo service apache2 reload

1.2.2 Add hostname to hosts file

Edit your system's map of hostnames to IP addresses

$ sudo nano /etc/hosts

Add your domain and save

127.0.0.1 mylxhive.com

1.2.3 Verify your server is set up correctly

$ ping mylxhive.com

# should return something like this

PING mylxhive.com (xx.xxx.xxx.xxx) 56(84) bytes of data.
64 bytes from mylxhive.com (xx.xxx.xxx.xxx): icmp_seq=1 ttl=54 time=10.3 ms
64 bytes from mylxhive.com (xx.xxx.xxx.xxx) icmp_seq=2 ttl=54 time=8.17 ms

...
  • Note: Some environments might block ping requests.
  • Note: There is NO root endpoint (/), requests to http:(s)://mylxhive.com/ will always return 404 Not Found

1.3 Set up lxHive local file storage

1.3.1 Create storage folders

Move into lxhive app root directory

$ cd /home/lrs/www/lxHive

Examine the xApi Config file

$ cat ./src/xAPI/Config/Config.yml

Find the filesystem settings

...

filesystem:
    exposed_url: /attachments
    in_use: local
    local: { root_dir: '%app.root%/storage/files' }

...

filestsystem.local defines the storage location relative to the lxhive app root.

Manually create these folders (This will be automated in future releases)

# verify if we are still in app root
$ pwd
/home/lrs/www/lxHive

# create folder /home/lrs/www/lxHive/storage/files and /home/lrs/www/lxHive/storage/logs
$ mkdir -p ./storage/files
$ mkdir -p ./storage/logs

1.3.1 Set rwx permissions for storage folders

The storage folder and it's subfolders require read/write/create permissions for your server. There are multiple approaches, depending on your server configuration and your privacy policy.

This is just one way to do it.

#set ownership (recursively) to Apache user (Apache2/Ubuntu)
$ sudo chown -R www-data:www-data ./storage

1.4 The ./X client

The ./X terminal is your tool for administrating your LRS.

Move into lxhive app root directory

$ cd /home/lrs/www/lxHive

Start the X client

$ ./X
# outputs a list of all available ./X commands

Read briefly through the command options the .X client offers. We will use some in the next steps.

1.5 Set up Mongo database

Create/register your lxHive data storage. This requires two steps:

1.5.1 Database configuration

$ ./X setup:db

This triggers a series of prompts:

  • Define name of your lxHive instance (required)
  • Define the name of your database (required)
  • Define the uri of your database (optional: enter for default)
$ ./X setup:db
Welcome to the setup of lxHive!
Enter a name for this lxHive instance: sandbox
Enter the URI of your MongoDB installation (default: "mongodb://127.0.0.1"):
Connection successful, MongoDB version 2.6.11.
Enter the name of your MongoDB database (default: "lxHive"): mylxhive
DB setup complete!

1.5.2 create (o)Authentication scopes

$ ./X setup:oauth
Setting up default OAuth scopes...
OAuth scopes configured!

At this stage your Mongo database has been created and populated with the default authentication scopes

1.5.2.1 Verify database (optional)

At this stage you might want to check the database

Start Mongo terminal, select your new lxhive database and show collections

$ mongo
MongoDB shell version: 3.0.12
> use mylxhive
switched to db mylxhive
> show collections
authScopes
system.indexes

Not much going on there yet... More collections will be added in later steps

1.6 Create Super user

Create your first user. This should be an administrative user with super permissions

$ ./X user:create

This starts a prompt sequence:

  • Enter user email (required) . This email will be used later to map users to authentication tokens
  • Enter password (required)
  • Select permissions: As we are creating the admin user we select super (0).
$ ./X user:create
Please enter an e-mail: admin@mylxhive.com
Please enter a password: *******
Please select which permissions you would like to enable (defaults to super). Separate multiple values with commas (without spaces). If you select super, all other permissions are also inherited:
  [0] super
  [1] statements/write
  [2] statements/read
  [3] statements/read/mine
  [4] attachments
  [5] state
  [6] profile
  [7] define
  [8] all/read
  [9] all
 > 0 #super user
User successfully created!
Info:
{
    "email": "admin@mylxhive.com",
    "passwordHash": "b762ad8a5f1e24ed836c84b9dca8bf5f6b27d6e6",
    "permissionIds": [
        {
            "$id": "57da0fa36bbbacd35d8b4567"
        }
    ],
    "_id": {
        "$id": "57da10036bbbacdc5d8b4567"
    }
}

Note: When we create users for our applications then we need to select the permissions more careful. See the xAPI specs for definition of the scopes

1.7. Test the LRS

At this point your LRS is operational! You can test this by calling the /about endpoint.

Either open a browser and go to http://mylxhive.com/about or enter the following in your terminal:

$ curl http://mylxhive.com/about`
{"version":["1.0.2"]}

The about endpoint is public and returns some JSON information about your LRS

  • Note: The /about is the ONLY public resource available on lxHive
  • Note: There is NO root endpoint (/), requests to http:(s)://mylxhive.com/ will always return 404 Not Found

2. Registering Applications for your LRS

In order to connect your application to your LRS you need to authenticate it with lxHvive.

We currently support 3 (or more correctly: 2 1/2) authentication methods.

  1. HTTP Basic Authentication: MACHINE-to-LRS
  2. oAuth2 (three-legged): HUMAN-to-LRS
  3. Temporary Access Token: MACHINE/HUMAN-to-LRS

The temporary access token is a more secure way to perform HTTP Basic Authentication without leaking your password/secret. See our Wiki for more info.

1. Registering a Basic Token

Move into lxhive app root directory.

$ cd /home/lrs/www/lxHive

Start the ./X terminal and run the command

./X auth:basic:create

This starts a prompt sequence:

  • Enter name (required)
  • Enter description (required)
  • enter expire date for token (optional, skip with enter key)
  • Associate the user connected to this token via a registered user email See (step 1.6)
  • Define the scope for this application. This is a sub-scope of the user scope you assigned in step 1.6
$ ./X auth:basic:create
Please enter a name: testaccount
Please enter a description: test account
Please enter the expiration timestamp for the token (blank == indefinite):
Please enter enter the e-mail of the associated user: admin@mylxhive.com
Please select which scopes you would like to enable (defaults to super). Separate multiple values with commas (without spaces). If you select super, all other permissions are also inherited:
  [0] super
  [1] statements/write
  [2] statements/read
  [3] statements/read/mine
  [4] attachments
  [5] state
  [6] profile
  [7] define
  [8] all/read
  [9] all
 > 9
Basic token successfully created!
Info:
{
    "userId": {
        "$id": "57da10036bbbacdc5d8b4567"
    },
    "key": "mGrId54hISqgS1Jb38TvckCw5uqKLhsSCygAYi0f",
    "secret": "weFj5IOneZx7O3r3Y4jODuD8elGQMczjGqCXve5j",
    "expiresAt": null,
    "createdAt": {
        "sec": 1473909116,
        "usec": 0
    },
    "name": "testaccount",
    "description": "test account",
    "scopeIds": [
        {
            "$id": "57da0fa36bbbacd35d8b4570"
        }
    ],
    "_id": {
        "$id": "57da117c6bbbac2d5e8b4567"
    }
}

Use key and secret in your app for any request to lxHive (HTTP BASIC authentication header)

Pseudo code:

headers[] = 'Authorization: ' + base64encode(<key>:<secret>);

A node.js http example.

var http = require('http');

var base64 = new Buffer('mGrId54hISqgS1Jb38TvckCw5uqKLhsSCygAYi0f' + ':' + 'weFj5IOneZx7O3r3Y4jODuD8elGQMczjGqCXve5j').toString('base64');

var options = {
  host: 'www.mylrs.com',
  path: '/statements',
  method: 'GET',
  headers: {
    'Authorization': 'Basic ' + base64,
    'X-Experience-API-Version': '1.0.2'
  }
};

http.get(options, function(response) {
        var body = '';
        response.on('data', function(d) {
            body += d;
        });
        response.on('end', function() {
            // Data complete, now trigger your callback
        });
    });

2. Register an oAuth2 client (human login)

lxHive oAuth2 is a browser based login. In short: Your app forwards the user to a login page on your LRS. After successfully logging in the user gets redirected back to your app. A more detailed explanation can be found in the following resources:

We are going to set up an oAuth2 token access client on lxHive.

Move into lxhive app root directory.

$ cd /home/lrs/www/lxHive

Start the ./X terminal and run the command

./X oauth:client:create

This starts a prompt sequence:

  • Enter name (required)
  • Enter description (required)
  • Enter the redirect URI: This is the (absolute) Url of your app. Your user will get redirected to this url after a successful login.
$ ./X oauth:client:create
Please enter a name: tester
Please enter a description: test account
Please enter a redirect URI: http://my-app.com/app/ #example url
OAuth client successfully created!
Info:
{
    "clientId": "ZhAOj7Rizs9hGFEN055xhkwt2yi5VgC00NRDeMUg",
    "secret": "RbSnTJ0XdyuoOyaH5lC9BpLbAxw8aBld7KnwJ3nK",
    "description": "test account",
    "name": "tester",
    "redirectUri": "http:\/\/my-app.com\/app\/",
    "_id": {
        "$id": "57da23386bbbacd7618b4567"
    }
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally