Managing access by defining permission rules

Permissions

Permissions allow you to define user access to perform GET, POST, PUT, or DELETE operations on specific resources. When the user submits a request via your app code to the API BaaS API, the user’s permissions are checked against the resource paths that the user is trying to access. The request succeeds only if access to the resource is allowed by the permission rules you specify.

Permissions syntax

In API BaaS, permissions are represented in the following format:
<operations>:<resource_path>
  • <operations>: A comma-delimited set of REST operations (GET, PUT, POST, DELETE) that are allowed for the specified entity path. For example, GET, POST would allow only GET and POST requests to be made to the specified resource.
  • <resource_path>: The path to the resources to be accessed. Complex paths can be specified using Apache Ant pattern syntax. For example, /users would apply the permission to the users collection, while /users/Tom would apply the permission to only the user entity with username 'Tom'.

Roles

In API BaaS, permissions are assigned to individual user entities using roles. Roles are named sets of one or more defined permissions, and are useful for defining specific access levels to resources in your API BaaS data store. Multiple roles can be assigned to a user, giving you a great deal of flexibility in how access to resources are defined.

For example, in a blogging app you might create a 'reviewer' role that allows GET and PUT access to an articles collection to allow the user to retrieve and update articles, but now allow them to create new articles.

Creating permissions sets with roles

To assign permissions to roles, do the following:

Admin portal

The API BaaS admin portal is the best place to create and manage permissions and roles. While you can manage roles and permissions programmatically (see Using permissions), security-related calls from a mobile app will pose a security risk. Consider doing so only from a server-side web application.

To make role and permission rule changes in the Admin Portal, do the following:

When preparing an application for production use, a good first step is to edit permission rules for the Default role. This role will be applied for every user who authenticates as an Application User.

For example, in the Default role, first remove the permission rule that grants full access to all authenticated users. You could then begin by creating a rule that grants access for the authenticated user to makes changes only to data associated with their account.

GET,PUT,POST,DELETE:/users/me/**

Example

Suppose you created a role named "worker". Here’s what the privileges for the role might look like:

  1. Click Add Permission.
  2. In the New Permission dialog, in the Path box, enter the entity path pattern.
  3. Select check boxes for the operations you want to allow, as appropriate. For example, the following adds permission to create, read, and update widgets:

  4. Click Add to add and the permission to the role.

  1. On the left sidebar of the portal, click Users > Roles. This displays the roles defined for the application.
  2. To create a role, click the Add button (it looks like a person's silhouette). To delete a role, select the role you want to delete and click the Remove button (it looks like a trash can). To view the privileges in a role, click the role.

cURL

curl -X POST "https://api.usergrid.com/my-org/my-app/roles/ -d '{"name":"manager","title":"Manager","permission" : "get,put,post,delete:/users/me/groups"}'

JavaScript (HTML5)

It is recommended that you use the Admin Portal for administrative activities instead of using JavaScript to do them programmatically in your app.

Ruby

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
result = app.create_role name: 'manager', title: 'Manager', 'permission' : 'get,put,post,delete:/users/me/groups'

Node.js

The example assumes use of the Node.js module.

var options = {
    method:'POST',
    endpoint:'roles',
    body:{ 
        name:'manager', 
        title:'Manager',
        permission : 'get,put,post,delete:/users/me/groups'
    }    
};
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call        
    }
});

Default roles

When defining user access to your application's data, you create roles, specify permission rules for them, then associate users with the roles. Your API BaaS applications include three predefined roles when you create an application.

The following table lists the three roles included by default. Note that two of these are in effect and applied from the time your application is created (until you change them). The API BaaS applies the following default behavior:

  1. An unauthenticated user is automatically added to the Guest role so that they can register for a user account.
  2. A user who has a user account and authenticates with it is automatically added to the Default role. Note that by default, this role is very permissive. Be sure to restrict it with specific permission rules before deploying to production.
Role Description Notes
Guest

Default for unauthenticated users. Includes a basic set of permissions for unregistered or unauthenticated users. Users are automatically added to the Guest role before they’re authenticated. After they’re authenticated, users are automatically added to the Default role.

Grants permission for a user to create a user account and for their device to be registered. You can change permission rules based on your goals for unregistered user access. This role is designed to provide access for people who haven't yet registered, and allow them to register.

Default

Default for authenticated users. Assigns the associated permissions to all users whose requests are authenticated with a valid authentication token.

Administrator

Unused until you associate it with users or groups. By default, includes no permissions that provide access.

Grants no access. Consider this a blank slate. Add permission rules and associate this role with users and groups as needed.