Authentication

Out of the box SlashDB provides most common authentication mechanisms:

Single Sign On
API Key
Basic Authentication
Login and password
Cookie Session
Public (unauthenticated) access

Other methods can be added to SlashDB using custom WSGI middlewares or by making SlashDB an endpoint behind a third party authentication system.

SSO / OpenID Connect

This feature is available only in Enterprise Edition

Authentication can be delegated to Identity Providers like MS Azure AD, Okta, PingOne, Google, and other that implement OpenID Connect.

In order to authenticate and authorize request SlashDB:

takes the ID Token sent as JWT in header Authorization,
takes identity provider id from header X-Identity-Provider-Id,
verifies the token and its signature with proper identity provider,
finds SlashDB user by comparing value of the claim of the id token with attribute in user config e.g. id token email == user config email,
checks permission to the requested resource.

When process is successful a response with resource is returned. In the case of HTML format a Set-Cookie header is sent to create a browser session.

Setup

Install SlashDB License that allows SSO.

Enable SSO by editing /etc/slashdb/auth.cfg and configuring identity providers. By default the auth.cfg file is delivered with disabled JWT authentication policy

The jwt section has to be enabled and identity providers must be configured properly

jwt:
  enabled: True
  priority: 10
  gui:
    visible: True
  identity_providers:
    myidp:
      idp_name: IDP Name
      enabled: False
      jwks_uri: https://path/to/jwks
      claim_attribute: email
      user_config_attribute: email
      authorization_endpoint: https://path/to/authorization/endpoint
      token_endpoint: https://path/to/token/endpoint
      client_id: client id in identity provider app
      redirect_uri: https://localhost/login/callback?idp_id=myidp # important to provide query string idp_id=myidp
      response_type: code # id_token or code
      scope: openid email
      gui:
        visible: True

Properties of jwt authentication policy:

enabled is a switch to enable jwt authentication. Accepts values True or False.
priority is a priority of the authentication policy in which the request is checked. Lower number is higher priority. Priority 1 means it will be the first authentication policy to check.
gui is a sub-section with properties for configuring GUI on the login page:
- visible is a switch to show or hide authentication policy on the login page. Accepts values True or False.
identity providers is a sub-section for configuring identity providers (IDP):
- myidp is a unique ID of the IDP. Allowed characters are ASCII letters a-z, uppercase A-Z, digits 0-9 and characters: @, _, ~ (tilde) and - (dash). Creates a sub-section of properties for the IDP:
  - idp_name is a full name of the IDP that appears in GUI,
  - enabled is a switch to enable authenticating with the IDP,
  - jwks_uri is a URL or path to file with JWSK on the server in JSON format. JWKS contains a set of public keys that will be used to verify signature in JWT.
  - claim_attribute is a property of the ID Token that will be used to match with attribute of the SlashDB user configuration e.g. email from ID Token is searched among emails used in SlashDB user configurations to pick right user and his privileges.
  - authorization_endpoint is a URL of the IDP that is used in OpenID Connect protocol to receive Authorization Code (when response_type is code) or ID Token (when response_type is id_token).
  - token_endpoint is a URL of the IDP that is used to receive tokens,
  - client_id is a unique ID created by the IDP to identify the application,
  - redirect_uri is a redirect URI required by OpenID Connect protocol for returning Authorization Code or ID Token. You'll have to:
    - set your own domain e.g. https://slashdb.my-server.com,
    - keep the path as is /login/callback
    - append query string with the unique ID of the IDP e.g. ?idp_id=myidp
    The full redirect_uri could look like: https://slashdb.my-server.com/login/callback?idp_id=myidp
  - response_type defines what type of OpenID Connect flow should be used with the IDP, use:
    - code for Authorization Code Flow with Proof Key for Code Exchange (PKCE)
    - id_token for Implicit Flow
  - scope are names of IDP scopes that will be providing required information pieces in token
  - gui is a sub-section with properties for GUI regarding certain IDP
    - visible is a switch to show or hide the button for signing in with that IDP.

For example configuration of Okta service:

After making changes restart SlashDB.

sudo systemctl restart slashdb

If SlashDB doesn't start it probably means the auth.cfg file is invalid after changes. Check logs at /var/log/slashdb/slashdb.log for any errors regarding authentication policies.

Log in using Single Sign On

Go to page /login. New section is added with separate button for each configured identity provider.

Authorize request with JWT token

A request from REST client can authorized by validating headers:

X-Identity-Provider-Id with ID of the Identity Provider that is configured in /etc/slashdb/auth.cfg
Authorization with Bearer with ID Token in a form of JWT

for example

curl -i 'http://localhost/db.json' \
-H 'X-Identity-Provider-ID: okta' \
-H 'Authorization: Bearer ZXlKcmFXUWlPaUpRYTBoVU1YSnJUalpEY1MxWlFXaENXWEpNWWtsblMwOXZWRVZyVlMxaWNVTjBiMlpNYmxWQ1QwdFpJaXdpWVd4bklqb2lVbE15TlRZaWZRLmV5SnpkV0lpT2lJd01IVmtZMlpyTTJsd2RtNTRVakpTV2pWa05pSXNJbVZ0WVdsc0lqb2lhbTlvYmk1MGRYUnZjbWxoYkVCbmFYUmlhWFF1Y0d3aUxDSjJaWElpT2pFc0ltbHpjeUk2SW1oMGRIQnpPaTh2WjJsMFltbDBMbTlyZEdFdVkyOXRJaXdpWVhWa0lqb2lNRzloWkdOaGMyTmpUMmR2V0hSaU5YWTFaRFlpTENKcFlYUWlPakUyTVRjd01EZ3dNelVzSW1WNGNDSTZNVFl4TnpBeE1UWXpOU3dpYW5ScElqb2lTVVF1UWxCRlNFVkdXV3hsUlU1MU9USndkRFoxWTFKRFExTXdWekJFY1cxRGVGWkVSWGRCYm5jMFoxQXpZeUlzSW1GdGNpSTZXeUp3ZDJRaVhTd2lhV1J3SWpvaU1EQnZaR00xWjJab1JHTXhPSGhJYzFBMVpEWWlMQ0p1YjI1alpTSTZJakEzYm5wa05DNXZTSFZ3YzJaWVNVSXRkRVZzUlMxc2RIUlNTRWQzVTBaS2VUZEljWEZ3ZHpsMVZWOVFSVkJqWXpodlUxSkRkRVJOTG0xLWIxODRjR3gwVkcxTGRXSm1NalJyWTNGc1ltRXpZbHBPVFV3eVJESjVZaTVrZVZvNGVGcE5lREphTGtaMk5UbHlTMzVwTG5aUmJqbFBWRk5SVDFBM2JsUldOVUpHSWl3aVlYVjBhRjkwYVcxbElqb3hOakUzTURBNE1ETXpMQ0poZEY5b1lYTm9Jam9pTlV0dVRqaHdYME5RT1ZwSVMxOWpRa2hmWkdKRFFTSjkuQjZuc3FVeDZzUXgyTWVHR1JYSWZ5ZncyNFFyVmhhb1JUZWFiNjM3Qnp4a3JDYlZEeUlxUUREWm9ZVE5NcHh1OFg3MFY3X0UyZ0tHU2JCT1N5U3VTTzNtQjZsUnZnS0E2QVhERmc2aC13STRydUNsZno1OEpYd3lPZW03MU1ISmF6dE9XYkhuSWFGNlJLRzRWTUNmaDRlcVlzaGRvcURQMFVpV1ZtU0RzYUhvUVRHQWVFaVpZV0hZU1RWbkVvb3puVVFxUFNsVktYWW84V3Z0U0NhVUwyY3YyREh3d0dzeFc1dFRjeE1HWjhzajRvTC1PVkN3c29zX3BXM1VrNDZoMVhiMEZ2aFUwUHZ2WXdzX0NhTklTZ3YtUXdTTUtRTEpab0lsWDR3V0NhenNPYUlxS0pTaTVNX2tYT1F6OTQzTF9ENzRONkhucHZ3MmQwN00yTGNnY3p3' \

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 29 Mar 2021 09:07:48 GMT
Content-Type: application/json
Content-Length: 544
Connection: keep-alive

[
    {
        "db_id": "Chinook",
        "__href": "/db/Chinook.json",
        "type": "sqlite",
        "description": "Example SQLite database",
        "status": "Disconnected"
    },
    {
        "db_id": "Northwind",
        "__href": "/db/Northwind.json",
        "type": "mssql",
        "description": "MS Sample Database",
        "status": "Connected"
    },
    {
        "db_id": "mysqlChinook",
        "__href": "/db/mysqlChinook.json",
        "type": "mysql",
        "description": "",
        "status": "Connected"
    }
]

API Key

There are two types of api keys available in SlashDB:

single parameter (apikey)
two parameters (appid and apikey)

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.

When valid API key is used for html format e.g. when using browser a cookie will be sent in response and browser will keep user logged in.

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 Red Hat 3scale API Management. 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 'appid: app1ABC' \
-H 'apikey: q7afxhxmyetbbq0ufi4bus82gglmzr0u'

HTTP/1.1 200 OK

Request with API key in query string - Access granted

curl -i 'http://localhost/db/Chinook2.json?appid=app1ABC&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

Cookies are mostly used by browsers for GUI to keep users logged in. A cookie is sent to the browser after successful authentication.

In SlashDB configuration file /etc/slashdb/slashdb.ini we have several parameters to tune up sessions and cookies.

memcached_server is server host and port e.g. 127.0.0.1:11211 of Memached server that is used for keeping processes and nodes sychronized.
session.secret takes part in encryption of the session cookie. Should be unique and random. Instances in the cluster should have the same secret.
session.timeout is number of seconds after which inactive user is logged out, by default 3600s (1 hour).
session.cookie_expires is number of seconds after which a cookie is valid and the session is invalidated too, by default 86400s (1 day).
cookie_http_only sets cookie httpOnly flag. True or False, by defualt True
cookie_secure sets cookie secure flag. True, False or auto, by default auto. When set to auto then cookie flag is set when it's request is using HTTPS.
session.type is a type how session is stored:
- cookie session information is stored client-side - in user's browser
- file session information is stored server-side in file system. Only session id in user's browser.
- ext:memcached session information is stored server-side in shared Memcached. Only session id in user's browser.
By default, if memcached_server is defined then ext:memcached else file.
session.url is Memcached server location, by default takes value from memcached_server
session.data_dir is a path to the folder where session files are stored, by default /var/lib/slashdb/sessions/data. Option valid when memacahed_server is undefined or session.type is file.
session.lock_dir is a lock used to ensure that multiple processes/threads are not attempting to make changes in stored sessions.

Server-side session

The session information is kept in the backend in files or shared memory memcached. A cookie that is sent to the client contains only session id. This is more secure and allows to invalidate sessions by system administrator.

For single process setup it's fine to keep sessions in file system. Update the /etc/slashdb/slashdb.ini accordingly:

For multi-process or multi-node setup session must be kept in memcache. Update the /etc/slashdb/slashdb.ini accordingly:

# Memcached server
memcached_server = 127.0.0.1:11211

# IMPORTANT: Please generate a new secret key for this SlashDB instance.
# Instances running in a cluster should have the same secret key.
# Keep the secret key used in production secret!
session.secret = 84eXRmVUdsMCRzSDycbLEQmej8wKRR

# How long a session is valid in sec.
session.timeout = 3600

# How long a cookie is valid in sec.
cookie_max_age = 86400

# Cookie httpOnly and secure flags
cookie_http_only = True
cookie_secure = auto

Client-side session

The session information is encrypted in the cookie and the cookie is systematically substituted to extend the user's session. The backend is not involved in keeping the session which is easier setup for multi-process or multi-node setup but it's not possible to invalidate cookie until it expires.


# IMPORTANT: Please generate a new secret key for this SlashDB instance.
# Instances running in a cluster should have the same secret key.
# Keep the secret key used in production secret!
session.secret = 84eXRmVUdsMCRzSDycbLEQmej8wKRR

# How long a session is valid in sec.
session.timeout = 3600

# How long a cookie is valid in sec.
cookie_max_age = 86400

# Cookie httpOnly and secure flags
cookie_http_only = True
cookie_secure = auto

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

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'

Authenticating Proxy

URLs in SlashDB are unique references to data. As a result optionally we can integrate the API service with an authorization system that would decide if incoming request should be sent to SlashDB. Solutions like that are typically implemented using authenticating proxies in conjunction with single sign-on and entitlement systems. If you require this level of integration please contact us.

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

Logging in using the GUI

User can explore resources in SlashDB using a browser but first he has to log in with username and password on login page /login'. The "Log in" button is visible in top right corner of the GUI when session is not initiated.

clicking on the button navigates to log in page that shows available logging in methods.

log in button

After logging the log in button is replaced with user name and dropdown menu with user's settings and button for logging out.

log in button

Log in throttling

Too frequent attempts to log in cause error responses with HTTP status 429 Too Many Requests. By default SlashDB allow average rate of 1 request per minute with temporary burst of 5 login requests.

The throttling can be adjusted in /etc/slashdb/nginx.conf by modifying NGINX configuration limit_req_zone

Most useful parameters are rate in line

limit_req_zone $limit_login_post zone=login_limit:20m rate=1r/m;

and burst in line

limit_req zone=login_limit burst=5 nodelay;

Example:

Below is part of http section of /etc/slashdb/nginx.conf that limits request rate to average 1 request per minute allowing temporary burst of 5 extra requests. When rate is exceeded error response with status code 429 is returned

limit_req_zone $limit_login_post zone=login_limit:20m rate=1r/m;

location / {
    uwsgi_pass  slashdb_app;
    include     uwsgi_params;

    location /login {
        # allow up to 5 requests in queue, then reject
        limit_req zone=login_limit burst=5 nodelay;
        uwsgi_pass slashdb_app;
        add_header Retry-After $retry_after always;
    }
}

User enumeration

To prevent revelation of existing user names the successful or failed logging in always takes exactly the same time.

Changing password

The password can be updated in User Configuration.

Regular users must provide current password to set a new one. Only admin may change any user's password without additional validation.

Password strength

The password strength leven can be set in INI settings with value from 0 to 4, where 0 is the weakest and 4 is strongest.

0 - too guessable: risky password. (guesses < 10³)

1 - very guessable: protection from throttled online attacks. (guesses < 10⁶)

2 - somewhat guessable: protection from unthrottled online attacks. (guesses < 10⁸)

3 - safely unguessable: moderate protection from offline slow-hash scenario. (guesses < 10¹⁰)

4 - very unguessable: strong protection from offline slow-hash scenario. (guesses >= 10¹⁰)

Example:

Password strength set to safely unguessable.

min_password_strength = 3

Empty password

By default, users's password is required. In case the empty password should be allowed there is an option allow_empty_password in INI settings that controls this feature

allow_empty_password = true

Out of the box SlashDB has standard login page that supports logging in using:

login and password submitted in the form
Single Sign On
API Key

The visibility of authentication methods on the log in page can be adjusted in configuration file /etc/slashdb/auth.cfg. A chosen authentication method can be switched on or off with parameter enabled set to True or False. If the authentication method is enabled then its visibility can be controlled in section gui by setting parameter visible to True or False.

For example in auth.cfg

authentication_policies:
  jwt:
    enabled: True
    priority: 10
    gui:
      visible: True
    identity_providers:
      okta:
        idp_name: Okta
        enabled: True
        jwks_uri: https://gitbit.okta.com/oauth2/v1/keys
        claim_attribute: email
        user_config_attribute: email
        authorization_endpoint: https://gitbit.okta.com/oauth2/v1/authorize
        token_endpoint: https://gitbit.okta.com/oauth2/v1/token
        client_id: 0oadcasccOgoXtb5v5d6
        redirect_uri: https://demo.slashdb.com/login/callback?idp_id=okta
        response_type: code # id_token or code
        scope: openid email
        gui:
          visible: True
  login_form:
    enabled: True
    priority: 20
    gui:
      visible: True
  apikey:
    enabled: True
    priority: 10
    appid_name: appid
    apikey_name: apikey
    gui:
      visible: False
  basic:
    enabled: True
    priority: 30
  cookie:
    enabled: True
    priority: 50

authentication_policies
- jwt
  - enabled True means SlashDB will be validating token in Authorization header
  - gui
    - visible True means to show Single Sign On section in standard login page
  - identity_providers
    - okta
      - enabled True means that requests with JWT can be identified with this identity provider okta
      - gui
        
        visible True means that a Single Sign On button for identity provider okta will show up in standard login page
- login_form
  - enabled True means it is possible to authenticate by sending login and password to /login endpoint.
  - gui
    - vibisle True means the login form will appear in the login page
- apikey
  - enabled True means it is possible to authenticate with API Key
  - gui
    - visible False means that a form to log in with API Key won't show up in standrd login page
- basic
  - enabled means SlashDB will be checking login and password as Basic Authentication sent in Authorization header
There is no gui section in for basic authentication.
- cookie:
  - enabled means SlashDB will be checking session id from cookie sent with request
There is no gui section in for basic authentication.