Export (0) Print
Expand All
6 out of 10 rated this helpful - Rate this topic

App permissions in SharePoint 2013

apps for SharePoint

Learn about app permissions in SharePoint 2013, 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.

Last modified: April 07, 2014

Applies to: apps for SharePoint | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013

In this article
App permissions in SharePoint 2013
Types of app permissions and app permission request scopes
Understanding differences between app permission rights and user rights
Permission request scopes, available rights, and Office Store apps rights
Managing app permissions
Next steps
Additional resources

You should first be familiar with the topic Authorization and authentication for apps in SharePoint 2013.

Watch a video about app permissions.

Videos

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. An app must be granted permissions by the user who is executing the app. Users can grant only the permissions that they have. The user who installs the app must grant all the permissions that an app requests or not grant any permission—the permission granted by the user to an app is all or nothing. Grants represent the permissions that a user has delegated to an app.

An app has the following basic information:

  • Client Id of the app

  • Display name of the app

  • The app domain of the app

The identity of an app, its display name, and other basic information, such as its app URI, are stored in the Microsoft Azure Access Control Service (ACS), and the ACS is the authority. When a user first grants an app permissions, SharePoint 2013 obtains information about the app from ACS. SharePoint 2013 then stores the basic information about the app in the app management shared service. The content database service and other components, such as the user profile service, can get the display name of an app and other app basic information directly from the app management shared service.

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 definition. So, the request can't include information about a specific location in SharePoint.

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 Types of app permissions and app permission request 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 associated with a security principal, called an app principal. Like users and groups, an app principal has certain permissions and 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 2013 supports three different permission scopes within the content database and tenancy, as shown in Table 1.

Table 1. SharePoint app permission request scope URIs and descriptions

Scope URI

Description

site collection

http://sharepoint/content/sitecollection

The permission request scope URI to the site collection where the app is installed. Includes all children of this scope.

website

http://sharepoint/content/sitecollection/web

The permission request scope URI to the website where the app is installed. Includes all children of this scope.

list

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

The permission request scope URI to the list where the app is installed. Includes all children of this scope.

tenancy

http://sharepoint/content/tenant

The permission request scope URI to the tenancy where the app is installed.

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. Content database–related permissions are organized under the following URI: http://sharepoint/content.

Permission request rights indicate the activities that an app is permitted to do within the requested scope. SharePoint 2013 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 permission levels: Reader, Contributor, Designer, and Full Control. For more information about user permission levels, see User permissions and permission levels.

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 Types of app permissions and app permission request 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 Types of app permissions and app permission request 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.

Note Note

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.

A user must have all permissions in the corresponding perm mask to grant a right to an app. If a user without sufficient permissions is prompted for consent by an app that a user is trying to install, 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 2013 are ignored. This means that, if an app requests a permission that SharePoint 2013 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 Office Store apps.

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.

Note Note

Apps that include an app web automatically get full control of the app web. Also, 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 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="Read"/>
  </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 Table 7. Without a base template ID a user can pick from all lists in the web. Specifying a base template ID filters the available lists down 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).

An app permission can be granted when:

  • An app is installed by a website administrator.

  • An app is explicitly granted permission by a tenant administrator or website administrator.

  • An end user gives consent.

  • An app is removed.

Content database grants are stored in the SharePoint content database. Each content database permission that is granted to an app is stored under the App Id of the app. 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 2013 does not modify the corresponding grant. This is so that if the object is restored from the Recycle Bin, the grant is still intact.

Using SharePoint 2013, users are able to manage app permissions at any point in an app life cycle:

  • Users can remove any and all previously granted rights to an app after installation.

  • Users can manage permissions for apps—they can give an app all requested permissions or none.

    Note Note

    The all-or-nothing permission set is intended to simplify the decision for the user, and to ensure that apps do not have to gracefully handle unexpected subsets of requested permissions.

In all cases in which SharePoint 2013 serves as a resource server, users are the corresponding resource owners. Users are responsible for granting or revoking specific permissions to a given app.

In summary, in the SharePoint 2013 implementation of the OAuth protocol, end users have four different opportunities to manage app permissions:

  • During app installation

  • By using explicit permissions management

  • By using an end-user consent UI

  • During app removal

On the app permission management page, clicking a link that is associated with an app takes a user to a page that lists the permissions of all installed apps. 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 2013.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.