Share via

Installing the Protected Document Library Sample

  • Article

The Active Directory Rights Management Services (AD RMS) SDK comes with a sample Web application: a secure document store. The folders and files that are used by the sample are described in the following table. All items are located inside the folder InstallationPath\Samples\Source\Rmhstore\. The sample application must be installed on a computer running Windows Server 2003. It does not require AD RMS; however, it must have access to a computer running AD RMS.

Folder or file Description
cdoclib\ Contains a C++ project that creates a DLL called Cdoclib.dll. This DLL handles creation and management of the container files that hold encrypted content and publishing or use licenses.
rmhstore\ Contains a C# project that creates the class to control the document store (RmhStore), the class that controls the whole application (Rmhdocs), and various helper methods to be used by the sample.
rmssrv\ Contains a C# project providing various functions, including cryptography and proxy wrapper references.
SvcRmhstore\ Contains a C# project that creates the document store Web server. It is a Web service that exposes publishing and prelicensing operations and also contains the user interface for the sample.
RmhStore.sln Contains a Visual Studio 2005 solution for the sample code.

To install the project

  1. Ensure that the sample has access to an existing AD RMS service, or install a new AD RMS service. The documentation that is included with AD RMS explains how to set up an AD RMS service. Be sure that your AD RMS service is enrolled in the Production key hierarchy. For more information about downloading and installing an AD RMS service, see Microsoft Windows Rights Management Services.

  2. Install the AD RMS client on any computers that will browse to and run the sample application, if it is not already installed. The sample application must be installed on a computer running Windows Server 2003. For more information about downloading and installing the AD RMS client, see Windows Rights Management Client.

  3. Install the Rights Management Add-on for Internet Explorer on any computers that will browse to and run the sample application, if it is not already installed.

  4. Open Internet Information Services (IIS) Manager. Create a new virtual directory and assign it a name. Point the new virtual directory to the Samples\ folder that was installed with the SDK. Read and run permissions are fine.

  5. Modify InstallationPath\Samples\Web.config. The settings inside the <StoreConfiguration> tags specify the physical location of the document store; the settings inside the <RMSServerConfiguration> tags specify the URL of the licensing AD RMS service you plan to use. You should modify these values to suit your own server setup. You can add or remove stores; you are only required to have one.

    In the following example, you must replace C:\SampleDocumentLibrary and https://localhost/_wmcs/licensing with values that match your server configuration.

    ...
<RmhDocLib>
     <StoreConfiguration
         <add key="SampleDocumentLibrary" value="C:\SampleDocumentLibrary" />
     </StoreConfiguration>
     <RMSServerConfiguration>
         <add key="SampleDocumentLibrary" value="https://localhost/_wmcs/licensing" />
     </RMSServerConfiguration>
 </RmhDocLib> 
...

  6. Add access control list (ACL) entries to the folder that holds your document library, to specify which users are allowed what rights to stored documents.

    To add ACL entries to your document library

    1. Use Windows Explorer to navigate to the physical location of the document store folder (C:\SampleDocumentLibrary in the example from step 5).
    2. Right-click the document library folder, and click Properties.
    3. Click the Security tab, and then click Add.
    4. Add the e-mail address or security identifier (SID) of specific users to whom to grant rights.
    5. Select the check boxes for the rights you want to grant to a user. The sample application grants only two classes of rights: rights that allow users to view content, and rights that allow users full control of content. To see which ACL rights map to which document rights, see StoreRights, Dacl, Ace, Sid, Right, and User Classes.

  7. Change the ACL of the EditIssuanceLicense.asmx file on the AD RMS service to allow you full access to this function.

    To edit this ACL

    1. Use Windows Explorer to navigate to the physical location of the EditIssuanceLicense.asmx file that is under the AD RMS Internet virtual directory on your server computer.

    2. Right-click the EditIssuanceLicense.asmx file, and click Properties.

    3. Click the Security tab, and then click Add.

    4. Add the identity that your sample application runs as. To determine this identity, follow the steps given at the end of this topic.

    5. Add "RMSHostMachineName\RMS Service Group" to the ACL of the EditIssuanceLicense.asmx page, granting it the default rights. RMSHostMachineName is the name of the computer that is hosting the EditIssuanceLicense.asmx page.

      Important  It is very important to understand that only approved computers or (occasionally) users should have access to EditIssuanceLicense because anyone with access to this function can gain full rights to any license issued by this service that has the "Allow_Server_Editing"/"True" pair.

  8. If you are using the sample application with an AD RMS account certification service that is not registered in Active Directory, you must add the following string value to the registry of the computer that will browse to the document library.

    HKEY_LOCAL_MACHINE
         SOFTWARE
              Microsoft
                   RMA
                        Certification
                             WindowsAuthProvider
                                  ServiceLocation = AccountCertificationURL

    This value contains the URL of the account certification service page of the AD RMS server that the document store sample will use. This URL will be something like https://ServerName/_wmcs/certification. This value forces the Rights Management Add-on for Internet Explorer to activate the current user using the AD RMS server that the sample application uses. If you are using the AD RMS account certification service registered in Active Directory, you do not need to add this registry value.

    Note  The AD RMS service that is used must be registered in the Production key hierarchy, not the Pre-production key hierarchy.

To determine the identity that your sample application runs as

  1. Open IIS Manager on the computer that is hosting the sample application, right-click the virtual root you created for the sample application, and then click Properties.
  2. On the Virtual Directory tab, note the application pool name listed in the Application pool drop-down box.
  3. In IIS Manager, expand the Application Pools branch, right-click the application pool that you noted in step 2, and then click Properties.
  4. In the Properties dialog box, click the Identity tab.
  5. Note the name selected as the application pool identity. This is the one you should add to the EditIssuanceLicense.asmx ACL list.

For information about how to run the sample application, see Running the Protected Document Library Sample.

See Also

Protected Document Library Sample

Send comments about this topic to Microsoft

Build date: 3/13/2008