Docs‎ > ‎CA Live API Creator‎ > ‎Security‎ > ‎

Roles


Role Based Access Control (RBAC)

Roles are used to control access to REST endpoints.  Each role controls Read, Insert, Update, and Delete to the Schema and Resource objects as well as fine-grain permissions on rows and columns of base tables.

Details

Role-based security provides authorization control over what resources, rows, and columns authenticated users can access. 

  • RolesUsers can have multiple roles. For a role, you can define:

  • What Resource endpoints are accessible (either by default, or specific enumeration)
  • permissions that specify row/column level access for a specific table

Globals

Global name

A "global" is a variable that will be made available to each transaction, so that it can determine what data the user should have access to.
A global can be used in a permission as part of a filter. For instance, if you define a global namedssn, and give it a value of '123-45-6789' (in single quotes), then you can use that value in a permission's predicate, e.g.:user_ssn = '@{ssn}' or owner_ssn = '@{ssn}'
Of course, a fixed value is not always interesting. The value is actualy a SQL query that will execute against your database, so you can retrieve data based on the information already available to you.

Global language

As part of the definition of a role, you define variables that will 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.
This can be done in two ways: either as a SQL query, which will read information from the database, or as a piece of JavaScript code, which will be executed, and whose return value will be used as the value.

Global required

If a global is required, it must have a value. If it does not have a value, then an error will be thrown, and the transaction will be aborted.This is useful if you need to make sure that the user has a value for this global. For instance, if you have some security settings that restrict access to data based on (say) the user's department number, then making the corresponding global required would guarantee that the user does in fact have a department number.

Predicates become particularly powerful when they represent not only constant expressions, but expressions that refer to Globals.  There are two kinds of Globals:
  • Global Values: a named value, such as Clearance whose value may be Low, Medium or High
  • Globals Objects: a named map of keyword/value pairs.   In particular, the Global Value name/value pairs can be a database row.
The following subsections describe how you can refer to and create Globals.

Global References

Globals can be referenced as follows:

@{<globalName>}                                          // reference a Global Value
@{<globalName>.<globalAttribute>}  // reference attribute of Global Object

Globals are not restricted to Security Predicates.  You can make global references in any of the contexts listed below:

 Global Reference     Notes
 Security Predicate 
 Resource Filter eg, screenName = '@{_apikey.user_identifier}'
   salesrep_id = @{current_employee_row.employee_id}
 Resource SqlFrom 
 Rule Expressions You can reference globals in expressions for formulas and validations
 Typical examples might include user id/name update and insert stamping
 JavaScript LogicContext provides access to globals


Global Definition Sources

Globals can be defined in a number of ways as described in the following sub-sections.   Global References described above 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.

Auth Provider (_apikey) Globals

In most cases, your Authentication Provider will make all of the values of the Authentication Token available as Globals (e.g., LoginId), with the possible exception of the Password.

In addition, your Authentication Provider can return a set of Global values.   Typical examples:
  • Scalar values such as UserName
  • Objects such as a database row (e.g., retrieved by LoginId)

Default Authentication Provider Globals

The Default Authentication Provider provides the following variables for an _apikey:
  • user_identifier - e.g, @{_apikey.user_identifier}


Permissions

Permission Properties

Each Role Permission has the properties described below.

Table

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

Permissions Name

Enables you to identify the entry within the list

Access Type

For rows that meet the Predicate, this indicates whether the row can be read or written.  You could, for example, 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.   To illustrate Predicates, we might have a Security attribute (high, low) for a table, so that only Admin roles can read high security rows.

Multiple Permissions for a table

Importantly, you can define multiple Permissions for a given table.  These are added together over all of the roles for the current Api Key. 

REST Endpoints

Each of the API Resources for this project can be selected for access (tables, views, procedures, resources, meta tables).