Using Windows PowerShell with AD RMS... 7 About this guide... 7 In this guide... 7

Transcription

1 Contents Using Windows PowerShell with AD RMS... 7 About this guide... 7 In this guide... 7 Using Windows PowerShell to Deploy AD RMS... 8 Getting started Understanding the AD RMS Deployment Provider Namespace AD RMS Deployment Cmdlets Installing an AD RMS Cluster Creating an AD RMS Cluster Windows PowerShell Drive Setting Properties on Objects in the AD RMS Drive Namespace Setting the configuration database Specifying the Windows Internal Database Specifying a Remote Database Setting the service account Setting the cluster key storage Using a centrally managed cluster key Using a CSP to store the cluster key Setting the cluster Web site Setting the cluster address Setting the SLC name Registering the SCP Running the Install-ADRMS Cmdlet Joining an Existing Cluster Creating an AD RMS Server Windows PowerShell Drive

2 Setting Properties on Objects in the AD RMS Drive Namespace Setting the database server Setting the database name Setting the cluster key password Setting the service account Setting the cluster Web site Running the Install-ADRMS Cmdlet Adding or Removing Federated Identity Support Adding federated identity support Removing federated identity support Upgrading the AD RMS Server Role Removing the AD RMS Server Role Getting started Understanding the AD RMS Administration Provider Namespace AD RMS Administration Cmdlets Installing Microsoft Federation Gateway Support Adding Microsoft Federation Gateway Support Enrolling with the Microsoft Federation Gateway Configuring AD RMS Cluster Properties Changing the Intranet Licensing URL Adding an Extranet Cluster URL

3 Changing AD RMS Proxy Settings Registering a Service Connection Point Administering Certificates Exporting the Server Licensor Certificate Specifying the Rights Account Certificate Validity Duration Changing the Server Licensor Certificate Name Enabling Exclusion Policies Excluding Users Excluding Applications Excluding Lockboxes Establishing Trust Policies Configuring Federated Identity Support Settings Adding a Trusted User Domain Exporting a Trusted User Domain Adding a Trusted Publishing Domain Exporting a Trusted Publishing Domain Using Windows Live ID to Establish RACs for Users... 66

4 Configuring Microsoft Federation Gateway Support Updating a Microsoft Federation Gateway Support Certificate Granting the AD RMS Service Group Permission to the SSL Certificate Setting the Microsoft Federation Gateway RAC Validity Period Managing the Microsoft Federation Gateway Licensing Filter List Managing the Microsoft Federation Gateway Publishing Filter List Terminating the Federation Relationship Removing Microsoft Federation Gateway Support Managing AD RMS Databases Turning on or Turning off Logging Configuring Accounts Setting up a Super Users Group Resetting the AD RMS Cluster Key Password Changing the AD RMS Service Account Specifying the Administrative Contact Configuring Rights Policy Templates Specifying the Location of Rights Policy Templates... 79

5 Creating a New Rights Policy Template Editing a Rights Policy Template Modifying all settings with a single command Modifying individual settings Viewing a Summary of User Rights for a Rights Policy Template Archiving a Rights Policy Template Deleting a Rights Policy Template Adding a New Language to a Rights Policy Template Restoring a Rights Policy Template Copying a Rights Policy Template Working with Reports Creating a System Health Report Creating a User Request Report Creating a User Request Information Report Creating a Certificate Chain Report Creating a Certificate Information Report Creating a Child Certificate Report Creating an Issuance License Report

6 Exporting Report Definition Language Files Decommissioning AD RMS

7 Using Windows PowerShell with AD RMS Active Directory Rights Management Services (AD RMS) for the Windows Server 2008 R2 operating system is information protection technology that works with AD RMS-enabled applications to help safeguard digital information from unauthorized use, both online and offline, and inside and outside of the firewall. In addition to such graphical user interface (GUI) tools as an installation wizard, a server-role page in Server Manager, and the AD RMS snap-in for Microsoft Management Console (MMC), you can use Windows PowerShell cmdlets to install, configure, and administer AD RMS. This guide provides information about using Windows PowerShell cmdlets to perform these tasks with AD RMS. About this guide This guide explains how to use the Windows PowerShell cmdlets that enable you to install, configure, and administer the AD RMS server role on a computer running Windows Server 2008 R2. It introduces the Windows PowerShell modules that implement AD RMS-specific cmdlets, describes the namespace that these cmdlets work in, and also shows how to use general-purpose cmdlets, such as Set-Itemproperty, to manipulate items in these namespaces that represent AD RMS settings. AD RMS cmdlets are implemented by two Windows PowerShell modules: The AD RMS deployment Windows PowerShell module (AdRmsInstall) and the AD RMS administrative Windows PowerShell module (AdRmsAdmin). To access cmdlets implemented by these modules, you must import their corresponding modules. To import the deployment module, at a Windows PowerShell prompt, type Import-Module AdRms. To import the administration module, type Import-Module AdRmsAdmin. You can also import these modules by importing all available Windows PowerShell modules. This document does not provide overview or introductory information about AD RMS or Windows PowerShell. To use this document, you should have enough experience with AD RMS that you can install, configure, and administer it by using GUI tools. You should also have basic experience running Windows PowerShell cmdlets. For general information about AD RMS, see the AD RMS TechCenter( For information about Windows PowerShell, see Scripting with Windows PowerShell( In this guide Using Windows PowerShell to Deploy AD RMS 7

8 Using Windows PowerShell to Deploy AD RMS The Active Directory Rights Management Services (AD RMS) Windows PowerShell deployment module gives you the ability to install and provision the AD RMS server role on a computer running Windows Server 2008 R2, to upgrade a server in an AD RMS cluster following a Windows upgrade, and to remove the AD RMS server role, all by using Windows PowerShell cmdlets. The module presents a drive namespace that consists of containers representing configuration settings you must make before installing the server role. Within this namespace, you manage cluster settings by creating and setting properties on items in the containers that are arranged hierarchically in the namespace, most often by using common Windows PowerShell cmdlets, such as New-Item and Set-ItemProperty. In some cases, the AD RMS Windows PowerShell deployment module implements special-purpose cmdlets to perform tasks that cannot be performed by using common cmdlets. Note To deploy AD RMS by using a Windows PowerShell session on a remote computer, you must enable the Credential Security Service Provider (CredSSP) and then specify - Authentication Credssp when creating the remote session. Note, however, that this practice increases the security risk of the remote operation because, if the remote computer is compromised, the credentials that are passed to it can be used to control the network session. For more information, type Get-Help Enable-WSManCredSSP -Full at a Windows PowerShell prompt. Getting started Before you can deploy AD RMS by using Windows PowerShell cmdlets, after starting Windows PowerShell, you must perform two tasks: 1. Import the AD RMS Windows PowerShell deployment cmdlet module. 2. Create a Windows PowerShell drive that represents the AD RMS cluster you want to create or join. The following procedures explain how to perform each of these tasks. Import the module At the Windows PowerShell prompt, type: Import-Module ADRMS Create the drive At the Windows PowerShell prompt, type: New-PSDrive -Name <drivename> -PsProvider AdRmsInstall -Root <installtype> 8

9 where <drivename> is the name you want to assign to the new drive, and <installtype> is the type of installation you want to perform: RootCluster installs the AD RMS server role as the first server in a root cluster. LicensingCluster installs the AD RMS server role as the first server in a licensingonly cluster. JoinCluster installs the AD RMS server role as a member server in an existing root or licensing-only cluster. For example, to create a drive named RC that represents the first server in a root cluster, type: New-PSDrive -Name RC -PsProvider AdRmsInstall -Root RootCluster Understanding the AD RMS Deployment Provider Namespace AD RMS Deployment Cmdlets Installing an AD RMS Cluster Joining an Existing Cluster Adding or Removing Federated Identity Support Upgrading the AD RMS Server Role Removing the AD RMS Server Role Understanding the AD RMS Deployment Provider Namespace The Active Directory Rights Management Services (AD RMS) Windows PowerShell deployment provider exposes a namespace that represents the various configuration settings that you can make to a server before installing AD RMS. You configure these settings by using Windows PowerShell cmdlets to traverse this namespace and then creating or deleting items in the namespace, or setting properties on those items. The namespace consists of a Windows PowerShell drive, which holds a root container and a number of additional subcontainers, depending on the type of drive representing the role the new server will play in an AD RMS cluster. For information about creating an AD RMS Windows PowerShell deployment provider drive, see Using Windows PowerShell to Deploy AD RMS. This topic lists the containers in the deployment namespace, explains what configuration settings each container represents, and lists the subcontainers or items that it can hold. <drive>:\ The root container of the deployment namespace represents the general properties of the server itself. You can work with these properties by using the Get-ItemProperty and Set-ItemProperty cmdlets to view and change the following properties for drives 9

10 that represent the first server in a cluster: ServiceAccount ClusterURL SLCName RegisterSCP (root cluster only) If <drive> represents a server that is being joined to an existing cluster, only the ServiceAccount property is available. <drive>:\adfssupport This container is not used in this version. Do not change any of the properties of this container. <drive>:\clusterdatabase This container represents the type and location of the cluster database used by the AD RMS cluster being created or joined. If <drive> represents the first server in a root or licensing cluster, use the Set-ItemProperty cmdlet to set the UseWindowsInternalDB, ServerName, and InstanceName properties to specify the location of the cluster database. If <drive> represents a server being joined to an existing cluster, you also set the DatabaseName property. <drive>:\clusterdatabase\databaseinstance This container holds items or containers representing the database instances hosted by the database server specified by the ServerName property of the parent container. If <drive> represents the first server in a cluster, this container holds items whose names are the names of database instances hosted by the server. You can use the name of one of these items to set the InstanceName property of the parent container. If <drive> represents a server that is being joined to an existing cluster, this container holds subcontainers that in turn hold items representing the databases hosted by those instances. <drive>:\clusterdatabase\databaseinstance\<instancename> If <drive> represents the first server in a cluster, this is an item representing an instance hosted by the database server. If <drive> represents a server being joined to an existing cluster, this is a container that holds items representing databases hosted by a database instance on the database server. You can use the name of one of these items to set the DatabaseName property of the \ClusterDatabase container. 10

11 <drive>:\clusterkey This container represents the AD RMS cluster key protection policy and holds a subcontainer that in turn holds subcontainers that represent the available cryptographic service providers (CSPs). If <drive> represents the first server in a cluster, you can use the Set-ItemProperty cmdlet to set the UseCentrallyManaged property of this container. If you set UseCentrallyManaged to TRUE (the default), you must also set the CentrallyManagedPassword property; if you set UseCentrallyManaged to FALSE, you must also set the CreateNewKeyPair property, or the UseExistingKeyPair and CSPName properties. Enumerate the contents of the CSP subcontainer to obtain the names of available CSPs. <drive>:\clusterkey\csp This container holds subcontainers that represent the available CSPs. This container has no properties. <drive>:\clusterkey\csp\<cspname> This container holds items that represent the key containers in the CSP identified by <CSPName>. <drive>:\clusterwebsite This container holds items representing the Web sites that the server hosts. You can use the Set-ItemProperty cmdlet to set the container s WebSiteName property to specify the cluster Web site name. Using Windows PowerShell to Deploy AD RMS AD RMS Deployment Cmdlets Installing an AD RMS Cluster Joining an Existing Cluster Adding or Removing Federated Identity Support Upgrading the AD RMS Server Role Removing the AD RMS Server Role 11

12 AD RMS Deployment Cmdlets The Active Directory Rights Management Services (AD RMS) Windows PowerShell deployment Windows PowerShell module gives you the ability to install, upgrade, or remove an AD RMS cluster by using Windows PowerShell cmdlets. The following describes these cmdlets. Install-ADRMS This cmdlet installs the Active Directory Rights Management Services (AD RMS) server role and, if necessary, any features required by AD RMS. Before running this cmdlet, prepare the server by setting properties on containers in the deployment provider namespace. You can also use this cmdlet to install federated identity support on an existing cluster. Uninstall-ADRMS This cmdlet removes the AD RMS server role. You can also use this cmdlet to remove identity federation support from a cluster. Update-ADRMS This cmdlet upgrades the AD RMS server role following an upgrade of the operating system to Windows Server 2008 R2. You can use the WhatIf parameter to view the actions that would be taken by the cmdlet without changing the system. For complete information about these cmdlets, see AD RMS Cmdlets in Windows PowerShell ( Using Windows PowerShell to Deploy AD RMS Understanding the AD RMS Deployment Provider Namespace Installing an AD RMS Cluster Joining an Existing Cluster Adding or Removing Federated Identity Support Upgrading the AD RMS Server Role Removing the AD RMS Server Role 12

13 Installing an AD RMS Cluster Before you can use Windows PowerShell cmdlets to install the Active Directory Rights Management Services (AD RMS) server role on a computer running Windows Server 2008 R2, you must start Windows PowerShell with administrator privileges after logging in with an account that meets the following requirements: The user account that you use to install AD RMS must not be the same account as the AD RMS service account. If you are registering the AD RMS service connection point (SCP) during installation, the user account that you use to install AD RMS must be a member of the Active Directory Domain Services (AD DS) Enterprise Admins group, or equivalent. If you are using an external database server for the AD RMS databases, the user account that you use to install AD RMS must have the right to create new databases. If Microsoft SQL Server 2005 or Microsoft SQL Server 2008 is used, the user account must be a member of the System Administrators database role, or equivalent. The user account that you use to install AD RMS must have access to query the AD DS domain, such as a domain user account. The user account that you use to install AD RMS must be a member of the Administrators group, or equivalent, on the server. Important You cannot use Windows PowerShell to install AD RMS with a Web site other than the default Web site. If you need to use a different Web site to host AD RMS, you must use Server Manager to install and configure AD RMS. Installing and provisioning the first server in an AD RMS cluster consists of the following steps: 1. Create the Windows PowerShell drive to represent the server you are provisioning. For more information, see Creating an AD RMS Cluster Windows PowerShell Drive. 2. Set properties on objects in the drive namespace that represent required configuration settings. For more information, see Setting Properties on Objects in the AD RMS Drive Namespace. 3. Run the Install-ADRMS cmdlet. In addition to installing the AD RMS server role and provisioning the server, this cmdlet also installs other features required by AD RMS, such as Message Queuing, if necessary. For more information, see Running the Install-ADRMS Cmdlet. Using Windows PowerShell to Deploy AD RMS Understanding the AD RMS Deployment Provider Namespace Pre-installation Information for Active Directory Rights Management Services 13

14 Creating an AD RMS Cluster Windows PowerShell Drive By creating an Active Directory Rights Management Services (AD RMS) deployment Windows PowerShell provider drive, you create a namespace that contains items that represent configuration settings of the server you are installing and provisioning. To create the Windows PowerShell drive At a Windows PowerShell prompt, type: Import-Module ADRMS New-PSDrive -PSProvider ADRMSInstall -Name <drive> -Root <cluster_type> where <drive> is the name of the Windows PowerShell drive you are creating, and <drive_type> is the type of cluster you are installing: RootCluster or LicensingCluster. For example, to create a Windows PowerShell drive named RC to install and provision the first server in an AD RMS root cluster, type: New-PSDrive -PSProvider ADRMSInstall -Name RC -Root RootCluster To create a Windows PowerShell drive named LC to install and provision the first server in an AD RMS licensing-only cluster, type: New-PSDrive -PSProvider ADRMSInstall -Name LC -Root LicensingCluster After creating the drive, do not exit the Windows PowerShell command prompt until you have finished installing the AD RMS server role. Doing so will delete the drive and all property settings will be lost. Installing an AD RMS Cluster Setting Properties on Objects in the AD RMS Drive Namespace Running the Install-ADRMS Cmdlet Setting Properties on Objects in the AD RMS Drive Namespace Setting properties on objects in the drive namespace is similar to using a wizard to specify configuration settings when installing a server role. Before you can finish the installation by running the Install-ADRMS cmdlet, you must provide necessary information about the initial configuration of the server role. The following table lists the required settings and the properties that represent those settings in the drive namespace. 14

15 Setting name Property name Location Configuration database UseWindowsInternalDatabase <drive>:\clusterdatabase Service account ServiceAccount <drive>:\ Cluster key storage UseCentrallyManaged or UseCSP <drive>:\clusterkey Cluster Web site WebSiteName <drive>:\clusterwebsite Cluster address ClusterURL <drive>:\ Server licensor certificate (SLC) name Register service connection point (SCP) SLCName RegisterSCP <drive>:\ <drive>:\ Notes The RegisterSCP property is available only when you are installing a root cluster. Depending on how you set these properties, additional property settings may be required. For example, if you set the UseWindowsInternalDatabase property to False, you must also specify the name of a remote database server and database instance. The following sections describe the configuration settings you must specify by setting properties on objects in the Windows PowerShell drive namespace. Setting the configuration database When installing the AD RMS server role on the first server in a cluster, you must specify the location of the database that will be used to store configuration and other data. You can choose to use the Windows Internal Database on the server, or you can designate a database instance on a remote database server. You must use a separate database server if you intend to add servers to the cluster or to add identity federation support. Specifying the Windows Internal Database By default, the first server in an AD RMS cluster uses the Windows Internal Database as its configuration database. You can use the following command to verify that the drive namespace is configured to use the Windows Internal Database: Get-ItemProperty -Path <drive>:\clusterdatabase -Name UseWindowsInternalDatabase If the UseWindowsInternalDatabase property is set to False, you can use the following procedure to configure the server to use the Windows Internal Database. Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. 15

16 To use the Windows Internal Database At the wps command prompt, type: Set-ItemProperty -Path <drive>:\clusterdatabase -Name UseWindowsInternalDatabase - Value $true Specifying a Remote Database You must use a database instance on a remote server if you plan to add servers to the cluster, or if you plan to use identity federation support. If you are using a named instance for the AD RMS configuration database, the SQL Server Browser service must be started on the database server before installing AD RMS. Otherwise, the AD RMS installation will not be able to locate the configuration database and the installation will not succeed. To perform this procedure, you must be logged on with a user account that is a member of the Administrators group of this server and that has the right to create a new database on the remote server. To use a remote database instance At the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\clusterdatabase -Name ServerName - Value <db_server> where <drive> is the name of the Windows PowerShell drive and <db_server> is the name of the remote server hosting the database. Unless you specify a named instance, the AD RMS server is configured to use the default database instance hosted by the specified server. If you want to use a named instance, use the following procedure to set the InstanceName property of the \ClusterDatabase container after setting the ServerName property. To use a named database instance 1. To enumerate the database instances hosted by the database server, at the Windows PowerShell command prompt, type: Get-ChildItem -Path <drive>:\clusterdatabase\databaseinstance where <drive> is the name of the Windows PowerShell drive. 2. To specify the database instance to be used by the cluster, at the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\clusterdatabase -Name InstanceName - Value <db_instance> where <drive> is the name of the Windows PowerShell drive and <db_instance> is the name of the database instance hosted by the remote database server. 16

17 Back to top Setting the service account During installation, AD RMS creates the AD RMS Service Group on the local computer and grants it appropriate permissions on all of the resources that are required for AD RMS to operate. When you install the AD RMS server role, you must define a domain account for use as the AD RMS service account. That account is made a member of the AD RMS Service Group, and it is granted the permissions that are associated with this group. During routine operations, AD RMS runs under the AD RMS service account. Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To set the AD RMS service account 1. At the Windows PowerShell command prompt, type: $svcacct = Get-Credential A dialog box appears. 2. In the dialog box, type the account domain and name (in the form <domain>\<account>) and password. 3. At the Windows PowerShell command prompt, type: Back to top Set-ItemProperty -Path <drive>:\ -Name ServiceAccount -Value $svcacct where <drive> is the name of the Windows PowerShell drive. Setting the cluster key storage You can protect the AD RMS cluster key by using a hardware- or software-based cryptographic service provider (CSP) or by storing the cluster key in the AD RMS configuration database. When using AD RMS to centrally manage the cluster key from the AD RMS configuration database, you should use a strong cluster key password. If you are upgrading from RMS to AD RMS and using a hardware-based CSP, ensure that the drivers are compatible with Windows Server 2008 R2 before proceeding with the upgrade. Note If there are multiple servers in the AD RMS cluster, and you are using either a softwareor hardware-based CSP to protect the cluster key, you must manually move the cluster key to the other computers before installing AD RMS. Consult the CSP documentation for procedures on moving the cluster key. 17

18 Using a centrally managed cluster key By default, the first server in an AD RMS cluster uses centrally managed key storage. However, if you choose to use this method to store the cluster key, you must provide a cluster key password before installing the AD RMS server role on the first server in the cluster. You can use the following command to verify that the drive namespace is configured to use the centrally managed cluster key storage: Get-ItemProperty -Path <drive>:\clusterkey -Name UseCentrallyManaged Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To set the centrally managed cluster key password 1. At the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\clusterkey -Name UseCentrallyManaged -Value $true where <drive> is the name of the Windows PowerShell drive. 2. To securely store the cluster key password in a variable, at the Windows PowerShell command prompt, type: $password = Read-Host -AsSecureString -Prompt Password: 3. Type the cluster key password, and then press the ENTER key. 4. At the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\clusterkey -Name CentrallyManagedPassword -Value $password where <drive> is the name of the Windows PowerShell drive. Using a CSP to store the cluster key When you configure the server to use a CSP to protect the cluster key, you must specify the key container name. You should also ensure that a new key pair will be created when the server is installed. To list the CSPs that are available on the server, at the Windows PowerShell command prompt, type: Get-ChildItem -Path <drive>:\clusterkey\csp -Name Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To specify a CSP to store the cluster key 1. To enable CSP key protection and specify the CSP to be used, at the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\clusterkey -Name UseCSP -Value $true Set-ItemProperty -Path <drive>:\clusterkey -Name CSPName -Value <CSP> where <drive> is the name of the Windows PowerShell drive and <CSP> is the name of 18

19 the CSP to be used to protect the store key. 2. Do one of the following: To ensure that a new key pair will be created for the CSP when AD RMS is installed, at the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\clusterkey -Name CreateNewKeyPair -Value $true To reuse an existing CSP key pair, at the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\clusterkey -Name UseExistingKeyPair -Value $true Set-ItemProperty -Path <drive>:\clusterkey -Name KeyContainerName - Value <KeyPairName> where <drive> is the name of the Windows PowerShell drive and <KeyPairName> is the name of a CSP key pair in the CSP container specified in the previous step. Back to top Setting the cluster Web site Before completing the installation of the AD RMS server role, you must specify the Web site where the AD RMS Web services will be installed if you are not using the default Web site. If you have installed the Internet Information Services (IIS) 6 Management Compatibility Service, you can get a listing of the Web sites hosted on the server by typing at a Windows PowerShell command prompt: Get-ChildItem -Path <drive>:\clusterwebsite where <drive> is the name of the Windows PowerShell drive. Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To specify the cluster Web site At the Windows PowerShell command prompt, type: Back to top Set-ItemProperty -Path <drive>:\clusterwebsite -Name WebSiteName -Value <web_site> where <drive> is the name of the Windows PowerShell drive and <web_site> is the name of the Web site to be used to host the AD RMS Web services. Setting the cluster address AD RMS clients use the cluster address to communicate with the cluster over the network. As a best security practice, you should specify an SSL-encrypted connection (that is, a connection that 19

20 uses as the AD RMS cluster address. If you specify an SSL-encrypted connection, you must configure the server with a valid certificate for SSL encryption. Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To specify the cluster address At the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\ -Name ClusterURL -Value http[s] ://<cluster_url>:<port> where <drive> is the name of the Windows PowerShell drive, <cluster_url> is the URL of the AD RMS cluster, and <port> is the number of the port used to access the cluster URL. For example, to set the property on a drive named RC to specify an unencrypted connection to a URL named Cluster1 on the default port, type: Set-ItemProperty -Path RC:\ -Name ClusterURL -Value To specify an encrypted connection to the same URL, type: Set-ItemProperty -Path RC:\ -Name ClusterURL -Value Back to top Setting the SLC name When the AD RMS server role is installed and configured on the first server in the cluster, AD RMS generates a unique SLC for itself called self-enrollment that establishes its identity and that has a validity time of 250 years. This enables the archiving of rights-protected data for an extended period of time. Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To specify the SLC name At the Windows PowerShell command prompt, type: Set-ItemProperty -Path <drive>:\ -Name SLCName -Value <SLC_name> where <drive> is the name of the Windows PowerShell drive and <SLC_Name> is the name you want to use to identify the SLC that will be created. Back to top Registering the SCP By default, the service connection point (SCP) for AD RMS is registered in Active Directory Domain Services when you install the AD RMS server role on the first server in a root cluster. The 20

21 SCP identifies the connection URL for the service to the AD RMS-enabled clients in your organization. After you register the SCP in Active Directory Domain Services (AD DS), clients will be able to discover the AD RMS cluster to request use licenses, publishing licenses, and rights account certificates (RACs). If you do not register the SCP when you install the first server in the root cluster, you can register the SCP from the cluster Properties sheet in the Active Directory Rights Management Services console. Note If you are registering an SCP from an AD RMS cluster in a child domain, you might receive an error stating that SCP registration failed. In many cases, the registration was successful, but the registration first takes place in the top-level domain and it takes time to replicate to the child domain where the AD RMS cluster checks for the SCP object. If this happens, allow enough time for the SCP to be replicated to all global catalog servers before attempting to re-register the SCP. To verify that the drive namespace is configured to register the SCP, at the Windows PowerShell command prompt, type: Get-ItemProperty -Path <drive>:\ -Name RegisterSCP If the RegisterSCP property is set to False, you can use the following procedure to register the SCP when the AD RMS server role is installed. Membership in the local AD RMS Enterprise Administrators, or equivalent, is the minimum required to complete this procedure. To register the SCP At the Windows PowerShell command prompt, type: Back to top Set-ItemProperty -Path <drive>:\ -Name RegisterSCP -Value $true where <drive> is the name of the Windows PowerShell drive. Installing an AD RMS Cluster Creating an AD RMS Cluster Windows PowerShell Drive Running the Install-ADRMS Cmdlet Running the Install-ADRMS Cmdlet After you create a Windows PowerShell drive and set properties on containers in the drive namespace, the final step in using Windows PowerShell cmdlets to install the first server in an Active Directory Rights Management Services (AD RMS) cluster is to run the Install-ADRMS cmdlet. 21

22 The Install-ADRMS cmdlet performs two principal functions: It installs any prerequisite features or services that are not yet installed on the server. It installs the AD RMS server role with the configuration settings represented by the properties set on containers in the drive namespace. To run the Install-ADRMS cmdlet At the Windows PowerShell command prompt, type: Set-Location <drive>:\ Install-ADRMS -Path. where <drive> is the name of the Windows PowerShell drive. You must set the current location to the root of the Windows PowerShell drive before running the Install-AD RMS cmdlet. The path supplied with the -Path parameter must be the same as the current location. Installing an AD RMS Cluster Creating an AD RMS Cluster Windows PowerShell Drive Setting Properties on Objects in the AD RMS Drive Namespace Joining an Existing Cluster For most purposes, joining one or more Active Directory Rights Management Services (AD RMS) servers to a root cluster is the best way to increase the availability and redundancy of your deployment. A root cluster can contain one or many servers that provide all services to AD RMS clients. You can also join an AD RMS server to a licensing-only cluster. When you install the AD RMS server role on a computer running Windows Server 2008 R2, you can choose the option to join the server to a cluster. When joining a server to a cluster, you must configure your load balancing software or hardware to work with the new cluster member. Before you can use Windows PowerShell cmdlets to install the AD RMS server role, you must start Windows PowerShell with administrator privileges after logging in with an account that meets the following requirements: Important The user account that you use to install AD RMS must not be the same account as the AD RMS service account. If you are using an external database server for the AD RMS databases, the user account that you use to install AD RMS must have the right to create new databases. If Microsoft SQL Server 2005 or Microsoft SQL Server 2008 is used, the user account must be a member of the System Administrators database role, or equivalent. 22

23 The user account that you use to install AD RMS must have access to query the AD DS domain, such as a domain user account. The user account that you use to install AD RMS must be a member of the Administrators group, or equivalent, on the server. Installing and provisioning AD RMS as a member server in an existing AD RMS cluster consists of the following steps: 1. Create the Windows PowerShell drive to represent the server that you are provisioning. For more information, see Creating an AD RMS Server Windows PowerShell Drive. 2. Set properties on objects in the drive namespace that represent required configuration settings. For more information, see Setting Properties on Objects in the AD RMS Drive Namespace. 3. Run the Install-ADRMS cmdlet. In addition to installing the AD RMS server role and provisioning the server, this cmdlet also installs other features required by AD RMS, such as Message Queuing, if necessary. For more information, see Running the Install-ADRMS Cmdlet. Using Windows PowerShell to Deploy AD RMS Understanding the AD RMS Deployment Provider Namespace Creating an AD RMS Server Windows PowerShell Drive By creating an Active Directory Rights Management Services (AD RMS) deployment Windows PowerShell provider drive, you create a namespace that contains items that represent configuration settings of the server you are joining to an existing AD RMS cluster. To create the Windows PowerShell drive At a Windows PowerShell prompt, type: Import-Module ADRMS New-PSDrive -PSProvider ADRMSInstall -Name <drive> -Root JoinCluster where <drive> is the name of the Windows PowerShell drive you are creating. For example, to create a Windows PowerShell drive named NewSvr to install and provision a new server in an existing AD RMS cluster, type: New-PSDrive -PSProvider ADRMSInstall -Name NewSvr -Root JoinCluster 23

24 After creating the drive, do not exit the Windows PowerShell command prompt until you have finished installing the AD RMS server role. Doing so will delete the drive and all property settings will be lost. Joining an Existing Cluster Setting Properties on Objects in the AD RMS Drive Namespace Running the Install-ADRMS Cmdlet Setting Properties on Objects in the AD RMS Drive Namespace Setting properties on objects in the drive namespace is similar to using a wizard to specify configuration settings when installing a server role. Before you can finish the installation by running the Install-ADRMS cmdlet, you must provide necessary information about the initial configuration of the server role. The following table lists the required settings and the properties that represent those settings in the drive namespace. Setting name Property name Location Database server ServerName <drive>:\clusterdatabase Database name DatabaseName <drive>:\clusterdatabase Cluster key password CentrallyManagedPassword <drive>:\clusterkey Service account ServiceAccount <drive>:\ Cluster Web site WebSiteName <drive>:\clusterwebsite Note The CentrallyManagedPassword property is not available if you are using either a software- or hardware-based cryptographic service provider (CSP) to protect the cluster key. If you are using a CSP, you must manually move the cluster key to the other computers before installing AD RMS. Consult the CSP documentation for procedures on moving the cluster key. The following sections describe the configuration settings you must specify by setting properties on objects in the Windows PowerShell drive namespace when adding a server to an existing Active Directory Rights Management Services (AD RMS) cluster. 24

25 Setting the database server When an AD RMS server is provisioned as a member of an existing cluster, it must be configured to use the cluster database server. To set the cluster database server 1. At the Windows PowerShell command prompt, type: Back to top Set-ItemProperty -Path <drive>:\clusterdatabase -Name ServerName -Value <db_server> where <drive> is the name of the Windows PowerShell drive and <db_server> is the name of the cluster database server. Setting the database name When the AD RMS server role is installed on the first server in a cluster, AD RMS creates a database on the specified server that it uses to record configuration, logging, and other information. When another AD RMS server is joined to the cluster, it must be configured to use the same database. To set the cluster database name 1. To list the database instances hosted by the cluster database server, at the Windows PowerShell command prompt, type: Get-ChildItem -Path <drive>:\clusterdatabase\databaseinstance where <drive> is the name of the Windows PowerShell drive. 2. To list the databases hosted by a database instance, at the Windows PowerShell command prompt, type: Get-ChildItem -Path <drive>:\clusterdatabase\databaseinstance\<db_instance> where <drive> is the name of the Windows PowerShell drive and <db_instance> is the name of a database instance. 3. To set the database name, at the Windows PowerShell command prompt, type: Back to top Set-ItemProperty -Path <drive>:\clusterdatabase -Name DatabaseName -Value <db_name> where <drive> is the name of the Windows PowerShell drive and <db_name> is the name of the cluster database. 25

26 Setting the cluster key password If you are using AD RMS to centrally manage the cluster key, you must set the cluster key password before you can add the server to the cluster. To set the centrally managed cluster key password 1. To securely store the cluster key password in a variable, at the Windows PowerShell command prompt, type: $password = Read-Host -AsSecureString -Prompt Password: 2. Type the cluster key password, and then press the ENTER key. 3. At the Windows PowerShell command prompt, type: Back to top Set-ItemProperty -Path <drive>:\clusterkey -Name CentrallyManagedPassword -Value $password where <drive> is the name of the Windows PowerShell drive. Setting the service account During installation, AD RMS creates the AD RMS Service Group on the local computer and grants it appropriate permissions on all of the resources that are required for AD RMS to operate. When you install the AD RMS server role, you must define a domain account for use as the AD RMS service account. That account is made a member of the AD RMS Service Group, and it is granted the permissions that are associated with this group. During routine operations, AD RMS runs under the AD RMS service account. Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To set the AD RMS service account 1. At the Windows PowerShell command prompt, type: $svcacct = Get-Credential A dialog box appears. 2. In the dialog box, type the account domain and name (in the form <domain>\<account>) and password. 3. At the Windows PowerShell command prompt, type: Back to top Set-ItemProperty -Path <drive>:\ -Name ServiceAccount -Value $svcacct where <drive> is the name of the Windows PowerShell drive. 26

27 Setting the cluster Web site Before completing the installation of the AD RMS server role, you must specify the Web site where the AD RMS Web services will be installed if you are not using the default Web site. If you have installed the Internet Information Services (IIS) 6 Management Compatibility Service, you can get a listing of the Web sites hosted on the server by typing at a Windows PowerShell command prompt: Get-ChildItem -Path <drive>:\clusterwebsite where <drive> is the name of the Windows PowerShell drive. Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To set the cluster Web site At the Windows PowerShell command prompt, type: Back to top Set-ItemProperty -Path <drive>:\clusterwebsite -Name WebSiteName -Value <web_site> where <drive> is the name of the Windows PowerShell drive and <web_site> is the name of the Web site to be used to host the AD RMS Web services. Joining an Existing Cluster Creating an AD RMS Server Windows PowerShell Drive Running the Install-ADRMS Cmdlet Running the Install-ADRMS Cmdlet After you create a Windows PowerShell drive and set properties on containers in the drive namespace, the final step in using Windows PowerShell cmdlets to add a server to an existing Active Directory Rights Management Services (AD RMS) cluster is to run the Install-ADRMS cmdlet. The Install-ADRMS cmdlet performs two principal functions: It installs any prerequisite features or services that are not yet installed on the server. It installs the AD RMS server role with the configuration settings represented by the properties set on containers in the drive namespace. To run the Install-ADRMS cmdlet At the Windows PowerShell command prompt, type: 27

28 Set-Location <drive>:\ Install-ADRMS -Path. where <drive> is the name of the Windows PowerShell drive. You must set the current location to the root of the Windows PowerShell drive before running the Install-AD RMS cmdlet. The path supplied with the Path parameter must be the same as the current location. Joining an Existing Cluster Creating an AD RMS Server Windows PowerShell Drive Setting Properties on Objects in the AD RMS Drive Namespace Adding or Removing Federated Identity Support After creating an Active Directory Rights Management Services (AD RMS) cluster, you can use Windows PowerShell cmdlets to add federated identity support to the cluster. You can also use Windows PowerShell cmdlets to remove federated identity support from a cluster without affecting other AD RMS settings. It is not necessary to create a Windows PowerShell drive in order to add or remove federated identity support. Before you add AD RMS federated identity support, you should ensure that the following conditions have been met: Important Ensure that you specified a secure cluster address when you installed AD RMS. Active Directory Federation Services (AD FS) requires secure communication between AD RMS and the AD FS resource server. Use the Local Security Policy console to assign the Generate Security Audits privilege to the AD RMS service account. Configure a federated trusted relationship before you add federated identity support. When you add federated identity support, you must specify the URL of the federation service. Ensure that the AD RMS extranet cluster URLs are accessible to the federated account partner. The following sections describe how to use Windows PowerShell cmdlets to add federated identity support to an existing cluster and to remove it when it is no longer needed. 28

29 Adding federated identity support Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To add federated identity support At a Windows PowerShell command prompt, type: Import-Module ADRMS Install-ADRMS -ADFSUrl where <federation_server> is the name of the federation server. Specify this name by using lowercase letters only. Removing federated identity support Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. To remove federated identity support At a Windows PowerShell command prompt, type: Import-Module ADRMS Uninstall-ADRMS -ADFSOnly Using Windows PowerShell to Deploy AD RMS AD RMS Deployment Cmdlets Upgrading the AD RMS Server Role After you upgrade a server that is running Windows Rights Management Services SP2 on Windows Server 2003 or that is running the Active Directory Rights Management Services (AD RMS) server role on Windows Server 2008, you must upgrade the AD RMS server role. You can use Windows PowerShell cmdlets to perform this task. The cmdlets that you use depend on whether the AD RMS cluster that the server belongs to uses a cryptographic service provider (CSP) or the AD RMS configuration database to store the cluster key. Membership in the local Administrators group, or equivalent, is the minimum required to complete this procedure. 29

30 To upgrade the AD RMS server role on a cluster that uses a CSP 1. At a Windows PowerShell command prompt, type: Import-Module ADRMS $svcacct = Get-Credential 2. In the dialog box that appears, type the user name and password of the AD RMS service account. 3. At the Windows PowerShell command prompt, type: Update-ADRMS -ServiceAccount $svcacct To upgrade the AD RMS server role on a cluster that does not use a CSP 1. At a Windows PowerShell command prompt, type: Import-Module ADRMS $svcacct = Get-Credential 2. In the dialog box that appears, type the user name and password of the AD RMS service account. 3. At the Windows PowerShell command prompt, type: $pword = Read-Host -AsSecureString -Prompt Password: 4. Type the cluster key password, and then press the ENTER key. 5. At the Windows PowerShell command prompt, type: Update-ADRMS -ServiceAccount $svcacct -PrivateKeyPassword $pword Important If the Identify Federation Support role service was installed and configured before you performed the upgrade, you must remove and then reinstall Identity Federation Support after running the Update-AD RMS cmdlet. If you do not, federation support will stop functioning. For more information, see Adding or Removing Federated Identity Support. Using Windows PowerShell to Deploy AD RMS AD RMS Deployment Cmdlets Pre-installation Information for Active Directory Rights Management Services Removing the AD RMS Server Role You can use a Windows PowerShell cmdlet to remove the Active Directory Rights Management Services (AD RMS) server role from a server. 30