Share via


Microsoft Windows SharePoint Services and Code Access Security

 

Maurice J. Prather
Suraj Poozhiyil
Andrew M. Miller
Microsoft Corporation

July 2003

Applies to:
    Microsoft® Windows® SharePoint™ Services
    Microsoft Office SharePoint Portal Server 2003
    Common Language Runtime

Summary: Learn how to implement policies for code access security for Microsoft SharePoint Products and Technologies and how to customize default security settings for Microsoft Windows SharePoint Services. This document also answers some of the most commonly asked questions about code access security and its applicability to Windows SharePoint Services. (11 printed pages)

Contents

Introduction
Default Security Permissions in Windows SharePoint Services
ASP.NET and SharePoint Security Policies
Setting the Trust Level for a Virtual Server
Frequently Asked Questions
Conclusion

Introduction

One of the key security enhancements of Microsoft® ASP.NET v1.1 is the ability for Web applications to operate in a partially trusted environment. For more information, see What's New in the .NET Framework v1.1. This is a change in behavior from ASP.NET v1.0 in which all Web applications were required to be fully trusted. With code access security enabled by ASP.NET v1.1, Windows SharePoint Services uses this feature to provide server administrators the flexibility to set execution permissions on assemblies tailored to their needs.

Developers creating Web Parts or custom solutions on the Windows SharePoint Services platform should familiarize themselves with its implementation of custom security permissions and policy files. The Windows SharePoint Services implementation allows developers the opportunity to customize their applications for partially trusted environments.

Default Security Permissions in Windows SharePoint Services

Windows SharePoint Services defines two security permissions by default as part of the Microsoft.SharePoint.Security namespace located in the Microsoft.SharePoint.Security.dll. Each permission contains one or more attributes as follows:

SharePointPermission. Controls rights to access resources used by Windows SharePoint Services.

Attribute Description
ObjectModel Set to TRUE to use the Microsoft.SharePoint object model
UnsafeSaveOnGet Set to TRUE to save data on HTTP-GET requests
Unrestricted Set to TRUE to enable all rights associated with this permission.

WebPartPermission. Controls rights to access Web Part resources

Attribute Description
Connections Set to TRUE to participate in Web Part to Web Part communications
Unrestricted Set to TRUE to enable all rights associated with this permission.

ASP.NET and SharePoint Security Policies

You can specify a level of trust that corresponds to a predefined set of permissions for ASP.NET applications. By default, ASP.NET defines the following trust levels:

  • Full
  • High
  • Medium
  • Low
  • Minimal

With the exception of the Full trust level, all trust levels grant only partial trust to the application folder of a virtual server instance. For more information on the ASP.NET trust levels, see Code Access Security for ASP.NET.

Additionally, Windows SharePoint Services defines two trust levels of its own:

  • WSS_Minimal
  • WSS_Medium

The trust levels extend the Minimal and Medium trust levels of ASP.NET for Windows SharePoint Services. The trust levels are defined in security policy files, wss_minimaltrust.config and wss_mediumtrust.config. By default, Windows SharePoint Services stores these files in the following location:

local_drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\config

By default, when you extend a virtual server with Windows SharePoint Services, Windows SharePoint Services sets the trust level to WSS_Minimal. This helps provide a secure trust level in which assemblies operate with the smallest set of permissions required for code to execute.

The following table outlines the specific permissions granted with the custom security policy files included with Windows SharePoint Services.

Permission WSS_Medium trust level WSS_Minimal trust level
AspNetHostingPermission Medium Minimal
Environment Read: TEMP, TMP, OS, USERNAME, COMPUTERNAME
FileIO Read, Write, Append, PathDiscovery:Application Directory    
IsolatedStorage AssemblyIsolationByUser, Unrestricted UserQuota    
Reflection        
Registry        
Security Execution, Assertion, ControlPrincipal, ControlThread, RemotingConfiguration Execution
Socket        
WebPermission Connect to origin host (if configured)    
DNS Unrestricted    
Printing Default printing    
OleDBPermission        
SqlClientPermission AllowBlankPassword=false    
EventLog        
Message Queue        
Service Controller        
Performance Counters        
Directory Service    
SharePointPermission ObjectModel = true  
WebPartPermission Connections = true Connections = true

Note   By default, Windows SharePoint Services does not grant access to the Microsoft SharePoint object model. To grant access, you must raise the associated trust level by one of several methods. The next section discusses these methods.

Setting the Trust Level for a Virtual Server

You can determine the trust level for a virtual server by the value of the level attribute of the <trust> tag in the web.config file. By default, Windows SharePoint Services sets the trust level to WSS_Minimal. In the web.config file of a virtual server extended with Windows SharePoint Services, you can find the following <trust>:

<trust level="WSS_Minimal" originUrl="" />

By default, you can use any one of the seven predefined trust levels outlined in the preceding section.

**Note   **After changing the trust level of a virtual server, you must reset the Web service such as by using iisreset.

Specifying a trust level in the web.config file results in the following:

  • The trust level specified in the web.config file applies to all assemblies used by the specified virtual server.
  • All SharePoint sites associated with the specified virtual server apply the same trust level.

Frequently Asked Questions

The following is a list of questions that apply to code access security and Windows SharePoint Services.

What does partial trust mean the Web Part developer?

If you install assemblies into the BIN directory, you must ensure your code provides error handling in the event that required permissions are not available. Otherwise, unhandled security exceptions may cause your Web Part to fail and may affect page rendering on the page where the Web Part appears.

The following is a typical example of a security exception:

Request for the permission of type 
  Microsoft.SharePoint.Security.SharePointPermission, 
  Microsoft.SharePoint.Security, Version=11.0.0.0, Culture=neutral, 
  PublicKeyToken=71e9bce111e9429c failed

As stated previously, the WSS_Minimal trust level does not grant permission to the SharePointPermission.ObjectModel to assemblies in the BIN directory for an application. Therefore, if your code attempts to use the Microsoft SharePoint object model, the common language runtime (CLR) throws an exception.

Since the minimal permission set provides the smallest set of permissions required for code to execute, the likelihood of additional security exceptions is increased.

Recommendation   Try-catch critical areas to address situations where you may not have the necessary permissions to accomplish a specified objective.

What if my assemblies are installed in the GAC?

By default, assemblies installed in the global assembly cache (GAC) run with Full trust. Although, installing your Web Part assembly in the GAC is a viable option, it is recommended that you install Web Part assemblies in the BIN directory for a more secure deployment.

How can I raise the trust level for assemblies installed in the BIN directory?

Windows SharePoint Services can use any of the following three options from ASP.NET and the CLR to provide assemblies installed in the BIN directory with sufficient permissions. The following table outlines the implications and requirements for each option.

Option Pros Cons
Increase the trust level for the entire virtual server. For more information, see "Setting the trust level for a virtual server" Easy to implement.

In a development environment, increasing the trust level allows you to test an assembly with increased permissions while allowing you to recompile assemblies directly into the BIN directory without resetting IIS.

This option is least secure.

This option affects all assemblies used by the virtual server.

There is no guarantee the destination server has the required trust level. Therefore, Web Parts may not work once installed on the destination server.

Create a custom policy file for your assemblies. For more information, see "How do I create a custom policy file?" Recommended approach.

This option is most secure.

An assembly can operate with a unique policy that meets the minimum permission requirements for the assembly.

By creating a custom security policy, you can ensure the destination server can run your Web Parts.

Requires the most configuration of all three options.
Install your assemblies in the GAC Easy to implement.

This grants Full trust to your assembly without affecting the trust level of assemblies installed in the BIN directory.

This option is less secure.

Assemblies installed in the GAC are available to all virtual servers and applications on a server running Windows SharePoint Services. This could represent a potential security risk as it potentially grants a higher level of permission to your assembly across a larger scope than necessary

In a development environment, you must reset IIS every time you recompile assemblies.

Licensing issues may arise due to the global availability of your assembly.

I changed the trust level in the web.config file—now my entire site fails to render. What should I do?

If you change the trust level in the web.config file, Windows SharePoint Services may fail to render on subsequent requests. The following is an example of a typical error:

Assembly <assemblyName> security permission grant set is incompatible 
  between appdomains.

To resolve the conflicting trust setting, reset Internet Information Services (IIS) such as by using iisreset.

**Note   **This is a known issue related to the architecture of ASP.NET and the .NET Framework.

How do I create a custom policy file?

To customize one of the built-in policy files, it is recommended that you make a copy of it and make changes to the copy to ensure that you can reuse the original file if necessary.

The following procedure describes how to give access to the Microsoft SharePoint object model to a specific assembly.

To give access to an assembly

  1. Copy the wss_minimaltrust.config file.

  2. Rename the file new_file_name**.config**.

  3. Using a text editor such as NotePad, open new_file_name**.config**

  4. Under the <SecurityClasses> element, add a reference to the SharePointPermission class as follows:

    <SecurityClasses>
      <!-- other security classes omitted for clarity -->
      <SecurityClass Name="SharePointPermission"
      Description="Microsoft.SharePoint.Security.SharePointPermission, 
      Microsoft.SharePoint.Security, Version=11.0.0.0, Culture=neutral, 
      PublicKeyToken=71e9bce111e9429c" /> 
    </SecurityClasses>
    
  5. Search for the <PermissionSet> tag where the name attribute equals ASP.Net.

  6. Copy this entire tag and all of its children, and paste a copy of it immediately below the one you copied.

  7. Change the name of the new PermissionSet element from ASP.Net to New_File_Name:

    Example (Before)

    <PermissionSet class="NamedPermissionSet" version="1" Name="ASP.Net">
    <!-- <IPermission> nodes omitted for clarity -->
      </PermissionSet>
    

    Example (After)

    <PermissionSet class="NamedPermissionSet" version="1" 
      Name="New_File_Name">
    <!-- <IPermission> nodes omitted for clarity -->
      </PermissionSet>
    
  8. Add the following <IPermission> node to the<PermissionSet> element where the name attribute equals New_File_Name:

    <IPermission class="SharePointPermission" 
                 version="1" 
                 ObjectModel="True" />
    

    Therefore, the resulting customized <PermissionSet> will look as follows:

    <PermissionSet class="NamedPermissionSet" version="1" Name=" 
      New_File_Name">
      <IPermission class="AspNetHostingPermission" version="1" 
        Level="Minimal" /> 
      <IPermission class="SecurityPermission" version="1" Flags="Execution" 
        /> 
      <IPermission class="WebPartPermission" version="1" Connections="True" 
        /> 
      <IPermission class="SharePointPermission" version="1" 
        ObjectModel="True" /> 
    </PermissionSet>
    
  9. Once you define the customized element, you must create a code group to specify when the CLR should apply the permission set.

    **Important   **By default, the AllCode code group is a FirstMatchCodeGroup in ASP.NET policy files. Therefore, the CLR stops assigning permissions to an assembly after the first match to a specific code group. To apply the custom permissions, you must declare the specific code group assigning the custom permissions to your assembly as the first code group within the AllCode group. This ensures that the CLR assigns the MyCustomPermissions permission set and stops without proceeding to the default $AppDirUrl$/* code group that is used to assign permissions based on whether the assembly is located in BIN directory.

    In the following example, the membership condition for the new code group is based on strong name membership:

    <!-- a custom group must precede the default ASP.NET code group -->
    <CodeGroup class="UnionCodeGroup" 
               version="1" 
               PermissionSetName="MyCustomPermissions">
      <IMembershipCondition class="StrongNameMembershipCondition" 
                            version="1" 
                            PublicKeyBlob="... see note below ..." 
                            Name="MyAssemblyName" /> 
    </CodeGroup>
    

    **Note   **To retrieve the public key blob for an assembly, use the secutil.exe tool as follows:

    secutil.exe -hex -s MyAssemblyName.dll
    

    For more information about secutil.exe, see Secutil Tool.

  10. Save and close the file. The policy file is ready to use.

  11. Open the web.config file for the virtual server extended with Windows SharePoint Services and add the following <trustLevel> tag to the SecurityPolicy element:

      <trustLevel name="MyCustomTrustLevel" 
                  policyFile="new_file_name.config" /> 
    

    In the web.config file, change the <trust> tag so that it refers to the newly defined trust level.

    <trust level="MyCustomTrustLevel " originUrl="" />
    
  12. Save and close the web.config file.

  13. Reset IIS, such as by using iisreset, to apply the custom policy to the specified virtual server.

What if my assembly is not strongly named? How does my code group change?

You can specify membership conditions for a code group in several ways. You can use the UrlMembershipCondition to specify conditions as follows:

<CodeGroup class="UnionCodeGroup" 
           version="1" 
           PermissionSetName="MyCustomPermissions">
  <IMembershipCondition class="UrlMembershipCondition" 
                        version="1" 
                        Url="$AppDirUrl$/bin/MyAssemblyName.dll" />
</CodeGroup>

My assembly refers to a library assembly. Everything works when the assembly is installed in the GAC, but fails once the assembly is placed in the BIN directory. What is going on?

Assuming you granted the required permissions to an assembly, the reason your assembly cannot run may be related to how the library assembly was built. By default, strongly named assemblies allow only callers who are granted Full Trust. Therefore, the CLR blocks a partially trusted assembly from calling into a Full Trust-only assembly.

You have several possible solutions, both of which have security implications that you must consider:

  1. When compiling the assembly, you can add the AllowPartiallyTrustedCallersAttribute attribute to the specified library assembly.

    Important   You can only add this attribute to the source code. If you are using a third-party assembly and do not have access to the source, you cannot choose this option. If you choose this option, you are allowing partially trusted callers to execute code from within the library. This could represent a potential security risk as it opens the specified library assembly for use by other callers with partial trust.

  2. You can give your assembly Full trust by installing it to the GAC.

    Important   Assemblies installed in the GAC are available to all virtual servers and applications on the server running Windows SharePoint Services. This could represent a potential security risk as it potentially grants a higher level of permission to your assembly across a larger scope than necessary.

  3. You can give your assembly Full trust by creating a custom policy file as outlined in the previous section.

    Important   It is recommended that you choose this option as it allows you to explicitly grant the required minimum level of permission to your assembly without increasing the scope of access to a larger number of callers.

I am trying to access a Web service by using a Web Part. When I do so, I get a Security Exception as follows:

Request for the permission of type System.Net.WebPermission, System, 
  Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 
  failed.

By default, assemblies in the BIN directory do not have the required permission, System.Net.WebPermission, to access Web services. To grant this permission, add the following to the corresponding IPermission element in the appropriate policy file:

<IPermission class="WebPermission" version="1">
  <ConnectAccess>
    <URI uri="...uri in the form of a regular expression..." />
  </ConnectAccess>
</IPermission>

I want to access a Web service from my Web Part. When I do so, I get an InvalidOperationException as follows:

One or more assemblies referenced by the XmlSerializer cannot be called 
  from partially trusted code.

When you create a reference to a Web service, Microsoft Visual Studio®.NET creates and places one or more objects in your assembly to store the argument data passed to the method(s) in the Web service. These objects are serialized using the XmlSerializer class when you invoke one or more of the methods in the Web service. By default, if your assembly is strongly named and resides in the BIN directory, callers with partial trust cannot access objects within that assembly. When you make the call to the Web service method, the XmlSerializer detects that there are partially trusted callers on the callstack (i.e. your assembly) and prevents the serialization from taking place even though the object resides in the same assembly.

You have several possible solutions, both of which have security implications that you must consider:

  1. You can add the AllowPartiallyTrustedCallersAttribute attribute to the specified library assembly.

    Important   You can only add this attribute to the source code. If you are using a third-party assembly and do not have access to the source, you cannot choose this option. If you choose this option, you are allowing partially trusted callers to execute code from within the library. This could represent a potential security risk as it opens the specified library assembly for use by other callers with partial trusts.

  2. You can give your assembly Full trust by installing it to the GAC.

    Important   Assemblies installed in the GAC are available to all virtual servers and applications on the server running Windows SharePoint Services. This could represent a potential security risk as it potentially grants a higher level of permission to your assembly across a larger scope than necessary.

  3. You can give your assembly Full trust by creating a custom policy file as outlined in the previous section.

    Important   It is recommended that you choose this option as it allows you to explicitly grant the required minimum level of permission to your assembly without increasing the scope of access to a larger number of callers.

Where can I learn more about code access security?

For more information about code access security, see the following:

Conclusion

Windows SharePoint Services uses custom ASP.NET policies to grant partial trust or full trust to assemblies according to your requirements. Developers and administrators can use existing knowledge of ASP.NET and code access security when working with Windows SharePoint Services to create custom security policies that help ensure a more secure environment for running custom assemblies.