Role Manager

The ASP.NET Role Manager feature is designed to simplify managing roles and the users that belong to those roles. After authentication, when Role Manager is enabled, ASP.NET will automatically add the users to the role(s) he or she belongs to. When ASP.NET authorization occurs, the user is either allowed or denied access to the requested resource based on his or her role(s). [15]

[15] Authorization always occurs after authentication, that is, first the user's credentials are validated , and if the credentials are valid, then the determination is made whether the user is allowed to access the requested resource.

URL-based role authorization is a feature of ASP.NET 1.0. We can control what users are allowed to access by specifying access permissions within configuration (see Listing 6.14).

Listing 6.14 Configuring Roles
 <configuration>   <system.web>     <authorization>       <deny users="?" />     </authorization>   </system.web>   <location path="PremiumContent.aspx">     <system.web>       <authorization>         <allow roles="Premium" />         <deny users="*" />       </authorization>     </system.web>   </location> </configuration> 

The above web.config file could be added to any application. It states that anonymous users are denied access to all resources. Furthermore, only users in the role Premium are allowed access to PremiumContent.aspx . All other users are denied access.

Before we can control access to resources through roles, we need to create some roles and then add users to them. Let's look at how we can do this with the new Role Manager feature.

Setting Up Role Manager

Similar to Membership, Role Manager relies on a provider to store data and thus allow us to create roles and associations between users and their roles. [16] Unlike Membership, Role Manager is not enabled by default. Therefore, before we can use the Role Manager API, we need to enable the feature.

[16] This is identical to how Membership uses a provider. The difference is that a different set of providers exists for the Role Manager feature. Different providers are used to avoid making Role Manager providers dependent on Membership.

Similar to Membership configuration settings, Role Manager configuration settings are defined in machine.config and can be overridden or changed within an application's web.config file. Listing 6.15 shows a sample web.config for Role Manager.

Listing 6.15 Configuring Role Manager
 <configuration>   <system.web>     <roleManager enabled="true"                  cacheRolesInCookie="true"                  cookieName=".ASPXROLES"                  cookieTimeout="30"                  cookiePath="/"                  cookieRequireSSL="false"                  cookieSlidingExpiration="true"                  cookieProtection="All"                  defaultProvider="AspNetAccessProvider" >       <providers>         <add name="AspNetAccessProvider2"              type="System.Web.Security.AccessRoleProvider, System.Web"              connectionStringName="AccessFileName"              applicationName="/"       </providers>     </roleManager>   </system.web> </configuration> 

Table 6.3 shows an explanation of the various configuration settings.

Table 6.3. Role Manager Configuration Settings

Attribute

Default Value

Description

Enabled

false

Controls whether or not the Role Manager feature is enabled. By default it is disabled because enabling breaks backward compatibility with ASP.NET 1.0. [a]

cacheRolesInCookie

true

Allows for the roles to be cached within an HTTP cookie. When the roles are cached within a cookie, a lookup for the roles associated with the user does not have to be done through the provider.

cookieName

.ASPXROLES

Sets the name of the cookie used to store the roles when cookies are enabled.

cookieTimeout

30

Sets the period of time for which the cookie is valid. If cookieSlidingExpiration is true , the cookie timeout is reset on each request within the cookieTimeout window.

cookiePath

/

Sets the path within the application within which the cookie is valid.

cookieRequireSSL

false

Specifies whether or not the cookie must be sent over an SSL channel.

cookieSlidingExpiration

true

Sets the cookie timeout. When true , the cookie timeout is automatically reset each time a request is made within the cookieTimeout window, effectively allowing the cookie to stay valid until the user's session is complete.

cookieProtection

All

Controls how the data stored within the cookie is secured.

defaultProvider

AspNet

Access

Provider

Sets the default provider to be associated with the Role Manager APIs.

[a] The class type returned by User.Identity.Principal is of type RolesPrincipal when Role Manager is enabled.

Now that we've seen how to configure the settings of Role Manager, let's create some roles.

Creating Roles

The Roles API supports a single method for creating roles:

 CreateRole(rolename As String) 

This API is used to create the friendly role name, such as Administrators, used to control access to resources. Listing 6.16 provides sample code for creating roles in an ASP.NET page.

Listing 6.16 Creating and Viewing Roles
 <script runat="server">   Public Sub Page_Load (sender As Object, e As EventArgs)     If Not Page.IsPostBack Then       DataBind()     End If   End Sub   Public Sub CreateRole_Click(sender As Object, e As EventArgs)     Try       ' Attempt to create the role       Roles.CreateRole (Rolename.Text)     Catch ex As Exception       ' Failed to create the role       Status.Text = ex.ToString()     End Try     DataBind()   End Sub   Public Overrides Sub DataBind()     RoleList.DataSource =  Roles.GetAllRoles()  RoleList.DataBind()   End Sub </script> <html>   <body style="FONT-FAMILY: Verdana">   <H1>Create Role</H1>   Below is a list of the current roles:   <asp:datagrid id="RoleList" runat="server" />   <hr />   <form runat="server">     Rolename to create: <asp:TextBox id="Rolename" runat="server" />     <asp:button Text="Create Role"                 OnClick="CreateRole_Click" runat="server"/>   </form>   <font color="red" size="6">   <asp:Label id="Status" runat="server"/>   </font>   </body> </html> 

The code sample above allows us to enter a role name, which is then created using the Roles.CreateRole() API. If the role already exists, an exception is thrown. Finally, all of the available roles are enumerated through a DataGrid using the Roles.GetAllRoles() API, discussed shortly.

Now that we can create roles, let's add some users to the roles.

Adding Users to Roles

Membership and Role Manager are not rigidly coupled . They are designed to work together, but you do not have to use one to use the other. Both use the authenticated username as the only shared piece of data. For example, it is possible to add a user to a role even if the user is not created through the Membership system. [17]

[17] This flexible design allows for various providers to be used for data storage. For example, you could have an AS/400 Membership provider and an Access Role Manager provider.

Adding users to roles is accomplished by using the following methods supported by the Roles API:

 AddUserToRole(  username  As String  , rolename  As String) AddUserToRoles(  username  As String  , rolenames()  As String) AddUsersToRole(  usernames()  As String  , rolename  As String) AddUsersToRoles(  usernames()  As String  , rolenames()  As String) 

These various methods allow for adding users to roles in bulk or individually. Listing 6.17 demonstrates Roles.AddUserToRole() .

Listing 6.17 Adding Users to Roles
 <%@ Page Language="VB" %> <script runat="server">   Public Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)     DataBind()   End Sub   Public Sub AddUserToRole_Click(sender As Object, e As EventArgs)     Roles.AddUserToRole(Username.Text, _                         RoleList.SelectedItem.Value)     DataBind()   End Sub   Public Overrides Sub DataBind()     RoleList.DataSource =  Roles.GetAllRoles()  RoleList.DataBind()   End Sub </script> <html>   <body style="FONT-FAMILY: Verdana">   <H1>Add User to role</H1>   <form runat="server">     User: <asp:TextBox id="Username" runat="server" />     Role to add user to: <asp:DropDownList id="RoleList"                                            runat="server" />     <asp:button Text="Add User To Role"                 OnClick="AddUserToRole_Click" runat="server"/>   </form>   <font size="6" color="Red">   <asp:Label id="StatusCheck" runat="server"/>   </font>   </body> </html> 

This code sample data binds the results of Roles.GetAllRoles() to a DropDownList control and then allows us to enter a user to add to a role. [18] The Roles.AddUserToRole() API is then used to add the user to the role.

[18] You could also data bind to a list of the Members from the Membership system.

When adding multiple users to roles or a user to multiple roles, the addition occurs within the context of a transaction. Either all updates succeed or all fail.

We can now use another Roles API to determine to what roles a particular user belongs.

Returning a User's Roles

To return a list of the roles to which a user belongs, we can simply use one of the following APIs:

 GetRolesForUser() As String() GetRolesForUser(  username  As String) As String() GetUsersInRole(  rolename  As String) As String() 

The Roles.GetRolesForUser() method will return a string array of all the roles that the current user is in. The overloaded version of this method that accepts a username parameter allows us to specify for which user we want a listing of roles. The last method, Roles.GetUsersInRole() , allows us to get a string array listing of usernames that belong to the specified role.

Listing 6.18 demonstrates the overloaded version of Roles.GetRoles ForUser() .

Listing 6.18 Finding the Roles for a User
 <script runat="server">   Public Sub GetRolesForUser_Click(sender As Object, e As EventArgs)     RolesForUser.DataSource = Roles.GetRolesForUser(Username.Text)     RolesForUser.DataBind()   End Sub </script> <html>   <body style="FONT-FAMILY: Verdana">   <H1>Roles user is in</H1>   <hr />   <form runat="server">     Username: <asp:TextBox id="Username" runat="server" />     <asp:button Text="Roles User Is In"                 OnClick="GetRolesForUser_Click" runat="server"/>   </form>   User is in roles:   <asp:DataGrid runat="server" id="RolesForUser" />   </body> </html> 

This code sample simply asks for the name of a user. When the page is posted back, the Roles.GetRolesForUser() API is called, passing in the name of the specified user. The results are then data-bound to a DataGrid .

Checking whether a User Is in a Role

Access to resources can be controlled by which roles the user belongs to. As was shown in the beginning of this section, it is possible to control access to URLs based on settings made in the configuration file. In addition to this declarative security access control, we can also perform programmatic checks for the role the user belongs to.

ASP.NET 1.1 allowed for programmatic checks for determining whether the user was in a role through User.IsInRole(string username) ; the result of this method returned True or False . The Roles API supports a similar Roles.IsUserInRole( rolename As String ) API:

 IsUserInRole(  rolename  As String) As Boolean IsUserInRole(  username  As String  , rolename As String  ) As Boolean 

Now that we've seen how to add users to roles and check whether users are in a particular role, let's look at how we can remove a user from a role.

Removing Users from Roles

Similar to the methods used for adding a user to roles, we have four different methods for removing users from roles:

 RemoveUserFromRole(  username  As String  , rolename  As String) RemoveUserFromRoles(  username  As String  , rolenames()  As String) RemoveUsersFromRole(  usernames()  As String  , rolename  As String) RemoveUsersFromRoles(  usernames()  As String  , rolenames()  As String) 

Again, similar to adding users to roles, when the process of removing users from roles is transacted, either all succeed or all fail.

Deleting a Role

Roles can be deleted easily by using the Roles.DeleteRole( rolename As String) method. Listing 6.19 shows a sample ASP.NET page that demonstrates how to use this API.

Listing 6.19 Deleting a Role
 <%@ Page Language="VB" %> <script runat="server">   Public Sub Page_Load()     If Not Page.IsPostBack Then       DataBind()     End If   End Sub   Public Sub DeleteRole_Click(sender As Object, e As EventArgs)     Try       Roles.DeleteRole(Rolename.Text)     Catch ex As Exception       StatusCheck.Text = "There was an error removing the role(s)"     End Try     DataBind()   End Sub   Public Overrides Sub DataBind()     RoleList.DataSource = Roles.GetAllRoles()     RoleList.DataBind()   End Sub </script> <html>   <body style="FONT-FAMILY: Verdana">   <H1>Delete Role</H1>   Below is a list of the current roles:   <asp:datagrid id="RoleList" runat="server" />   <hr />   <form runat="server">     Rolename to delete: <asp:TextBox id="Rolename" runat="server" />     <asp:button Text="Delete Role" OnClick="DeleteRole_Click"                 runat="server"/>   </form>   <font color="red" size="6">   <asp:Label id="StatusCheck" runat="server"/>   </font>   </body> </html> 

The code above lists all the available roles by binding the result of Roles.GetAllRoles() to a DataGrid . It then allows for a specific role to be named and deleted using the Roles.DeleteRole() method.

Figure 6.13 is a screen capture of this page.

Figure 6.13. Deleting roles

graphics/06fig13.gif

Role Manager uses a provider to write back to and read from a data store in which the roles and user-to-role mapping is done. Rather than reading/writing to this database on each requestsince a list of the roles the user belongs to must be obtaineda cookie can optionally be used to cache roles, as described in the next subsection.

Role Caching

Role caching is a feature of Role Manager that enables user-to-role mappings to be performed without requiring a lookup to the data store on each request . [19] Instead of looking up the user-to-role mapping in the data store, the roles the user belongs to are stored, encrypted, within an HTTP cookie. If the user does not have the cookie, a request is made against the provider to retrieve the roles the user belongs to. The roles are then encrypted and stored within a cookie. On subsequent requests the cookie is decrypted and the roles obtained from the cookie.

[19] This is a similar implementation to what is done within all the ASP.NET Starter Kits.

Internally, in cases where there are more roles than can fit in the cookie, the cookie is marked as an incremental role cookie. That is, the cookie stores as many roles as possible but likely not all the roles. When role checking is performed, and the user is not in one of the roles being checked for, ASP.NET will call the Roles API and check whether the user belongs to that role. If not, access is denied. If the user is in the role and the role is not currently stored in the cookie, the last role stored within the cookie is removed and the requested role is added. Thereby, in cases where the user has more roles than can fit in the cookie, the cookie over time will contain a list of the most frequently accessed roles.



A First Look at ASP. NET v. 2.0 2003
A First Look at ASP. NET v. 2.0 2003
ISBN: N/A
EAN: N/A
Year: 2004
Pages: 90

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net