Share via

Set-AipServiceKeyProperties

  • Reference
Module:
AIPService

Updates the properties of a tenant key object for Azure Information Protection.

Syntax

Set-AipServiceKeyProperties
   [-Force]
   -KeyIdentifier <String>
   -Active <Boolean>
   [-WhatIf]
   [-Confirm]
   [-RefreshSlcName]
   [<CommonParameters>]

Description

The Set-AipServiceKeyProperties cmdlet changes an Archived status for a specified key object for the tenant to be Active. Because there can be only one active tenant key at any one time, the previously active tenant key is automatically set to Archived.

New users of Azure Information Protection immediately use the identified tenant key to protect content. Existing users of the service gradually transition from the previously active tenant key to the newly active tenant key, and this staggered transition can take a few weeks to complete. You can force the update on clients by re-initializing the user environment (also known as bootstrapping). Documents and files that were protected with the previously active tenant key remain accessible to authorized users by using the tenant key that is now archived.

Setting the tenant key object status to Active also resigns all protection templates with the newly active tenant key. Because this can be a time-consuming operation, especially if you have many protection templates, we do not recommend that you run this operation frequently.

To run this cmdlet, you must specify the KeyIdentifier for the tenant key object that you want to set to Active. To get this value, use the Get-AipServiceKeys cmdlet.

Unless you are in middle of a migration from AD RMS, do not activate a 1024-bit RSA key, which is considered an inadequate level of protection. Microsoft doesn’t endorse the use of lower key lengths such as 1024-bit RSA keys and the associated use of protocols that offer inadequate levels of protection, such as SHA-1. We recommend moving to a higher key length.

Note

You cannot use this cmdlet to change an Active status to be Archived. To set a tenant key object to have a status of Archived, you must set another tenant key object to Active.

For more information about the tenant key, see Planning and implementing your Azure Information Protection tenant key.

Examples

Example 1: Change the status of a tenant key object to be active

PS C:\> Set-AipServiceKeyProperties -Force -KeyIdentifier "c0f102b3-02cc-4816-b732-fcee73edd0e6" -Active $True

This command changes the status of a tenant key object from Archived to Active. The KeyIdentifier parameter identifies the tenant key object to change, and this value can be found by running Get-AipServiceKeys. The tenant key object that previously had a status of Active is automatically set to Archived.

Because the command specifies the Force parameter, the command does not prompt you for confirmation.

Example 2: Refresh SLC to reflect tenant friendly name

PS C:\> Set-AipServiceKeyProperties -KeyIdentifier "c0f102b3-02cc-4816-b732-fcee73edd0e6" -RefreshSlcName

This command retrieves the current tenant friendly name from Azure Active Directory and updates the SLC to have the user keys reflect the same name.

Parameters

-Active

Sets the status of the tenant key object.

This parameter can only be use with the value of $True, which sets the status to be Active. If you want to change the status of a tenant key object to Archived, you must set another tenant key object to Active.

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

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Forces the command to run without asking for user confirmation.

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

-KeyIdentifier

Specifies the key identifier for the tenant key object. You can get this value by running Get-AipServiceKeys.

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

-RefreshSlcName

Refreshes the user key (SLC) to reflect the tenant-friendly name.

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

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False