Skip to content

Commit 77a92f4

Browse files
Linda-EditorLinda-Editor
authored
Final edit of Develop topics (SharePoint#1184)
* Final edit * Final edit * Final edit * Tweaks * sttempt to fix code block * Trying to fix table * Final edit * Final edit * Tweaks * Final edit
1 parent c57fc0e commit 77a92f4

7 files changed

+1116
-1608
lines changed

‎docs/sp-add-ins/add-in-authorization-policy-types-in-sharepoint.md

Lines changed: 61 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,165 +1,123 @@
11
---
22
title: Add-in authorization policy types in SharePoint
3-
ms.date: 09/25/2017
3+
description: Overview of add-in-only policy, user-only policy, and user+add-in policy, and guidelines for using the add-in-only policy.
4+
ms.date: 12/26/2017
45
ms.prod: sharepoint
56
---
67

78

89
# Add-in authorization policy types in SharePoint
9-
Learn about the different authorization policies for add-ins in SharePoint: add-in-only policy, user+add-in policy, and user-only policy. It also provides guidelines for using add-in-only policy.
1010

11+
Before reading this article, you should first be familiar with the articles [Add-in permissions in SharePoint](add-in-permissions-in-sharepoint.md) and [Context Token OAuth flow for SharePoint Add-ins](context-token-oauth-flow-for-sharepoint-add-ins.md).
1112

1213

13-
Before reading this article, you should first be familiar with the articles [Add-in permissions in SharePoint](add-in-permissions-in-sharepoint.md) and [Context Token OAuth flow for SharePoint Add-ins](context-token-oauth-flow-for-sharepoint-add-ins.md).
14-
15-
16-
## Get an overview of add-in authorization policies types
1714
<a name="Overview"> </a>
1815

19-
SharePoint provides three types of authorization policies:
20-
16+
## Overview of add-in authorization policy types
2117

22-
18+
SharePoint provides three types of authorization policies:
2319

24-
- **User-only policy** — When the user-only policy is used, SharePoint checks only the permissions for the user. SharePoint uses this policy when the user is accessing resources directly without using an add-in, such as when a user first opens a SharePoint website's home page or accesses SharePoint APIs from PowerShell.
25-
26-
27-
28-
29-
- **User+add-in policy** —When the user+add-in policy is used, SharePoint checks the permissions of both the user and the add-in principal. Authorization checks succeed only if both the current user and the add-in have permissions to perform the action in question.
30-
31-
For example this policy is used when a SharePoint Add-in wants to get access to the user's resources on SharePoint. (The code in the remote components of the SharePoint Add-in have to be designed to make user+add-in calls to SharePoint.)
32-
33-
34-
35-
36-
- **Add-in-only policy** —When the add-in-only policy is used, SharePoint checks only the permissions of the add-in principal. Authorization checks succeed only if the current add-in has sufficient permissions to perform the action in question, regardless of the permissions of the current user (if any).
37-
38-
An expense approval add-in is an example of an add-in that could be designed to use this policy. The add-in allows users who wouldn't otherwise be able to approve expenses to approve expenses below a certain amount. See the scenario below for details.
39-
20+
- **Add-in-only policy**. When the add-in-only policy is used, SharePoint checks only the permissions of the add-in principal. Authorization checks succeed only if the current add-in has sufficient permissions to perform the action in question, regardless of the permissions of the current user (if any).
4021

22+
An expense approval add-in is an example of an add-in that could be designed to use this policy. The add-in allows users who wouldn't otherwise be able to approve expenses to approve expenses below a certain amount. For an example, see the [scenario](#Scenario) in the next section.
4123

4224
> [!NOTE]
4325
> Certain APIs require a user context and can't be executed with an add-in-only policy. These include many APIs for interacting with Project Server 2013 and for performing search queries.
4426
45-
### See an example scenario of an add-in that uses the add-in-only policy
46-
<a name="Scenario"> </a>
27+
- **User-only policy**. When the user-only policy is used, SharePoint checks only the permissions for the user. SharePoint uses this policy when the user is accessing resources directly without using an add-in, such as when a user first opens a SharePoint website's home page or accesses SharePoint APIs from PowerShell.
4728

48-
Let's says a sales manager at Contoso, Adam, buys an expense submission add-in that uses the add-in-only policy. When Adam chooses to buy the add-in, Adam is prompted to allow the add-in to elevate user permissions; that is, to allow the add-in to make add-in-only calls to SharePoint. Adam grants the add-in the requested permissions. He then purchases enough licenses of the add-in for all of the Contoso sales people, and he installs the add-in in the sales team's SharePoint website.
49-
50-
51-
52-
Soon, the salespeople are submitting expense reports using the new expense submission add-in. Salespeople usually cannot approve their own expense reports, but they can do this when using the add-in because Adam granted it the ability to do this for expense submissions below $50 because he set the add-in to automatically approve reports below $50. The add-in automatically assigns him a task to approve reports of $50 or more. This could be implemented by giving the SharePoint Add-in Write permission to a SharePoint list of approved expenses. But, among users, only human resources managers have Write permission to the list. The code in the add-in is designed to add the expense to the list by making an add-in-only call to SharePoint whenever the expense is less than $50. Since the user's permissions aren't checked, any user's submissions below $50 are automatically added to the approved expenses list, even if the user doesn't have Write permission to the list.
53-
29+
- **User+add-in policy**. When the user+add-in policy is used, SharePoint checks the permissions of both the user and the add-in principal. Authorization checks succeed only if both the current user and the add-in have permissions to perform the action in question.
30+
31+
For example, this policy is used when a SharePoint Add-in wants to get access to the user's resources on SharePoint. (The code in the remote components of the SharePoint Add-in have to be designed to make user+add-in calls to SharePoint.)
32+
33+
<a name="Scenario"> </a>
5434

55-
35+
### Example scenario of an add-in that uses the add-in-only policy
5636

37+
Let's says a sales manager at Contoso, Adam, buys an expense submission add-in that uses the add-in-only policy. When Adam chooses to buy the add-in, Adam is prompted to allow the add-in to elevate user permissions; that is, to allow the add-in to make add-in-only calls to SharePoint. Adam grants the add-in the requested permissions. He then purchases enough licenses of the add-in for all the Contoso sales people, and he installs the add-in on the sales team's SharePoint website.
5738

39+
Soon the salespeople are submitting expense reports by using the new expense submission add-in. Salespeople usually cannot approve their own expense reports, but they can do this when using the add-in because Adam granted it the ability to automatically approve reports under $50. The add-in automatically assigns Adam a task to approve reports of $50 or more.
5840

41+
This could be implemented by giving the SharePoint Add-in Write permission to a SharePoint list of approved expenses. But, among users, only human resources managers have Write permission to the list. The code in the add-in is designed to add the expense to the list by making an add-in-only call to SharePoint whenever the expense is less than $50. Because the user's permissions aren't checked, any user's submissions under $50 are automatically added to the approved expenses list, even if the user doesn't have Write permission to the list.
5942

60-
61-
### Learn how add-ins get permission to use the add-in-only policy
6243
<a name="Approve"> </a>
6344

64-
To be able to make add-in-only calls to SharePoint, your add-in must request permission to use the add-in-only policy. This request is made in the add-in manifest. You do this by adding the **AllowAppOnlyPolicy** attribute to the **AppPermissionRequests** element and setting it to **true** as shown in the following markup:
65-
45+
## How add-ins get permission to use the add-in-only policy
6646

67-
47+
To be able to make add-in-only calls to SharePoint, your add-in must request permission to use the add-in-only policy. This request is made in the add-in manifest. You do this by adding the **AllowAppOnlyPolicy** attribute to the **AppPermissionRequests** element and setting it to **true** as shown in the following markup:
6848

6949
```XML
70-
<AppPermissionRequests AllowAppOnlyPolicy="true">
71-
...
72-
</AppPermissionRequests>
50+
<AppPermissionRequests AllowAppOnlyPolicy="true">
51+
...
52+
</AppPermissionRequests>
7353
```
7454

75-
7655
> [!NOTE]
77-
> SharePoint Add-ins used to be called "apps for SharePoint". To maintain backward compatibility, the app manifest schema was not changed, so the string "app" appears in may element and attribute names.
56+
> SharePoint Add-ins used to be called "apps for SharePoint". To maintain backward compatibility, the app manifest schema was not changed, so the string "app" appears in many element and attribute names.
7857
7958

80-
A user installing the add-in will be prompted to approve this request. If the add-in asks for tenant-scoped permissions, then only a tenant administrator can grant use of the add-in-only policy, so only a tenant administrator can install the add-in. If the add-in does not ask for any permissions scoped higher than site collection, then a site collection administrator can install the add-in. For more information about permission scopes, see [Add-in permissions in SharePoint](add-in-permissions-in-sharepoint.md).
81-
59+
A user installing the add-in is prompted to approve this request. If the add-in asks for tenant-scoped permissions, only a tenant administrator can grant use of the add-in-only policy, so only a tenant administrator can install the add-in.
8260

61+
If the add-in does not ask for any permissions scoped higher than site collection, a site collection administrator can install the add-in. For more information about permission scopes, see [Add-in permissions in SharePoint](add-in-permissions-in-sharepoint.md).
8362

8463

85-
### Learn how add-ins make add-in-only calls
86-
<a name="AppOnlyCalls"> </a>
64+
<a name="AppOnlyCalls"> </a>
8765

88-
The difference between an add-in-only call to SharePoint and a user+add-in call is the type of access token that is included in the call. The following code shows how to obtain user+add-in and add-in-only access tokens in managed code. The detailed coding is done for you in the TokenHelper.cs (or .vb) file that the Office Developer Tools for Visual Studio automatically add to the project in Visual Studio.
89-
66+
## How add-ins make add-in-only calls
9067

91-
68+
The difference between an add-in-only call to SharePoint and a user+add-in call is the type of access token that is included in the call. The following code shows how to obtain user+add-in and add-in-only access tokens in managed code. The detailed coding is done for you in the TokenHelper.cs (or .vb) file that the Office Developer Tools for Visual Studio automatically add to the project in Visual Studio.
9269

9370
```C#
94-
string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
95-
if (contextTokenString != null)
96-
{
97-
//Get context token.
98-
SharePointContextToken contextToken =
99-
TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
100-
Uri sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
101-
102-
//Get user+add-in access token.
103-
string accessToken =
104-
TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;
105-
106-
ClientContext clientContext =
107-
TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), accessToken);
108-
109-
//Do something.
110-
...
111-
112-
//Get add-in-only access token.
113-
string addinOnlyAccessToken =
114-
TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName,
115-
sharepointUrl.Authority, contextToken.Realm).AccessToken;
116-
//Do something.
117-
...
118-
}
71+
string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
72+
if (contextTokenString != null)
73+
{
74+
//Get context token.
75+
SharePointContextToken contextToken =
76+
TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
77+
Uri sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);
78+
79+
//Get user+add-in access token.
80+
string accessToken =
81+
TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;
82+
83+
ClientContext clientContext =
84+
TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), accessToken);
85+
86+
//Do something.
87+
...
88+
89+
//Get add-in-only access token.
90+
string addinOnlyAccessToken =
91+
TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName,
92+
sharepointUrl.Authority, contextToken.Realm).AccessToken;
93+
//Do something.
94+
...
95+
}
11996
```
12097

12198

12299
> [!NOTE]
123-
> Add-ins that do not make OAuth authenticated calls (for example, add-ins that are only JavaScript running in the add-in web) cannot use the add-in-only policy. They can request the permission, but they will not be able to take advantage of it because doing so requires passing an add-in-only OAuth token. Only add-ins with web applications running outside of SharePoint can create and pass add-in-only tokens.
124-
100+
> Add-ins that do not make OAuth authenticated calls (for example, add-ins that are only JavaScript running in the add-in web) cannot use the add-in-only policy. They can request the permission, but they are not able to take advantage of it because doing so requires passing an add-in-only OAuth token. Only add-ins with web applications running outside of SharePoint can create and pass add-in-only tokens.
125101
126-
In general, a current user is required to be present for a call to be made. In the case of add-in-only policy, SharePoint creates a SHAREPOINT\APP, similar to the existing SHAREPOINT\SYSTEM user. All add-in-only requests are made by SHAREPOINT\APP. There is no way to authenticate as SHAREPOINT\APP through user-based authentication.
127-
102+
In general, a current user is required to be present for a call to be made. In the case of an add-in-only policy, SharePoint creates a SHAREPOINT\APP, similar to the existing SHAREPOINT\SYSTEM user. All add-in-only requests are made by SHAREPOINT\APP. There is no way to authenticate as SHAREPOINT\APP through user-based authentication.
128103

129-
130-
131-
### Get guidelines for using the add-in-only policy
132104
<a name="GuidelinesFor"> </a>
133105

134-
Since add-in-only calls effectively elevate user privileges, you should be conservative in creating add-ins that ask for permission to make them. Calls should use the add-in-only policy only if:
135-
106+
## Guidelines for using the add-in-only policy
136107

137-
108+
Because add-in-only calls effectively elevate user privileges, you should be conservative in creating add-ins that ask for permission to make them. Calls should use the add-in-only policy only if:
138109

139110
- The add-in needs to elevate its permissions above the user for a specific call; for example, to approve an expense report under conditions evaluated by the add-in.
140-
141-
111+
142112
- The add-in is not acting on behalf of any user; for example, an add-in that performs nightly maintenance tasks on a SharePoint document library.
143-
144-
145113

146114
## See also
147115
<a name="AR"> </a>
148116

117+
- [Context Token OAuth flow for SharePoint Add-ins](context-token-oauth-flow-for-sharepoint-add-ins.md)
118+
- [Get started creating provider-hosted SharePoint Add-ins](get-started-creating-provider-hosted-sharepoint-add-ins.md)
119+
- [Authorization and authentication of SharePoint Add-ins](authorization-and-authentication-of-sharepoint-add-ins.md)
149120

150-
- [Authorization and authentication of SharePoint Add-ins](authorization-and-authentication-of-sharepoint-add-ins.md)
151-
152-
153-
- [Add-in permissions in SharePoint](add-in-permissions-in-sharepoint.md)
154-
155-
156-
- [Context Token OAuth flow for SharePoint Add-ins](context-token-oauth-flow-for-sharepoint-add-ins.md)
157-
158-
159-
- [SharePoint Add-ins](sharepoint-add-ins.md)
160-
161-
162-
- [Get started creating provider-hosted SharePoint Add-ins](get-started-creating-provider-hosted-sharepoint-add-ins.md)
163121

164122

165123

0 commit comments

Comments
 (0)