Security
SlashDB is based on two levels of authentication and authorization.
- Access to the API
- Access to data
Accordingly
- Each request to the API has to be made on behalf of a certain SlashDB user. In above picture they are John, App1 and App2. These users can be authenticated by passing valid credentials using one of available methods: provide a cookie, basic authentication or API key.
- Each SlashDB user (pictured in blue) can be mapped to a database login (more on that in User Configuration section). As a result, every request from that user will execute queries in the database under privileges the assigned database user (db_user1, db_user2 or db_admin as pictured above in purple). Database permissions are effectively passed on to SlashDB user.
In above example we have 3 common scenarios:
- John is visiting SlashDB API via 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 db_user1 database login when making queries. Effectively John can SELECT or UPDATE data, as those are the privileges that were configured in the database.
- A mobile application sends SlashDB credentials using Basic Authentication method. The credentials identifies the mobile application as SlashDB user App1, which uses database login db_user2 when connecting to the database. Effectively App1 can only SELECT data.
- Another application utilizes an API key to authenticate, which is sent with every request. The application is recognized as SlashDB user App2, which uses database login db_admin. Effectively this application can SELECT, UPDATE, INSERT and DELETE data.
Authentication
Out of the box SlashDB provides most common authentication mechanisms:
- API Key
- Basic Authentication
- Cookie Session
- Public Access
Other methods can be added right to SlashDB using custom WSGI middlewares or by making SlashDB an endpoint behind a third party authentication system.
API Key
There are two types of api keys available in SlashDB:
- single parameter
- two parameters aka app id and secret
The API key identifies and authenticates request to access SlashDB on behalf of certain SlashDB user. The API key has to be sent either in header or in query string of each request.
The name of the header and query string argument can be changed in SlashDB ini file /etc/slashdb/slashdb.ini. More on that here.
The API key is configured in User Configuration.
Single parameter API key
Probably the easiest way to authenticate is by sending single parameter API key.
Request with API key in header - Access granted
curl -i 'http://localhost/db/Chinook2.json' \
-H 'apikey: q7afxhxmyetbbq0ufi4bus82gglmzr0u'
HTTP/1.1 200 OK
Request with API key in query string - Access granted
curl -i 'http://localhost/db/Chinook2.json?apikey=q7afxhxmyetbbq0ufi4bus82gglmzr0u'
HTTP/1.1 200 OK
Two parameters API key
SlashDB also allows a two parameters credentials in this authentication method - app id and api key. This may come handy when integrating with API management systems like 3Scale. By default header and query string argument would be:
- appid - identifies certain application
- apikey - secret for the application
Request with API key in header - Access granted
curl -i 'http://localhost/db/Chinook2.json' \
-H 'apikey: q7afxhxmyetbbq0ufi4bus82gglmzr0u'
HTTP/1.1 200 OK
Request with API key in query string - Access granted
curl -i 'http://localhost/db/Chinook2.json?apikey=q7afxhxmyetbbq0ufi4bus82gglmzr0u'
HTTP/1.1 200 OK
Basic Authentication
SlashDB supports Basic Authentication simply add the header with encoded user name and password.
curl -i 'http://localhost/db.json' \
-H 'Authorization: Basic YWRtaW46YWRtaW4='
HTTP/1.1 200 OK
Cookie Session
Cookies are mostly used by browsers for GUI. To receive correct Set-Cookie header in response we need to make a POST request with username and password to /login. We can send credentials either as a JSON or urlencoded form data.
Credentials sent as JSON
curl -i -X POST 'http://localhost/login' \
-H "Content-Type:application/json" \
-d '{"login": "admin", "password": "admin"}'
The response will be a 200 OK and will contain Set-Cookie
HTTP/1.1 200 OK
Set-Cookie: auth_tkt=a34e5f0535fada973074a68ec5eb855b5a0af71fYWRtaW4%3D!userid_type:b64unicode; Max-Age=3600; Path=/; expires=Tue, 14-Nov-2017 15:01:03 GMT
Credentials sent as urlencoded form.
curl -i -X POST 'http://localhost/login' \
-H "Content-Type:application/x-www-form-urlencoded" \
-d "login=admin" -d "password=admin" -d "came_from=/db"
The response will be 302 with Set-Cookie header and location taken from came_from data field or header referrer (if came_from is not given).
HTTP/1.1 302 Found
Location: http://localhost/db
Set-Cookie: auth_tkt=a34e5f0535fada973074a68ec5eb855b5a0af71fYWRtaW4%3D!userid_type:b64unicode; Max-Age=3600; Path=/; expires=Tue, 14-Nov-2017 15:01:03 GMT
Making requests with a cookie
Having a cookie, you can use it for requests within the session
curl -i 'http://localhost/db.json' \
-H 'Accept: application/json' \
-H 'Cookie: auth_tkt=c7e39bdd4e670d796e506ac5ddab8ba95a0af9b9YWRtaW4%3D!userid_type:b64unicode'
Ending cookie session
To end the session send a GET request to /logout. Then remove/invalidate the cookie in your application.
curl -i 'http://localhost/logout' \
-H 'Cookie: auth_tkt=c7e39bdd4e670d796e506ac5ddab8ba95a0af9b9YWRtaW4%3D!userid_type:b64unicode'
Public Access
For situations when we would like to give an open access to the API we can create/edit the SlashDB user "public".
Requests identified as "public" do not require any method of authentication. Consequently, requests, which do not contain any authentication credentials will be assigned the identity (and authorizations) of user public.
To disable public access, remove that user from SlashDB or limit his permissions in User Configuration
Authorization
SlashDB users can be granted permissions to:
- access the API, identify as correct SlashDB user
- configuration of databases, users and queries by editing SlashDB settings
- data by mapping to database login (database grants are effective)
API Access
The vary basic authorization is to API itself and some of the account information.
A user that knows credentials and has not been granted any permissions is able to change: password, API key, full name, email and decide which users can view his/her configuration. Other fields are disabled.
Authorization so limited does not make sense for utilizing SlashDB, but can be used as authority that verify credentials for other systems.
Configuration Permissions
SlashDB contains database, user and SQL Pass-Thru query configurations. Users can be given permission to access and modify those settings. These are particularly useful if you need to create one or more power user with certain administrative privileges granted to them.
In Database Configuration select:
- view list: to allow the user to view/edit the database configurations
- create new: to allow the user to connect and disconnect databases
In User Configuration we can:
this doesn't seem to fit the picture
- allow other users to view/edit the specific user configuration
- allow the user to view list of databases, users, SQL Pass-Thru queries
- allow the user to create new databases, users and SQL Pass-Thru queries
In Query Configuration we can:
- allow users to view/edit the query configuration
Data Permissions
Access to data via Data Discovery
As described in the intro at the top of this document, access to data for each user is determined by database mappings. These are configured on the User Configuration screen.
Database grants like SELECT, CREATE, UPDATE, DELETE would be configured on the database server by a database administrator.
By way of this mapping they are effectively passed on from database login to SlashDB user.
Authenticated user will only have access to databases that were set in the user's database mappings and only those databases will be listed on the Data Discovery home page /db.
Example
Let's give "mike" only read permission by mapping him to database login "ro_hr" that is granted only SELECT.
MySQL "ro_hr" login
SlashDB user "mike"
We can get data with no problem.
curl -i 'http://localhost/db/hr/departments.json' -H 'apikey: pgtw8mgdamjzx99m5mxf8sfeipwkdw0u'
HTTP/1.1 200 OK
But we can't create and we get explanation of the problem in header "Warning" and in the body of the response.
curl -i -X POST 'http://localhost/db/hr/departments.json' \
-H 'apikey: pgtw8mgdamjzx99m5mxf8sfeipwkdw0u' \
-d '{"dept_name": "New Dept", "dept_no": "d020"}'
HTTP/1.1 404 Not Found
Warning: (_mysql_exceptions.OperationalError) (1142, "INSERT command denied to user 'ro_hr'@'pc140.home' for table 'departments'")
{"http_code": 404, "description": "(_mysql_exceptions.OperationalError) (1142, \"INSERT command denied to user 'ro_hr'@'pc140.home' for table 'departments'\")"}
Access to data via SQL Pass-Thru
In Query Configuration we can define list of users allowed to execute SQL Pass-Thru query.
Administrative Permissions
User "admin" is a superuser of SlashDB and is not limited by any rules with regards to configuration. Still to access data the "admin" user has to be mapped to database logins just like a regular user does.
Public Permissions
SlashDB treats unauthenticated requests as user "public" and we can set grants for that user as any other user using User Configuration.
For example let's give public user access to Chinook database.
Requests that do not provide any authentication will identified as user public.
User public has only mapping for Chinook database thus we'll find only the Chinook on list of available databases.
curl -i 'http://localhost/db.json'
HTTP/1.1 200 OK
{
"Chinook": "/db/Chinook.json",
"__href": "/db.json"
}
When we remove Database Mapping for Chinook we receive 404 Not Found.
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."}
And if we remove user public completely we'll get 403 Forbidden.
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."}
HTTPS/SSL
HTTPS provides authentication of the web server and encryption of communication between client and server. It's strongly recommended to use it especially that it's easily configurable for SlashDB.
To enable HTTP Secure you will require a private key and a signed certificate and access to instance of SlashDB via SSH. For testing or development purposes only you may generate a self-signed certificate.
Add or edit NGINX directives listen, ssl_certificate ssl_certificate_key to /etc/slashdb/nginx/nginx.conf file
server_name your-slashdb.your-domain.com;
listen 80;
listen 443 ssl;
ssl_certificate /path/to/ssl/server.crt;
ssl_certificate_key /path/to/ssl/server.key;
and restart NGINX server
sudo /etc/init.d/nginx restart
It's also important to remember to allow inbound traffic on port 443 especially for Microsoft Azure or Amazon EC2
Creating self-signed SSL certificate
Generate a private key
Generate a CSR (Certificate Signing Request)
Remove Passphrase from Key
Generate a Self-Signed Certificate
Cross-Origin Resource Sharing (CORS)