Managing user role assignments

The purpose of roles is to control what services non-admin users have access to for a given app. Each user can be assigned a single role per app. This is normally done from the Users tab of the DreamFactory admin console but it can also be done via the API. If no assignment is made the user inherits the default role for the app, which can be set from the Apps tab in the admin console. To use the API to create and manage roles you must be an admin user or a user with a role that allows API access to /system/role. When operating on more than one record, the default behavior is to stop after the first error. Any successes before the error will be committed to the database. To keep going with best effort for all records set the query param continue=true. To revert all changes on any error set the query param rollback=true.

Delete (DELETE)

WARNING: It is currently not possible to use the API to delete a role's service mapping by supplementing a Role deletion call with the related=role_service_access_by_role_id parameter and an associated JSON body. Any call to DELETE /api/v2/system/role/{id} *will result* in the deletion of said role and all associated service-to-role mappings. Please use the web-based administration console to delete any undesired service mappings for a given role. Otherwise, you can issue a PUT method to modify the role's service mappings.

Role and Role Service Access Details

Let's look closer at what makes up a role.

name is the display name for the role.

description is the text description for the role.

is_active enables and disables the role. Users assigned to an inactive role can't log in.

role_service_access_by_role_id is an array of service/component pairs the role allows access to.

verb_mask defines a bit mask for which verbs are allowed on each service/component pair.

GET: 1,
POST: 2,
PUT: 4,
PATCH: 8,
DELETE: 16

For example to select GET and PATCH, set verb_mask to 1 + 8 = 9. To allow all verbs, set verb_mask to 31.

requestor_mask defines a bit mask for allowing API and/or script access on each service/component pair.
Script access means that a script service or event script can use platform.api calls to access the selected service/component.

API: 1,
SCRIPT: 2

1 = API access only
2 = Script access only
3 = API and script access

To allow both API and script access to the selected service/component, set requestor_mask to 3.

service_id is the database id for the service for this role service access entry.

component is the portion of the service this entry allows access to. You can use the component to fine tune the role access.

user_to_app_to_role_by_role_id defines which user/app this role applies to. Each user can have a unique role for each app.

role_lookup_by_role_id defines name/value pairs that apply to this role.

We'll focus on role service access using a service named mysql. Here are some detailed examples showing common combinations of service and components.

No Components

Component = (empty string)
Allows access at the root service level to return a list of resources for the service. GET is the only applicable verb.

All Components

Component = *
Allows access to all resources for the service including schemas, tables (records), stored procedures, and functions. This setting should be used with care.

Table Components

To access specific tables from the API there are three levels of role service access to deal with.

Component = _table/
Allow listing of all tables available to API

Component = _table/*
Make all tables available to API

Component = _table/todo
Make a single table named 'todo' available to API

The second two control which tables are available to the API, while the first one controls whether or not a list of available tables can be retrieved. You can allow API access to tables that can't be listed, but you can't list tables that have no API access.

With no role service access provisioned a list of available tables cannot be returned. A 403 error is returned.

Stored Procedure and Functions Components

Configuring access to stored procedures and functions is essentially the same as _table and _schema. Consider a trivial stored procedure named 'findname'. It takes a single input param named 'str' and returns all 'todo' table records with matching name.

BEGIN
SELECT * FROM todo
WHERE name = str;
END

To access stored procs from the API there are three levels of role service access to deal with.

Component = _proc/
Allow listing of all procs that are available to be called.

Component = _proc/*
Make all procs available for calling.

Component = _proc/findname
Make a single proc named 'findname' available for calling.

The second two control which procs are available to be called, while the first one controls whether or not a list of available procs can be retrieved. You can call procs that can't be retrieved, but you can't retrieve procs that can't be called.

With no role service access provisioned a list of available procs cannot be returned. A 403 error is returned.

With access allowed for calling and listing you can now see findname in the list.

GET /mysql/_proc
{
"resource": [
{
"name": "findname"
}
]
}

Assigning users to roles

To assign a role you have to include the relationship 'user_to_app_to_role_by_user_id'. As an example let's say we want to assign user id 100 with a certain role for a certain app. If the role id is 7 and the app id is 4, the following would create the required relationship to assign that role to that user for that app.

To delete a role assignment, do a PUT with relationship 'user_to_app_to_role_by_user_id'. Set the user_id field to null for the one you wish to delete. After deletion, the user will inherit the default role for that app.