Docs‎ > ‎API Creator‎ > ‎Security‎ > ‎

Roles

You control access to REST endpoints using roles. Role-based access security (RBAC) provides authorization control over what resources, rows, and columns authenticated users can access. Roles control Read, Insert, Update, and Delete to the schema and resource objects as well as fine-grain permissions on base table rows and columns.

For more information about authorization, see Authorization.

Define Roles

You can define one or more roles for a user. You define:

  • What resource endpoints are accessible (either by default, or specific enumeration).
  • Permissions that specify row/column-level access for a specific table.
Define roles on the Manage, Roles, Details tab. The following image shows the Manage, Roles, Details tab:

Define Globals for Roles

Globals are variables that API Creator makes available to each transaction so that the transaction can determine what data the user should have access to. Fixed values are SQL queries that are executed against your database. You can retrieve data based on the information already available to you.

As part of the definition of a role, you define globals that influence how security is enforced. For instance, you may want to read the current user's employee information so that you can use the user's department number in your security definitions. The Language property indicates how the global is defined.

You define globals in one of the following ways:

  • SQL queries. SQL queries read information from the database. Code is the valid SQL as part of supplied SELECT, returning a row from which you can access attributes.

Tip: Use use existing globals in this SQL, such as the LoginId.

  • A piece of a JavaScript code/method. Transactions use the global that is returned as a result of executing the JavaScript code.
If the global is required, it must have a defined value. This is useful is you need to make sure that the user has a value for this global. For example, if you have security settings that restrict access to data based on the user's department number, make the corresponding global required to guarantee that the user has a department number.

Define globals on the Roles, Globals tab. The following image shows the Roles, Globals tab:

Reference Globals

Globals are global values or global objectsFor example, the global value named Clearance can be Low, Medium, or High. The global value name/value pairs can be a database row. Global objects are named maps of keyword/value pairs. Global references are independent of the source. System behavior is undefined when multiple sources define the same global name and generates log entries when non-equal duplicates are detected.

You can reference:
  • As a global value, for example:
@{<globalName>}
  • An attribute of a global object, for example:
@{<globalName>.<globalAttribute>}

Use globals in predicates and rules. Predicates represent constant expressions and expressions that refer to globals and use the @[<globalName>.<globalAttribute>} syntax. Globals are not restricted to security predicates.

You can reference a global in any of the following contexts:
  • Security predicate.
  • Resource filter. For example:
    screenName = '@{_apikey.user_identifier}'
    salesrep_id = @{current_employee_row.employee_id}
  • Resource SqlFrom.
  • Rule expression. In expressions for formulas and validations. Typical examples include user id/name update and insert stamping.
  • JavaScript. The LogicContext object provides access to globals and makes visible key aspects of logic execution.

    For more information about logic execution, see 
    Logic Execution.

Define Role Permissions

Role permissions specify row/column filtering for roles. A role's default read/write access applies to all tables not specifically defined in the role permissions. Define role permissions on the Manage, Roles, Permissions tab. The following image shows this tab:
On the Manage, Roles, Permissions tab, complete the following fields, and then click Save:

Table

The table the permission applies to. You can have multiple permissions entries for a given table as shown below for Products.

Permissions Name

Use to identify the entry within the list.

Access Type

For rows that meet the predicate, this specifies a role's default read/write access. You can define one or more permission entries. For example, you can enable rows to be inserted, but not read back.

Columns

Which columns are allowed for the enabled access.

Predicate

A selection filter appended to all requests against this table. You can use a global in a permission as part of a filter. For example, you can define a "Security" global (high, low) for a table, so that only admin roles can read high security rows. Another example, you can define a global named "ssn", and give it a value of '123-45-6789' (in single quotes), then you can use that value in a permission's predicate, such as: user_ssn = '@{ssn}' or owner_ssn = '@{ssn}'.

Define Multiple Permissions for a Table

The permissions are added together over all of the roles for the current api key.


Role Permission Example


Let's imagine you want User with the testRole to see Purchase Orders only if their login id is present in the Notes field.  We specify the Filter like this:

locate( '@{_apikey.user_identifier}', "notes") > 0

Note the use of quotes:
  1. Double quotes denote a column name
  2. Single quotes denote a string, here created from the users' login id (part of the apikey)
  3. Locate is a SQL function that returns the location of string1 in string2.  This is supported by most databases (e.g., MySQL, Derby), but not all (e.g., Postgres).

Select API Resources for an API Project for Access

Select the API resources for an API project for access (tables, views, procedures, resources, meta tables) on the Manage, Roles, REST End Points tab. The following image shows this tab: