Application users are assigned a role, which represents a set of permissions that allow specified operations (GET, POST, PUT, or DELETE) to be performed on a specific resource. When the user submits a request to the App Services API, the user’s permissions are checked against the resource paths that the user is trying to access. The operations are only allowed if they are valid.
Note: An exception to permission-based access exists for users that have higher-level access credentials than an application user. For example, if a user submits application-level credentials, the user has access to all the resources of the application, and is not limited by permissions. Even higher-levels of access exist, such as organization access, which gives the user more widespread access to resources. However, access levels above application user should be used sparingly and carefully. See Authentication and access in App Services for further details about access levels.
Roles
Every application has three roles by default:
- Guest: The guest role for unauthenticated users
- Default: The default role for authenticated users
- Administrator: An empty role
The Guest role has a basic set of permissions for creating a new user or to register a device. You can remove permissions from the role or add permissions. The Default role includes permissions for the set of operations you want an authenticated user to be able to perform. Users automatically get added to the Guest role before they’re authenticated. After they’re authenticated, users are automatically added to the Default role.
The Administrator role has no permissions and is available for you to add permissions and to which you can assign users.
You can define other roles (in addition to Guest, Default, and Administrator), specify permissions for them, and assign users to them.
Note: Do not confuse the Administrator role with an administrator of the organization. When you create an organization, an administrator (also known as an admin user) is created for the organization. After providing credentials, the organization administrator has full access to all of the administration features of the App Services API. By comparison, the Administrator role is simply a role (initially without permissions) that can be assigned to any user.
Specifying permissions for a role
You specify permissions for a role using this format:
<operations>:<entity path pattern>
The <operations> field is a comma-delimited set of REST operations (GET, PUT, POST, DELETE) that are allowed for the specified entity path. The <entity path pattern> parameter is evaluated using Apache Ant pattern matching (see http://ant.apache.org/manual/dirtasks.html#patterns).
We recommend you use the Admin Portal to add or remove permissions in a role. You can also use the portal to create or delete a role. (If you want to manage roles and permissions programmatically, see Role.)
On the left sidebar of the portal, click Roles. This displays the roles defined for the application. Click Add to create a role. To delete a role, select the role you want to delete and click Remove. To view the privileges in a role, click the role.
Suppose you created a role named 'worker'. Here’s what the privileges for the role might look like:
Notice that specific privileges for operations are represented using checkboxes in the Permission Rules section. The path indicates the resource path for which the permissions apply. The permissions apply to all resources in the specified path directory and its subdirectories. As currently specified, the worker role has GET permission on the base directory path (/) and all resource paths below it (in other words, all resource paths).
You can add a permission, by entering the entity path pattern in the Path field of the Add Permission Rule section, and checking the operation checkboxes (get, post, put, and delete) as appropriate. For example, the following adds permission to create a user:
Click Add, and the permission is added to the role.
Permission examples
Here are some examples to illustrate how permissions are specified:
- A permission to create a user:
post:/users/*
- A permission that allows someone to look at a specific user:
get:/users/john.doe
- A permission that allows the current user to see his activity feed:
get:/users/${user}/feed/*The ${user} in the entity path refers to a variable that represents the current user’s UUID.
- A permission allowing linked entities to be read:
get:/users/${user}/**The /** in the entity path is a wildcard that matches everything under that path. This means that the full specification matches multiple resource paths, including, but not limited to, the following:
/users/${user}/feed /users/${user}/feed/item1/a/b/c - A permission that allows the current user to add himself or another user to a group:
post:/groups/${user}/users/**
