This article describes how to leverage SharePoint 2013 permission management to create different roles in an app for SharePoint.
When you develop an app for SharePoint, you might want to assign roles to different users. Each role accesses a subset of information and does different tasks. You can write code to create these roles. The more efficient approach is to leverage SharePoint 2013 permission management to create those roles. For the second approach, you don’t write code and you set permissions for those roles (groups) in the hosting SharePoint website.
Travel app for SharePoint
This article uses a travel app for SharePoint to show how to set permissions. The app allows employees to request a business travel, managers to approve/manage travel requests, and finance department to monitor the travel budget. The app stores information such as individual user profiles, reporting structures, user 12-month travel history, group total travel spending, and the remaining budget in the hosting site. More importantly, roles are created using SharePoint groups with different permissions.
The travel app supports three roles: administrator, requestor, and approver. An administrator manages all requests. A requestor submits new travel requests. Approvers approve or reject requests. As user behaviors of the app depend on roles, we can leverage SharePoint 2013 permission management to create those roles. The following sections show how to set the app permissions as well as the hosting website permissions.
To create these roles, after setting your app permissions, set the hosting website permissions as well as the list permissions.
First, set app permissions.
Set the app permissions
When developing an app for SharePoint in Visual Studio 2012, for the app permission setup, configure the app manifest file, AppManifest.xml.
As shown in Figure 1, you can assign different permissions to different scopes. In the travel app, we assign Manage permission to the Web scope and Read permission to the User Profiles (Social) scope so the app can manage data from Custom Lists on the hosting website and extract user information using the User Profile APIs.
App permissions in SharePoint 2013 discusses types of app permissions, permission request scopes, and permissions management. Plan app permissions management in SharePoint 2013 discusses app permission request scopes, app permission requests, and app authorization policies.
After setting app permissions, the next step is to set hosting website permissions.
Set the hosting website permissions
If your app business logic is complex and your app has different roles assigned to different users, managing group permissions on the SharePoint Online site can be a simple way to keep your SharePoint users aligned with your business requirements.
Note that you must be the site administrator of the hosting website to perform the actions below.
First, create three groups—each group corresponds to one role: administrator, requestor, or approver.
Create a SharePoint group and add group members
Within the SharePoint Online site, each user is a member of at least one group. You can use the default groups listed in table 1.
Use this group to grant people contribute permissions to the SharePoint site.
Use this group to grant people full control permissions to the SharePoint site.
Use this group to grant people read permissions to the SharePoint site.
Or create a new group and assign it a permission level.
From your Office 365 SharePoint Administrator portal, on the Site Actions menu, choose Site Settings > Users and Permissions > People and groups.
To create a new group, as shown in figure 2, choose New > New Group.
Figure 2. Create a new group
Add members to a group
After creating a new group “Travel approvers” for all travel approvers, add those approvers. To add approvers, as shown in figure 3, choose New > Add Users, and then add approvers to this group.
Change group permissions
Choose your hosting website and then choose Site Settings > Users and Permissions > Site permissions.
You can see all groups on the site. To edit group permissions, as shown in figure 4, select the group, and then choose “Edit User Permissions”.
To modify group permissions, select the permissions to assign to the group and clear the permissions you want to remove, and then choose OK. For example, as shown in figure 5, choose the group “Travel approvers” and add it the “Contribute” permissions.
Review all permissions level within a site
If you are not sure which permission level to choose, go back to the Site permissions page, and choose Permission Levels as shown in figure 6.
Figure 6. Review website permission levels
All available permission levels on the site are listed. For example, as shown in figure 7, choose “Contribute” to check all the permissions in this site and what actions a permission can do.
Click the link (shown in figure 7) of one particular permission level to review the permissions. As shown in figure 8, you can review and update a permission level name, description as well as the permissions.
Except for “Full Control” and “Limited Access”, there are five editable default permission levels: “Design”, “Edit’, “Contribute”, “Read”, and “View Only”. You can enable/disable a specific permission in each permission level. You can also create a new permission level.
Create a new permission level
To create a new permission level, as shown in figure 9, choose Add a Permission Level, then add the permissions to include in this level.
Now you are ready to set the list permissions. The list is used to store you app data.
Set list permissions
Apps for SharePoint often use lists to store data. A SharePoint 2013 site provides the ability to manage permissions on individual lists and libraries. If you use a site template other than the team site, by default, the site owners have the “Manage Hierarchy” permission level. Any user with the “Full Control” permission level on a particular securable object can also manage permissions on that securable object.
Set permissions on a list
To set permission on a list, open a Custom List on the hosting website. As shown in figure 10, on the LIST menu, choose List Settings > Permission and Management > Permissions for this list.
As shown in figure 11, click the link Permissions for the list.
Figure 11. Permissions for the list
As shown in figure 12, you can review the users and group permission levels assigned to them related to this list.
By default, a list inherits permissions from the site that contain this list. To create a unique permission set on a particular list, you must break the permission inheritance.
Break permission inheritance
To break permission inheritance for a list, go to the website that contains the list and open it. Choose the LIST tab, and then choose List Settings > Permission and Management > Permissions for this list > Stop Inheriting Permissions as shown in figure 13.
Figure 13. Break the permission inheritance
Edit list permissions
Now you can edit the unique permissions for this list the same way as site permissions management shown above.
Delete list permissions and restore inheritance
To restore permission inheritance, first delete the list permissions. To delete the unique permissions, as shown in figure 14, choose Delete unique permissions on the PERMISSIONS menu. Now, the list permissions inherits from the parent securable object, that is, the SharePoint site that hosts the list, again.
Set list-item permissions
List item-level permissions are also supported on the SharePoint Online website. To set list-item permissions, open the list on the hosting website, as shown in figure 15, on the LIST menu, choose List Settings > General Settings > Advanced settings.
Figure 15. General settings
For the item-level permissions, as shown in figure 16, you can select the Read items that were created by the user or Create items and edit items that were created by the user to specify which item users can read and edit. We select Create items and edit items that were created by the user in our travel app so that a requestor can only create or edit his/her own travel requests.
Edit permissions for a list, library, or individual item describes procedures to break permission inheritance, remove users from a group, grant access to groups or users, and delete unique permissions and restore inheritance.
- How to: Create a basic SharePoint-hosted app
- App permissions in SharePoint 2013
- Plan app permissions management in SharePoint 2013
- Explore the app manifest and the package of an app for SharePoint
- User permissions and permission levels in SharePoint 2013
- Edit permissions for a list, library, or individual item
This article was written by Microsoft ecoSystem interns Chenxiao Li, Yu He and content publisher Tony Liu.