Edit

Elevated privileges

  • Article

Use the app-only policy or service accounts to elevate privileges in SharePoint Add-ins or other remotely hosted solutions.

Applies to: apps for SharePoint | SharePoint 2013 | SharePoint Add-ins | SharePoint Online

Different methods are used to elevate privileges in SharePoint Add-ins and farm solutions. Farm solutions elevate privileges by using RunWithElevatedPrivileges(SPSecurity.CodeToRunElevated), which belongs to the SharePoint server-side object model. SharePoint Add-ins use either the app-only policy or service accounts.

You might want to use elevated privileges in your add-in when:

  • Your add-in performs actions for users that the users don't have adequate individual permissions to complete. Administrators might not assign users certain permissions because the permission level is too high.

    Your organization might, for example, implement a custom site collection provisioning solution that users must use to create site collections. Your organization might specify that all new site collections must have certain lists, content types, or fields associated with them. If users create site collections on their own, they might or might not remember to create these objects on their new site collection. In this scenario, users create site collections by using the add-in, but users aren't individually assigned permissions to create site collections.

  • Your add-in is not acting on behalf of any user; for example, a governance or management process.

App-only policy authorization

App-only policy uses OAuth to authenticate your add-in. When your add-in uses the app-only policy, SharePoint checks the permissions of the add-in principal only. These are the permissions that were granted to the add-in. Authorization succeeds if the add-in has sufficient permissions to perform the task, regardless of the permissions associated with the current user. When authorization succeeds, an access token is returned to your add-in. Your add-in will use this access token to perform any operations required by your code.

For more information, see App authorization policy types in SharePoint 2013.

Note

The app-only policy is available only for provider-hosted add-ins. SharePoint-hosted add-ins that access the host web must use the user+app policy.

Benefits of using the app-only policy in your add-in include:

  • You do not need to grant a separate user license. Service accounts require a separate user license.

  • You get more granular control over permissions than is available with service accounts. For example, you can apply FullControl permissions on your web, which isn't possible when you use service accounts.

You can't use the app-only policy with the following APIs:

  • User Profile

  • Search

To use the app-only policy, you first must grant permissions to the add-in by using appinv.aspx. The following code from AppManifest.xml file shows how to set the app-only policy and the permissions for your add-in.

 <AppPermissionRequests AllowAppOnlyPolicy="true">
   <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />
 </AppPermissionRequests>

Using the app-only policy requires that your add-in use either low-trust or high-trust authorization. The policy is not available with the SharePoint cross-domain JavaScript library, which is a third way of getting authorized access to SharePoint resources.

app@sharepoint permission no longer works in the modern term store user interface. That’s because app@sharepoint permission is no longer required for an app to perform taxonomy write operations, as long as the app is registered in Azure AD with the required resource consents for app-only taxonomy access.

Low-trust authorization

Your add-in can use low-trust authorization when using the Microsoft Azure Access Control Service (ACS) to establish trust between your provider-hosted add-in and either your Office 365 site or your on-premises SharePoint farm. You can learn more at Three authorization systems for SharePoint Add-ins 2013.

Important

Using Azure ACS (Access Control Services) for SharePoint Online has been retired as of November 27th 2023, checkout the full retirement announcement to learn more. Using Azure ACS outside of the context of SharePoint was already retired on November 7th, 2018 and is end-of-life now.

Retirement means that the feature will not get any new investments, but it's still supported. End-of-life means that the feature will be discontinued and is no longer available for use.

To get a reference to the ClientContext object, your add-in should:

  1. Get the access token by using TokenHelper.GetAppOnlyAccessToken.

  2. Use TokenHelper.GetClientContextWithAccessToken to get the ClientContext object.

Note

The TokenHelper file is source code that is generated by the Microsoft Office Developer Tools for Visual Studio. There is no reference documentation for it, but there are extensive comments in the TokenHelper class. To see the code comments, create a provider-hosted add-in in Visual Studio.

Note

he code in this article is provided as-is, without warranty of any kind, either express or implied, including any implied warranties of fitness for a particular purpose, merchantability, or non-infringement.

Uri siteUrl = new Uri(ConfigurationManager.AppSettings["MySiteUrl"]);
try
{
    // Connect to a site using an app-only token.
    string realm = TokenHelper.GetRealmFromTargetUrl(siteUrl);
    var token = TokenHelper.GetAppOnlyAccessToken(TokenHelper.SharePointPrincipal, siteUrl.Authority, realm).AccessToken;

    using (var ctx = TokenHelper.GetClientContextWithAccessToken(siteUrl.ToString(), token))
    {
        // Perform operations on the ClientContext object, which uses the app-only token. 
    }
}
catch (Exception ex)
{
    Console.WriteLine("Error in execution: " + ex.Message);
}

High-trust authorization

If your add-in uses the high-trust authorization system (also known as S2S protocol), it calls a different TokenHelper method: TokenHelper.GetS2SAccessTokenWithWindowsIdentity.

Important: The TokenHelper.GetS2SAccessTokenWithWindowsIdentity is used for both app-only and user+app calls. The second parameter of the method, which holds the user identity, determines which policy is used. Pass null to use the app-only policy.

Service accounts

Use service accounts to elevate privileges for your add-in only when the app-only policy does not provide sufficient permissions to complete your task. Also, in certain scenarios a user account is required. For example, you need to use service accounts when your code works with any of the following SharePoint service applications:

  • User Profile service using the client-side object model (CSOM)

  • Managed metadata service

  • Search

When planning to use service accounts in your add-in, consider the following:

  • Service accounts require a separate user license.

  • Create either one service account per add-in, or use one service account for all add-ins in your SharePoint environment.

  • You must supply the user name and password during authorization. Ensure service account credentials are stored or retrieved securely.

  • Before your add-in can perform an action on a site, service accounts first must be granted permission to access the site.

Note

Add-ins purchased from the Office Store cannot use service accounts.

The following code shows how to authenticate by using SharePointOnlineCredentials with a service account.

using (ClientContext context = new ClientContext("https://contoso.sharepoint.com"))
{

    // Use default authentication mode.
    context.AuthenticationMode = ClientAuthenticationMode.Default;  

    // Specify the credentials for the service account.
    context.Credentials = new SharePointOnlineCredentials("User Name", "Password");
}

See also