Create a workflow with elevated permissions by using the SharePoint Workflow platform
This article describes how to create SharePoint workflows that access objects in SharePoint that require elevated permissions. These solutions use two features: granting permissions to the workflow app and wrapping actions with the App Step.
Note
SharePoint 2010 workflows have been retired since August 1, 2020 for new tenants and removed from existing tenants on November 1, 2020. If you’re using SharePoint 2010 workflows, we recommend migrating to Power Automate or other supported solutions. For more info, see SharePoint 2010 workflow retirement.
Important
This article assumes that the SharePoint Workflow platform has been installed and configured and that SharePoint has been configured for add-ins. For more information about SharePoint Workflows and SharePoint Add-ins, including installation and configuration, see Workflows in SharePoint and Install and manage SharePoint Add-ins.
Imagine that as a SharePoint administrator, you would like to define some processes for managing user requests for purchases of add-ins from the Office Store. In the simplest case, you want to send an acknowledgment email when a user requests an add-in. In addition, you might also want to add structure to the request approval process.
By default, workflow does not have permissions to access the app catalog. Catalog lists in SharePoint require owner (full control) permissions. Workflows generally run at a permission level equivalent to write.
To solve this, you have to create a workflow with elevated permissions by doing the following in the Site Collection site:
- Allow the workflow to use add-in permissions.
- Grant full control permission to the workflow.
- Develop the workflow to wrap actions inside an App Step.
Allow a workflow to use add-in permissions on a SharePoint site
The first step is to allow the workflow to use add-in permissions. You configure a workflow to use add-in permissions on the Site settings page of the SharePoint site where the workflow runs. The following procedure configures the SharePoint site to allow the workflow to use add-in permissions.
Important
The procedure must be completed by a user that has Site Administrator permissions.
To allow workflow to use add-in permissions
- Select the Settings icon as shown in the figure to open the Site settings page.
Go to Site settings.
In the Site Actions section, select Manage site features.
Locate the feature called Workflows can use app permissions, as shown in the figure, and then select Activate.
Warning
This feature will not activate unless you have properly configured the SharePoint Workflow platform and SharePoint Add-ins.
Grant full control permission to a workflow
For the workflow to function properly, it must be granted full control on the site. The following procedure grants full control permission to the workflow.
Important
The procedure must be completed by a user that has Site Owner permissions. The workflow must already be published to the SharePoint site.
To grant full control permission to a workflow
- Select the Settings icon.
Go to Site settings.
In the Users and Permissions section, select Site app permissions.
Important
In SharePoint Online, select Site collection app permissions. This option is only visible to Site Collection Administrators.
Copy the client section of the App Identifier. This is the identifier between the last "|" and the "@" sign, as shown in the figure.
Go to the Grant permission to an app page. This must be done by browsing to the appinv.aspx page of the site.
Example:
http://{hostname}/{the Site Collection}/_layouts/15/appinv.aspx.Note
The 'app' in this step refers to the workflow add-in in general and not just a specific workflow. Individual workflows cannot be access controlled. When you enable add-in permissions, you are enabling for all workflows within the Site Collection.
For more information about setting up a workflow, see the Blog article from Sympraxis Consulting: Looping Through Content in a SharePoint Site Workflow
The following figure shows an example.
Paste the client ID in the App Id field, and then select Lookup, as shown in the previous figure.
Paste the following code in the Permission Request XML field to grant full control permission (note: this code block was updated on 12/29/17 to include the
AllowAppOnlyPolicy).<AppPermissionRequests AllowAppOnlyPolicy="true"> <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" /> </AppPermissionRequests>Warning
There are no placeholders in the Scope value. It is a literal value. Enter it exactly as it appears here.
The following figure shows an example of the completed page (note that the code in the Permission Request XML area does not reflect the recent update to the code in Step 7).
Select Create.
You are then asked to trust the workflow add-in, as shown in the following figure. Select Trust It.
Wrap actions inside an App Step
Finally, you need to wrap the workflow actions inside an App Step. The following procedure wraps a Send an Email action inside an App Step. The workflow in this example sends an acknowledgement email message from a custom list.
To wrap actions inside an App Step
Open the app catalog site in SharePoint Designer.
Create a new Custom List on which to run the workflow. In this example, the list name is App Demo.
Select Workflows in the navigation window.
Create a new List Workflow for the App Demo list, as shown in the figure.
Insert an App Step, as shown in the figure.
Insert a Send an Email action in the App Step.
Select the Address book button. In the To field, select Workflow Lookup for a User, and then select Add as shown in the figure.
Enter the Created By field as the lookup value, as shown in the figure.
Enter Email from the App Demo list in the email message body.
Select OK to return to the workflow. The completed workflow is shown in the figure.
Select the Workflow Settings icon in the ribbon, as shown in the figure.
Clear the check box next to Automatically update the workflow status to the current stage name, and then select Publish.
Understand how it works
To understand why elevating permissions for a workflow is required, consider that workflows are fundamentally add-ins for SharePoint, and they follow the same authorization rules of the add-in model. The default configuration for workflow is that the effective permissions of the workflow are an intersection of user permissions and the add-in permissions, as shown in the figure.
Two reasons why it is necessary to elevate permissions to create a workflow in the App Request list are:
- By default, workflow only has write permission.
- The user has no permissions.
The first step to solve this problem is to allow the application to authorize by using only its identity and ignoring that of the user. This is done by enabling the App Step feature. The second step grants full control permission to the workflow.
The following diagram illustrates the change in permissions.
