Account Management Concepts

You can create as many accounts as you need for individual users, applications, and services, to log into a FairCom server. FairCom uses the role-based access control model (RBAC) to authorize an account to perform actions.

Each object in a FairCom server has built-in privileges, such as the read privilege on a table. You can assign privileges to roles and assign roles to accounts. You may create as many roles as you need and assign as many accounts to each role as desired.

The Admin API provides actions to manage and use accounts.

Use "createAccount" to create an account.
Use "alterAccount" to change account settings.
Use "dropAccount" to delete an account.
Use "cloneAccount" to create a new account using the settings of an existing account.
Use "listAccounts" to get a list of existing accounts that your account is authorized to view.
Use "describeAccounts" to get all information about existing accounts that your account is authorized to view.
Use "assignRolesToAccounts" to assign roles to accounts or remove them.
Use "createSession" to log an account into a FairCom server and create a session in the JSON ADMIN API.

Account

Each account has a "username" property that is the unique identifier of the account. You can also use the "description" property to help you recognize what the account is used for, such as an application, service, user's full name, etc.

An account has other properties that control authentication, including "password", "enableDatetime", "disableDatetime", "oneTimePassword", "lockoutAfterNFailedAttempts", "maxDaysBeforePasswordMustChage", and "maxMinutesBeforeNextLogin".

When an account logs into a FairCom server, the server creates a session that consumes memory, which you can control using the properties "memoryLimit" and "memoryRule".

An Account cannot see or use an object unless a Server Admin Account grants it access.

FairCom provides two types of administrative accounts:

ADMIN
Server Admin

ADMIN Account

The ADMIN Account is the all-powerful account built into each FairCom server. It is the master recovery account because no other account can change its password or modify its privileges.

Important

You should immediately change the ADMIN password to a long, crypto-random string up to 64 bytes.
The ADMIN account always has the username "ADMIN" and a default password of "ADMIN".
Usernames are case-insensitive, and passwords are case-sensitive.

It is convenient to use the ADMIN Account, but you should only use it to create Server Admin Accounts. This best practice allows the ADMIN Account to be used infrequently by a tiny group of trusted users, which helps protect it from being compromised by attackers.

Protecting the ADMIN Account is important because if it is compromised, an attacker can do anything with the server including accessing all data, modifying all data, altering all objects, and changing the passwords, roles, and privileges assigned to all other accounts.

Server Admin Accounts

A Server Admin Account can do everything except modify the ADMIN account or other Server Admin Accounts. You create a Server Admin Account by assigning an account to the built-in role "ADMIN".

Tip

Using a Server Admin Account instead of the ADMIN account improves security because a Server Admin Account cannot create, delete, or change the password for the ADMIN account and other Server Admin accounts.

A Server Admin Account controls access to objects and data by assigning accounts to roles and assigning roles to privileges. A Server Admin Account does the following to administer security:

It can create, alter, and delete roles.
It can assign any account to any role and later unassign it.
It can assign privileges to roles (and accounts).
It can create, alter, and drop database objects while impersonating another account. During impersonation, it has the limited privileges of the impersonated account. The server tracks that the Server Admin Account did the change.
It may optionally create, own, and manage objects, such as database administration, creating temporary copies of tables for troubleshooting, upgrades, emergency fixes, data migrations, etc.

A Server Admin Account is automatically a database administrator (DBA) in each database on the server. It can manage all SQL roles, database objects, and privileges assigned to roles and accounts.

Assigning the "ADMIN" role to the "adminMike" user

{
  "api": "admin",
  "action": "assignRolesToAccounts",
  "params": {
    "add": [
      {
        "roleNames": [ "ADMIN" ],
        "usernames": [ "adminMike" ]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

Role names are case-insensitive.
The words "role" and "group" are synonymous.
Newer FairCom documentation uses the word "role", while older FairCom documentation uses "group".

A Server Admin Account controls access to objects and data by assigning accounts to roles and assigning roles to privileges. A Server Admin Account does the following to administer security:

It can create, alter, and delete roles.
It can assign any account to any role and later unassign it.
It can assign privileges to roles (and accounts).
It can create, alter, and drop database objects while impersonating another account. During impersonation, it has the limited privileges of the impersonated account. The server tracks that the Server Admin Account did the change.
It may optionally create, own, and manage objects, such as database administration, creating temporary copies of tables for troubleshooting, upgrades, emergency fixes, data migrations, etc.

A Server Admin Account is automatically a database administrator (DBA) in each database on the server. It can manage all SQL roles, database objects, and privileges assigned to roles and accounts.

Ownership

An account owns the objects it creates. Being the owner automatically gives the account complete control over its objects, which include tables, indexes, views, synonyms, triggers, functions, stored procedures, and code packages. The owner account is also automatically authorized to select, insert, update, and delete all records in its tables.

Each object belongs to a database and an account, which are object containers and namespaces. The server creates an object in the namespace of the account that created it; thus, an object can have only one owner.

Important

A database object has an owner account; thus, the owner account has complete control over all objects in the database. A database object it is not in the namespace of its owner; therefore, you do not need to use the owner name to reference a database object. A database object has a unique name in the server and cluster in which it exists.

Namespace

Each object has a fully qualified name that includes the database's name, the owner's name, and the object's name. In SQL, the full name of an object includes the database, owner, and object names, such as "mydb.admin.mytable". In SQL, a two-part name refers to the database and object, such as "mydb.mytable", and a one-part name refers only to the object, such as "mytable".

In the JSON DB API, you use the following properties to identify a table:

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "databaseName": "mydb",
    "ownerName": "admin",
    "tableName": "mytable"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Many objects with the same name can exist in the same database if they have different owners. For example, you can create a table named "product" owned by "shoppingcart" in the "prod" database and another table named "product" owned by "shoppingcart" in the "test" database. This approach allows you to use the same server for different dev, test, stage, and production environments.

Note

Some database products use the phrase "database schema", which is the same concepts as "owner". Because JSON is a fundamental part of the FairCom database engine, FairCom uses the phrase "owner" instead of "database schema" to avoid confusion with "JSON schema".

Default database and owner

All SQL and JSON DB operations run in a session. A session has default database and owner names. You can omit these names from your code and use the session defaults, which allow you to use the same code to process objects in different databases and with different owners. This approach maximizes code reuse in different environments.

Tip

In SQL and JSON DB, the best practice is to omit the database and owner names from all actions and use the session defaults.

In the JSON DB API, you can alter a session to change the default database and owner:

{
  "api": "admin",
  "action": "alterSession",
  "params": {
    "defaultDatabaseName": "test",
    "defaultOwnerName": "shoppingcart"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

A JSON DB action can omit the "databaseName" or "ownerName" property or both. The server uses the default session values for omitted properties:

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "myTable"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}