Authorization and Role-Based Endpoint Access

Roles are authorized to the union of their permissions. Role-level permissions are Read, Insert, Update, and Delete permissions to all entities and Execute permissions to all functions.  determines what authenticated API calls (API users) have permissions to do by retrieving the authentication token. Authentication tokens are authorized unions of their role-based permissions. Role-based access control (RBAC) provides authorization control over what entity, procedure, resource, and meta table REST endpoints are visible to which roles. You can simplify administration using RBAC instead of assigning authorization directly to API users.
lac52
Roles are authorized to the union of their permissions. Role-level permissions are Read, Insert, Update, and Delete permissions to all entities and Execute permissions to all functions. 
Layer7 Live API Creator
 determines what authenticated API calls (API users) have permissions to do by retrieving the authentication token. Authentication tokens are authorized unions of their role-based permissions. Role-based access control (RBAC) provides authorization control over what entity, procedure, resource, and meta table REST endpoints are visible to which roles. You can simplify administration using RBAC instead of assigning authorization directly to API users.
You can also control a role's permissions to call function-based endpoints, entity-based endpoints, and resource-based endpoints.
For each role, you can define the REST endpoints that an API user can access (either by default or by enumeration) and the permissions that specify what rows/columns the user can access for a specific entity.
For more information about how 
Layer7 Live API Creator
 ensures security, see the Security Examples.
In this article:
 
 
2
 
 
Predefined Roles
By default, when you create an API in API Creator, your API includes the API Documentation, Full access, and Read only roles. 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 
Layer7 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
 
Layer7 Live API Creator
 uses this role only to generate OpenAPI (Swagger) documentation. 
Layer7 Live API Creator
 uses the table, view, stored procedure, table-based resource, function, and meta table REST endpoints that this role has permission to generate the Swagger 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 Access OpenAPI (Swagger) Documentation for your API.
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.
Follow these steps:
 
  1. With your API open, in the Secure section, click 
    API Roles
    .
    The Details tab displays by default.
  2. Click 
    Add
    .
    The 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.
      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 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 permissions.
Function-level permissions supersede role-level permissions.
If your authentication 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.
Follow these steps:
 
  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 can call the function.
    • Do 
      not
       execute. The role cannot call the function.
    Default:
     Execute
    Comments
     
    Comments about this function permission.
The role is granted permission to call or not call this function.
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 
Layer7 Live API Creator
 makes available to each transaction so that they can determine to what data the API user should have access. Global variables are global values or global objects Global name/value pairs that can be database rows. Global objects are named maps of keyword/value pairs. 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.
Follow these steps:
 
  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 that 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 or EXECUTE statement, returning a row from which you can access attributes.
    Use system authentication token globals in this SQL, such as the 
    LoginId
     global. For more information about this global, see The apikeys Endpoint.
    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 sample:
    select * from "employee" where "login" = '@{_apikey.user_identifier}'
    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
     
    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
You can retrieve data based on the information that is already available to you. Global references are independent of the source. 
Layer7 Live API Creator
 behavior is undefined when multiple sources define the same global name. 
Layer7 Live API Creator
 generates log entries when it detects non-equal duplicates.
You can reference a global in the following contexts:
  • A global value.  
     
    @{<globalName>}
  • 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.
  • Free SQL resource.
     
  • Rule expression.
     In expressions for formulas and validations. Typical examples include API user id/name update and insert stamping.
For more information:
Set Entity-Level Permissions for Roles
You can set a role's permission to call specific entity-based endpoints. By setting entity-level permissions for roles, you are applying security access (Read, Insert, Update, or Delete) to individual tables or specified/defined set of rows and columns. 
Layer7 Live API Creator
 automatically reuses the permissions that you define over your resources, which can simplify compliance verification.
Entity-level permissions supersede role-level permissions.
The number of permissions that you add increases the response time for the resources that reference the entity in the definition.
You can optionally set a role's default permissions (Read, Insert, Update, and Delete) to all entities and Execute permissions to all functions.
For more information, see the "Add Roles" section.
For examples of setting entity-level permissions for roles, see Security Examples.
Follow these steps:
 
  1. From the 
    Details
     tab, click the 
    Entity Permissions
     tab.
    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 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
     
    Specifies the columns for which the selected role can access. 
    Layer7 Live API Creator
     returns the columns that you do not specify in this list as null values in the JSON response.
    Example:
     
    "order_number", "amount_total", "notes", "customer_name", "salesrep_id"
    Row Filter
     
    Specifies the rows for which the selected role can access. Row filters are selection filters that 
    Layer7 Live API Creator
     appends to requests against the entity. You can use a global in a permission as part of a filter. 
    Layer7 Live API Creator
     injects the row filter into the queries on the designated table. Security for entity permissions (entity-level permissions for roles) at the row level can include a simple Where clause, a global, and references to the parent for filtering the rows themselves.
    You can reference a simple constant, a simple global, an attribute of a row global, or an attribute in a parent table.
    The following example shows an example of referencing a simple constant. In the 
    Demo
     API sample, the API User role includes the 
    Access products 2 full
     entity permission with the following row filter:
    "product_number" = 2
    To reference a simple global
    , use the following syntax:
    @{<global_name>}
    Example 1:
     
    In the 
    Demo
     API sample, the 
    API User
     role includes the 
    Access orders
     entity permission with the following row filter:
     
    "customer_name" = '@{customerName}'
    To reference an attribute of a row global
    , use the following syntax:
    @{<global_name>.<attribute_name>}
    Example 2:
     
    In the 
    Demo
     API sample, the 
    Sales Rep
     role includes the 
    My Order - no update of paid flag
     entity permission with the following row filter:
     
    "salesrep_id" = @{current_employee_row.employee_id}
    To reference an attribute in a parent table
    , use the following syntax:
    <role_name>.<attribute in parent table> = '@{<global_name>}'
    Example 3:
     
    In the 
    Demo
     API sample, the 
    LineItem
     table is related to the 
    PurchaseOrder
     parent table using the 
    PurchaseOrder
     role name. The  
    API User
     role includes the 
    Access lineitems
     entity permission. This permission restricts line items to a customer by way of the following row filter:
     
    PurchaseOrder.customer_name = '@{customerName}'
    The customer is defined using the 
    @{customerName
     } global reference that is under the 
    Restricted access
     authentication token. In this example, it is set to 
    Bravo Hardware
    . However, in production environments, the value for the global reference is typically set from the authentication provider (for example, an LDAP property).
    To reference a complex query,
     see the example of complex permission predicates in Security Examples
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 the 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 Secure section, click 
    API Roles
    .
  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 endpoints to which you want to authorize the role access, and then save your changes.
     You can select the REST endpoints that are listed by clicking 
    Check All
     or clear 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.