This document is a systematic instruction sheet for creating and installing an ASP.NET 2.0 Membership Provider into SharePoint 2007 Beta 2 installation. This document assumes the reader is familiar with ASP.NET 2.0, SharePoint 2007 Beta 2, and the existence of membership providers to facilitate custom forms authentication. The intended audiences of this document are developers.

In addition, this document discusses the use of Code Access Security. For further reading and background-knowledge read the document titled “Code Access Security - A Primer.”

Creating a Membership Provider

Follow the rudimentary instructions below to create a simple membership provider for ASP.NET 2.0:

1. Using Visual Studio 2005 – create a new class library.
2. Add a class to the library; give it a name that reflects the membership that you will eventually create.
3. Add a reference to the System.Web.Security namespace.
4. Make your membership class inherit from System.Web.Security.MembershipProvider.
5. Use Visual Studio to implement the stub methods to implement from the inherited abstract class.
6. Implement the following methods, these methods are used by SharePoint when adding users to groups, and at authentication:

   1. FindUsersByName
   2. GetAllUsers
   3. GetUser (both versions)
   4. ValidateUser

Minimum Trust Considerations

Update:  It is often easier to install the membership provider DLL in the Global Assembly Cache to achieve full trust, but in cases where you're working with a hosted SharePoint site and cannot deploy to the GAC these instructions should steer you right.

SharePoint 2007 runs in a partial trust environment. This means that the membership provider created in the previous section must also operate in a partial trust environment. Before continuing with the steps below, read, “Understand code access security issues in SharePoint 2007” for a better understanding of Code Access Security in .NET.

1. Edit the configuration file for the web site (web.config), as mentioned in the above section.
2. Add the following XML to the system.web XML node:

   <trust level=”minimal” originUrl=””/>

3. Run the ASP.NET configuration tool again and test the custom membership provider. If you are lucky the provider may operate without a hitch, but more likely throw a security exception – this is because some code in the provider assembly or dependent assembly is demanding an elevation of permission.
4. Open the Assembly Info file in the membership class library project and add the following attributes (assumes C# syntax):

   [assembly:AllowPartiallyTrustedCallers]
   [assembly:SecurityCritical]

5. The above attributes allow partially trusted callers (the web site, and eventually SharePoint 2007) to use the custom membership provider, as well as making the assembly security transparent (with exceptions to security critical methods).
6. Note: If you or your organization routinely performs security audits on code, then the audit team must check the membership provider before apply the attributes above. Allowing partially trusted callers and can potentially cause security vulnerabilities.
7. Make a copy of the file web_minimaltrust.config in C:/WINDOWS/Microsoft.NET/Framework/version/CONFIG and place the file in the main web site folder.
8. Rename the file to web_minimaltrust.config, this file is the security policy file for the web application.
9. Add the following XML to the system.web XML node in the web site configuration file (web.config):

   <securityPolicy> <trustLevel name=”CustomTrust” policyFile=” web_minimaltrust.config”/></securityPolicy>

10. The above defines a new security policy using a copy of the ASP.NET 2.0 minimal trust policy file in the web site folder.
11. Change the level attribute of the trust node, defined in step #2, to CustomTrust.
12. Open the security policy file, web_minimaltrust.config, in Visual Studio 2005.
13. The policy file defines a series of security classes, permission sets, and code groups. The code groups define evidence criteria for code and the mapping to the permission sets. The security classes are references to the hosting assembly and fully qualified type name.
14. Find the permission set for ASP.Net. Notice, how little permission this set defines. Do not add permissions to this set because doing so will open the whole scope of ASP.Net to elevated permissions.
15. Create a new custom permission set node at the same level as the ASP.Net permission set. Give it a name.
16. To start with, apply unrestricted access (Full Trust) to the permission set, as follows:

    <PermissionSet class=”NamedPermissionSet” version=”1” Name=”MyCustomPermissionSet” Unrestricted=”true” Description=”My custom permission set”> </PermissionSet>

17. Create a strong name key pair file using the command:

    sn –k secure.snk

18. Add the key file to the custom membership provider, class library project. Under the project properties select the “signing” tab and set the strong named key to the key you just added in step #17.
19. You now have a strong named custom membership assembly.
20. Extract the public key token and public key blob from the assembly with the following command:

    sn –Tp customMembershipAssembly.dll

21. Find the first code group node with class FirstMatchCodeGroup, and add a nested code group node as follows:

    <CodeGroup class=”UnionCodeGroup” version=”1” PermissionSetName=”MyCustomPermissionSet” Description=”Custom code group for my signed assembly”> <IMembershipCondition class=”StrongNameMembershipCondition” version=”1” PublicKeyBlob=”Insert the blob here from step #20”/></CodeGroup>

22. What have we done? The code group above tells the CLR that any strong named assembly signed with a public key blob matching that specified in the attribute in the configuration file belongs to the MyCustomPermssionSet permission set. The custom permission set was set to unrestricted (Full Trust), so the custom membership provider should now operate under full trust.
23. Decorate each method in the custom membership class that performs a security critical request with the SecurityCritical attribute.
24. Surround security critical method calls with permission asserts so that demands for elevated permissions do not enter the minimum trust environment of ASP.Net.
25. Test the custom membership provider in the ASP.Net configuration tool and confirm that it operates successfully.
26. Remove the Unrestricted=true statement from the custom permission set.
27. Test the custom membership provider again, but make a note of each security permission exception, e.g. There could be a requirement for the FileIOPermission class.
28. Add each permission class to the custom permission set; make sure that there exists a definition of security permission class in the security classes section. Example permission:

    <PermissionSet class=”NamedPermissionSet” version=”1” Name=”MyCustomPermissionSet” Unrestricted=”true” Description=”My custom permission set”> <IPermission class=”FileIOPermission” version=”1” Unrestricted=”true” </PermissionSet>

29. If you know the desired properties of the permission (such as read only file access in the FileIOPermission) then you can set the properties explicitly as node attributes. Setting unrestricted allows only the custom membership assembly full access to the permission. If the custom membership has completed a security audit full-access to this permission may be safe, otherwise, lock down the permission specifically.
30. The custom membership provider should succeed under minimal trust once all the permission exceptions suppressed by adding the permission classes to the permission set.
31. If you custom membership provider continues to throw security exceptions check the following:

    1. Check for existence of all desired permission classes in the permission set.
    2. Make sure that there exists a definition of the SecurityClass node for each permission class, and the StrongNameMembershipCondition.
    3. Confirm that the code group is working for the custom membership assembly by setting the custom permission set to unrestricted=true.
    4. Make sure that the public key blob (not the public key token) is correct in the code group.

Installing the Custom Membership Provider in SharePoint 2007

Now that we have created a custom membership provider that operates under minimal trust, it is time to add this provider to SharePoint 2007.

Part 1 – The SharePoint Central Administration Website

1. Find the directory where the main central administration website resides, opening up IIS manager and looking for the home directory for the site will provide the location.
2. Copy the custom membership (and any dependent) assemblies to the app_bin sub directory.
3. Copy the web_minimaltrust.config policy file to the SCAW directory (step #1).
4. Open the website configuration file (web.config) and add a new trust level, using the new policy file.
5. Add the membership provider node (see #13 in first section).
6. Add the custom provider fully qualified assembly name (and those of any dependent assemblies) to the assemblies node under compilation, e.g.:

   <compilation batch=”false” debug=”false”> <add assembly=” MyCustomProvider Version=1.0.0.0, Culture=neutral, PublicKeyToken= 8e78636d3b27ebb9”/></compilation>

7. Add the name of the custom membership provider to the PeoplePickerWildcards tag (assuming your provider handles wildcards):

   <PeoplePickerWildcards> <clear /> <add key=”MyCustomProvider” value=”%”/></PeoplePickerWildcard>

Part 2 – Custom Web Application and Site Collection

1. Create your web application and site collection.
2. Follow steps #2 through #7 in the previous section for the custom web application. The directory can be located using the IIS manager, similar to step #1 above.
3. Turn on forms authentication and specify the custom membership provider for the custom web application (Application Management Tab, Application Security, and Authentication Providers).
4. Add a new administrator to the site collection of your web application from the custom membership provider:

   1. Click Application Management Tab, SharePoint Site Management, and Site Collection Administrators.
   2. Change the site collection context to that of the custom-web -application site collection.
   3. Click the book icon to search for users within your custom membership provider. You should be able to search users from the custom provider.
   4. Assign an administrator user.

5. Open a new browser window using the URL for the custom web application. Expect a login page using forms authentication. Authentication will use the custom authentication provider.

Problems Experienced

After much experimentation, the above instructions were constructed. Most of the problems experienced were because the custom membership provider did not operating correctly under minimal trust. The quick solution would have been to raise the trust level of SharePoint to medium trust but a solution was required that would not compromise the security of SharePoint and install in the default minimal security level.

Before embarking on adding a custom membership provider into SharePoint 2007, make sure that the provider works correctly in the ASP.Net Configuration tool with no security exceptions or errors. Be sure to try all the functions of the provider – validation worked correctly in the tests performed, but I overlooked one of the calls to retrieve user information from SQL server and caused a SqlClientPermission exception. SharePoint 2007 Beta 2 will not give you much of an error message, just a failure notice.

The log files, located at c:/Program Files/Common Files/Microsoft Shared/web server extensions/12/LOGS, can be of some help.

Tests would sometimes fail, with a notice about not being able to find the custom membership provider assembly. I experienced this problem after resetting IIS, and suspect that this is something to do with caching of assemblies at the ASP.Net level. Make an edit to the web configuration file and save the changes to fix the problem – this will cause IIS to reload the ASP.Net web application for the portal and reload the custom membership provider.