Building Secure ASP.NET Applications: Authentication, Authorization, and Secure Communication

How To: Use Role-based Security with Enterprise Services in .NET 1.1

J.D. Meier, Alex Mackman, Michael Dunner, and Srinath Vasireddy
Microsoft Corporation

Published: November 2002

Last Revised: January 2006

Applies to:

• Enterprise Services (Microsoft® .NET Framework 1.1)

See the "patterns & practices Security Guidance for Applications Index" for links to additional security resources.

See the Landing Page for a starting point and complete overview of Building Secure ASP.NET Applications.

Summary: Enterprise Services (COM+) provides roles for authorization purposes. This How To shows you how to create and configure a serviced component for method-level role-based security. (7 printed pages)

Contents

Notes
Summary of Steps Step 1. Create a C# Class Library Application to Host the Serviced Component Step 2. Create the Serviced Component Step 3. Configure the Serviced Component Step 4. Generate a Strong Name for the Assembly Step 5. Build the Assembly and Add it to the Global Assembly Cache Step 6. Manually Register the Serviced Component Step 7. Examine the Configured Application Step 8. Create a Test Client Application

This How To describes how to create a simple serviced component that uses Enterprise Services (ES) roles for authorization.

Notes

• ES roles are not the same as .NET roles.
• ES roles can contain Windows group or Windows user accounts.
• ES roles are maintained in the COM+ catalog.
• ES roles can be applied at the (ES) application, interface, class or method levels.
• ES roles can be partially configured declaratively by using .NET attributes in the serviced component's assembly.
• Windows group and user accounts must be added by an administrator at deployment time.
• Administrators can use the Component Services administration tool, or script.
• To effectively use Enterprise Services role-based security from an ASP.NET Web application, the Web application must use Windows authentication and impersonate callers prior to calling the serviced components.

Summary of Steps

This How To includes the following steps:

• Step 1. Create a C# Class Library Application to Host the Serviced Component
• Step 2. Create the Serviced Component
• Step 3. Configure the Serviced Component
• Step 4. Generate a Strong Name for the Assembly
• Step 5. Build the Assembly and Add it to the Global Assembly Cache
• Step 6. Manually Register the Serviced Component
• Step 7. Examine the Configured Application
• Step 8. Create a Test Client Application

Step 1. Create a C# Class Library Application to Host the Serviced Component

This procedure creates a new C# class library application that contains the serviced component.

To create a C# class library application to host the serviced component

1. Start Visual Studio .NET and create a new C# class library application called ServicedCom.
2. Rename the default class file Class1.cs to SimpleComponent.cs.
3. Double-click SimpleComponent.cs to open it and rename the Class1 type as SimpleComponent. Also update the name of the class' default constructor.

Step 2. Create the Serviced Component

This procedure derives the SimpleComponent class from the EnterpriseServices.ServicedComponent class to turn this type into a serviced component. You will then create an interface and implement it within the SimpleComponent class. To use interface and method level security, you must define and implement interfaces.

To create the serviced component

1. Add a reference to the System.EnterpriseServices assembly.

2. Add the following using statement to the top of the SimpleComponent.cs file beneath the existing using statements.

   using System.EnterpriseServices;
   

3. Derive the SimpleComponent class from ServicedComponent.

   public class SimpleComponent : ServicedComponent
   

4. Add the following interface definition within the ServicedCom namespace.

   public interface ISomeInterface
   {
     int Add( int operand1, int operand2 );
   }
   

5. Derive SimpleComponent from this interface.

   public class SimpleComponent : ServicedComponent, ISomeInterface
   

6. Implement the interface within the SimpleComponent class as follows.

   public int Add( int operand1, int operand2 )
   {
       return operand1 + operand2;
   }
   

Step 3. Configure the Serviced Component

This procedure configures the serviced component for method-level role-based security.

To configure the serviced component

1. Add the following attributes directly above the SimpleComponent class. The ComponentAccessControl attribute enables component-level access checks and the SecureMethod attribute enables method level access checks.

    [ComponentAccessControl]
   [SecureMethod]
   public class SimpleComponent : ServicedComponent, ISomeInterface
   

2. Add the following attribute above the Add method to create the Manager role and associate it with the method.

    [SecurityRole("Manager")]
   public int Add( int operand1, int operand2 )
   {
     return operand1 + operand2;
   }
   

3. Open assemblyinfo.cs and add the following using statement to the top of the file below the existing using statements.

   using System.EnterpriseServices;
   

4. Move to the bottom of the file and add the following attributes. These are used to configure the Enterprise Services application used to host the serviced component.

   // Configure the application as a server (out-of-process) 
     application
   [assembly: ApplicationActivation(ActivationOption.Server)]
   // For meaningful role-based security, enable access checking at the 
     process 
   // and component levels by using the following .NET attribute.
   [assembly: ApplicationAccessControl(AccessChecksLevel= 
                        AccessChecksLevelOption.ApplicationComponent)]
   // Set the name and description for the application
   [assembly: ApplicationName("SimpleRoles")]
   [assembly: Description("Simple application to show ES Roles")]
   // Add some additional roles
   [assembly:SecurityRole("Employee")]
   [assembly:SecurityRole("Senior Manager")]
   

Step 4. Generate a Strong Name for the Assembly

Assemblies that host serviced components must be strong named. This procedure generates a public-private key pair used to strong name the assembly.

To generate a strong name for the assembly

1. Open a command window and go to the current project directory.

2. Use the sn.exe utility to generate a key file that contains a public-private key pair.

   sn.exe -k SimpleComponent.snk
   

3. In Visual Studio, open assemblyinfo.cs.

4. Locate the [AssemblyKeyFile] attribute and modify it to reference the key file in the project directory as follows.

    [assembly: AssemblyKeyFile(@"..\..\SimpleComponent.snk")]
   

Step 5. Build the Assembly and Add it to the Global Assembly Cache

This procedure builds the assembly that contains the serviced component and then adds it to the global assembly cache. Serviced components should generally be registered in the global assembly cache because they are system level resources. Serviced components hosted in COM+ server applications require installation in the global assembly cache, while library applications do not (although it is recommended).

To build the assembly and add it to the global assembly cache

1. On the Build menu, click BuildSolution.

2. Return to the command window and run the following command to add the assembly to the global assembly cache.

   gacutil–i bin\debug\ServicedCom.dll
   

Step 6. Manually Register the Serviced Component

Serviced components can either be manually registered with the Regsvcs.exe tool, or they can be automatically registered using "lazy" registration. With "lazy" registration, the component is registered (and the hosting COM+ application created and configured using the assembly's meta data) the first time an instance of the serviced component is instantiated.

To avoid the one time performance hit associated with this approach, this procedure manually registers the serviced component.

To manually register the serviced component

1. Return to the command window.

2. Run regsvcs.exe to register the component.

   regsvcs bin\debug\ServicedCom.dll
   

Step 7. Examine the Configured Application

This procedure uses the Component Services tool and examines the catalog settings created as a result of the .NET attributes used earlier.

To examine the configured application

1. From the Administrative Tools program group, start Component Services.
2. Expand ComponentServices, Computers, MyComputer, and COM+ Applications.
3. Right-click SimpleRoles, and then click Properties.
4. Click the Security tab and make sure that Enforce access checks for this application is selected and that the security level is set to perform access checks at the process and component level. This configuration is a result of the .NET attributes used earlier.
5. Click OK to close the Properties dialog box.
6. Expand the SimpleRoles application, and then expand the Components folder and the ServicedCom.SimpleComponent class.
7. Navigate to the Add method beneath the ISomeInterface method in the Interfaces folder.
8. Right-click Add, and then click Properties.
9. Click the Security tab and notice that the Manager role is associated with the method.
10. Click OK to close the Properties dialog box.
11. Expand the Roles folder beneath the SimpleRoles application. Notice the roles that you created earlier with .NET attributes. Also notice the Marshaler role. This is created as a direct result of the [SecureMethod] attribute added earlier, and is required for method level security.

Step 8. Create a Test Client Application

This procedure creates a Windows Forms-based test client application to instantiate and call the serviced component.

To create a test client application

1. Add a new C# Windows-based application called TestClient to the current solution.

2. Add a new project reference to the ServicedCom project.

   1. In Solution Explorer, right-click References, and then click Add Reference.
   2. Click the Projects tab.
   3. Select ServicedCom, click Select, and then click OK.

3. Add a reference to System.EnterpriseServices.

4. Add a button to the application's main form.

5. Double-click the button to create a button click event handler.

6. Add the following using statement to the top of the form1.cs beneath the existing using statements.

   using ServicedCom;
   

7. Return to the button click event handler and add the following code to instantiate and call the serviced component.

   SimpleComponent comp = new SimpleComponent();
   MessageBox.Show( "Result is: " + comp.Add(1, 2));
   

8. On the Build menu, click BuildSolution.

9. In Solution Explorer, right-click the TestClient project, and then click Set as StartUp Project.

10. Press Ctrl+F5 to run the TestClient application.

    You should see that an unhandled exception is generated.

11. Click the Details button on the message box to view the exception details.

    You will see that a System.UnauthorizedAccessException has been generated. This is because your interactive logon account used to run the TestClient application is not a member of the Manager role, which is required to call the Add on the serviced component.

12. Click Quit to stop the application.

13. Return to Component Services and add your current (interactive) account to the Manager role and the Marshaler role.

    Note   The Enterprise Services infrastructure uses a number of system-level interfaces that are exposed by all serviced components. These include IManagedObject, IDisposable, and IServiceComponentInfo. If access checks are enabled at the interface or method levels, the Enterprise Services infrastructure is denied access to these interfaces.

    As a result, Enterprise Services creates a special role called Marshaler and associates the role with these interfaces. At deployment time, application administrators need to add all users to the Marshaler role who needs to access any methods or interface of the class. You could automate this in two different ways:

    1. Write a script that uses the Component Services object model to copy all users from other roles to the Marshaler role.

    2. Write a script which assigns all other roles to these three special interfaces and delete the Marshaler role.

14. Close the SimpleRoles application to enable the changes to take effect. To do this, right-click the application name, and then click Shut down.

15. Return to Visual Studio .NET and press Ctrl+F5 to run the TestClient application again.

16. Click the form's button and confirm that the method is successfully called.

© Microsoft Corporation. All rights reserved.