Chapter 7. Data Roles

7.1. Permissions
7.2. XML Definition

Data roles, also called entitlements, are sets of permissions that are defined per VDB that dictate data access (create, read, update, delete). The use of data roles is controlled system wide with the property in <jboss-install>/server/<profile>/deploy/teiid/teiid-jboss-beans.xml file in bean configuration section of RuntimeEngineDeployer with property useDataRoles.

Once data roles are enabled, the access permissions defined in a VDB will be enforced by the Teiid Server.

Warning

Teiid uses a deny by default permission system, so all VDBs deployed to the server will need roles granting access with this feature enabled.

7.1. Permissions

CREATE, READ, UPDATE, DELETE (CRUD) permissions can be set for any resource path in a VDB. A resource path can be as specific as the fully qualified name of a column or as general a top level model (schema) name. Permissions granted to a particular path apply to it and any resource paths that share the same partial name. For example, granting read to "model" will also grant read to "model.table", "model.table.column", etc. Allowing or denying a particular action is determined by searching for permissions from the most to least specific resource paths. The first permission found with a specific allow or deny will be used. Thus it is possible to set very general permissions at high-level resource path names and to override only as necessary at more specific resource paths.

Permission grants are only needed for resources that are visible. All non-visible, typically physical, models in a VDB are automatically inaccessible by user level requests. Permissions are also only applied to the columns and tables in the user query - not to every resource accessed transitively through views and procedures. It is important therefore to ensure that permission grants are applied consistently across visible models that access the same resources.

To process a SELECT statement or a stored procedure execution, the user account requires the following access rights:

READ - on the Table(s) being accessed or the procedure being called.
READ - on every column referenced.

To process an INSERT statement, the user account requires the following access rights:

CREATE - on the Table being inserted into.
CREATE - on every column being inserted on that Table.

To process an UPDATE statement, the user account requires the following access rights:

UPDATE - on the Table being updated.
UPDATE - on every column being updated on that Table.
READ - on every column referenced in the criteria.

To process a DELETE statement, the user account requires the following access rights:

DELETE - on the Table being deleted.
READ - on every column referenced in the criteria.

To process a EXEC statement, the user account requires the following access rights:

READ - on the Procedure being executed.

7.2. XML Definition

Data roles are defined inside the vdb.xml file (inside the .vdb Zip archive under META-INF/vdb.xml) if you used Designer. This example will show a sample "vdb.xml" file with few simple data rules.

For example, if a VDB defines a table "TableA" in schema "modelName" with columns (column1, column2) - note that the column types do not matter. And we wish to define three roles "RoleA", "RoleB", "RoleC" with following permissions:

RoleA has privileges to read, write access to TableA, but can not delete.
RoleB has no privileges that allow access to TableA
RoleC has privileges that only allow read access to TableA.column1

Example 7.1. vdb.xml defining RoleA, RoleB, and RoleC

<?xml version="1.0" encoding="UTF-8"?>
<vdb name="sample" version="1">

    <model name="modelName">
        <source name="source-name" translator-name="oracle" connection-jndi-name="java:myDS" />
    </model>

    <data-role name="RoleA">
        <description>Allow all, except Delete</description>

        <permission>
            <resource-name>modelName.TableA</resource-name>
            <allow-create>true</allow-create>
            <allow-read>true</allow-read>
            <allow-update>true</allow-update>
        </permission>

        <permission>
            <resource-name>modelName.TableA.colum1</resource-name>
            <allow-create>true</allow-create>
            <allow-read>true</allow-read>
            <allow-update>true</allow-update>
        </permission>

        <permission>
            <resource-name>modelName.TableA.column2</resource-name>
            <allow-create>true</allow-create>
            <allow-read>true</allow-read>
            <allow-update>true</allow-update>
        </permission>

        <mapped-role-name>role1</mapped-role-name>

    </data-role>

    <data-role name="RoleC">
        <description>Allow read only</description>

        <permission>
            <resource-name>modelName.TableA</resource-name>
            <allow-read>true</allow-read>
        </permission>

        <permission>
            <resource-name>modelName.TableA.colum1</resource-name>
            <allow-read>true</allow-read>
        </permission>

        <mapped-role-name>role2</mapped-role-name>
    </data-role>
</vdb>

The above XML defined two data roles, "RoleA" which allows everything except delete on the table, "RoleC" that allows only read operation on the table. Since Teiid uses deny by default, there is no explicit data-role entry needed for "RoleB". The "mapped-role-name" defines the JAAS "role" to whom these policies are applicable.

For assigning roles to your users in the JBoss AS, check out the instructions for the selected Login Module. Check the "Admin Guide" for configuring Login Modules.

The "vdb.xml" file is checked against the schema file vdb-deployer.xsd, check the documents sections of the Teiid kit to find a copy of the schema file.