Creating APIs‎ > ‎Security‎ > ‎Authorization‎ > ‎

Role-Based Endpoint Access

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. There are usually fewer roles than users, so roles make administration much simpler than assigning authorization directly to users. A role is authorized to the union of its permissions and an auth token is an authorized union of its role-based permissions.

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

  • The REST endpoints that authentication users can access (either by default, or specific enumeration).
  • Permissions that specify row/column-level access for a specific table.

For more information:

Define Roles

Define roles on the Manage, Roles, Details tab. The following image shows this tab:

 

Define Globals for Roles

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

If the global is required (the Required field is selected), it must have a defined value. This is useful if 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.
  1. Go to the Manage, Roles, Globals tab. The following image shows this tab:
  2. Define the following field and save your changes:
    Language
Indicates how the global is defined.
Options:
  • SQL. SQL queries read information from the database. Fixed values are SQL queries that are executed against your database. Code is the valid SQL as part of supplied SELECT, returning a row from which you can access attributes.

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

For more information about the 
the LoginId global, see Authorization.

  • JavaScript. Transactions use the global that is returned as a result of executing the JavaScript code.
Default: SQL
The global is defined for the role.

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:

Define Role Permissions

A role's default read/write access applies to all tables not specifically defined in the role permissions. A table can have multiple permissions entries.

The following image shows the Manage, Roles, Permissions tab:

On the Manage, Roles, Permissions tab, complete the following fields, and then save your changes:

Table

Specifies the table the permission applies to.

Permissions name

Identifies the entry within the list.

Access type

Defines the operations that are allowed. For rows that meet the row filter, 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.

Options: Read, Insert, Update, and Delete

Columns

Defines which columns are allowed for the enabled access.

Row Filter

Defines row and column access. Row filters are a selection filter appended to all requests against the table. You can use a global in a permission as part of a filter.

Example 1: A "Security" global (high, low) for a table, so that only admin roles can read high security rows.

Example 2: An "ssn" global with a value of '123-45-6789' (in single quotes). Use the value in a permission's row filter, 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 auth token.

Example: Role Permissions

In this example, you want user with the testRole to see purchase orders only if their login ID is present in the notes field. Specify the filter like this:

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

Use double quotes (") to denote a column name and single quotes (') to denote a string. In this example, a string is created from the users' login id (part of the auth token). The locate SQL function returns the location of string1 in string2. Most databases, such as MySQL and Derby support this, but not all (for example, Postgres).

The following image shows this role permission, including the row filter, on the Manage, Security, Permissions tab:


Default Security Settings

When you first create an API, you can restrict default access. In this example, suppliers can only access the v1 SupplierAlert and v1 SupllierInfo tables:

You can set the default access for objects, like this:

Select API Resources for an API Project for Access

Each role can have access rights to specific resource types. You can define which roles have access to which specific tables, views, procedures, custom resources, and meta tables API resources. You can also set verb-based permissions.

  1. On the Manage, Roles, REST End Points tab, select the role you want to grant access and then select the tab for the API resource you want to define access to: Tables, Views, Procedures, Resources, or Meta Tables. The following image shows the Manage, Roles, REST End Points, Tables tab for the Sales Rep role:
  2. Enable one or more of the API resources to which you want to grant the role access and then save your changes.
    Tip! You can select all of the tables, views, procedures, custom resources, or meta tables API resources listed by clicking 
    Check All or clear all of the checkboxes by clicking Clear All.

The role has been granted access to the specific table, view, procedure, custom resource, or meta tables API resource.