How to: Create an Application Principal User

Applies to: SharePoint Foundation 2010

This topic explains how to create an application principal; an SPUser object that represents a non-SharePoint application that accesses Microsoft SharePoint Foundation data.

For security reasons, administrators cannot add application principals in the SharePoint Foundation UI. Application principals can only be created with code. Typically, the code is in a small console application, but it could be in a custom PowerShell cmdlet, or a Windows PowerShell command-line interface script that uses the Add-Type cmdlet, or any other executable context.

Note

The process of making a user account into an application principal cannot be reversed. The SPUser.IsApplicationPrincipal property is read only. This is because application principals should only be used for the Silverlight Cross-Domain Data Access model, to allow a third party server access to SharePoint data when another human user is logged in and has opened a page hosting a Silverlight web part which is itself hosting a Silverlight application on the third party server.  If application principals could be turned into regular users, then such a user might accidentally full access to SharePoint data without the need for a human to browse to the page first.

The code must run in the context of an administrator of the site collection parent of the Web site to which the application principal user is being added.

To Create an Application Principal

1. Add references to Microsoft.SharePoint.dll to your C# project and a using statement for Microsoft.SharePoint.

2. Get a reference to the Web site to which the application principal user is being added. The following is an example.

   SPSite site = new SPSite("https://localhost");
   SPWeb web = site.RootWeb;
   

   Dim site As New SPSite("https://localhost")
   Dim web As SPWeb = site.RootWeb
   

3. Create the user object with a call to AddApplicationPrincipal(String, Boolean, Boolean). In this example, the user is given a logon name that contains a reminder that it represents an external server on which one or more external applications are installed. The two Boolean parameters set the user’s AllowBrowseUserInfo and RequireRequestToken properties, respectively, to their recommended values. This ensures that:

   • The application cannot access user information, even if its permission assignments would otherwise allow it to have such access.

   • The application cannot access the SharePoint Foundation Web application at all unless it is hosted in a Web Part on a page to which a real user has navigated. The application’s effective permissions are the intersection of its own permission assignments and the permissions of the real user.

   SPUser principal = web.AddApplicationPrincipal("ContosoAppServer", false, true);
   

   Dim principal As SPUser = web.AddApplicationPrincipal("ContosoAppServer", False, True)
   

   Important

   The logon name passed to AddApplicationPrincipal(String, Boolean, Boolean), in this case ‘ContosoAppServer’ must be of a user who is already known to the authentication system (for example, a user that already exists in Active Directory Domain Services), but who is not already a user in the Web site.

4. Assign the application principal to a permission level. In this example, the application principal is made a contributor.

   SPRoleDefinitionBindingCollection roleDefBindCol = new SPRoleDefinitionBindingCollection();
   roleDefBindCol.Add(web.RoleDefinitions.GetByType(SPRoleType.Contributor));
   
   SPRoleAssignment roleAssign = new SPRoleAssignment(principal);
   roleAssign.ImportRoleDefinitionBindings(roleDefBindCol);
   
   web.RoleAssignments.Add(roleAssign);
   

   Dim roleDefBindCol As New SPRoleDefinitionBindingCollection()
   roleDefBindCol.Add(web.RoleDefinitions.GetByType(SPRoleType.Contributor))
   
   Dim roleAssign As New SPRoleAssignment(principal)
   roleAssign.ImportRoleDefinitionBindings(roleDefBindCol)
   
   web.RoleAssignments.Add(roleAssign)