Export (0) Print
Expand All

App permissions in SharePoint 2013

apps for SharePoint

Learn about app permissions in SharePoint, including types of app permissions, permission request scopes, and managing permissions. This article also discusses the differences in app permission rights, user rights, and Office Store app rights.

An app for SharePoint requests the permissions that it needs during installation from the user who is installing it. The developer of an app must request, through the app manifest file, the permissions that the particular app needs to be able to run. (Device and web apps that access SharePoint, but are not installed to SharePoint websites must be granted permissions at runtime by the user who is executing the app. For more information, see Get an overview of apps that request access permission from SharePoint on the fly.) Users can grant only the permissions that they have. The user must grant all the permissions that an app requests or not grant any permission. Selective grants are not possible. (For apps that request permissions on the fly, only a user with Manage permissions to the SharePoint resources that the app seeks to access can run the app, even if the app is asking only for lesser permissions, such as Read.)

The permissions that the app has been granted are also stored in the content database of the SharePoint farm or SharePoint Online tenancy. They are not stored with a secure token service, such as Microsoft Azure Access Control Service (ACS). When a user first grants an app permissions, SharePoint obtains information about the app from ACS. SharePoint then stores the basic information about the app in the app management service and the content database along with the app's permissions. For more information about ACS, see Creating apps for SharePoint that use low-trust authorization.

If an object to which an app was granted permission is deleted, the corresponding grants are deleted also. When an object to which an app was granted permission is recycled, SharePoint does not modify the corresponding grant. This is so that if the object is restored from the Recycle Bin, the grant is still intact.

When an app is removed, all the permissions granted to that app at the scope from which it was removed are revoked. This is to ensure that the app can't use its credentials to continue accessing protected SharePoint resources remotely after a user removes the app from SharePoint.

An app for SharePoint uses permission requests to specify the permissions that it needs to function correctly. The permission requests specify both the rights that an app needs and the scope at which it needs the rights. These permissions are requested as part of the app manifest.

Note Note

The scopes described in this section apply to list content and library content only. For information about scopes for other features, see the Understand the types of app permissions and permission scopes section in this article.

Permission request scopes indicate the location in the SharePoint hierarchy where a permission request applies.

Note Note

An app for SharePoint has its own identity and is a security principal, called an app principal. Like users and groups, an app principal has certain permissions or rights. The app principal has full control rights to the app web so it only needs to request permissions to SharePoint resources in the host web or other locations outside the app web. For more information about app web, see Important aspects of the app for SharePoint architecture and development landscape and Host webs, app webs, and SharePoint components in SharePoint 2013.

SharePoint supports four different permission scopes within the content database and tenancy, as shown in Table 1. Permission scopes are named with URIs, including a "http:" prefix, but they are not URLs and they contain no placeholders. The permission scopes in this table and this article are literal strings.

Table 1. SharePoint app permission request scope URIs and descriptions

Scope URI

Description

tenancy

http://sharepoint/content/tenant

The tenancy where the app is installed. Includes all children of this scope.

site collection

http://sharepoint/content/sitecollection

The site collection where the app is installed. Includes all children of this scope.

website

http://sharepoint/content/sitecollection/web

The website where the app is installed. Includes all children of this scope.

list

http://sharepoint/content/sitecollection/web/list

All the lists in the website where the app is installed. Includes all children of this scope. (But there is a way to narrow the permission request to certain subsets of lists. See Permission request scope with associated properties below.)

If an app is granted permission to one of the scopes, the permission applies to all children of the scope. For example, if an app is granted permission to a website, the app is also granted permission to each list that is contained in the website, and all list items that are in each list.

Because permission requests are made without information about the topology of the site collection where the app is installed, the scope is expressed as a type instead of as the URL of a specific instance. These scope types are expressed as URIs. Permissions to resources that are stored in the SharePoint content database are organized under the following URI: http://sharepoint/content.

Permissions indicate the activities that an app is permitted to do within the requested scope. SharePoint supports four rights levels in the content database. For each scope, an app can have the following rights:

  • Read

  • Write

  • Manage

  • FullControl

Note Note

For more information about what Read, Write, Manage, and FullControl rights include, see Plan app permissions management.

Note Note

These rights correspond to the default user permission levels of SharePoint: Reader, Contributor, Designer, and Full Control. For more information about user permission levels, see User permissions and permission levels.

The apps rights names do not match SharePoint user roles rights names, to avoid confusion between user roles rights and app rights. Because customizing the permissions that are associated with SharePoint user roles does not affect app permission request levels, the app rights names do not match the corresponding SharePoint user roles, except Full Control, which can't be customized through the permissions management user interface.

In addition:

  • For Search only, an app can have the Query right.

  • For some Microsoft Project Server 2013 scopes, there is also the SubmitStatus right or the Elevate right. For most scopes for Project Server 2013, only Read and Write are available. For more information, see the Understand the types of app permissions and permission scopes section in this article.

  • For taxonomy, only rights for Read and Write are available.

Note Note

Office Store apps have some restrictions as to what type of rights an app can request. For more information, see the Understand the types of app permissions and permission scopes section in this article.

Unlike SharePoint user roles, these rights levels are not customizable. This is to ensure that when an app is granted a permission request, the app is guaranteed a predictable set of capabilities, and it does not have to account for the possibility of being granted less permission than it expects.

A user cannot grant an app permissions that the user himself or herself does not have. If a user attempts to install an app that requests more permissions than the user has, an error message displays to the user informing them that they don't have sufficient permissions to grant the app its request.

Permissions that are not known to SharePoint are ignored. This means that, if an app requests a permission that SharePoint does not recognize, the app can still be installed, but the user is not prompted to grant the permission, and the permission is not granted to the app.

Different scopes have different sets of rights that are available for an app to request. This section describes the sets of rights that are available for each scope. Also, it highlights the restrictions for apps for SharePoint that are sold through the Office Store.

Office Store apps' rights

Only Read, Write, and Manage rights are allowed for Office Store apps. If you try to submit an app to the Office Store that requires FullControl rights, your app is blocked from submission. Because the block is in the Office Store submission pipeline, apps that request more than Manage permissions can still be deployed through the app catalog.

Permission request scopes for list content and library content

Table 2 shows the permission request scope for list and library content. It also lists the rights that can be specified for each scope URI.

Note Note

The URIs used in Table 2 are literal values.

Table 2. SharePoint app permission scope URIs and available rights

Scope URI

Available Rights

http://sharepoint/content/sitecollection

Read, Write, Manage, FullControl

http://sharepoint/content/sitecollection/web

Read, Write, Manage, FullControl

http://sharepoint/content/sitecollection/web/list

Read, Write, Manage, FullControl

http://sharepoint/content/tenant

Read, Write, Manage, FullControl

The following code shows how you use permission scopes and rights in the AppManifest.xml file. In the first example, an app is asking for Write access to the list scope.

<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0"
     Name="MySampleApp"
>
  <Properties>
    <Title>My Sample App</Title>
    <StartPage>~remoteAppUrl/Home.aspx?{StandardTokens}</StartPage>
  </Properties>

  <AppPrincipal>
    <RemoteWebApplication ClientId="1ee82b34-7c1b-471b-b27e-ff272accd564" />
  </AppPrincipal>

  <AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write"/>
  </AppPermissionRequests>
</App>

The following code shows an app that is asking for Read access to the web scope and Write access to the list scope.

<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0"
     Name="MySampleApp"
>
  <Properties>
    <Title>My Sample App</Title>
    <StartPage>~remoteAppUrl/Home.aspx?{StandardTokens}</StartPage>
  </Properties>

  <AppPrincipal>
    <RemoteWebApplication ClientId="6daebfdd-6516-4506-a7a9-168862921986" />
  </AppPrincipal>

  <AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Read"/>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write"/>
  </AppPermissionRequests>
</App>

Permission request scopes for other SharePoint features

The permission request scope for other SharePoint features are listed in the following tables.

Note Note

The URIs used in the tables are literal values.

Table 3 shows the permission request scope for Business Connectivity Services (BCS) . It also lists the rights that can be specified for that scope URI.

Table 3. BCS app permission request scope URIs and available rights

Scope URI

Available Rights

http://sharepoint/bcs/connection

Read

Note Note

For more information about the BCS app permission request scope, see Business Connectivity Services in SharePoint 2013.

Table 4 shows the permission request scope for Search. It also lists the rights that can be specified for that scope URI.

Table 4. Search app permission request scope URIs and available rights

Scope URI

Available Rights

http://sharepoint/search

QueryAsUserIgnoreAppPrincipal

Note Note

For more information about the Search app permission request scope, see Search in SharePoint 2013.

Table 5 shows the permission request scope for Project Server 2013. It also lists the rights that can be specified for each scope URI.

Note Note

An app that uses Project Server 2013 features and services should be tested in an environment that has the required Project Server features and services. The Project Server 2013 permission provider assembly that knows about Project Server 2013 permission scopes is not installed by default with SharePoint Server. For more information, see the Project Server 2013 developer documentation.

Table 5. Project Server app permission request scope URIs and available rights

Scope

Available Rights

http://sharepoint/projectserver

Manage

http://sharepoint/projectserver/projects

Read, Write

http://sharepoint/projectserver/projects/project

Read, Write

http://sharepoint/projectserver/enterpriseresources

Read, Write

http://sharepoint/projectserver/statusing

SubmitStatus

http://sharepoint/projectserver/reporting

Read

http://sharepoint/projectserver/workflow

Elevate

Table 6 shows the permission request scope for social features. It also lists the rights that can be specified for each scope URI.

Table 6. Social features app permission request scope URIs and available rights

Scope URI

Available Rights

http://sharepoint/social/tenant

Read, Write, Manage, FullControl

http://sharepoint/social/core

Read, Write, Manage, FullControl

http://sharepoint/social/microfeed

Read, Write, Manage, FullControl

Note Note

For more information about social features app permission request scope, see App permission requests for accessing social features.

Table 7 shows the permission request scope for taxonomy. It also lists the rights that can be specified for that scope URI.

Table 7. Taxonomy app permission request scope URIs and available rights

Scope URI

Available Rights

http://sharepoint/taxonomy

Read, Write

Note Note

For more information about the taxonomy app permission request scope, see Add SharePoint 2013 capabilities.

Permission request scope with associated properties

The list permission request scope has an additional optional property. The list scope can take a property with the name BaseTemplateId, and an integer value corresponding with a list base template, as shown in the markup sample below. Without a base template ID, the app can access all lists in the web. Specifying a base template ID limits the app's access to the set of lists that match what is specified by the BaseTemplateId property.

The BaseTemplateId property is a child element, not an attribute of the AppPermissionRequest element. The following code shows how to use the BaseTemplateId property.

<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write">
  <Property Name="BaseTemplateId" Value="101"/>
</AppPermissionRequest>
Table 7. Permission request scope with associated properties

Scope URI

Property

Type

http://sharepoint/content/sitecollection/web/list

BaseTemplateId

Integer

NoteNote

For more information about BaseTemplateId and the corresponding integer value for the list base template, see the Type attribute of the List Element (List).

Apps for SharePoint that are installed to SharePoint are granted permissions when they are installed. Apps that are installed on other platforms but access SharePoint, are granted permissions at runtime, by the user who is running the app. Occasionally, the first kind of app may lose its permissions. Apps can be regranted its permissions with the following steps:

  1. On the Site Contents page of the website where the app seems to have lost permissions, click the button on the app's tile. This will open a callout with either a PERMISSIONS link or another button.

  2. Click the PERMISSIONS link if it is there and skip the next step, or click the button.

  3. Click the Permissions link.

  4. On the page that opens, click here link in the last sentence. This will regrant the app its permissions and redirect the browser back to the Site Contents page.

Regranting permissions to an app

When you are developing an app or troubleshooting an app, there may be occasions when you want to change, or regrant, the permissions of an app that has already been installed. You can do so with these steps:

  1. Navigate to http://<SharePointWebSite>/_layouts/15/AppInv.aspx, where <SharePointWebSite> is the URL of the website where the app is installed. Be careful not to add any query parameters on the URL. The form you need only appears on this page if the URL is exactly as shown.

  2. Enter the app's ID, also called the client ID, in the App Id box and click Lookup. The other boxes on the form are then populated with information about the app.

  3. Fill the Permission Request XML box with permission requests exactly as you would enter them in an app manifest. For examples, see Permission request scopes for list content and library content above. For complete syntax information see AppPermissionRequest Element.

  4. Click Create.

An app's permissions for a specific scope are revoked when it is removed from that scope.

Any user with browse rights to a SharePoint website can launch any app for SharePoint installed on the site. Whether the user can do anything with the app will depend on the user's other permissions and what authorization policy type is being used by the app. If the user tries to do something with the app that the user does not have permission to do, and the call to SharePoint is using the user+app policy, then the call will fail.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft