Creating a New Rights Policy Template

  • Article

Updated: November 7, 2012

Applies To: Windows Server 2008 R2, Windows Server 2008 R2 with SP1, Windows Server 2012

When you create a new Active Directory Rights Management Services (AD RMS) rights policy template by using Windows PowerShell cmdlets, you can specify the template settings, or you can create a blank template. In either case, you can subsequently use Windows PowerShell cmdlets or the AD RMS console to modify the contents of the template.

The following procedure creates a mostly empty rights policy template that you can modify later to add settings. For more information about modifying an existing rights policy template, see Editing a Rights Policy Template.

Membership in the local AD RMS Template Administrators, or equivalent, is the minimum required to complete this procedure.

To create a new rights policy template to be modified later

  • At the Windows PowerShell command prompt, type:

    New-Item -Path <drive>:\RightsPolicyTemplate -LocaleName <locale_names> -DisplayName <display_names> -Description <descriptions>

    where <drive> is the name of the Windows PowerShell drive, and where <locale_names>, <display_names>, and <descriptions> are the strings required by their respective parameters. For more information about the meaning and format of these strings, see the table later in this topic.

The following procedure creates a rights policy template with initial settings that can be supplemented by modifying the template after it has been created. For more information about modifying an existing rights policy template, see Editing a Rights Policy Template.

Membership in the local AD RMS Template Administrators, or equivalent, is the minimum required to complete this procedure.

To create a new rights policy template with initial settings

  • At the Windows PowerShell command prompt, type:

    New-Item -Path <drive>:\RightsPolicyTemplate -LocaleName <locale_names> -DisplayName <display_names> -Description <descriptions> [-UserGroup <user_list> [-Right <standard_rights>] [-CustomRight <custom_rights>]] [-RightsRequestUrl <url>] [-ContentExpiredOnDateInDaysOrNever <expiration>] [-UserLicenseRenewalInDays <days>] [-ArchivedTemplate] [-EnableViewInTrustedBrowser] [-EnableOnetimeLicense] [-ExtendedAppName <pair_names> -ExtendedAppValue <pair_values>] [-RevocationLocation <list_url> -RevocationRefreshPerDays <days> -RevocationPublicKeyFilePath <path>]

    where <drive> is the name of the Windows PowerShell drive. For more information about the meaning and format of other parameter values, see the table later in this topic.

To create a rights policy template, you use the New-Item cmdlet to create an item in the \RightsPolicyTemplate container in the AD RMS administration namespace in Windows PowerShell. When the path of this cmdlet is set to the \RightsPolicyTemplate container, it supports dynamic parameters that allow you to specify settings for the new rights policy template. The following table lists the parameters that you can use to specify settings when creating a rights policy template.

Dynamic Parameter Description Usage

-LocaleName

Required parameter that specifies one or more locales for the template.

For each locale represented in the template, specify a two-part locale code consisting of a two-letter language code and a two-letter country/region code. For example, to specify United States English, use en-us, and to specify Canadian French, use fr-ca. For each locale you specify, you must also specify a corresponding display name and description. You must specify at least one locale.

-DisplayName

Required parameter that specifies a name to be shown to users for each template locale provided with the -LocaleName parameter. Typically, this name describes the purpose of the template (such as “Read-Only”) in the language corresponding to the locale.

For each locale, specify a name for the template in quotation marks, separating each name with a comma.

-Description

Required parameter that specifies a description of the template for each locale provided with the -LocaleName parameter. Typically, this description explains the purpose of the template (such as “Allows users to read, but not change, protected content”) in the language corresponding to the locale.

For each locale, specify a description of the template in quotation marks, separating each description with a comma.

-UserGroup

Optional parameter that specifies the users or groups who are granted rights by the template.

For each user or group to be granted rights by the template, specify the e-mail address of the user or group, separated by a comma. You can also specify the keyword ANYONE to designate all users.

-Right

Optional parameter that specifies the standard rights to be granted by the template for each user or group. This parameter is required if the -UserGroup parameter is specified.

For each user or group specified with the -UserGroup parameter, specify a list of one or more rights. Each list must be contained within parentheses, and each right must be contained within single quotation marks (‘) and separated by a comma (,). Multiple lists are separated by commas. For example, to specify View and Print rights for two users or groups, provide this list:

(‘View’,’Print’),(‘View’,’Print’)

Standard rights consist of the following: View, Extract, AllowMacros, ViewRightsData, Print, Forward, Reply, ReplyAll, Export, Save, Edit, EditRightsData, and FullControl.

-CustomRight

Optional parameter that specifies custom rights to be granted by the template for each user or group.

For each user or group specified with the -UserGroup parameter, specify a list of one or more custom rights using the same format as for the -Rights parameter.

RightsRequestUrl

Optional parameter that specifies the URL from which users can request additional rights to rights-protected content.

Specify a URL in the standard format.

-ContentExpiredOnDateInDaysOrNever

Optional parameter that specifies when content expires.

Specify one of the following:

  • NEVER to indicate that content protected by the template never expires

  • A single number (such as 31) to indicate the number of days to elapse before the content expires

  • A date (such as 01/31/2011) indicating when the content expires at midnight, Coordinated Universal Time (UCT), also known as Greenwich Mean Time.

-UserLicenseRenewalInDays

Optional parameter that specifies when the use license expires.

Specify a number indicating the number of days the use license will remain valid.

-ArchivedTemplate

Optional parameter that specifies whether the template is archived or distributed. A distributed rights policy template allows users to publish and consume rights-protected content, and an archived rights policy template only allows consumption once the rights policy template has been removed from the client computer.

Specify the -ArchivedTemplate parameter to designate an archived template. If you do not specify this parameter, the template will be distributed.

-EnableViewInTrustedBrowser

Optional parameter that specifies whether a user who does not have an AD RMS-enabled application installed can view rights-protected content protected by this template.

Specify the -EnableViewInTrustedBrowser parameter to allow users to view protected content by using a Web browser. If you do not specify this parameter, users will be required to use an AD RMS-enabled application to use content protected by this template.

-EnableOnetimeLicense

Optional parameter that requires users to re-authenticate with AD RMS each time the rights-protected content is consumed.

Specify the -EnableOnetimeLicense parameter to require users to re-authenticate. If you do not specify this parameter, users will not be required to re-authenticate each time they access the content.

-ExtendedAppName

Optional parameter that specifies the names of one or more application-specific data pairs.

Specify one or more names as a list of comma-separated strings.

-ExtendedAppValue

Optional parameter that specifies the values of one or more application-specific data pairs. This parameter is required if you specify the -ExtendedAppName parameter.

Specify one or more values corresponding to the names specified with the -ExtendedAppName parameter. Specify values as a list of comma-separated strings.

-RevocationLocation

Optional parameter that enables revocation and specifies the URL where the revocation list file is posted. If you need to support disconnected users or external users, this URL should be accessible from both the internal organization's network and the Internet.

Caution
Be careful when implementing revocation. Based on the refresh interval that you specify, you must renew a revocation list periodically or it will automatically expire, preventing users from consuming content that requires that list. To ensure that you do not inadvertently prevent users from consuming content, carefully evaluate the interval you require for refreshing the revocation list.

Note

Effective with the release of Windows Server 2012, this parameter is no longer supported in Windows Server 2008, Windows Server 2008 R2, and Windows Server 2012. For additional information on this change, see the Note that follows this table.

Specify a URL in the standard format.

- RevocationRefreshPerDays

Optional parameter that specifies the number of days that the revocation list remains valid. If a user has a copy of the revocation list that is older than this value, the user must obtain an updated revocation list to consume the content. This parameter is required if you specify the -RevocationLocation parameter.

Note

Effective with the release of Windows Server 2012, this parameter is no longer supported in Windows Server 2008, Windows Server 2008 R2, and Windows Server 2012. For additional information on this change, see the Note that follows this table.

Specify a number.

- RevocationPublicKeyFilePath

Optional parameter that specifies the path of the public key file for the revocation list. This parameter is required if you specify the -RevocationLocation parameter.

Note

Effective with the release of Windows Server 2012, this parameter is no longer supported in Windows Server 2008, Windows Server 2008 R2, and Windows Server 2012. For additional information on this change, see the Note that follows this table.

Specify the path to the public key file.

Note

Effective with the release of Windows Server 2012, license revocation is no longer supported in Windows Server 2008, Windows Server 2008 R2, and Windows Server 2012. Instead, the document lifecycle should be set in the protection policy. If there is a high probability of a need to remove access to a particular document, Microsoft recommends that the customer set the validity time to zero in the template, or select Require a connection to verify a user’s permission in the Office application under IRM settings. Note that use of these options will require a connection to the server when opening content, which will impact offline consumption scenarios. For more information on working around this product design change, see the following Microsoft TechNet blog post: Your revocation has been revoked…sort of

Important

If you use both the -Right and -CustomRight parameters, each parameter must specify a list containing at least one right for each user or group. For example, when creating a template, you cannot assign standard rights to one set of users and custom rights to a different set of users. If this is required, create a template without specifying the users and then modify the existing template to add the users and rights. For more information about modifying an existing template, see Editing a Rights Policy Template.

See Also

Concepts

Using Windows PowerShell to Administer AD RMS
Understanding the AD RMS Administration Provider Namespace
Configuring Rights Policy Templates

Other Resources

Understanding Rights Policy Templates
Understanding Rights Enforcement