Complete Using Roles conversion to Markdown. (cherry picked from commit c886d1f2d7c70a55d83046371b4dbf96dc8aafe3)
Project: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/commit/d54b0fb6 Tree: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/tree/d54b0fb6 Diff: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/diff/d54b0fb6 Branch: refs/heads/two-dot-o-dev Commit: d54b0fb614926adbe4f8c108353fbcb753419e99 Parents: c3fb331 Author: Dave Johnson <snoopd...@apache.org> Authored: Thu Aug 6 12:40:08 2015 -0400 Committer: Dave Johnson <snoopd...@apache.org> Committed: Wed Aug 12 13:02:46 2015 -0400 ---------------------------------------------------------------------- docs/security-and-auth/using-roles.md | 183 +++++++++++++++-------------- 1 file changed, 97 insertions(+), 86 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/d54b0fb6/docs/security-and-auth/using-roles.md ---------------------------------------------------------------------- diff --git a/docs/security-and-auth/using-roles.md b/docs/security-and-auth/using-roles.md index 3428405..6404edb 100644 --- a/docs/security-and-auth/using-roles.md +++ b/docs/security-and-auth/using-roles.md @@ -1,10 +1,10 @@ # Using roles -Roles are named sets of one or more 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 or group, giving you a great deal of flexibility in how access to resources are defined. +Roles are named sets of one or more permissions, and are useful for defining specific access levels to resources in your Usergrid data store. Multiple roles can be assigned to a user or group, 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 not allow them to create new articles. ## Default roles -While you can create as many custom roles as you want per application, all API BaaS applications include three default roles. These roles each serve a special purpose and should not be deleted; however, you can and should adjust the permissions assigned to these roles to suit the needs of you app. +While you can create as many custom roles as you want per application, all Usegrid applications include three default roles. These roles each serve a special purpose and should not be deleted; however, you can and should adjust the permissions assigned to these roles to suit the needs of you app. The following table describes each pre-defined role, and the permissions that are assigned to them by default. @@ -39,54 +39,28 @@ The following table describes each pre-defined role, and the permissions that ar </td> <td> - Default for authenticated users. Assigns the associated permissions to all users whose requests are authenticated with a valid access token. +Default for authenticated users. Assigns the associated permissions to all users whose requests are authenticated with a valid access token. - <div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠- __Note__: By default, __grants full access for all resources in your application__. A first task in securing your application should be to restrict access by redefining this role to narrow the access it provides. Remove the default full permission rule and add restrictive permission rules for a production deployment. - </p></div> +<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠+By default, __grants full access for all resources in your application__. A first task in securing your application should be to restrict access by redefining this role to narrow the access it provides. Remove the default full permission rule and add restrictive permission rules for a production deployment. +</p></div> </td> </tr> <tr> <td>Administrator</td> - <td></td> - <td></td> -</tr> -<tr> - <td></td> - <td></td> - <td></td> -</tr> -<tr> - <td></td> - <td></td> - <td></td> + <td>None</td> + <td> + +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. +<div class="admonition note"> <p class="first admonition-title">NOTE</p> <p class="last">⨠+The Administrator role is <i>not</i> the same as an organization administrator, that is, someone who authenticates as an Admin User. The Admin User is an implicit user created when you create an organization. After authenticating, the Admin User has full access to all of the administration features of the Usergrid API. By comparison, the Administrator role is simply a role (initially without permissions) that can be assigned to any user. +</p></div> + + </td> </tr> </table> -Role Permissions Description -Guest -post: /devices -post: /users -put: /devices/* -Assigned to all unauthenticated requests. Includes a basic set of permissions that are commonly needed by unregistered or unauthenticated users. - -Grants permission for a user to create a user account and for their device to be registered. - -Default -get, post, put, delete: /** -Default for authenticated users. Assigns the associated permissions to all users whose requests are authenticated with a valid access token. - -By default, grants full access for all resources in your application. A first task in securing your application should be to restrict access by redefining this role to narrow the access it provides. Remove the default full permission rule and add restrictive permission rules for a production deployment. -Administrator -None - -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. - -Note: The Administrator role is not the same as an organization administrator -- that is, someone who authenticates as an Admin User. The Admin User is an implicit user created when you create an organization. After authenticating, the Admin User has full access to all of the administration features of the API BaaS API. By comparison, the Administrator role is simply a role (initially without permissions) that can be assigned to any user. - ## Creating roles Generally, it is easiest to a create a role for each access type you want to enable in your app. You may, however, assign multiple roles to any user or group entity, so you have the flexibility to define any schema for applying roles that you like. @@ -144,6 +118,18 @@ roleName The name of the role to be created "organization" : "your-org", "applicationName" : "your-app" } + + +### Creating Roles in the Admin Portal + +1. In the left sidebar of the Usergrid portal, click Users > Roles. This displays the roles defined for the application. +Click the '+' button. +2. In the dialog box, provide a 'title' and 'role name.' A title is an alias for the role name. +3. Click 'Create'. The role will be created, but will not have any permissions assigned to it. +4. Click the role you created in the list. +5. Click the 'Add permissions' button. +6. In the dialog box, click the check boxes for the HTTP methods you want to grant permissions for, and enter the resource path in the 'Path' field. +7. The 'Inactivity' field lets you control automatic user logout during periods of inactivity. Set a number of seconds of inactivity before users assigned to this role are automatically logged out. ## Assigning roles Once you have created some roles, you will need to explicitly assign them to a user or group entity. The permissions associated with that role will be granted to the entity immediately for any requests they send that are authenticated by a valid access token. Please note that assigning a role to a group will grant the associated permissions to every user in that group. @@ -172,51 +158,65 @@ For groups, the 'name' property can be used. For users, the 'username' property ### Example response -{ - "action" : "post", - "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", - "params" : { }, - "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users", - "uri" : "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users";, - "entities" : [ { - "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376", - "type" : "user", - "name" : "someUser", - "created" : 1395681911491, - "modified" : 1399070010291, - "username" : "someUser", - "activated" : true, - "file" : "fobnszewobnioerabnoiawegbrn\n", - "metadata" : { - "connecting" : { - "friends" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends", - "likes" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes" - }, - "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376", - "sets" : { - "rolenames" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles", - "permissions" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions" - }, - "connections" : { - "completed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed", - "follows" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows" - }, - "collections" : { - "activities" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities", - "devices" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices", - "feed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed", - "groups" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups", - "roles" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles", - "following" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following", - "followers" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers" - } - } - } ], - "timestamp" : 1402965083889, - "duration" : 41, - "organization" : "your-org", - "applicationName" : "your-app" -} + + { + "action" : "post", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users", + "uri" : "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users";, + "entities" : [ { + "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376", + "type" : "user", + "name" : "someUser", + "created" : 1395681911491, + "modified" : 1399070010291, + "username" : "someUser", + "activated" : true, + "file" : "fobnszewobnioerabnoiawegbrn\n", + "metadata" : { + "connecting" : { + "friends" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends", + "likes" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes" + }, + "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376", + "sets" : { + "rolenames" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles", + "permissions" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions" + }, + "connections" : { + "completed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed", + "follows" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows" + }, + "collections" : { + "activities" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities", + "devices" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices", + "feed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed", + "groups" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups", + "roles" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles", + "following" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following", + "followers" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers" + } + } + } ], + "timestamp" : 1402965083889, + "duration" : 41, + "organization" : "your-org", + "applicationName" : "your-app" + } + + +### Assigning Roles in the Admin Portal + +The easiest way to assign roles to user or group entities is to use the 'Users' tab of the Usergrid admin portal, by doing the following: + +1. In the left sidebar of the admin portal, click Users > Users or Users > Groups to display either the list of users or groups in your application. +2. In the list, click the name of the user or group entity you want to assign roles to to display its details in the right pane. +3. Click the 'Roles & Permissions' tab above the right pane. +4. Click the 'Add Role' button. +5. In the popup, select a role from the drop down menu. +6. Click the 'Add' button. + ## Removing roles At times it may be necessary to remove a role from a user or group entity, for example if a user changes jobs, or the duties of a group are altered. Please note that removing a role from a group will remove the associated permissions from every user in that group. @@ -290,4 +290,15 @@ For groups, the 'name' property can be used. For users, the 'username' property "organization" : "your-org", "applicationName" : "your-app" } + +### Removing Roles in the Admin Portal + +The easiest way to remove roles from user or group entities is to use the 'Users' tab of the Usergrid admin portal, by doing the following: + +1. In the left sidebar of the Usergrid admin portal, click Users > Users or Users > Groups to display either the list of users or groups in your application. +2. In the list, click the name of the user or group entity you want to remove roles from to display its details in the right pane. +3. Click the 'Roles & Permissions' tab above the right pane. +4. Click the role you created in the list. +5. Under 'Roles', click the checkbox beside the role you want to remove from the entity. +6. Click the 'Leave roles' button. \ No newline at end of file
