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

(1)

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(http://go.microsoft.com/fwlink/?LinkId=80907). For information about Windows PowerShell, see Scripting with Windows

PowerShell(http://go.microsoft.com/fwlink/?LinkID=93317).

In this guide

Using Windows PowerShell to Deploy AD RMS Using Windows PowerShell to Administer AD RMS

(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.

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.

 At the Windows PowerShell prompt, type: Import-Module ADRMS

 At the Windows PowerShell prompt, type:

New-PSDrive -Name <drivename> -PsProvider AdRmsInstall -Root <installType> Note

Import the module

(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 licensing-only 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

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

(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.

(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.

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 (http://go.microsoft.com/fwlink/?LinkID=165547).

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.

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.

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.

 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.

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.

(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 SLCName <drive>:\ Register service connection point (SCP) RegisterSCP <drive>:\

 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.

(16)

 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.

 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.

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.

To use the Windows Internal Database

To use a remote database instance

(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.

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:

Set-ItemProperty -Path <drive>:\ -Name ServiceAccount -Value $svcacct where <drive> is the name of the Windows PowerShell drive.

Back to top

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.

If there are multiple servers in the AD RMS cluster, and you are using either a software- or 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.

To set the AD RMS service account

(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

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

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 To set the centrally managed cluster key password

(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

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.

Back to top

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

(20)

uses https://) 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.

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 “http://Cluster1:80” To specify an encrypted connection to the same URL, type:

Set-ItemProperty -Path RC:\ -Name ClusterURL -Value “https://Cluster1:443” 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.

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

To specify the cluster address

(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.

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.

Set-ItemProperty -Path <drive>:\ -Name RegisterSCP -Value $true where <drive> is the name of the Windows PowerShell drive. Back to top

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.

Note

(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.

 At the Windows PowerShell command prompt, type: Set-Location <drive>:\

Install-ADRMS -Path .

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

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:

 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.

To run the Install-ADRMS cmdlet

(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.

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.

 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 To create the Windows PowerShell drive

(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.

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

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.

(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.

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.

Back to top

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.

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: 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.

Back to top

To set the cluster database server

(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.

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:

Set-ItemProperty -Path <drive>:\ClusterKey -Name CentrallyManagedPassword -Value $password

where <drive> is the name of the Windows PowerShell drive. 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.

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.

Set-ItemProperty -Path <drive>:\ -Name ServiceAccount -Value $svcacct where <drive> is the name of the Windows PowerShell drive.

Back to top

To set the centrally managed cluster key password

(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

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.

Back to top

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.

 At the Windows PowerShell command prompt, type: To set the cluster Web site

(28)

Set-Location <drive>:\ Install-ADRMS -Path .

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.

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:

 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.

(29)

Adding federated identity support

 At a Windows PowerShell command prompt, type: Import-Module ADRMS

Install-ADRMS -ADFSUrl

“https://<federation_server>/adfs/fs/federationserverservice.asmx”

where <federation_server> is the name of the federation server. Specify this name by using lowercase letters only.

Removing federated identity support

Uninstall-ADRMS -ADFSOnly

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.

To add federated identity support

(30)

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

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

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.

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.

To upgrade the AD RMS server role on a cluster that uses a CSP

To upgrade the AD RMS server role on a cluster that does not use a CSP

(31)

If you are removing every server in the AD RMS cluster, be sure to first decommission AD RMS and remove all protection from the content that is rights-protected by this AD RMS cluster. For more information, see Decommissioning AD RMS.

If you are only removing one AD RMS server from the cluster, you do not need to decommission the AD RMS environment because other servers continue to issue certification and licensing requests to AD RMS users.

Uninstall-ADRMS

Using Windows PowerShell to Administer AD

RMS

The Active Directory Rights Management Services (AD RMS) Windows PowerShell

administration module gives you the ability to administer all aspects of an AD RMS cluster by using Windows PowerShell cmdlets. The provider in the administration module presents a drive namespace that is based on the organization of cluster settings that is shown by the AD RMS graphical user interface (GUI). 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 administration module implements special-purpose cmdlets to perform tasks that cannot be performed by using common cmdlets.

Important

(32)

The AD RMS Windows PowerShell administration module does not support the 32-bit version of Windows PowerShell. It can only be used on the 64-bit version.

Getting started

Before you can administer AD RMS by using Windows PowerShell cmdlets, after starting Windows PowerShell, you must perform three tasks:

1. Import the AD RMS Windows PowerShell administration module.

2. Create a Windows PowerShell drive that represents the AD RMS cluster you want to administer.

3. Set the current location to a container on the drive you created. The following procedures explain how to perform each of these tasks.

 At the Windows PowerShell prompt, type: Import-Module AdRmsAdmin

 At the Windows PowerShell prompt, type:

New-PSDrive -Name <drivename> -PsProvider AdRmsAdmin -Root <clusterURL>

where <drivename> is the name you want to assign to the new drive, and <clusterURL> is the URL of the AD RMS cluster you want to administer.

For example, to create a drive named AdrmsCluster that represents the AD RMS cluster hosted by the local computer, type:

New-PSDrive -Name AdrmsCluster -PsProvider AdRmsAdmin -Root https://localhost

 At the Windows PowerShell command prompt, type: Set-Location <drivename>:\[<container>]

where <drivename> is the name of the drive, and <container> is the optional path name of container within the drive. For information about how to use these containers, see Understanding the AD RMS Administration Provider Namespace.

For example, to set the current location to the TrustPolicy\TrustedPublishingDomain container in the AdrmsCluster drive, type:

Set-Location AdrmsCluster:\TrustPolicy\TrustedPublishingDomain Note

Import the module

Create the drive

(33)

Understanding the AD RMS Administration

Provider Namespace

administration provider exposes a namespace that represents the various configuration settings that you can make to a server running AD RMS. You configure these settings by using Windows PowerShell cmdlets to traverse this namespace and then create or delete items in the

namespace, or set properties on those items. The namespace closely parallels the hierarchy of settings that are made available in the AD RMS graphical user interface (GUI) administration tools to make it easier to associate the items in the administration namespace with the corresponding settings exposed by the GUI tools.

This topic lists the containers in the administration namespace, explains what configuration settings each container represents, and lists the subcontainers or items that it can hold. <drive>:\

The root container of the administration namespace represents the properties of the cluster itself. You can work with these properties by using the Get-ItemProperty and Set-ItemProperty cmdlets to view and change the following properties:

 IsDecommissioned  AdministrativeContact  IsLoggingEnabled  IntranetLicensingUrl  ExtranetCertificationUrl  ExtranetLicensingUrl

(34)

 SvrLicCertFriendlyName

 ScpUrl

 IsProxyRequired

You can also use the Get-ItemProperty cmdlet to view these read-only properties:

 ClusterName  ClusterType  ClusterServerList  LoggingDatabaseServer  LoggingDatabaseName  LoggingServiceName  LoggingQueueName  ConfigurationDatabaseServer  ConfigurationDatabaseName  IntranetCertificationUrl  SvrLicCertHierarchy  RegisteredServiceDomain <drive>:\ExclusionPolicy

This container holds containers that represent the application, lockbox, and user exclusion policies of the cluster. For more information about working with exclusion policies, see Enabling Exclusion Policies.

<drive>:\ExclusionPolicy\Application

This container holds items that represent excluded application versions. Use Set-ItemProperty to change the IsEnabled property of the container to enable or disable application exclusion. To control which application versions are excluded, use the New-Item and Remove-New-Item cmdlets. For more information, see Excluding Applications.

<drive>:\ExclusionPolicy\Lockbox

This container holds items that represent excluded application lockboxes. Use Set-ItemProperty to change the IsEnabled property of the container to enable or disable lockbox exclusion. To change the minimum lockbox version, set the

LockBoxMinimumVersionproperty . For more information, see Excluding Lockboxes.

<drive>:\ExclusionPolicy\User

This container holds items that represent excluded users. Use Set-ItemProperty to change the IsEnabled property of the container to enable or disable user exclusion. To

(35)

control which users are excluded, use the New-Item and Remove-Item cmdlets. For more information, see Excluding Users.

<drive>:\IssuancePolicy

This container represents the rights account certificate issuance policy. Use the Set-ItemProperty cmdlet to set the StandardCertValidityPeriodInDays and

TemporaryCertValidityPeriodInMinutes properties of the container to modify this policy. For more information, see Specifying the Rights Account Certificate Validity Duration.

<drive>:\Report

This container gives you access to a set of cmdlets that query the cluster databases for different kinds of information. For more information, see Working with Reports.

<drive>:\RightsPolicyTemplate

This container holds subcontainers that represent rights policy templates. Use the Set-ItemProperty cmdlet to set the PublishUNCFilePath property of this container to specify where templates are published. To create a rights policy template, use the New-Item cmdlet, use the Copy-New-Item cmdlet to copy a template, and use the Remove-New-Item cmdlet to remove a template. For more information, see Configuring Rights Policy Templates and Creating a New Rights Policy Template.

<drive>:\RightsPolicyTemplate\<templateID>

This container represents the rights policy template identified by <templateID> and holds subcontainers that represent settings of the template. Use the Set-ItemProperty cmdlet to change the IsDistributed property of this container to distribute or archive the template. If the template is archived, you can also set the IsReadyOnly property. For more information, see Configuring Rights Policy Templates and Archiving a Rights Policy Template.

<drive>:\RightsPolicyTemplate\<templateID>\ExpirationPolicy

This container represents the expiration policy for the rights policy template identified by

<templateID>. Use the Set-ItemProperty cmdlet to set the

ContentExpiredOnDateInDaysOrNever and UseLicenseExpiredInDays properties of this container. For more information, see Editing a Rights Policy Template.

<drive>:\ RightsPolicyTemplate\<templateID>\ExtendedPolicy

(36)

identified by <templateID> and contains items that represent application-specific policy name-value pairs. Use the Set-ItemProperty cmdlet to set the

IsViewInTrustedBrowserEnabled and IsOnetimeLicenseEnabled properties of the container, and use the New-Item cmdlet to add a name-value pair. For more

information, see Editing a Rights Policy Template.

<drive>:\ RightsPolicyTemplate\<templateID>\IdentificationInfo

This container holds items that represent the locale-specific information of the rights policy template identified by <templateID>. Use the New-Item cmdlet to add locale-specific identification information to the template. For more information, see Editing a Rights Policy Template.

<drive>:\ RightsPolicyTemplate\<templateID>\RevocationPolicy

This container represents the revocation policy of the rights policy template identified by

<templateID>. Use the Set-ItemProperty cmdlet to set the Location, RefreshPerDays,

and PublicKeyFilePath properties of this container. For more information, see Editing a Rights Policy Template.

<drive>:\ RightsPolicyTemplate\<templateID>\UserRight

This container holds items representing users and the rights granted to them. Use the Set-ItemProperty cmdlet to set the RightsRequestUrl and

CustomRightDefinitionList properties of the container. Use the New-Item cmdlet to add a user and assign rights to the user. For more information, see Editing a Rights Policy Template.

<drive>:\SecurityPolicy

This container holds subcontainers that represent the super-user and cluster key– password settings of the cluster.

<drive>:\SecurityPolicy\SuperUser

This container represents the super-user security settings of the cluster. Use the Set-ItemProperty cmdlet to enable or disable the IsEnabled and the SuperUserGroup properties of the container. For more information, see Setting up a Super Users Group.

<drive>:\SecurityPolicy\ClusterKeyPassword

This container represents the cluster key–password settings of the cluster. Use the Set-ItemProperty cmdlet to change the cluster key password. For more information, see

(37)

Resetting the AD RMS Cluster Key Password.

<drive>:\TrustPolicy

This container holds items that represent the cluster‟s federated identity support and collections of trusted domains. For more information, see Establishing Trust Policies.

<drive>:\TrustPolicy\FederatedIdentitySupport

This container represents the federated identity support policy of the cluster and is available only when federated identity support is installed. Use the Set-ItemProperty cmdlet to set the IsEnabled, CertificateValidityPeriod, CertificateServiceUrl, and IsProxyEmailAddressAllowed properties of the container. For more information, see Configuring Federated Identity Support Settings.

<drive>:\TrustPolicy\TrustedPublishingDomain

This container holds items that represent the publishing domains trusted by the cluster. Use the Import-RmsTPD cmdlet to add a trusted publishing domain to this container and the Remove-Item cmdlet to remove a trusted publishing domain. You can also use the Export-RmsTPD cmdlet to export a trusted publishing domain to a file. For more information, see Adding a Trusted Publishing Domain and Exporting a Trusted Publishing Domain.

<drive>:\TrustPolicy\TrustedUserDomain

This container holds items that represent the user domains trusted by the cluster. Use the Import-RmsTUD cmdlet to add a trusted useer domain to this container and the Remove-Item cmdlet to remove a trusted user domain. You can also use the Export-RmsTUD cmdlet to export a trusted user domain to a file. For more information, see Adding a Trusted User Domain, Using Windows Live ID to Establish RACs for Users, and Exporting a Trusted User Domain.

<drive>:\TrustPolicy\TrustedUserDomain\<domainID>

This container represents a user domain trusted by the cluster. These user domains can include the internal trusted user domain (TUD), an external TUD that was previously imported, or Windows Live ID. Use the Set-ItemProperty cmdlet to set the IsLicensingToSIDEnabled property of an internal or external TUD, the

TrustedEmailDomain property of an external TUD or the Windows Live ID domain, or the IsADFederatedUserTrused property of an external TUD.

(38)

AD RMS Administration Cmdlets

administration module gives you the ability to administer all aspects of an AD RMS cluster by using Windows PowerShell cmdlets. Most often, you will perform these tasks by using common Windows PowerShell cmdlets, such as New-Item and Set-ItemProperty, that manipulate objects in the AD RMS Windows PowerShell administration namespace. In cases where common

cmdlets cannot provide the required functionality for AD RMS administration, the AD RMS Windows PowerShell administration module implements special-purpose cmdlets to perform tasks that cannot be performed by using common cmdlets. These cmdlets are available only when the current location or the Path parameter is set to a specific path in the AD RMS Windows PowerShell administration namespace.

The following table briefly describes these cmdlets. For complete information about a cmdlet, at a Windows PowerShell prompt, type Get-Help <cmdlet_name> -full.

Cmdlets that are marked with an asterisk (*) are available only on systems with Service Pack 1 (SP1) for Windows Server® 2008 R2 installed.

Path Cmdlet Description

<drive>:\ Get-RmsSvcAccount The

Get-RmsSvcAccoun t cmdlet gets service account credentials for an AD RMS cluster.

Set-RmsSvcAccount The

Set-RmsSvcAccoun t cmdlet sets the

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

Contents