Joola is a secure framework, this means that any request needs to have a security context/token.

There are three ways to authenticate through joola API.

Direct REST API access

Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private information to unauthorized users.

Basic Authentication

$ curl -u "workspace/username:password" http://localhost:8080/system/version

APIToken (sent in a header)

$ curl -H "Authorization: token my-apitoken" http://localhost:8080/system/version

APIToken (sent as a parameter)

$ curl http://localhost:8080/system/version?APIToken=my-apitoken

Using the SDK

Before we can execute requests using the SDK, we need to initialize it and authenticate. During this process we will instruct the SDK what security context it should use. If authentication completes successfully, then the SDK will be immediately ready for use. If authentication fail and error will be thrown or passed to the callback.

This example shows how we can produce a authenticate using plaintext on the client-side.

var options = {
  host: 'http://localhost:8080'
};

joola.init(options, function (err, result) {
    if (err)
        throw err;
    joola.users.authenticate('workspace', 'user', 'password', function (err, token) {
        joola.TOKEN = token._;

        //joola is now ready for work, event `core.ready` is emitted
    });
});

In this example, the page/module receives the token in advance.

var options = {
  host: 'http://localhost:8080',
  token: '123456abcdef'
}
joola.init(options, function(err){
  if (err)
    throw err;

  console.log('joola is ready for work');
});

In this example, the page/module will be using an APIToken.

var options = {
  host: 'http://localhost:8080',
  APIToken: 'apitoken-demo'
}
joola.init(options, function(err){
  if (err)
    throw err;

  console.log('joola is ready for work');
});

Server-side token generation

For your app to be secure, you must ensure that sensitive tokens are never generated client-side. For this purpose, using the REST API, you can create a token on behalf of a user and communicate the secure token to the webpage for usage.

So far we have drawn visualizations without worrying about who gets to see what, but what if you need User X to see only its data, while User Y should see only hers? Joola offers a set of techniques to offer segmented, secure data views in which each user see their data segment only.

A user with the permission users:generatetoken can be used to generate secure tokens allowing users access to specific data. A user may have a filters which control the data they are allowed to view.

So, we will generate a new token using the apitoken-demo token for a user restricted by a filter, here's an example for generating a token for user to be allowed only to view data relating to the Country France.:

Generate Token [POST /tokens/{?APIToken}]

  • Parameters

    • APIToken (string, <your-token>) ... The APIToken of the user holding permission to generate tokens.
  • Request (application/json)

    {
      "username": "restricted-user",
      "password": "a-random-password",
      "displayName": "Restricted User",
      "filter": [
        ["Country", "eq", "France"]
      ],
      "roles": ["reader"]
    }
    
  • Response 200 (application/json) js { "user": { "username": "restricted-user", "displayName": "Restricted User", "filter": [ ["Country", "eq", "France"] ], "roles": ["reader"] }, "_": "0ektI1zId", "timestamp": 1399620503649, "last": 1399620503651, "expires": 1406131703000 }

The token for the new user is available in the _ field. By using this token, the user will be restricted to access only allowed data by the Filter.

To continue this example, here's a small snippet of HTML showing the usage of the new token.

<html>
  <body>
    <div id="example">

    <script src="http://localhost:8080/joola.js?token=<the-token-we-just-generated>"></script>
    <script language="javascript">
      joola.on('ready', function() {
        var options = {
          query: {
            timeframe: 'last_30_seconds',
            interval: 'second',
            dimensions: ['timestamp'],
            metrics: ['rounds.played'],
            collection: 'Gameplay'
          }
        };
        $('#example').Timeline(options);
      });
    </script>
  </body>
</html>

Learn more about SSO and Token Generation