Edit

New-RMSProtectionLicense

  • Reference
Module:
AzureInformationProtection

Creates an ad-hoc rights policy for RMS protection.

Syntax

New-RMSProtectionLicense
   [-RmsServer <String>]
   [-OwnerEmail <String>]
   [-UserEmail <String[]>]
   [-Permission <String[]>]
   [-ValidForDays <String>]
   [-Name <String>]
   [-Description <String>]
   [<CommonParameters>]

Description

The New-RMSProtectionLicense cmdlet creates an ad-hoc rights policy that you store as a variable and then use to protect a file or files when you run the Protect-RMSFile cmdlet.

Create an ad-hoc rights policy (also known as a publishing license) when you cannot use a previously created rights policy template.

Examples

Example 1: Create an ad-hoc policy that has a different owner and grants another user Edit rights

PS C:\>$License = New-RMSProtectionLicense -OwnerEmail "user1@contoso.com" -UserEmail "user2@contoso.com" -Permission "EDIT"

This command creates an ad-hoc rights policy that sets user1@contoso.com as the owner and grants user2@contoso.com EDIT rights, and stores this policy in a variable named License. This ad-hoc policy can then be used to apply protection to a file or files.

There is no output displayed for this command.

Example 2: Create an ad-hoc policy with an expiry period that grants a group View and Extract rights

PS C:\>$License = New-RMSProtectionLicense -UserEmail "marketing@contoso.com" -Permission "VIEW", "EXTRACT" -ValidForDays 100

This command creates an ad-hoc rights policy with an expiry period of 100 days that grants the marketing group marketing@contoso.com VIEW and EXTRACT rights, and stores this policy in a variable named License.

There is no output displayed for this command.

Example 3: Create an ad-hoc rights policy for a user and then protect a file using the policy

PS C:\>$License = New-RMSProtectionLicense -OwnerEmail 'user1@contoso.com' -UserEmail 'user2@contoso.com','user3@contoso.com' -Permission 'VIEW','PRINT'
PS C:\> Protect-RMSFile -License $License -File "C:\Test.txt"
InputFile             EncryptedFile
---------             -------------
C:\Test.txt           C:\Test.ptxt

The first command creates an ad-hoc rights policy that sets user1@contoso.com as the owner and grants user2@contoso.com and user3@contoso.com VIEW and PRINT rights, and stores this policy in a variable named License.

The second command then uses the created ad-hoc policy to protect the file C:\Test.txt.

Parameters

-Description

Specifies the description of the rights policy.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Specifies the name of this rights policy.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OwnerEmail

Specifies the Rights Management owner of the rights policy by email address. You can use this parameter to set a Rights Management owner other than yourself.

By default, the account running this cmdlet is both the Rights Management issuer and the Rights Management owner of the protected file. This parameter lets you assign a different Rights Management owner to the protected file so that the specified account has all usage rights (Full Control) for the file and can always access it. The Rights Management owner is independent from the Windows file system owner. For more information, see Rights Management issuer and Rights Management owner.

If you do not specify a value, the cmdlet will use your email address to identify you as the Rights Management owner of this ad-hoc rights policy.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Permission

Specifies the usage rights for the ad-hoc policy. Use this parameter and the UserEmail parameter to grant rights to specified users.

The acceptable values for this parameter:

  • VIEW
  • EDIT
  • PRINT
  • EXPORT
  • COMMENT
  • VIEWRIGHTSDATA
  • EDITRIGHTSDATA
  • EXTRACT
  • OWNER
  • DOCEDIT
  • OBJMODEL

Warning: If you later want to remove this rights policy from a file, you must have the EXTRACT or OWNER right to use the Unprotect-RMSFile cmdlet to unprotect a file, or be a Rights Management super user for your organization.

For more information about these rights, see Configuring usage rights for Azure Information Protection on the Microsoft documentation site.

Type:String[]
Accepted values:VIEW, EDIT, PRINT, EXPORT, COMMENT, VIEWRIGHTSDATA, EDITRIGHTSDATA, EXTRACT, OWNER, DOCEDIT, OBJMODEL
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RmsServer

Specifies the name of an AD RMS server (or cluster) to use when creating this ad-hoc rights policy.

This parameter is not applicable for Azure RMS or if your computer knows the right AD RMS server to use by using service discovery.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UserEmail

Specifies users who will have rights to use the file or files that is protected by this ad-hoc policy. Use this parameter and the Permission parameter to grant rights to specified users or groups.

These users or groups can be internal to your organization, or external. For Azure AD authentication to be successful, the user must have an account in Azure Active Directory. Office 365 users automatically have an account in Azure Active Directory.

Some applications also support personal email addresses with a Microsoft account. For more information about using Microsoft accounts for authentication, see the supported scenarios table.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ValidForDays

Specifies an expiry period in number of days, which starts when the ad-hoc policy is applied to a file or files.

After this expiry period, the specified users will no longer be able to access the file or files. However, the owner and a super user can always access the file, even after the expiry period is reached.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False