Skip to content

Database Credentials

Database credentials are a security control mechanism for allowing SlashDB users with elevated privileges to grant access to database resources, without the need to know sensitive database login information.

This documentation will guide you through the process of creating and managing database credentials.

Important

Database credentials are used in conjunction with Database Configuration and Database Mapping. See those documents for information about assigning database credentials.

Use Case

The database credentials controls allow administrators to grant access to databases without divulging sensitive passwords.

Example Scenario

Imagine a SlashDB deployment connected to a database, Chinook, and multiple users with tiers of privileges:

  • admin, a SlashDB administrator, who knows the database passwords
  • assistant, a SlashDB power user who is responsible for granting other users access to databases, but doesn't know any passwords
  • reader, a SlashDB user who requires access to databases

How can assistant give reader access to the Chinook database if neither can have the login info?

admin can:

  • create a database credentials entry for Chinook that stores the password securely
  • grant assistant permissions to assign the credentials

Then assistant can:

  • create a database mapping for reader with the credentials

Now reader can:

  • access Chinook

In this scenario, only admin ever knows the password.

Database Credentials List

The Database Credentials page provides a list of all credentials that are configured in SlashDB.

The list is accessible from the main menu (Database Credentials) or from the URL /dbcreds. 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 Select Database ID dropdown filters credentials by database ID.

The Credentials ID is a unique identifier for the entry which is used for assigning it to a database configuration or Database Mapping. The credentials ID is also used in the user account endpoint:

  • /dbcredentials/Chinook/ro_credentials - the HTTP endpoint for the ro_credentials entry for the Chinook database:

Each entry in the list also has:

  • the Database ID of the database that the entry is for.

Info

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

Actions

To edit a credential, click on the Edit icon, or on the Credentials ID.

Adding a New Credentials Entry

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

Clicking it will bring up the Add Database Credentials screen.

Editing a Credentials Entry

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

Deleting a Credentials Entry

Click on a Credentials ID or the Edit icon to delete an entry. This opens the Database Credentials Configuration screen. Then click on the Delete button in the top right corner.

Database Credentials Configuration

This screen contains a form with account configuration fields, in two sections - Credentials and Privileges.

Info

The header on this screen displays the database ID and the credentials ID. The breadcrumbs navigation also contains the database ID, which leads to a list of all credentials configured for the database.

Database Credentials Configuration Actions

Actions such as saving or deleting credentials 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 credentials list without saving.

Users with privileges to edit credentials will have the Save button available. This saves the credentials configuration.

Users with privileges to edit credentials will have the Delete button available. This deletes the credentials configuration and returns to the credentials list.

Credentials

These fields are for database login information.

  • Enter the Database Login ID
  • Enter the Database Password

Test Connection

test connection success test connection fail

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

A notification message will appear below the button indicating if the connection was successful or not.

Privileges

These fields grant users different privileges to these credentials (admin always has access). Click on them to choose user accounts on the system that you want to grant access to.

  • View Privileges - grant users access to view the other users who can view, edit, or assign

  • Edit Privileges - grant users access to view, edit or delete these credentials

    Important

    Users with Edit Privileges will be able to see and modify the database login and password

  • Assign Privileges - grant users the ability to assign these credentials to other users as a Database Mapping, or directly to a Database Connection.

Important

Users with View or Edit privileges must also be granted the Manage Database Credentials privilege to access this entry.

Users with only the Assign privilege will be able to assign the credentials, but do not have access to view or edit them.

Add Database Credentials

Click the New button on the Database Credentials List to create a new credentials entry. This form is similar to the configuration form but has some extra fields.

Credentials

  • Enter the Credentials ID (required) - this is used throughout SlashDB to identify this credentials entry

    Important

    Each Credentials ID entry must be unique to the database it belongs to. ID names can be duplicated only when assigned to different databases.

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

  • Select the Database to pair the credentials entry with

  • Enter the Database Login ID
  • Enter the Database Password

Use the Test Connection button to verify that the configuration works properly.

Privileges

The privileges are configured the same way as when modifying an existing entry.

Finish

Click the Save button to complete the process.

If any errors are encountered, a message will appear in the top right corner of the screen.

Success

Once saved, you will be taken to the Database Credentials Configuration screen for the entry.

Configuration File

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

Caution

It is recommended to modify credentials entries 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 of credential entries for Northwind and msChinook databases and details about attributes.

  • Northwind has two entries, northwind-testro, northwind-testrw
  • msChinook has one entry, dbo
Northwind:
  credentials:
    northwind-testro:
      assign:
      - credmgr
      dbpass: gAAAAABnvJ9_-nnuPkcw7wTBYQgjdATdsT2k3P2j2gVlb_ofwSG-hp1YOGHKNRTtMGpof8sW-pZU-fPygD9mPaGUFzcX3fPt-w==
      dbuser: northwind
      edit:
      - credmgr
      view:
      - credmgr

    northwind-testrw:
      assign:
      - credmgr
      dbpass: 0YVyE2NCBjf_-iS6yBTktazqAjvDlxW98iSkPrsixutbB_24Ym-iVHUy52brXCYqTKBVwLmvig9jl8a2JvRhYzn1ai1Gsdprjg==
      dbuser: north
      edit:
      - credmgr
      view:
      - credmgr

  db_id: Northwind

msChinook:
  credentials:
    dbo:
      assign:
      - credmgr
      - powerusr
      dbpass: iS6yBTktazq_-bB_24Ym-iVHUy52blxW98iSkPrsixutbB_24Ym-yBTktazqAjvDlxgqTKBVwLmvig9jl8a2JYzn1ai1Gsdprjg==
      dbuser: chinook
      edit:
      - credmgr
      - powerusr
      view:
      - credmgr
      - powerusr
  db_id: msChinook

Each entry is defined under the database ID it belongs to, and then its unique ID - e.g. northwind-testro - and contains several attributes.

Info

A credentials entry ID can be duplicated but only under a different database ID. Each database ID must have a single instance of the entry ID.

Attributes

assign

Contains user IDs for accounts which have Assign Privileges to give users access to databases using a credentials entry. Each user ID appears on its own line, prefixed with a hyphen.

Important

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

Example

Users credmgr and powerusr have privileges to assign the dbo credentials for the msChinook database

msChinook:
  credentials:
    dbo:
      assign:
      - credmgr
      - powerusr

dbpass

The encrypted password used by the credentials entry for the database.

Example

The encrypted password for the dbo credentials ID on msChinook

msChinook:
  credentials:
    dbo:
      dbpass: iS6yBTktazq_-bB_24Ym-iVHUy52blxW98iSkPrsixutbB_24Ym-yBTktazqAjvDlxgqTKBVwLmvig9jl8a2JYzn1ai1Gsdprjg==

dbuser

The database login used by the credentials entry for the database.

Example

The database login for the dbo credentials ID on msChinook is chinook

msChinook:
  credentials:
    dbo:
      dbuser: chinook

edit

Contains user IDs for accounts which have Edit Privileges to update or delete the credentials entry. Each user ID appears on its own line, prefixed with a hyphen.

Important

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

Important

Users with Edit Privileges can see the database login and password.

Example

User credmgr has privileges to edit the dbo credentials entry

Northwind:
  credentials:
    northwind-testro:
      edit:
      - credmgr

view

Contains user IDs for accounts which have View Privileges to see the credentials entry. The database password is still kept hidden. Each user ID appears on its own line, prefixed with a hyphen.

Important

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

Example

User powerusr has privileges to view the dbo credentials entry

Northwind:
  credentials:
    northwind-testro:
      view:
      - powerusr