OAuth support in Turnilo

[adrianmroz-allegro]

In 1.32.0 we added support for OAuth in Turnilo.

How it works

• Turnilo redirects user to authorisation page
• After successful authorisation, received code is exchanged for token. See flow details here
• Received token is kept in browser and sent to server whenever client requests data sources information or issues query.

As you can see, Turnilo does only authorisation part which is regulated with OAuth spec. You need to secure your endpoints on the server with plugins.

Configuration

To enable OAuth support you need to add top level oauth option in your config with following fields:

• clientId: OAuth Client Identifier for your Turnilo instance
• tokenEndpoint: Full address of your token endpoint
• authorizationEndpoint: Full address of your authorization endpoint
• redirectUri: Full address of your Turnilo installation. If you go to this address in browser, your Turnilo install should launch and show home view.
• tokenHeaderName: Name of your choosing for the OAuth token header. You will be reading this header in your server plugin.

Example:

oauth:
  clientId: "turnilo"
  tokenEndpoint: "https://oauth.example.com/auth/oauth/token"
  authorizationEndpoint: "https://oauth.example.com/auth/oauth/authorize"
  tokenHeaderName: "x-turnilo-oauth-token"
  redirectUri: "https://turnilo.example.com/"

Server plugin

Now every request to backend has header with user token. You can write plugin for server where you check token with your identity server and restrict access. You can also set allowed-datacubes setting, but more about it later.

We use plugin that looks something like this:

function plugin(app, pluginConfig, serverConfig, appConfigGetter, logger) {
  app.use(async (req, res, next) => {
    // If path is not restricted, pass control to next handler. We restrict only `/settings` and `/plywood` endpoints
    if (!isRestrictedPath(req.path)) {
      next();
      return;
    }
    // Plugins have access to appSettings, so we get oauth settings from there
    const appConfig = await appConfigGetter();
    const oauth = appConfig.oauth;
    // We read header with token. We can use tokenHeaderName to pick correct one.
    const token = req.header(oauth.tokenHeaderName);
    // If no token is present, we return 401 and Turnilo handles it on the client
    if (!token) {
      res.status(401).send();
      return;
    }
    // We send request to our identity server with token and client credentials. 
    checkToken(token, ...)
      .then((resp) => {
        // In turniloMetadata object we save user authorities to use in later plugins.
        req.turniloMetadata.authorities = resp.data.authorities;
        next();
      })
      .catch((error) => {
        // In case of error, we return 403 and Turnilo handles it on the client
        res.status(403).send();
      });
  });
}

What can I do with token?

1. You can return 401/403 for users with insufficient permissions and Turnilo would show error.
2. You can set x-turnilo-allow-datacubes header based on users permissions. Please note, that this feature will change in the future. We want to keep functionality but we would prefer to use turniloMetadata object instead of header.
3. You can set some information on turniloMetadata object and use it in your query decorator. You could hide some rows for specific users.

What is next?

We want to smooth the edges around x-turnilo-allow-datacubes. We started some discussion there in #714 .
Because list of data sources is now behind endpoint we also have some technical debt around that.

[adrianmroz-allegro]

To reiterate on #714:

We want to remove x-turnilo-allow-datacubes header. You should put that information into turniloMetadata. Plugin for backward compatibility is simple:

function plugin(app, pluginConfig, serverConfig, appConfig) {
  app.use(function (req, res, next) {
    const allowedDataCubes = req.headers["x-turnilo-allow-datacubes"];
    req.turniloMetadata.allowedDatacubes = allowedDataCubes;
    next();
  });
}

Because you requested some new features around this, the API is not final (and we'd not decided yet on names ;)).

We would like to add ability to not only restrict access to data cube but also better handle restricted data cube. For example some data cubes should be hidden, but sometimes it would be nice if Turnilo would show message like "You have no access to this Data Cube. Contact your Administrator".

[VA-PLE]

Hi. Please tell me what I am missing when I turn on OAuth. The documentation says that it is enough to add only

oauth:
  clientId: "turnilo"
  tokenEndpoint: "https://oauth.example.com/auth/oauth/token"
  authorizationEndpoint: "https://oauth.example.com/auth/oauth/authorize"
  tokenHeaderName: "x-turnilo-oauth-token"
  redirectUri: "https://turnilo.example.com/"

to top level in config file. After applying the new configuration, I don't get any effect or errors. What am I doing wrong? Turnilo v1.40.1

[adrianmroz-allegro]

Yo still need to write a server plugin as described in first post here.