Role-Based Endpoint Access

Role-Based Endpoint Access
lac31
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.
For each user, you can specify a set of authorized roles and global values/objects and use the set of global values, in addition to those values you explicitly add, in the resource and security filters that the built-in authentication provider provides.
 For more information:
In this article:
 
 
Define Roles
You define roles on the Manage, Roles, Details tab. Be default, your role cannot read, insert, update, and delete database tables. You can define the level of access you want this role to have to database tables using the checkboxes on this tab. By default, your role has access to all tables, views, resources, procedures, functions, and meta tables that are part of your API. There is no limit to the number or roles you can define 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.
Grant Permissions to Roles to Call All Functions
Prerequisite:
 The function is created.
You can grant a role permission to call all functions from the Manage, Roles, Details tab or from the Manage, Roles, Function Permissions tab. This procedure describes how to grant role access to functions from the Manage, Roles, Details tab.
  1. With your API open, go to the Manage, Roles, Details tab.
  2. Select the role to which you want to set access.
  3. Select the 
    All Functions
     checkbox and then save your changes.
    By default, this checkbox is selected.
The role can now call all functions.
Set the Default Access for Objects
  1. With your API open, go to the Manage, Security, Details tab.
  2. Select the role to which you want to set access and set the following access levels:
    Default Database Table Access
     
    Defines the role's level of access to database tables.
    Options:
     Read, Insert, Update, Delete
    Automatic Enabling of REST EndPoints
     
    If you want to individually select the reachable end points, leave the option cleared.
    Options:
     All Tables, All Views, All Resources, All Procedures, All Functions, All Meta Tables
The default access is set for the object.
Control Permissions to Roles to Call Specific Functions
You can control a role's permission to call specific functions. You control a role's permission by changing an existing permission to a function or by creating a new permission to a function. Function-level permissions supersede role-level permissions.
  1. With your API open, go to the Manage, Roles, Function Permissions tab.
  2. Select the role to which you want to grant a permission to the function.
  3. Do one of the following:
    • Create a new permission to a function by clicking 
      Create Permission
      .
      A permission row for the function is added to the table.
    • Change an existing permission to a function.
  4. Complete or change the following fields and then save your changes:
    Function
     
    The function you want to set function-level call-privileges for this role.
    Privilege
     
    The role's call-privilege to the function. By default, the role can call the new function.
    Comments
     
    Comments about this function permission.
Your changes are saved.
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.
 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 calling the JavaScript code.
Default:
 SQL
The global is defined for the role.
Reference Globals
Globals are global values or global objects. For example, the 
Clearance
 global value 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
You define a role's permissions to tables A role's default read/write access applies to all tables not specifically defined in the role permissions. There is no limit to the number of permissions you can define for a table. 
CA Live API Creator
 adds the permissions together over all of the roles for the current auth token.
With your API open, go to the Manage, Roles, Table 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}'
Your table permission is defined.
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. Use the following syntax to specify the filter:
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 Permissions tab:
  CA Technologies  
Default Security Settings
When you first create an API, you can restrict default access. In the following image, users with the 
Supplier
 role can only access the 
v1 SupplierAlert
 and 
v1 SupllierInfo
 tables:
  Screen Shot 2016-08-05 at 4.20.52 PM.png  
Select API Resources for an API 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.  With your API open, go to the Manage, Roles, REST End Points tab and select the role you want to grant access.
  2. 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 in the Demo API:
    CA Technologies  
  3. Enable one or more of the API resources to which you want to grant the role access and then save your changes.
     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 is granted access to the specific table, view, procedure, custom resource, or meta tables API resource.