WebPartManager.IsAuthorized Method

Reference

Definition

Namespace:: System.Web.UI.WebControls.WebParts

Assembly:: System.Web.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Determines whether a WebPart or other server control can be added to a page.

Overloads

IsAuthorized(WebPart)	Carries out the initial steps in determining whether a control is authorized to be added to a page.
IsAuthorized(Type, String, String, Boolean)	Carries out the final steps in determining whether a control is authorized to be added to a page.

Remarks

Part of the flexibility of the Web Parts feature is the ability to add server controls to Web pages at run time. There are a number of common scenarios in which a server control (which can be a custom WebPart control, a custom server control, a user control, or an ASP.NET control) can be added.

In the following common scenarios, the Web Parts control set attempts to add server controls to a page, and the IsAuthorized method is called to authorize them:

When a server control is added by declaring it in the markup of a Web page within a WebPartZoneBase zone.
When a server control is added programmatically to a zone.
When a user imports a server control into a Web Parts catalog of controls.
When an existing server control is loaded from the personalization data store.
When a server control is added to a DeclarativeCatalogPart control to make it available in a catalog of server controls.

In each scenario where controls are added, the IsAuthorized method is called to ensure that all authorization criteria have been met to allow a control to be added. When a control is authorized, it is added normally as it would be if there was no filtering scenario. When a control is not authorized, the Web Parts control set can respond in several ways, depending on the context. The control set can silently fail to add an unauthorized part (if there is no need to inform the user), it can display an error message, or it can add an instance of the UnauthorizedWebPart class as a placeholder. This placeholder object is not visible on the page, but is visible in the page source code to indicate that an unauthorized control was excluded.

The determinant of whether a control is authorized is the authorization filter. An authorization filter is a feature in the Web Parts control set that enables developers to exclude from a page any controls that do not meet the specified criteria.

To create a filtering scenario, developers must do two things. First, they must assign a string value (the value can be arbitrary) to the AuthorizationFilter property of each WebPart control they plan to use in the scenario. They can also assign a value to this property for other types of server controls that are not WebPart controls, because if they are placed in WebPartZoneBase zones, such controls are wrapped with a GenericWebPart control at run time, and this control inherits the AuthorizationFilter property.

The second necessary step for creating a filtering scenario is to either override the IsAuthorized(Type, String, String, Boolean) method, or to create an event handler for the AuthorizeWebPart event. In these methods, a developer can check the AuthorizationFilter property, and if the value indicates that the control should not be authorized, the developer ensures that the IsAuthorized method returns a value of false.

Note

For code examples and a description of how to set up a customized filtering scenario using the IsAuthorized method, see the topics for the overloads of the method.

IsAuthorized(WebPart)

Carries out the initial steps in determining whether a control is authorized to be added to a page.

public:
 bool IsAuthorized(System::Web::UI::WebControls::WebParts::WebPart ^ webPart);

public bool IsAuthorized (System.Web.UI.WebControls.WebParts.WebPart webPart);

member this.IsAuthorized : System.Web.UI.WebControls.WebParts.WebPart -> bool

Public Function IsAuthorized (webPart As WebPart) As Boolean

Parameters

webPart: WebPart

A WebPart or other server control being checked for authorization.

Returns

Boolean

A Boolean value that indicates whether webPart can be added to a page.

Exceptions

ArgumentNullException

webPart is null.

Examples

The following code example demonstrates how to call the IsAuthorized(WebPart) method from your code to determine whether a control is authorized to be added to a page.

The code example has three parts:

A custom WebPartManager control that overrides the IsAuthorized method.
A Web page that creates a filter for a WebPart control.
An explanation of how to run the code example.

This code example uses a custom WebPartManager control that overrides the IsAuthorized(Type, String, String, Boolean) overload method to provide custom handling of the AuthorizationFilter property. This control checks for a property value of admin and, if the value is present, authorizes the control. If a control has a different value, it is not authorized; controls without the property value are authorized as well, as they are presumed not to be part of the filtering scenario.

For this code example to run, you must compile this source code. You can compile it explicitly and put the resulting assembly in your Web site's Bin folder or the global assembly cache. Alternatively, you can put the source code in your site's App_Code folder, where it will be dynamically compiled at run time. This code example uses the dynamic compile method. For a walkthrough that demonstrates how to compile, see Walkthrough: Developing and Using a Custom Web Server Control.

using System;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

namespace Samples.AspNet.CS.Controls
{
  public class MyManagerAuthorize : WebPartManager
  {
    public override bool IsAuthorized(Type type, string path, string authorizationFilter, bool isShared)
    {
      if (!String.IsNullOrEmpty(authorizationFilter))
      {
        if (authorizationFilter == "admin")
          return true;
        else
          return false;
      }
      else
            {
                return true;
            }
        }
  }
}

Imports System.Web
Imports System.Web.Security
Imports System.Security.Permissions
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts

Namespace Samples.AspNet.VB.Controls

  <AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  <AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class MyManagerAuthorize
    Inherits WebPartManager

    Public Overrides Function IsAuthorized(ByVal type As Type, _
      ByVal path As String, ByVal authorizationFilter As String, _
      ByVal isShared As Boolean) As Boolean

      If Not String.IsNullOrEmpty(authorizationFilter) Then
        If authorizationFilter = "admin" Then
          Return True
        Else
          Return False
        End If
      Else
        Return True
      End If

    End Function

  End Class

End Namespace

The second part of the code example creates a filter that can potentially exclude a control. The following Web page contains three ASP.NET server controls in an <asp:webpartzone> element. Notice that the first and second controls have their AuthorizationFilter properties set to different values, and the third does not assign the property. This authorization value can be checked at run time, and the control can be added to the page if the filter matches criteria set by the developer. Notice also that in the Page_Load method, the code calls the IsAuthorized(WebPart) method to determine whether each of the controls is authorized, and if so, it sets each control's ExportMode property.

<%@ Page Language="C#" %>
<%@ Register Namespace="Samples.AspNet.CS.Controls" 
    TagPrefix="aspSample"%>


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
  
  protected void Page_Load(object sender, EventArgs e)
  {
    foreach (WebPart part in mgr1.WebParts)
    {
      if (mgr1.IsAuthorized(part))
        part.ExportMode = WebPartExportMode.All;
    }
    
  }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <aspSample:MyManagerAuthorize ID="mgr1" runat="server"  />
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <asp:BulletedList 
            ID="BulletedList1" 
            Runat="server"
            DisplayMode="HyperLink" 
            Title="Favorite Links"
            AuthorizationFilter="admin">
            <asp:ListItem Value="http://msdn.microsoft.com">
              MSDN
            </asp:ListItem>
            <asp:ListItem Value="http://www.asp.net">
              ASP.NET
            </asp:ListItem>
            <asp:ListItem Value="http://www.msn.com">
              MSN
            </asp:ListItem>
          </asp:BulletedList>
          <asp:Label ID="Label1" runat="server" 
            Text="Hello World"
            AuthorizationFilter="user" />
          <asp:Calendar ID="Calendar1" runat="server"></asp:Calendar>
        </ZoneTemplate>
      </asp:WebPartZone>
      <hr />
      <asp:Literal ID="Literal1" runat="server"></asp:Literal>
    </div>
    </form>
</body>
</html>

<%@ Page Language="vb" %>
<%@ Register Namespace="Samples.AspNet.VB.Controls" 
    TagPrefix="aspSample"%>


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

  Protected Sub Page_Load(ByVal sender As Object, _
    ByVal e As System.EventArgs)
    
    Dim part As WebPart
    For Each part In mgr1.WebParts
      If mgr1.IsAuthorized(part) Then
        part.ExportMode = WebPartExportMode.All
      End If
    Next
  End Sub

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <aspSample:MyManagerAuthorize ID="mgr1" runat="server"  />
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <asp:BulletedList 
            ID="BulletedList1" 
            Runat="server"
            DisplayMode="HyperLink" 
            Title="Favorite Links"
            AuthorizationFilter="admin">
            <asp:ListItem Value="http://msdn.microsoft.com">
              MSDN
            </asp:ListItem>
            <asp:ListItem Value="http://www.asp.net">
              ASP.NET
            </asp:ListItem>
            <asp:ListItem Value="http://www.msn.com">
              MSN
            </asp:ListItem>
          </asp:BulletedList>
          <asp:Label ID="Label1" runat="server" 
            Text="Hello World"
            AuthorizationFilter="user" />
          <asp:Calendar ID="Calendar1" runat="server"></asp:Calendar>
        </ZoneTemplate>
      </asp:WebPartZone>
      <hr />
      <asp:Literal ID="Literal1" runat="server"></asp:Literal>
    </div>
    </form>
</body>
</html>

Note that for the code example to work, you must add a setting in the Web.config file to enable exporting Web Parts description files. Ensure that you have a Web.config file in the same directory as the Web page for this code example. Within the <system.web> section, make sure there is a <webParts> element with an enableExport attribute set to true, as in the following markup.

<webParts enableExport="true">

...

</webParts>

After you load the page in a browser, note that the first control is displayed, because it matches the criteria in the overridden method. The second control is not added to the page, because it is excluded by the filter. The third control is also added, because it does not have its AuthorizationFilter property set. Notice that if you click the verbs menu icon in the title bar of either control, they can both be exported because their respective ExportMode property values were assigned.

Remarks

The IsAuthorized method is the initial method called by the Web Parts control set to check authorization for a WebPart control. It accepts webPart as a parameter, and begins a process that ultimately determines whether the control will be added to a page. Call this method from your code directly when you need to determine whether a given control is authorized.

This method carries out the initial tasks of determining whether the control inherits from the WebPart class or is a GenericWebPart control and, if so, what type of child control it contains. To finish the task of authorization, it calls the IsAuthorized(Type, String, String, Boolean) overload method.

Notes to Callers

This method is called directly from your code. If you want to gain greater programmatic control over the authorization process, you can override the IsAuthorized(Type, String, String, Boolean) overload method.

Applies to

IsAuthorized(Type, String, String, Boolean)

Carries out the final steps in determining whether a control is authorized to be added to a page.

public:
 virtual bool IsAuthorized(Type ^ type, System::String ^ path, System::String ^ authorizationFilter, bool isShared);

public virtual bool IsAuthorized (Type type, string path, string authorizationFilter, bool isShared);

abstract member IsAuthorized : Type * string * string * bool -> bool
override this.IsAuthorized : Type * string * string * bool -> bool

Public Overridable Function IsAuthorized (type As Type, path As String, authorizationFilter As String, isShared As Boolean) As Boolean

Parameters

type: Type

The Type of the control being checked for authorization.

path: String

The relative application path to the source file for the control being authorized, if the control is a user control.

authorizationFilter: String

An arbitrary string value assigned to the AuthorizationFilter property of a WebPart control, used to authorize whether a control can be added to a page.

isShared: Boolean

Indicates whether the control being checked for authorization is a shared control, meaning that it is visible to many or all users of the application, and its IsShared property value is set to true.

Returns

Boolean

A Boolean value that indicates whether a control is authorized to be added to a page.

Exceptions

ArgumentNullException

type is null.

ArgumentException

type is a user control, and path is either null or an empty string ("").

-or-

type is not a user control, and path has a value assigned to it.

Examples

The following code example demonstrates how to override the IsAuthorized method to determine whether a control is authorized to be added to a page.

The first step is to create a filter that can potentially exclude a control. The following Web page contains three ASP.NET server controls in an <asp:webpartzone> element. Notice that the first and second controls have their AuthorizationFilter properties set to different values, and the third does not assign the property. This authorization value can be checked at run time, and the control can be added to the page if the filter matches criteria set by the developer.

<%@ Page Language="C#" %>
<%@ Register Namespace="Samples.AspNet.CS.Controls" 
    TagPrefix="aspSample"%>


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
  
  protected void Page_Load(object sender, EventArgs e)
  {
    foreach (WebPart part in mgr1.WebParts)
    {
      if (mgr1.IsAuthorized(part))
        part.ExportMode = WebPartExportMode.All;
    }
    
  }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <aspSample:MyManagerAuthorize ID="mgr1" runat="server"  />
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <asp:BulletedList 
            ID="BulletedList1" 
            Runat="server"
            DisplayMode="HyperLink" 
            Title="Favorite Links"
            AuthorizationFilter="admin">
            <asp:ListItem Value="http://msdn.microsoft.com">
              MSDN
            </asp:ListItem>
            <asp:ListItem Value="http://www.asp.net">
              ASP.NET
            </asp:ListItem>
            <asp:ListItem Value="http://www.msn.com">
              MSN
            </asp:ListItem>
          </asp:BulletedList>
          <asp:Label ID="Label1" runat="server" 
            Text="Hello World"
            AuthorizationFilter="user" />
          <asp:Calendar ID="Calendar1" runat="server"></asp:Calendar>
        </ZoneTemplate>
      </asp:WebPartZone>
      <hr />
      <asp:Literal ID="Literal1" runat="server"></asp:Literal>
    </div>
    </form>
</body>
</html>

<%@ Page Language="vb" %>
<%@ Register Namespace="Samples.AspNet.VB.Controls" 
    TagPrefix="aspSample"%>


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

  Protected Sub Page_Load(ByVal sender As Object, _
    ByVal e As System.EventArgs)
    
    Dim part As WebPart
    For Each part In mgr1.WebParts
      If mgr1.IsAuthorized(part) Then
        part.ExportMode = WebPartExportMode.All
      End If
    Next
  End Sub

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <aspSample:MyManagerAuthorize ID="mgr1" runat="server"  />
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <asp:BulletedList 
            ID="BulletedList1" 
            Runat="server"
            DisplayMode="HyperLink" 
            Title="Favorite Links"
            AuthorizationFilter="admin">
            <asp:ListItem Value="http://msdn.microsoft.com">
              MSDN
            </asp:ListItem>
            <asp:ListItem Value="http://www.asp.net">
              ASP.NET
            </asp:ListItem>
            <asp:ListItem Value="http://www.msn.com">
              MSN
            </asp:ListItem>
          </asp:BulletedList>
          <asp:Label ID="Label1" runat="server" 
            Text="Hello World"
            AuthorizationFilter="user" />
          <asp:Calendar ID="Calendar1" runat="server"></asp:Calendar>
        </ZoneTemplate>
      </asp:WebPartZone>
      <hr />
      <asp:Literal ID="Literal1" runat="server"></asp:Literal>
    </div>
    </form>
</body>
</html>

The second step is to override the IsAuthorized(Type, String, String, Boolean) method, and create custom handling for authorization filters. Note that the code first checks whether the property has a value, so that any control that does not assign the AuthorizationFilter property will be added automatically. If a control has a filter, the code returns true only if the filter value is equal to admin. This demonstrates a simple mechanism you can use for displaying certain controls to certain users, depending on their role. While a full example using roles is beyond the scope of this topic, you could use the same logic as the overridden method in this code example, except that you could check whether the current user is in a role that matches the authorization filter value, and then add the control only for that user. This would enable you to create pages where some users would see all the controls, and other users would see only selected controls. This is how the logic that checks the filter might look if you used roles:

If Roles.IsUserInRole(Page.User.Identity.Name, authorizationFilter) Then  
  return True  
Else  
  return False  
End If

if(Roles.IsUserInRole(Page.User.Identity.Name, authorizationFilter))  
    return true;  
else  
    return false;

For the code example to run, you must compile this source code. You can compile it explicitly and put the resulting assembly in your Web site's Bin folder or the global assembly cache. Alternatively, you can put the source code in your site's App_Code folder, where it will be dynamically compiled at run time. This code example uses the dynamic compile method. For a walkthrough that demonstrates how to compile, see Walkthrough: Developing and Using a Custom Web Server Control.

using System;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

namespace Samples.AspNet.CS.Controls
{
  public class MyManagerAuthorize : WebPartManager
  {
    public override bool IsAuthorized(Type type, string path, string authorizationFilter, bool isShared)
    {
      if (!String.IsNullOrEmpty(authorizationFilter))
      {
        if (authorizationFilter == "admin")
          return true;
        else
          return false;
      }
      else
            {
                return true;
            }
        }
  }
}

Imports System.Web
Imports System.Web.Security
Imports System.Security.Permissions
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts

Namespace Samples.AspNet.VB.Controls

  <AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  <AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class MyManagerAuthorize
    Inherits WebPartManager

    Public Overrides Function IsAuthorized(ByVal type As Type, _
      ByVal path As String, ByVal authorizationFilter As String, _
      ByVal isShared As Boolean) As Boolean

      If Not String.IsNullOrEmpty(authorizationFilter) Then
        If authorizationFilter = "admin" Then
          Return True
        Else
          Return False
        End If
      Else
        Return True
      End If

    End Function

  End Class

End Namespace

After you load the page in a browser, note that the first control is displayed, because it matches the criteria in the overridden method. The second control is not added to the page, because its filter value is excluded. The third control is added, because it does not have its AuthorizationFilter property set. If you change the property value on the second control to match that of the first control, and then run the page again, the second control is added as well.

Remarks

The IsAuthorized(Type, String, String, Boolean) overload method carries out the final steps in determining whether a control is authorized to be added to a page. The method ensures that type is a valid type, and that path has a value only if the control being checked is a user control. Then it calls the critical OnAuthorizeWebPart method, which raises the AuthorizeWebPart event.

Notes to Inheritors

This method can be overridden by inheriting from the WebPartManager class, if you want to provide additional handling when checking authorization. You might want to override the method to check for certain values in the authorizationFilter parameter, and based on the value, return a Boolean value that determines whether the control will be added to a page.

For page developers who also want to check for authorization filters and provide custom handling, there is an option for doing this inline in an .aspx page, or in a code-behind file, without having to inherit from any classes. You can declare an alternate event handler in the page for the OnAuthorizeWebPart(WebPartAuthorizationEventArgs) method of the WebPartManager control. For more details and an example, see the OnAuthorizeWebPart(WebPartAuthorizationEventArgs) method.

Applies to

Share via

WebPartManager.IsAuthorized Method

Definition

Overloads

Remarks

IsAuthorized(WebPart)

Parameters

Returns

Exceptions

Examples

Remarks

Notes to Callers

See also

Applies to

IsAuthorized(Type, String, String, Boolean)

Parameters

Returns

Exceptions

Examples

Remarks

Notes to Inheritors

See also

Applies to

Aanvullende resources