Create a workflow with elevated permissions by using the SharePoint 2013 Workflow platform

FROM MSDN

Learn how to create a workflow with elevated permissions by using the SharePoint 2013 Workflow platform.

Applies to: SharePoint Server 2013 Enterprise

In this article
SharePoint Server 2013 App Catalog and workflow
Understanding how it works
Additional resources

SharePoint Server 2013 App Catalog and workflow

This article describes how to create SharePoint 2013 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.

Important note Important

This article assumes that the SharePoint 2013 Workflow platform has been installed and configured and that SharePoint 2013 has been configured for apps. For more information on SharePoint 2013 Workflow and apps for SharePoint 2013, including installation and configuration, see Workflow in SharePoint 2013 and Install and manage apps for SharePoint 2013.

Overview of creating a workflow with elevated permissions

Imagine that as a SharePoint administrator, you would like to define some processes for managing user requests for purchases of apps from the Office Store. In the simplest case you want to send an acknowledgement email when a user requests an app. In addition, you could also want to add structure to the request approval process.

By default, workflow does not have permissions to access the app request catalog. Catalog lists in SharePoint require owner (full control) permissions. Workflows generally run at permission level equivalent to write.

To solve this, you have to create a workflow with elevated permissions by doing the following in the App Catalog site:

Allow workflow to use app permissions.
Grant full control permission to workflow.
Develop the workflow to wrap actions inside an App Step.

Allowing a workflow to use app permissions in a SharePoint Server 2013 site

The first step is to allow workflow to use app permissions. You configure workflow to use app permissions on the Site Settings page of the SharePoint Server 2013 site where the workflow will run. The following procedure configures the SharePoint Server 2013 site to allow workflow to use app permissions.

Important note Important

The procedure must be completed by a user that has Site Owner permissions.

To allow workflow to use app permissions

Click the Settings icon as shown in the figure.

Figure: Opening 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 click Activate.

Caution

This feature will not activate unless you have properly configured the SharePoint 2013 Workflow platform and also apps for SharePoint.

Figure: The site feature, 'Workflows can use app permissions'

Granting full control permission to a workflow

In order for the workflow to function properly it must be granted full control in the site. The following procedure grants the full control permission to the workflow.

Important note Important

The procedure assumes the following:

The procedure must be completed by a user that has Site Owner permissions.
The workflow must already be published to the SharePoint Server 2013 site.

To grant full control permission to a workflow

Click the Settings icon as shown in the figure.

Figure: Opening the Site Settings page
Go to Site Settings.
In the Users and Permissions section, select Site app permissions.
Copy the client section of the App Identifier. This is the identifier between the last "|" and the "@" sign, as shown in the figure.

Figure: Selecting the App Identifier
Navigate 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}/{catalog site}/_layouts/15/appinv.aspx.

The following figure shows an example.

Figure: The appinv.aspx page and URL example
Paste the client id in the App Id field and then click Lookup, as shown in the figure.
Paste the following Permissions Request XML to grant full control permission.
```
<AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />
</AppPermissionRequests>
```
Caution

Make sure to set the Scope to the URL of your particular SharePoint Server 2013 installation. The preceding code uses an example URL.

The following figure shows an example of the completed page.

Figure: Looking up an App Id
Click Create.
You will then be asked to trust the Workflow app, as shown in the figure. Click Trust It.

Figure: Trust the Workflow app

Wrapping 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 2013.
Create a new Custom List on which to run the workflow. In this example the list name is App Demo.
Click Workflows in the navigation window.
Create a new List Workflow for the App Demo list, as shown in the figure.

Figure: Create a new List workflow
Insert an App Step, as shown in the figure.

Figure: Add an App Step
Insert a Send an Email action in the App Step.
Click the address book button. In the To field select Workflow lookup for a user and click add as shown in the figure.

Figure: Select Workflow lookup for a user
Enter the Created By field as the lookup value, as shown in the figure.

Figure: Lookup for Person dialog box
Enter Email from App Demo list in the email message body.
Click OK to return to the workflow. The completed workflow is shown in the figure.

Figure: Email action in App Step
Click the Workflow Settings icon in the ribbon, as shown in the figure.

Figure: Workflow Settings icon in ribbon
Clear the check box next to Automatic updates to workflow status to the current stage name, and then click Publish, as shown in the figure.

Figure: Clear the automatic updates check mark and then publish

Understanding how it works

To understand why elevating permissions for a workflow is required, consider that workflows are fundamentally apps for SharePoint and they follow the same authorization rules of the app model. The default configuration for workflow is that the effective permissions of the workflow are an intersection of user permissions and the app permissions, as shown in the figure.

Figure: Permissions diagram

Permissions diagram.

There are two reasons why it is necessary to elevate permissions to create a workflow in the App Request list. These 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

Figure: Permissions matrix

Permissions matrix.

Additional resources