COM+ Role-Based Security Sample

COM+ Role-Based Security Sample

     (Windows Forms Application)

This document contains the release information for the .NET Framework COM+ Role-Based Security sample. You will find the following sections below:

Overview

This sample demonstrates some aspects of COM+ Role-Based Security in a .NET Framework application. The sample code accesses security-related methods on the ContextUtil class to retrieve run-time information about the security environment. The sample also calls into a SecurityCallContext object in order to retrieve the account information of the current caller.

Information retrieved by the sample application includes: 1) whether COM+ security is enabled, 2) whether the current caller is a member of a security role created by the sample, and 3) the account name of the current caller.

The sample also demonstrates how to enable security at the application or component level and create security roles by means of attributes.

NOTE: COM+ Security interoperability in .NET is provided for application developers who might wish to write managed code that extends an existing application which uses COM+ 1.0 security services. .NET provides its own role-based security. This mechanism and that provided by COM+ are independent and only one should be used within a single application.

Topics

The following bullets briefly describe the technologies used by this sample.

Location

This sample is located in the Technologies\ComponentServices\RoleBasedSecurity subdirectory of the .NET Framework SDK samples directory.

For Example:

C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\RoleBasedSecurity

Building the Sample

In order to properly build and run this sample, the following steps need to be performed.

Type BuildAll.bat from the command line.

For Example:

C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\RoleBasedSecurity>buildall.bat

If you're building the sample from Visual Studio 7, you will need to install the OCDemoSvr.dll assembly to the Global Assembly Cache before running the sample. Note: The gacutil.exe program is located in the SDK\v1.1\Bin directory.

For Example:

C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\RoleBasedSecurity\CS>gacutil -i RBSecDemoSvr.dll

The sample builds a C# and VB version of the client application and COM+ component. Source code for each language is stored in subdirectories named \CS and \VB. The C# component has 'CS' appended to its name as viewed in the Component Services administrative tool, 'RBSecDemoServerCS.RBSecurityObject'. The VB version is named 'RBSecDemoServerVB.RBSecurityObject'. When working with the sample code, be sure to observe and/or modify the version of the COM+ component that corresponds to the client application you launch.

Review comments in the source code and build.bat files for more information on sample binary creation and registration steps.

Running the Sample

In order to run this sample, follow the instructions listed below.

  • NOTE: The COM+ .NET samples require Windows 2000 or higher in order to build and run.
  • Build the Role-Based Security sample code following the instructions above.
  • Type RBSecDemo.exe from the command line.

    For Example:

    C:\Program Files\Microsoft.NET\SDK\v1.1\Samples\Technologies\ComponentServices\RoleBasedSecurity\CS>rbsecdemo.exe

  • Click the button labeled 'Display Logged On User'. The current logged on user account name should appear in the application window.
  • Click the button labeled 'Is Caller in Demo Role?'. The message 'You ARE in RBSecurityDemoRole' should appear.
  • Launch the Component Services administrative tool (also called the 'COM+ explorer'), by clicking 'Start\Settings\Control Panel' then double-clicking 'Administrative Tools\Component Services'. Locate the RBSecDemoSvr COM+ application by expanding Component Services\Computers\My Computer\COM+ Applications in the left-hand COM+ explorer pane.
  • Next, right-click the RBSecDemoSvr application and select 'Properties'. This will invoke the Properties dialog for the application.
  • Click the 'Security' tab. The information here corresponds to the settings specified by means of the ApplicationAccessControl attribute. Uncheck the 'Enforce access checks for this application' checkbox. IMPORTANT: this will disable COM+ security for all components contained in the application. Click 'OK' to dismiss the properties dialog.
  • Return to the RBSecDemo client application. Click 'Display Logged On User'. The message 'Unknown caller (Security is not enabled)' should appear. Click 'Is Caller In Demo Role?'. The client still reports that the user is in the RBSecurityDemoRole. This is because when security is disabled, all calls into ContextUtil::IsCallerInRole return true.
  • Return to the COM+ explorer and invoke the RBSecDemoSvr properties page once more by right-clicking the application and selecting 'Properties'. Click the tab labeled 'Security' and recheck the 'Enforce access checks for this application' checkbox. Security is enabled again for the application. Click 'OK' to dismiss the properties dialog.
  • Locate the RBSecDemoServerCS.RBSecurityObject or RBSecDemoServerVB.RBSecurityObject component by expanding 'RBSecDemoSvr\Components'. Right-click the 'RBSecDemoServerCS.RBSecurityObject' or 'RBSecDemoServerVB.RBSecurityObject' component and select 'Properties' from the popup menu.
  • Click the 'Security' tab. The Authorization setting here corresponds to the ComponentAccessControl attribute specified in the sample code. You should see a role labeled 'RBSecurityDemoRole' listed as a role explicitly associated with the component. This role was created and bound to the sample component by means of the SecurityRole attribute in the sample code. Click 'OK' to dismiss the properties dialog.
  • In the COM+ explorer, expand the Roles folder located beneath the RBSecDemoSvr application. You should see the RBSecurityDemoRole here. Expand RBSecurityDemoRole/Users. You should see a single account ('Everyone') in the Users folder. Right-click 'Everyone' and select 'Delete' from the pop-up menu. Confirm the delete in the subsequent dialog.
  • COM+ caches security settings related to roles, so we must shut down the RBSecDemoSvr application before we can observe the results of making the change above. In the COM+ explorer, right-click the application and select 'Shut down' from the pop-up menu.
  • Now return to the RBSecDemo client application. On clicking either button, you should see a MessageBox reporting that 'Access is denied'. An access denied security exception was thrown on object creation because the component RBSecurityDemoRole does not contain the current caller.

Uninstalling the Sample

In order to uninstall this sample, follow the instructions listed below.

  • To uninstall this sample, run buildall.bat -u. or build.bat -u. The batch file will then call regsvcs and gacutil with the /u switch in order to remove the sample files from the COM+ catalog and Global Assembly Cache.

Notes

For the .Net Framework samples to function properly, your Path, Include, and Lib environment variables must be set correctly. In many cases, the SDK install program updates these environment variables for you. However, if you installed the .Net Framework SDK using Visual Studio .NET, or unselected "register environment variables" during setup, these environment variables will not be updated. You can set the Path, Include and Lib environment variables by running SDKVars.bat, located in the <SDKRoot>\Bin directory. SDKVars.bat must be executed in every command shell.