4. Administration¶

The BI Explorer is a python web application that runs against a PostgreSQL server. The database connection parameters are set in the explorer configuration file.

4.1. Explorer Configuration¶

The configuration of the main Explorer application is stored in a YAML file. Separately from this file, there is a directory with filters, presets, projections and reports.

4.1.1. Sessions¶

Server side caches are tied to users using Web sessions. Users receive a user specific http-cookie that facilitates quick continuation of a session without additional login. SECRET_KEY is an arbitrary secret that is used to encode the session data. It should be set to a new value for every explorer installation.

4.1.2. Program caches¶

The explorer uses program caches to store information that is used often.

The short_term cache is used to cache distinctlists, which are used to enumerate possible filter values found in the explorer table.

The platform_api cache is used to cache shared preset results typically used for dashboards. Using this cache data can already be calculated and stored before a user requests it.

4.1.3. User security¶

User passwords are salted, peppered and hashed using sha512 to the database. The salt is randomly generated and stored per user. The SECRET_KEY is used to encode data in the cookie before sending it to the user.

Make sure SECURITY_PEPPER, SECRET_KEY are set differently per explorer installation.

The JSON Web Token settings (SECURITY_JWT_*) are part of the Platform API as used by the MGRID Dashboard, so these should match on both sides. The SECURITY_PLATFORM_USER should match the subject in the JWT.

User roles are obtained during login (e.g., using OAuth2). A role determines thw following access:

SECURITY_PII_ROLES: which roles are allowed to see personally identifiable information (PII).
SECURITY_ADMIN_ROLES: which roles are allowed to change configuration using the configadmin page.
SECURITY_GROUP_MANAGEMENT_ROLES: which roles are allowed to create and manage group presets.
SECURITY_PRESET_MANAGEMENT_ROLES: which roles are allowed to create and manage public presets.

4.2. SSL configuration¶

The nginx software is used to expose the web application externally. By default the Python webcontainer is configured to only serve on 127.0.0.1. Additional configuration in /etc/nginx/nginx.conf:

user              nginx;
worker_processes  1;

error_log  /var/log/nginx/error.log;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;

    keepalive_timeout  65;

    include /etc/nginx/conf.d/*.conf;

    ssl_protocols  TLSv1 TLSv1.1 TLSv1.2;
}

With /etc/nginx/conf.d/explorer.conf:

upstream explorer-site {
    server 127.0.0.1:6543;
}

server {
    listen 443 ssl;
    server_name  explorer.outsidename.nl;
    ssl_certificate /etc/ssl/explorer/server.crt;
    ssl_certificate_key /etc/ssl/explorer/server.key;

    location / {
        proxy_set_header        Host $http_host;
        proxy_set_header        X-Real-IP $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header        X-Forwarded-Proto $scheme;

        client_max_body_size    10m;
        client_body_buffer_size 128k;
        proxy_connect_timeout   60s;
        proxy_send_timeout      90s;
        proxy_read_timeout      90s;
        proxy_buffering         off;
        proxy_temp_file_write_size 64k;
        proxy_pass http://explorer-site;
        proxy_redirect          off;
    }
}

4.3. User Management¶

User management is done using the command line tool invoke. This tool determines database location using a configuration file (set through the environment variable APP_CONFIG_FILE), and can be instructed to add, remove and list users. It should be run from the explorer application directory (/opt/mgrid/explorer).

$ invoke --list app.user
Available 'app.user' tasks:

  .add        Add a user
  .grant      Grant role to a user
  .list       List all users
  .password   Change password of a user
  .remove     Remove a user
  .revoke     Revoke role from a user

Default 'app.user' task: .list