Consider the following navigational structure, which is displayed in an ASP.NET page.

Home
   Products
      Hardware
      Software
      Discounts
   Services
      Training
      Consulting
      Support

Clients who are not members of a role called Customers are restricted from viewing the Support Web page by an ASP.NET access rule that is configured for the Support.aspx page.

To hide the Support link in the navigational display, configure the site-map provider in the Web.config file to enable security trimming. No additional changes are needed because the application will use ASP.NET URL authorization and file authorization to hide the link to the Support page. The XmlSiteMapProvider control that is included with ASP.NET version 2.0 automatically performs authorization checks against each site-map node by using the URL- and file-authorization features.

If you want show the Support link to clients who are not in the Customers role, you can use the roles attribute in the site-map node for the Support.aspx file. The roles attribute expands access to a site-map node beyond the level of access that URL authorization and file authorization grant.

The following code example sets the roles attribute for the Support page to Customers. After enabling security trimming, this setting allows users in the Customers role to view the navigation link to the Support page, even if they are not permitted to view the actual file by URL authorization or file authorization.

<?xml version="1.0" encoding="utf-8" ?>
  <siteMap>
    <!-- other <siteMapNode> elements -->
      <siteMapNode title="Support" description="Support"
        url="~/Customers/Support.aspx" roles="Customers" />
  </siteMap>

Users who are not members of the Customers role would see the following navigational structure if they are restricted from viewing the Support page because of URL- or file-authorization rules.

Home
   Products
      Hardware
      Software
      Discounts
   Services
      Training
      Consulting

Security trimming works in conjunction with ASP.NET roles. Therefore, pages must be restricted by using access rules (allow and deny elements) for security trimming to work. For more information about access rules, see Managing Authorization Using Roles.

Security trimming is not enabled by default, and it cannot be enabled programmatically; it can only be set in the Web.config file. This is also true for any custom class that inherits from the SiteMapProvider class.

To enable security trimming, you need to configure a siteMap Element (ASP.NET Settings Schema) element in your Web.config file. If your site map uses the default ASP.NET site-map provider, then the Web.config file might not contain a siteMap Element (ASP.NET Settings Schema) element, in which case you will need to add one. The following code example adds the default site-map provider and enables security trimming.

<system.web>
<!-- …other configuration settings -->
  <siteMap defaultProvider="XmlSiteMapProvider" enabled="true">
    <providers>
      <add name="XmlSiteMapProvider"
        description="Default SiteMap provider."
        type="System.Web.XmlSiteMapProvider "
        siteMapFile="Web.sitemap"
        securityTrimmingEnabled="true" />
    </providers>
  </siteMap>
</system.web>

The security-trimming feature uses URL authorization on each request to determine whether a user has access to a URL that is associated with a siteMapNode element. This extra work reduces performance depending on the number of nodes that are being authorized. When security trimming is enabled, you can use the following methods to improve performance:

• Limit the number of nodes in the site-map file   Site-map files with more than 150 nodes can take substantially longer to perform security-trimming operations.

• Set the roles attribute explicitly on siteMapNode elements   Note that setting the roles attribute to a wildcard character, or asterisk (*), should be used only for nodes that can safely be displayed to any client. The presence of a roles attribute allows ASP.NET to bypass URL authorization for the URL that is associated with the siteMapNode when a user belongs to one of the roles that is listed in the attribute.

To prevent the unintended trimming of child site-map nodes, configure authorization rules and roles attributes carefully. Consider the following navigational structure, which is displayed in an ASP.NET page.

Home
   Products
      Hardware

The URL- or file-authorization rules set on the Products.aspx file should not be more restrictive than the authorization rules that are set on the Hardware.aspx file. Otherwise, the Hardware link will be hidden from users who should be able to view it because the parent link to Products will be hidden. To expose the hidden links, add to both site-map nodes a roles attribute that lists the neglected ASP.NET roles.

It is recommended that the root node in a site map allow everyone access. To do this, set the roles attribute to an asterisk (*), or wildcard character, as shown in the following code example.

<?xml version="1.0" encoding="utf-8" ?>
<siteMap>
  <siteMapNode title="Home" description="Home" 
    url="default.aspx" roles="*">
    <!-- other <siteMapNode> elements -->
  </siteMapNode>
</siteMap>

In a site map, you can reference URLs that are outside of your Web application. Access to a URL outside of the application cannot be tested by ASP.NET. Therefore, if you enable security trimming, the site-map node will not be visible unless you set the roles attribute to an asterisk (*), which enables all clients to view the site-map node without first testing access to the URL.

You can use multiple site maps together to define the navigation structure for a single Web site. For example, a Web.sitemap file is similar to a Web.config file because it can be split up and placed in different folders.

Site maps are linked to each other by referencing a child site-map file or provider in the siteMapFile or provider attribute of a SiteMapNode object in the parent site map.

The following code example illustrates a site-map node that references another site map.

<?xml version="1.0" encoding="utf-8" ?>

<siteMap>
  <!-- other <siteMapNode> elements -->
    <siteMapNode siteMapFile="~/Customers/Customers.sitemap" 
      securityTrimmingEnabled="true" />
</siteMap>

You can use navigation controls to add site navigation to your pages with little or no code, but you can also work with site navigation programmatically. When your Web application runs, ASP.NET exposes a SiteMap object that reflects the site-map structure. All of the members of the SiteMap object are static. The SiteMap object, in turn, exposes a collection of SiteMapNode objects that contain properties for each node in the map. This is because, when you use the SiteMapPath control, the control works with the SiteMap and SiteMapNode objects to render the appropriate links automatically.

You can use the SiteMap, SiteMapNode, and SiteMapProvider objects in your own code to traverse the site-map structure or create a custom control to display site-map data. You cannot write to the site map, but you can alter site-map nodes in the instance of the object. For more information, see How to: Programmatically Modify Site-Map Nodes in Memory or How to: Programmatically Enumerate Site-Map Nodes.

ASP.NET uses the default site-map provider, XmlSiteMapProvider, to read the Web.sitemap file. If you want to store site-map information in a location other than the site-map file, you can create your own site-map provider and configure your application to call the custom provider. The site-map provider is configured in the Web.config file. When the application runs, ASP.NET will invoke your provider, which can retrieve site-map information as needed. ASP.NET then creates and populates the SiteMapNode objects based on the information that your provider returns. These objects can be programmatically accessed by using the SiteMap class. For more information, see Implementing ASP.NET Site-Map Providers.

Security Note:

Implementing a custom site-map provider that stores site-map data in a file with a file name extension other than .sitemap is a potential security risk. By default, ASP.NET is configured to protect files with known file name extensions — such as .sitemap — from being downloaded by a client. To help protect your data, place any custom site-map data files that have a file name extension other than .sitemap in the App_Data folder. For more information, see Securing ASP.NET Site Navigation.

When enabled, security trimming affects the behavior of some of the members in the SiteMap, SiteMapNode, and SiteMapNodeCollection classes. When using these classes, you will see the following behavior:

• A null is returned by a site navigation API member if it attempts to reference a site-map node that the user does not have the security rights to see. For example, the CurrentNode, NextSibling, ParentNode, and PreviousSibling properties will return a null if the properties attempt to return a site-map node that is restricted.

• If a site navigation API member needs to traverse the tree of site-map nodes, any site-map node that the user is not allowed to see is excluded from the traversal. For example, when the ChildNodes method runs, the collection of nodes is filtered to include only those nodes that the user is allowed to see. In the case of API members that need to keep track of node paths, such as the Clone or IsDescendantOf methods, the paths end at restricted nodes. This can result in cloning operations returning a reduced number of nodes. It can also result in the IsDescendantOf method returning a value of false even though structurally a node might actually be a descendant of the requested node.

• An InvalidOperationException exception is returned if a site navigation API member references a root node that the user does not have the security rights to see. Only the root node of the root provider needs to be accessible to all users, which prevents an exception from being thrown when first obtaining the SiteMap object.

• A ConfigurationException exception is thrown if a SiteMapNode object references another site-map file or provider incorrectly.

Note:
In a site map, you can reference URLs that are outside of your Web application. Access to a URL outside of the application cannot be tested by ASP.NET. Therefore, if you enable security trimming, the site-map node will not be visible unless you set the roles attribute to an asterisk (*), which enables all clients to view the site-map node without first testing access to the URL.

Tasks

Concepts

Other Resources