Users

User accounts in SlashDB are used for:

controlling access to Data Discovery and SQL Pass-thru resources
granting selected users management privileges for the entire system or parts of it

Access to both the GUI and the API requires some level of authentication and authorization. SlashDB has a robust security mechanism which supports authentication with usernames and passwords or with API keys.

This documentation will guide you through the process of creating and managing local user accounts.

Info

See here for information about authentication methods and configuring SlashDB to work with single sign on providers.

Important

SlashDB has two special user accounts built in:

admin - this account has administrative privileges and access to all system features.
public - acts as a regular account, but does not require any authentication. Just like a regular account, it must be configured with a database mapping to access resources. Users that do not log in are treated as the public user.

Users List

The Users page provides a list all of user accounts that are configured in SlashDB.

The list is accessible from the main menu (Users) or from the URL /userdef. It is available only to the admin user and users with Administrative Privileges to view it.

The list can be searched using the Search field above the list or sorted by clicking on column headers.

The User ID is a unique identifier for the account which is used for logging in, and in system configuration for granting access to resources. The user ID is also used in the user account endpoint:

/userdef/admin - the HTTP endpoint for the admin account

Each account in the list also has:

the Full Name of the user

Info

The list can also be viewed in JSON format by clicking the button in the top right corner.

Actions

The Action column has 2 icons:

To edit a user, click on the Edit icon, or on the User ID.
To copy a user account to a new account, click on the Copy button.

Adding a New User

The admin user can create a new user account. Additionally, any user with privileges to do so may create new accounts. Users with this ability will see the New button in the top right corner of the Users list.

Clicking it will bring up the User Configuration screen.

Tip

You can also clone an existing user account to a new one using the Copy action, or the Copy button on the user configuration screen.

Editing a User

Click the Edit icon in the Action column, or on the User ID to edit an existing user. This will take you to the User Configuration screen.

Deleting a User

Click on a User ID or the Edit icon to delete a user. This opens the User Configuration screen. Then click on the Delete button in the top right corner.

User Configuration

This screen contains a form with account configuration fields, in four sections - Configuration, User Privileges, Administrative Privileges, and Database Mapping.

User Configuration Actions

Actions such as saving or deleting a configuration are performed using the row of buttons in the top right corner of the screen. Some buttons may not be enabled depending on the user's privileges.

The Close button will return to the user list without saving.

Users with privileges to create new users will have the Copy button available.

Info

Copy clones the current configuration to a new user configuration. The basic details (full name, email, etc.) will not be copied.

Users with privileges to manage users will have the Save button available. This saves the user configuration.

Users with privileges to manage users will have the Delete button available. This deletes the user configuration and returns to the user list.

Info

The admin user account cannot be deleted.

Configuration

These are the basic options for configuring a user account. Each field is explained below.

Enter the User ID (required) - this will be the user's login ID

Important

This field is only available when creating a new user. Existing user configurations will not have this field.

All user names must start with a letter or underscore, and may only contain letters, numbers, and the symbols @, _, -, and ~.
Enter the user's Full Name (optional)
Enter an API Key, or use the Random button to generate one (optional)

Important

The API key must be unique for each user account. If the API key is not set, this method of authentication will be disabled for this user.
Enter the user's Email address (optional)
For a new user account - Enter a Password (required)
For an existing user account - click the Edit Password toggle to reveal the Password field

Info

The password must meet certain complexity requirements. These can be tuned in the INI settings.

User Privileges

These fields give other users privileges to this user account (admin always has access). Click on them to choose other user accounts on the system that you want to grant access to.

Important

Users in these lists must also be granted the Manage Users privilege to access this user's account.

View Privileges - a list of users who may view this account
Edit Privileges - a list of users who may edit or delete this account

Administrative Privileges

Info

The admin user configuration does not include this section, since it always has access to these functions.

These settings control user access to lists for: Database Connections, Users, SQL Pass-thru Queries, and [Database Credentials].

The Manage checkboxes give access to the respective top-level menus/URLs for each configuration (e.g. Users /userdef).

The Create checkboxes allow this user to create new configurations.

Important

It's recommended to turn these settings off for normal users and applications. For power users and secondary admins, turn on the appropriate settings.

Database Mapping

A SlashDB user needs to be assigned a database login and password for any database they need to access.

Important

The admin user is a special case. If there is no mapping for a given database, the database credentials from the database configuration file will be used.

Existing database mappings will be listed here. They can be modified or deleted.

Add Database Mapping

To set a user's database credentials, click on the Add Mapping button. A new form will appear.

To use a database login and password directly:

Select a Database ID from the first drop-down list
Select local in the next drop-down list
Enter the username in the DB Login field
Enter the password in the DB Password field

To use a predefined [database credentials] entry:

Select a Database ID from the first drop-down list
Select credential in the next drop-down list
Select the credential entry you want to use from the Select credential drop-down list

Info

If a database doesn't require or does not support logins (such as SQLite databases), add the mapping but leave
all fields but the Database ID blank.

The credentials can be verified by clicking on the Test Connection button .

A notification message will appear in the top right corner of the screen indicating if the connection was successful or not:

Delete Database Mapping

Click the Delete icon next to the database mapping .

A confirmation window will appear. Click Yes to delete the mapping.

Configuration File

All user configurations are saved in the YAML file /etc/slashdb/users.cfg.

Caution

It is recommended to modify user configurations using the GUI whenever possible. Typos or formatting errors in this file may prevent SlashDB from starting.

Below you can a find a sample configuration for the admin, public, and app1 users and details about attributes.

admin:
  api_key: 61527b29:5a031433fff9ff3edbcbc9f13f7b7026
  creator: admin
  databases:
    Chinook: {dbpass: '', dbuser: ''}
  dbdef: []
  edit: [admin]
  email: ''
  name: Default administrator with full permissions
  password: $6$rounds=697243$8B7YGw6fOYSQw.2O$iQvj/Z3SP5ob647xTRidfRpGvCfzB6S1DaPvnYQZZggWWyAcZ6.0ld/zOe9SzF18he4OtjKgL8EyvsWboew9t/
  querydef: []
  userdef: []
  view: []
  user_id: admin
public:
  api_key: null
  creator: admin
  databases:
  dbdef: []
  edit: [admin]
  email: ''
  name: ''
  password: ''
  querydef: []
  userdef: []
  view: []
  user_id: public
app1:
  api_key: app1api:oqjbz59qca8ba0df
  creator: admin
  databases:
    SQLiteChinook: {dbpass: '', dbuser: ''}
    MSNorthwind: {dbpass: '1SAd7V-5CUfvjnvDQ==', dbuser: 'northwind_ro'}
  dbdef: []
  edit: [admin]
  email: app1-contact@mycompany.com
  name: User with access to Chinook database
  password: $6$rounds=656000$MLzjH30FKz22DCxO$nslVMsK4jbj5EeCCfz/Xd2gHiG2tCjeqWo3p8USCG9j6TvfX6H7dRvjJ9N7gGGzoUBY6oGrihFjWULk./Gm1I.
  querydef: []
  userdef: []
  view: []
  user_id: mike

Each user configuration is defined under its unique ID - e.g. admin - and contains several attributes.

Attributes

`api_key`

Stores the key for API key authentication. See the API Key documentation for more information.

Example

A request that is sent with App Id "app1api" and Api Key "oqjbz59qca8ba0df" in header or query string will be executed on behalf of user app1.

app1:
  api_key: app1api:oqjbz59qca8ba0df

`creator`

Stores the user ID of the user that created this account.

Example

User app1 was created by admin.

app1:
  creator: admin

`databases`

This attribute stores information about user's access to databases along with credentials used for connecting the database. The format for this setting is a group of key/value pairs, where each key is a database ID from /etc/slashdb/databases.cfg and the value is another group of key/value pairs, with the database username identified as dbpass, and the encrypted password as dbpass.

Example

User app1 has access to these databases:

SQLiteChinook - SQLite database that doesn't require credentials (blank passwords are still encrypted)
MSNorthwind - MSSQL database with login northwind_ro and password 1SAd7V-5CUfvjnvDQ==

Important

All database names must start with a letter or underscore, and may only contain letters, numbers, and the symbols @, _, -, and ~.

app1:
  databases:
    SQLiteChinook: {dbpass: 'nk9h3S-wjI30BP2ss==', dbuser: ''}
    MSNorthwind: {dbpass: '1SAd7V-5CUfvjnvDQ==', dbuser: 'northwind_ro'}

`user_id`

Unique user ID. Must be the same as the parent key.

`name`

User's full name or more detailed description for the account.

Example

app1:
  name: Account used by Application-1 to acquire data

`password`

The hashed password.

Important

The only way to reset the admin password is by setting an empty password for admin in this file, restart the SlashDB service and visit the GUI where you will be able to set a new password.

Example

Hashed password for user app1

app1:
  password: $6$rounds=656000$MLzjH30FKz22DCxO$nslVMsK4jbj5EeCCfz/Xd2gHiG2tCjeqWo3p8USCG9j6TvfX6H7dRvjJ9N7gGGzoUBY6oGrihFjWULk./Gm1I.

Set an empty password for user admin to reset the password in the GUI.

admin:
  password: ''

`email`

User's email for contact and identification purposes.

Example

app1:
  email: app1-contact@mycompany.com

`dbdef`

Sets whether the user has administrative privileges to:

view Database Connections
create new connections

Accepted keywords:

view
create

Example

User app1 can view database connections and create new database configs.

app1:
  dbdef: [view, create]

User app2 can view database connections.

app2:
  dbdef: [view]

`querydef`

Sets whether the user has administrative privileges to:

view SQL Pass-thru query configurations.
create new queries

Accepted keywords:

view
create

Example

User app1 can view query configurations and create new queries.

app1:
  querydef: [view, create]

User app2 can view query configurations.

app2:
  querydef: [view]

`userdef`

Sets whether the user has administrative privileges to:

view User configurations.
create new users

Accepted keywords:

view
create

Example

User app1 can view user configurations and create new users.

app1:
  userdef: [view, create]

User app2 can view user configurations.

app2:
  userdef: [view]

view

A list of users allowed to view this user's configuration. The admin user doesn't have to be added to the list because it has full access to all configs.

Important

All user names must start with a letter or underscore, and may only contain letters, numbers, and the symbols @, _, -, and ~.

Example

Only admin and mike can view the app1 user configuration.

app1:
  view: [mike]

`edit`

A list of users allowed to change or delete this user's configuration. The admin user doesn't have to be added to the list because it has full access to all configs.

Important

All user names must start with a letter or underscore, and may only contain letters, numbers, and the symbols @, _, -, and ~.

Example

Only admin and mike can change the app1 user configuration.

app1:
  edit: [mike]