Skip to content

Security

SlashDB uses a two-part security model:

Each request to the API must be made as a specific SlashDB user. In the diagram above, they are John, App1 and App2. These users can be authenticated by passing valid credentials using one of these methods:

Info

Each SlashDB user (light blue in the diagram) can be mapped to a database login. Once a mapping has been created, the user can execute queries on the database with the privileges of the assigned database account (db_user1, db_user2 or db_admin, purple in the diagram). Database permissions are effectively passed on to the SlashDB user.

Scenario 1

John navigates to the SlashDB application using a browser. He logs in using his SlashDB username and password. He is identified as John and his browser receives a cookie. The cookie is sent with each subsequent request.

John's account in SlashDB has been configured to use the db_user1 database account when making queries. John can SELECT or UPDATE data, as those are the privileges for the db_user1 account.

Scenario 2

A mobile application sends SlashDB credentials using the Basic Authentication method. The credentials identifies the mobile application as SlashDB user App1, which uses the database account db_user2 for the database. App1 can only SELECT data.

Scenario 3

A backend process utilizes an API key to authenticate, which is sent with every request. The application is recognized as SlashDB user App2, which uses database account db_admin. This application can SELECT, UPDATE, INSERT and DELETE data.

System Accounts

SlashDB has two special system accounts, admin and public.

admin

The SlashDB administrator account admin has system-wide access to the SlashDB configuration.

public

Important

SlashDB treats unauthenticated requests as being sent by the public user.

You can set permissions for public just like any other user on the User Configuration screen.

For example, you can give public access to the Chinook database with a mapping.

Now that public has a mapping for Chinook, an unauthenticated request to the /db endpoint will return Chinook as an available database:

curl -i 'http://localhost/db.json'

HTTP/1.1 200 OK
{
    "Chinook": "/db/Chinook.json",
    "__href": "/db.json"
}

If you remove the mapping for Chinook, and public has no other mappings, the /db endpoint will return a 404 error:

curl -i 'http://localhost/db.json'

HTTP/1.1 404 Not Found
Warning: No models for user public.

{"http_code": 404, "description": "No models for user public."}

If you remove the public user, the /db endpoint will return a 403 Forbidden error:

curl -i 'http://localhost/db.json'

HTTP/1.1 403 Forbidden
Warning: Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key.

{"http_code": 403, "description": "Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key."}

Failed Authentication

Whenever a client sends a request to SlashDB with unrecognized credentials (e.g. an invalid API token) a 403 Forbidden response is returned.

The response Warning header will contain an error message, and the response body will contain the HTTP status code and the error message, in the same format as the request was sent.

curl -i "https://localhost/userdef/admin.json"


HTTP/1.1 403 Forbidden
Server: nginx/1.12.2
Date: Mon, 23 Sep 2019 08:56:41 GMT
Content-Type: application/json
Content-Length: 159
Connection: keep-alive
Warning: Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key.

{"http_code": 403, "description": "Access was denied to this resource. Please log in with your username/password or resend your request with a valid API key."}

Info

More information about status codes can be found in sections about Client Errors and Server Errors.

HTTPS/SSL

It is strongly recommended to configure SlashDB to use SSL certificates to encrypt the communication between clients and the server.

To enable SSL, you will need:

  • a private key and a certificate
  • SSH access to the SlashDB deployment to upload files
  • a modified NGINX configuration (/etc/slashdb/nginx.conf)

Tip

Let's Encrypt is a certificate authority providing free SSL certificates. Visit the Getting Started page to find out how to correctly set up a free and renewable certificate.

Installing an SSL certificate

Once you have a private key and certificate for your domain, you only need to upload the files to the SlashDB server and then update the NGINX configuration.

For testing or development purposes only, you may generate a self-signed certificate. However, client browsers and REST clients will raise warnings about insecure communication.

Run the command below to generate a self-signed key and certificate and save them in /etc/slashdb directory

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/slashdb/nginx-selfsigned.key \
-out /etc/slashdb/nginx-selfsigned.crt

Configuring HTTPS in NGINX

Add the NGINX directives listen, ssl_certificate and ssl_certificate_key to the NGINX configuration file /etc/slashdb/nginx.conf.

server {
    listen 80;
    listen 443 ssl;
    server_name your-slashdb-domain.com;
    ssl_certificate /etc/slashdb/nginx-selfsigned.crt;
    ssl_certificate_key /etc/slashdb/nginx-selfsigned.key;
}

Info

It's recommended to redirect traffic from HTTP to HTTPS. To do so:

  • create an additional server object in NGINX config that redirects clients to the HTTPS URL
  • comment out the listen 80 directive in the server with HTTPS configuration
server {
    listen 80;
    server_name your-slashdb-domain.com;
    return 301 https://$host$request_uri;
}

server {
    #listen 80;
    listen 443 ssl;
    server_name your-slashdb-domain.com;
    ssl_certificate /etc/slashdb/nginx-selfsigned.crt;
    ssl_certificate_key /etc/slashdb/nginx-selfsigned.key;

    location ~ /db*|/query* {
       uwsgi_pass              slashdb_app;
       include                 uwsgi_params;
    }
}

Then restart the NGINX server to apply changes:

sudo /etc/init.d/nginx restart`

Info

Remember to allow inbound traffic on port 443, especially for Microsoft Azure or Amazon EC2.

More info about configuring a server for HTTPS can be found in this tutorial.

AWS

Info

The AWS EC2 instances of SlashDB can be set up with an AWS Application Load Balancer to create a single endpoint for the service. AWS Certificate Manager can be used to easily manage SSL/TLS certificates.

For more information, read the AWS Application Load Balancer and AWS Certificate Manager documentation.

Cross-Origin Resource Sharing (CORS)

CORS is a mechanism that controls which origins (domains) are accepted by a SlashDB server and what HTTP methods and headers are exposed to those domains.

Those rules can be configured in the SlashDB INI Settings file /etc/slashdb/slashdb.ini in the section [filter:cors]. By default SlashDB comes with a free policy which allows traffic from any domain.

[filter:cors]
use = egg:wsgicors#middleware
# CORS available policies
# "free" policy
free_origin=copy
free_headers=*
free_expose_headers=Set-Cookie, Warning
free_methods=HEAD, OPTIONS, GET, POST, PUT, DELETE
free_maxage=180
free_credentials=true

# CORS enabled policies
policy=free

Info

Refer to wsgicors documentation for details on setting up CORS policies.