Authentication

Out of the box, SlashDB supports many common authentication methods:

• Single Sign On (SSO)
• API Key
• Basic Authentication
• Usernames and passwords
• Cookie Session
• Public (unauthenticated) access

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

SSO / OpenID Connect

This feature is available only in Enterprise Edition

OpenID Connect is an authentication layer on top of the OAuth 2.0 authorization framework.

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

In order to authenticate/authorize request SlashDB:

• use the ID Token sent as a JSON Web Token (JWT) in the Authorization header
• use the identity provider ID in the X-Identity-Provider-Id header
• verify the token and its signature with identity provider
• finds the associated SlashDB user account by comparing the value of the claim of the token with attribute in user config e.g. id token email == user config email
• checks permission to the requested resource

When the process successfully completes, a response with a resource is returned. When requesting resources in HTML format, a Set-Cookie header is sent to create a browser session.

Setup

1. Install a SlashDB License that allows Single Sign-On (SSO) with OpenID Connect using JWT.

   

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

   

   The jwt method must be enabled and identity providers must be configured properly:

   ```yaml
   jwt:
     enabled: True
     priority: 10
     gui:
       visible: True
     identity_providers:
       myidp:
         idp_name: IdP Name
         enabled: False
         claim_attribute: email
         user_config_attribute: email
         jwks_uri: https://path/to/jwks
         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://slashdb_host/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
   ```
   

3. In section identity_providers configure each identity provider that should allow SSO with jwt

   • replace my_idp key with identity provider id that is unique in SlashDB
   • give idp_name a more user-friendly name e.g. "My Azure IdP"
   • set enabled: True
   • set jwks_uri, authorization_endpoint, token_endpoint from well-known configuration url from IdP
   • set client_id from IdP
   • in redirect_uri set actual hostname and replace in idp_id=myidp with actual IdP id
4. Configure cross-origin request policy (CORS) to allow requests to the IdP domain
5. On identity provider side
   • set scope to openid email. Alternatively configure claim_attribute: email and user_config_attribute: email accordingly
   • set redirect url to same value as redirect_uri
6. Make sure users at SlashDB side has same email as users at identity provider side
7. Restart slashdb and log in using a button with idp_name you set earlier e.g. "My Azure IdP"

JWT authentication method properties:

• enabled is a switch to enable JWT authentication. Accepted values are True or False.
• priority is the priority given to the JWT authentication method as compared to other configured methods. A lower number signifies higher priority; e.g. a priority value of 1 means it will be the first authentication method to try.
• gui is a sub-section with properties for configuring the GUI on the login page:
  • visible is a switch to show or hide the OpenID login form on the login page. Accepted values are True or False.
• identity providers is a sub-section for configuring identity providers (IdP):

  • myidp is a unique ID for the IdP. Can consist of ASCII letters a-z, uppercase A-Z, digits 0-9, characters: @, _, ~ (tilde) and - (dash). It contains a sub-section of properties for the IdP:

    • idp_name is the full name of the IdP that appears in the GUI
    • enabled is a switch to enable authenticating with the IdP
    • jwks_uri is a URL or path to a local file with a JSON Web Key Set (JWKS) in JSON format. JWKS is a set of public keys that will be used to verify signature in the JWT.
    • claim_attribute is a property of the ID Token that will be used to find the associated SlashDB user account (see user_config_attribute below) to validate an authentication request; e.g. an email address in the ID Token must match an email address for a SlashDB user account to identify the SlashDB user the OpenID account is associated with.
    • user_config_attribute is a property of SlashDB User Configuration to be compared with the claim_attribute property for matching an OpenID account with a SlashDB user. Typically, the value will be email.
    • authorization_endpoint is the URL of the IdP that is used in the OpenID Connect protocol to receive an Authorization Code (when response_type is code) or ID Token (when response_type is id_token).
    • token_endpoint is the 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 the redirect URI used by OpenID Connect protocol for returning an Authorization Code or ID Token. You must set it as follows:

      • Hostname of SlashDB server, e.g. https://slashdb.my-server.com
      • append URL string /login/callback
      • append query string with the unique ID of the IdP defined previously, e.g. ?idp_id=myidp

      The full redirect_uri for this example would be: 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 contain required claims in the token
    • gui is a sub-section with properties for the GUI applicable to this IdP
      • visible is a switch to show or hide the button for signing in with this IdP.

For example, to configure Okta as an IdP:

After making changes, restart SlashDB:

sudo systemctl restart slashdb

If SlashDB doesn't restart, there may be errors in the auth.cfg file that need to be fixed. Check the logs at /var/log/slashdb/slashdb.log to find any errors regarding authentication policies.

Log in using OpenId Connect

Using a browser, navigate to the SlashDB login URL at /login. There will be a new section in the GUI with a separate button for each configured identity provider.

Authorize request with JWT token

A request from a REST client can be authorized by providing these headers in the request:

• X-Identity-Provider-Id with the ID of an Identity Provider that is configured in /etc/slashdb/auth.cfg
• Authorization with Bearer with a valid JWT from the Identity Provider specified above

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"
    }
]

SSO / SAML 2.0

This feature is available only in Enterprise Edition

SAML 2.0 is a standard for exchanging authentication and authorization information between domains. It allows users to sign in to SlashDB by providing proof of their identity from an Identity Provider like MS Azure AD, Okta, PingOne, Google, or any others that implement the SAML 2.0 standard.

To authenticate a user in SlashDB using SAML 2.0:

1. Add Identity Provider configuration details to /etc/slashdb/auth.cfg.
2. On the SlashDB login page, a user can click the button to log in using the Identity Provider.
3. The user is redirected to the Identity Provider site where authentication takes place, and then onto a page that automatically sends the SAML response to the SlashDB backend.
4. SlashDB verifies the integrity of the SAML response and searches for a matching account in the user database by comparing saml_auth_attribute and user_config_attribute.
5. Assuming valid credentials were provided, the user is logged in and a response with a session cookie is returned. In case of an authentication error, the user is returned to the SlashDB login page.

Setup

1. Install a SlashDB License that allows Single Sign-On (SSO) with SAML 2.0.

2. The default /etc/slashdb/auth.cfg file has SAML authentication disabled. Edit the file to enable SAML 2.0 SSO. In the saml section of the file, set this parameter: enabled: true.

3. In the section identity_providers, configure each identity provider that should allow SSO with SAML

   • replace my_idp key with a unique identity provider id
   • give idp_name a more user friendly name e.g. "My Azure IdP"
   • set enabled: True
   • set the following values in the sp section:
     • for entityId, enter the SlashDB hostname or some other unique value
     • in the url property, set actual hostname and replace "my_idp" with the actual identity provider id as configured above
4. Go to the identity provider configuration and set the same values for entityId and Assertion Consumer Service (ACS) URL
5. Go back to the auth.cfg file in SlashDB to the identity provider configuration
   • in the idp section:
     • for metadata use the URL were identity provider metadata can be found or path to the metadata XML file saved in local file system. If url is used, it must be reachable from the backend
     • alternatively configure the section by setting the entityId, url and cert manually. The values may be found in metadata xml document
6. On identity provider side set NameID format to email. Alternatively configure saml_auth_attribute: NameID user_config_attribute: email accordingly
7. Make sure users at SlashDB side has same email as users at identity provider side
8. Restart slashdb and log in using a button with idp_name you set earlier e.g. "My Azure IdP"

Sample SAML config:

saml:
  enabled: True
  priority: 10
  gui:
    visible: True
  identity_providers:
    my_idp:
      idp_name: my_idp
      enabled: True
      saml_auth_attribute: NameID # case sensitive
      user_config_attribute: email
      gui:
        visible: True
      settings:
        sp:
          entityId: http://slashdb_host/ or other unique string
          assertionConsumerService:
            url: http://slashdb_host/sso/callback/saml/my_idp
          NameIDFormat: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
        idp:
          metadata: http://idp_site url to saml metadata autoconfiguration or to local file
          # uncomment next lines to override or for manual setup
          # entityId: unique string from the IdP
          # singleSignOnService:
          #   url: https://idp_url/
          # x509cert: cert as base64
        security:
          nameIdEncrypted: false
          authnRequestsSigned: false
          logoutRequestSigned: false
          logoutResponseSigned: false
          signMetadata: false
          wantMessagesSigned: false
          wantAssertionsSigned: false
          wantNameId: true
          wantNameIdEncrypted: false
          wantAssertionsEncrypted: false
          wantAttributeStatement: false
          allowSingleLabelDomains: false
          signatureAlgorithm: http://www.w3.org/2000/09/xmldsig#rsa-sha512
          digestAlgorithm: http://www.w3.org/2001/04/xmlenc#sha256
          rejectDeprecatedAlgorithm: true

Properties of saml authentication policy:

• enabled is a switch to enable SAML authentication. Accepted values are True or False.
• priority sets the priority of the SAML authentication policy as compared to other authentication policies. A lower number indicates higher priority. A value of 1 will set SAML as the first authentication policy to execute.
• gui is a sub-section with properties for configuring GUI on the login page:
  • visible a switch to show or hide the configured SAML Identity Providers on the login page. Accepted values are True or False.
• identity_providers is a sub-section for configuring identity providers (IdP)
  • my_idp is a unique ID for the IdP. Allowed characters are upper and lowercase A-z, digits 0-9 and characters: @, _, ~ (tilde) and - (dash). Note – this value is used as part of the url property configured in the assertionConsumerService sub-section. This value also contains a sub-section of properties for the IdP.
  • idp_name is the full name of the IdP that appears on the button in the GUI on SlashDB Log In page.
  • enabled is a switch to enable authenticating with the IdP.
  • saml_auth_attribute is a property from the SAML response that will be compared with user_config_attribute when searching for a matching SlashDB user. The SAML protocol typically stores this value in its NameID property, and the value is typically an email address. For custom SAML configurations, another property may be used; in that case, set this attribute to that property name.
  • user_config_attribute is a property of the SlashDB User Configuration to compare with saml_auth_attribute in order to match an IdP user with a SlashDB user. Customarily, the value will be email.
  • gui is a sub-section with properties to configure the GUI for each IdP.
    • visible is a switch to show or hide the button for signing in with that IdP.
  • settings is a sub-section with SAML 2.0 configuration details:
    • sp is a sub-section with Service Provider (SP) settings:
      • entityId is the globally unique ID of the Service Provider.
      • assertionConsumerService is a sub-section with settings for the Assertion Consumer Service:
        • url is the URL where user will be redirected after being successfully authenticated by IdP. For SlashDB, it looks like: https://my-slashdb.com/sso/callback/saml/my_idp where
          • "my-slashdb.com" is the domain or IP of the SlashDB instance
          • "my_idp" is the unique value set for the my_idp property previously
      • NameIDFormat defines the name identifier formats supported by the identity provider. Typically, it is one of:
        • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
        • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
        • urn:oasis:names:tc:SAML:2.0:nameid-format:transient
        • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
        • urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
        • urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
        • urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
        • urn:oasis:names:tc:SAML:2.0:nameid-format:entity
    • idp is sub-section with Identity Provider (IdP) settings:
      • metadata is a URL for a SAML metadata endpoint. It is used for automatically fetching idp section values. It can also be a path to a local file. The metadata contain values for the entityId, url and x509cert properties. If a URL is used, it must be reachable from the back end. If this is not possible, use a local file instead.
      • entityId is the globally unique ID of Identity Provider.
      • singleSignOnService is a sub-section with settings for SSO service in IdP.
        • url is the Identity Provider login page where the user is redirected to login.
      • x509cert is the Identity Provider certificate in base64 format to verify the SAML Response.
    • security is a sub-section for additional SAML security settings:
      • nameIdEncrypted indicates whether the nameID property in the logout request sent by this SP will be encrypted. Accepted values are True or False.
      • authnRequestsSigned indicates whether the AuthnRequest messages sent by this SP will be signed. The SP metadata contains this information. Accepted values are True or False.
      • logoutRequestSigned Indicates whether the logout request messages sent by this SP will be signed. Accepted values are True or False.
      • logoutResponseSigned indicates whether the logout response messages sent by this SP will be signed. Accepted values are True or False.
      • signMetadata sign the Metadata. Accepted values are False, True (use SP certificates) or an object with keyFileName and keyFileName properties: { "keyFileName": "metadata.key", "certFileName": "metadata.crt" }
      • wantMessagesSigned sets whether SAML Response, LogoutRequest and LogoutResponse messages received by this SP must be signed. Accepted values are True or False.
      • wantAssertionsSigned sets whether SAML Assertion messages received by this SP must be signed. The SP metadata contains this information. Accepted values are True or False.
      • wantNameId sets whether the NameID element in the SAMLResponse received by this SP must be present. Accepted values are True or False.
      • wantNameIdEncrypted sets whether the NameID property received by this SP must be encrypted. Accepted values are True or False.
      • wantAssertionsEncrypted sets whether SAML Assertion messages received by this SP must be encrypted. Accepted values are True or False.
      • wantAttributeStatement sets whether AttributeStatement property is required. Accepted values are True or False.
      • allowSingleLabelDomains if enabled, URLs with single-label-domains will be permitted by the settings validator. Accepted values are True or False.
      • signatureAlgorithm is the cryptographic algorithm that will be used in the signing process. Options:
        • http://www.w3.org/2000/09/xmldsig#rsa-sha1
        • http://www.w3.org/2000/09/xmldsig#dsa-sha1
        • http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
        • http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
        • http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
      • digestAlgorithm is the cryptographic algorithm that will be used in the digest process. Options:
        • http://www.w3.org/2000/09/xmldsig#sha1
        • http://www.w3.org/2001/04/xmlenc#sha256
        • http://www.w3.org/2001/04/xmldsig-more#sha384
        • http://www.w3.org/2001/04/xmlenc#sha512
      • rejectDeprecatedAlgorithm sets whether messages signed with a deprecated algorithm should be rejected. Accepted values are True or False.

Log in using SAML 2.0

1. Go to the /login page. You will see a new section for logging in using SAML. Each configured identity provider has a button that links to their login portal.

2. Click on the button for the identity provider you want to log in with.

3. Next, you need to log in to your identity provider. If you are already logged in, this step is skipped. Otherwise, the identity provider login page appears where you enter your credentials.
   

4. On successful login, the proof of authentication is passed from the identity provider to SlashDB. A new browser session is created for the SlashDB user and you will be redirected back to the last page you were browsing before logging in.

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

Cookie Session

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

Cookie session configuration

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

Authenticate to receive the session cookie

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.

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 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

Standard login page

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
      • visible 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.

Customized login page

This feature is available only in Enterprise Edition

SlashDB allows to create custom login pages. To find out please contact your SlashDB technical support.