Role-Based Endpoint Access

denote a column name and single quotes (')
calac41
Role-based access control (RBAC) provides authorization control over what resources, rows, and columns authenticated API users can access. You can simplify administration using RBAC instead of assigning authorization directly to API users.
Roles are authorized to the union of their permissions. An authentication token is an authorized union of its role-based permissions. Roles control READ, INSERT, UPDATE, DELETE, and EXECUTE (on functions) permission to the schema and resource objects and fine-grain permissions on base entity (table or view) rows and columns.
For each role, you can define what REST endpoints an API user can access (either by default or by specific enumeration) and the permissions that specify what rows/columns the 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 API users access to all table, view, stored procedure, resource, function, and meta table REST endpoints that are part of your API. You can access the internal definitions for those tables, views, stored procedures, functions, and resources using the meta table system endpoints (for example, 
@tables
@views
, and 
@procedures
).
For more information about the system REST endpoints 
CA Live API Creator
 provides as metadata services, see System REST Endpoints.
You can authorize API 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 API users permissions to make calls.
  • Do not remove this role or make it unavailable.
For more information about the Swagger documentation, see API Docs.
Full access
Grants the API user full access to the repository.
Read only
Grants the API user read-only access to the repository.
Add Roles
You can assign roles to API users. If you need more roles than the predefined roles in API Creator, add them.
  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 role-level permissions for the role. Role-level permissions are Read, Insert, Update, and Delete permissions to all entities (tables and views) and Execute permissions to all functions.
      You can optionally set a permission for a role to call specific entity-based endpoints. For more information, see the "Set Entity-Level Permissions for Roles" section.
    • Set the ability for the role to call all table, view, resource, stored procedure, top-level function, and meta table REST endpoints.
The new role is added.
Set Function-Level Permissions for Roles
By default, roles have permission to call all functions. You can also set permissions to specific function-based endpoints for a given role. You control role permission by changing existing function-level permissions or by creating new permissions.
Function-level permissions supersede role-level permissions.
If your auth token has more than one role with differing permissions to a function, the EXECUTE permission takes precedence.
Prerequisite:
 You have defined at least one function in your API.
  1. From the Details tab, click the 
    Function Permissions
     tab.
  2. Select the role to which you want to grant a permission to a function.
  3. Do one of the following:
    1. Create a permission to a function by clicking 
      Create Permission
      .
      A permission row for the function is added for the role.
    2. Change an existing permission to a function.
  4. 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 role is granted permission to call or not call this 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) and Execute permissions to all functions.
For more information, see the "Add Roles" section.
Follow these steps:
  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.
    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 row filter for the permission, such as:
    user_ssn = '@{ssn}' or owner_ssn = '@{ssn}'
    Example 3:
     You want API users 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 API users' login id (part of the authentication token). The 
    locate
     SQL function returns the location of string1 in string2.
    For some databases you can denote a column name and single quotes (') using double quotes ("), for example, MySQL and Derby.
The permission for the role 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. Table-based resources inherit the security permissions from the underlying entity.
Follow these steps:
  1. With your API open, in the Manage section, click 
    Security
    .
  2. Define access to tables, views, stored procedures, resources, top-level functions, or meta tables, by completing the following:
    1. Select the role that you want to authorize access.
    2. Click the 
      REST Endpoints
       tab.
      The Functions tab displays by default.
    3. Click the tab (
      Tables
      Views
      Procedures
      Resources, Functions
      , or 
      Meta Tables
      ) for the resource to which you want to define access.
  3. Clear the Enable All Tables/Views/Procedures
    /Resources
    /Top-Level Functions/Meta Tables checkbox.
    Clearing this checkbox clears the All Tables/Views
    /Resources
    /Procedures/Top-Level Functions/Meta Tables checkbox that is 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 that are 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, top-level 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. The transaction uses these variables to determine what data the API user can access. For example, you want to get the API user's department number from their employee information and use it in your security definitions.
  1. From the Details tab, click the 
    Globals
     tab.
  2. Complete one of the following:
    • To define an existing global for the role, click the name of the global that you want to define from the list of globals.
    • To create a global, click
      Add
      above the list of globals.
  3. Define the following fields and then save your changes:
    Global name
    The name for your global variable.
    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 authentication token globals in this SQL, such as the 
    LoginId
     global.
    For example, the following code snippet shows the SQL code for the 
    current_employee_row
     global for the Sales Rep role in the 
    Demo
     API:
    * from "employee" where "login" = '@{_apikey.user_identifier}'
    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 the API user to define a value for this global. For example, if you have security settings that restrict access to data based on the API user's department number, ensure the security of this data. Require that the API user define the department number.
    Default:
     Selected
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. 
CA Live API Creator
generates log entries when it detects non-equal duplicates. You can retrieve data based on the information that is 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 API users who are assigned the Sales Rep role to modify purchase orders for which they are the assigned rep. They can use a global defined in SQL language:
    salesrep_id = @{current_employee_row.employee_id}
    For more information about the
    Demo
    API, see Demo API Sample.
  • Resource SqlFrom.
  • Rule expression.
     In expressions for formulas and validations. Typical examples include API 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:
denote a column name and single quotes (')