Role-Based Endpoint Access

Role-Based Endpoint Access
lac32
Role-based access control (RBAC) provides authorization control over what resources, rows, and columns authenticated users can access. You can simplify administration using RBAC instead of assigning authorization directly to users.
A role is authorized to the union of its permissions. An auth token is an authorized union of its role-based permissions. Roles control READ, INSERT, UPDATE, and DELETE to the schema and resource objects and fine-grain permissions on base entity (table or view) rows and columns.
You can assign users to multiple roles. For a role, you can define the following:
  • What REST endpoints a user can access (either by default or specific enumeration).
  • Permissions that specify what rows/columns a user can access for a specific entity.
In this article:
Predefined Roles
By default, when you create an API, the API Documentation, Full access, and Read only roles are included. These roles give users access to all table, view, stored procedure, resource, function, and meta table REST endpoints that are part of your API. Meta tables are system (for example, 
@tables
@views
, and 
@procedures
) that give you access to the internal definitions for those tables, views, stored procedures, functions, and resources.
For more information about the system REST endpoints 
CA Live API Creator
 provides as metadata services, see System REST Endpoints.
You can authorize users to perform API Creator facilities by assigning one of the following predefined roles:
Role
Authorizes
API Documentation
API Creator uses this role only for documentation calls, that is, to generate OpenAPI (Swagger) documentation. API Creator uses the table, view, stored procedure, resource, function, and meta table REST endpoints that this role has permission to generate the documentation.
By default, this role has access to all table, view, resource, stored procedure, function, and meta table REST endpoints that are part of your API.
  • Do not use this role to assign users permissions to make calls.
  • Do not remove this role or make it unavailable.
Full access
Users assigned this role have full access to the repository.
Read only
Users assigned this role have read-only access to the repository.
Add Roles
There is no limit to the number or roles you can define for a user.
  1. With your API open, in the Manage section, click 
    Security
    .
    The Details tab displays by default.
  2. Click 
    Add
    .
    A new role displays in the roles list.
  3. Complete the following and then save your changes:
    • Define the role name.
    • Set the default permissions (Read, Insert, Update, and Delete) for the role to all entities (tables and views). These are the role's role-level permissions. By default, roles have view-only permission to views.
      You can optionally set a role's permission to call specific entity-based endpoints. For more information, see the "Set Entity-Level Permissions for Roles" section.
    • Set the selected role's ability to invoke all table, view, resource, stored procedure, function, and meta table REST endpoints.
The new role is added.
Set Function-Level Permissions for Roles
By default, roles have access to all functions. You can control a role's permission to call specific function-based endpoints. 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.
 
Prerequisite:
 You have defined at least one function in your API.
  1. From the Details tab, click 
    Function Permissions
    .
    The Function Permissions tab displays.
  2. Select the role to which you want to grant a permission to the function.
  3. Clear the 
    Enable All Functions
     checkbox.
     Clearing this checkbox clears the 
    All Functions
     checkbox on the Details tab.
  4. Do one of the following:
    • Create a new permission to a function by clicking 
      Create Permission
      .
      A permission row for the function is added for the role.
    • Change an existing permission to a function.
  5. Complete or change the following fields and then save your changes:
     
    Function
     
    The function that you want to set function-level permissions for this role.
     
    Privilege
     
    Specifies whether the selected role has or does not have permission to call this function.
     
    Options:
     
    • Execute. The role has permission to call the function.
    • Do not execute. The role does not have permission to call the function.
     
    Default:
     Execute
     
    Comments
     
    Comments about this function permission.
The permission is created and defined. The role has permission to call the function.
Set Entity-Level Permissions for Roles
You can set a role's permission to call specific entity-based endpoints. The number of permissions you add increases the response time for the resources referencing the entity in the definition.
Entity-level permissions supersede role-level permissions.
 You can optionally set a role's default permissions (Read, Insert, Update, and Delete) to all entities (tables and views).
For more information, see the "Add Roles" section.
  1. From the Details tab, click 
    Entity Permissions
    .
    The Entity Permissions tab displays and the entity permissions display in the list.
  2. Select the role to which you want to grant a permission to the entity.
  3. Do one of the following:
    • Create a new permission to an entity by clicking 
      Add
      .
      A permission row for the entity is added for the role.
    • Change an existing permission to an entity by clicking the entity name in the list.
  4. Complete or change the following fields and then save your changes:
     
    Entity
     
    Specifies the entity (using the syntax: 
    <database prefix>:<table or view name>
    ) to which the permission applies.
     
    Permission name
     
    Identifies the entity within the list.
     
    Access type
     
    Defines the operation (Read, Insert, Update, and Delete) that the selected role can perform for the selected entity/column/row-filter combination. For example, you can create an entity permission that allows the selected role to insert rows for one entity permission set and then create another entity permission that allows the selected role to read rows for matching a defined row filter. There is no limit to the number of permission entries you can define for an entity.
     
    Options:
     Read, Insert, Update, and Delete
     
    Columns
     
    Defines the columns for which the selected role can view data. The columns that you do not define here are returned as null values in the JSON response.
     
    Row Filter
     
    Defines row access. Row filters are a selection filter that is appended to all requests against the entity. You can use a global in a permission as part of a filter.
     
    Example 1:
     A "Security" global (high, low) for an entity, 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}'
     
    Example 3:
     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 using double quotes (") to denote a column name and single quotes (') to denote a string, but not all (for example, Postgres).
The role's permission to call specific entity-based endpoints is set.
Set Resource-Level Access for Roles
By default, the predefined roles–API Documentation, Full access, and Read only–have access to all table, view, resource, stored procedure, function, and meta table REST endpoints that are part of your API. You can grant role access to call only specific table, view, resource, stored procedure, function, or meta table REST endpoints. You can also set verb-based permissions. Resources of type Normal (that are based on tables or views) inherit the security permissions from the underlying entity.
  1. With your API open, in the Manage section, click 
    Security
    .
  2. Do one of the following:
    • To define access to tables, views, stored procedures, resources, or meta tables, complete the following:
      1. Select the role that you want to authorize access.
      2. Click 
        REST Endpoints
        .
        The Tables tab displays by default.
      3. Select the tab for the resource you want to define access to: 
        Tables
        Views
        Procedures
        Resources
        , or 
        Meta Tables
        .
    • To define access to functions, click 
      Function Permissions
      .
  3. Clear the 
    Enable All Tables/Views/Procedures/Functions/Resources/Meta Tables
     checkbox.
     Clearing this checkbox clears the 
    All Tables/Views/Procedures/Functions/Resources/Meta Tables
     checkbox on the Details tab.
    A list of resource endpoints display.
  4. Select the checkbox for one or more of the REST endpoint to which you want to authorize the role access and then save your changes.
     You can select all of the REST endpoints listed by clicking 
    Check All
     or clear all the checkboxes by clicking 
    Clear All
    .
The role is granted access to the specific table, view, resource, stored procedure, function, or meta table REST endpoint.
Define Globals for Roles
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.
  1. From the Details tab, click 
    Globals
    .
    The Globals tab displays. The following image shows an example of the
    current_employee_row
    global for the Sales Rep role in the Demo database:
     
  2. Complete one of the following:
    • To define an existing global for the role, click the name of the global you want to define from the list of globals.
    • To create a new global, click 
      Add
       above the list of globals.
  3. Define the following fields and then save your changes:
     
    Code
     
    Based on the Language option you select, enter SQL or JavaScript code. If you select SQL as the language, the code is the valid SQL as part of supplied SELECT, returning a row from which you can access attributes.
     Use existing auth token globals in this SQL, such as the 
    LoginId
     global.
    For more information about the 
    LoginId
     global, see Authorization.
     
    Language
     
    Determines how the transaction invokes the global.
     
    Options:
     
    •  
      SQL.
       SQL queries read information from the database. Fixed values are SQL queries that the transaction executes against your database.
    •  
      JavaScript.
       Transactions use the global that is returned as a result of calling the JavaScript code.
     
    Default:
     SQL
    Database
     
    (SQL) Defines the data source on which you want the selected role to have permission to invoke.
     
    Required
     
    Define whether to require user to define a value for this global. For example, if you have security settings that restrict access to data based on the user's department number, ensure the security of this data by requiring that the user define the department number.
The global is defined for the role.
Reference Globals
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 retrieve data based on the information already available to you.
You can reference a global in any of the following contexts:
  •  
    Security predicate.
     Predicates represent constant expressions and expressions that refer to globals and use the following syntax:
    @{<globalName>.<globalAttribute>}
  •  
    Resource (Entity Permissions) row filter.
     
     
    Example 1:
     
    screenName = '@{_apikey.user_identifier}'
     
    Example 2:
     
    In the Demo API, the row filter set on the 
    demo:PurchaseOrder
     entity allows users who are assigned the Sales Rep role to modify purchase orders for which they are the assigned rep using a global defined in SQL language. 
    salesrep_id = @{current_employee_row.employee_id}
    For more information about the Demo API, see Business Logic API Project Sample .
  •  
    Resource SqlFrom.
     
  •  
    Rule expression.
     In expressions for formulas and validations. Typical examples include user id/name update and insert stamping.
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.
You can reference as:
  •  
    A global value.
     Syntax:
    @{<globalName>}
  •  
    An attribute of a global object.
     Syntax:
    @{<globalName>.<globalAttribute>}
For more information: