New-AzKeyVaultRoleDefinition

Reference

Module:: Az.KeyVault

Creates a custom role definition on an HSM.

Syntax

New-AzKeyVaultRoleDefinition
   [-HsmName] <String>
   [-Scope <String>]
   [-Role] <PSKeyVaultRoleDefinition>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

New-AzKeyVaultRoleDefinition
   [-HsmName] <String>
   [-Scope <String>]
   [-InputFile] <String>
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

The New-AzKeyVaultRoleDefinition cmdlet creates a custom role in Azure Role-Based Access Control of an Azure KeyVault managed HSM.

Provide either a JSON role definition file or a PSKeyVaultRoleDefinition object as input. First, use the Get-AzKeyVaultRoleDefinition command to generate a baseline role definition object. Then, modify its properties as required. Finally, use this command to create a custom role using role definition.

Examples

Example 1

$role = Get-AzKeyVaultRoleDefinition -HsmName myHsm -RoleDefinitionName 'Managed HSM Crypto User'
$role.Name = $null
$role.RoleName = "my custom role"
$role.Description = "description for my role"
$role.Permissions[0].DataActions = @("Microsoft.KeyVault/managedHsm/roleAssignments/write/action", "Microsoft.KeyVault/managedHsm/roleAssignments/delete/action") # todo
New-AzKeyVaultRoleDefinition -HsmName myHsm -Role $role

This example uses the predefined "Managed HSM Crypto User" role as a template to create a custom role.

Example 2

Get-AzKeyVaultRoleDefinition -HsmName myHsm -RoleDefinitionName 'Managed HSM Crypto User' | ConvertTo-Json -Depth 9 > C:\Temp\roleDefinition.json
# Edit roleDefinition.json. Make sure to clear "Name" so as not to overwrite an existing role.
New-AzKeyVaultRoleDefinition -HsmName myHsm -InputFile C:\Temp\roleDefinition.json

This example uses a JSON file as the input of the custom role.

Parameters

-Confirm

Prompts you for confirmation before running the cmdlet.

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

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with Azure.

Type:	IAzureContextContainer
Aliases:	AzContext, AzureRmContext, AzureCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HsmName

Name of the HSM.

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

-InputFile

File name containing a single role definition.

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

-Role

A role definition object.

Type:	PSKeyVaultRoleDefinition
Position:	2
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Scope

Scope at which the role assignment or definition applies to, e.g., '/' or '/keys' or '/keys/{keyName}'. '/' is used when omitted.

Type:	String
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:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

None

Outputs

PSKeyVaultRoleDefinition