0
# Key Vault Administration
1

2
Azure Key Vault administration capabilities for managing Managed HSM instances. Provides role-based access control (RBAC) management and full HSM backup/restore operations. These administrative functions are essential for enterprise HSM deployments requiring granular permission management and disaster recovery capabilities.
3

4
## Capabilities
5

6
### Access Control Client
7

8
Manages role assignments and role definitions for Key Vault Managed HSM instances.
9

10
```python { .api }
11
class KeyVaultAccessControlClient:
12
    def __init__(self, vault_url: str, credential, **kwargs):
13
        """
14
        Initialize KeyVaultAccessControlClient for RBAC management.
15
        
16
        Parameters:
17
        - vault_url: str, Managed HSM URL (https://hsm-name.managedhsm.azure.net/)
18
        - credential: Azure credential object for authentication
19
        - api_version: ApiVersion, API version to use (default: latest)
20
        - **kwargs: Additional configuration options
21
        """
22

23
    def close(self) -> None:
24
        """Close the client and release resources."""
25
```
26

27
### Role Assignment Management
28

29
Create, retrieve, and manage role assignments for HSM access control.
30

31
```python { .api }
32
def create_role_assignment(self, role_scope: KeyVaultRoleScope, role_definition_id: str, principal_id: str, **kwargs) -> KeyVaultRoleAssignment:
33
    """
34
    Create a new role assignment.
35
    
36
    Parameters:
37
    - role_scope: KeyVaultRoleScope, scope of the role assignment (global or keys)
38
    - role_definition_id: str, ID of the role definition
39
    - principal_id: str, object ID of the principal (user, group, or service principal)
40
    - role_assignment_name: str, optional name for the assignment (UUID if not provided)
41
    
42
    Returns:
43
    KeyVaultRoleAssignment: The created role assignment
44
    """
45

46
def get_role_assignment(self, role_scope: KeyVaultRoleScope, role_assignment_name: str, **kwargs) -> KeyVaultRoleAssignment:
47
    """
48
    Get a specific role assignment.
49
    
50
    Parameters:
51
    - role_scope: KeyVaultRoleScope, scope to search within
52
    - role_assignment_name: str, name of the role assignment
53
    
54
    Returns:
55
    KeyVaultRoleAssignment: The role assignment details
56
    """
57

58
def delete_role_assignment(self, role_scope: KeyVaultRoleScope, role_assignment_name: str, **kwargs) -> KeyVaultRoleAssignment:
59
    """
60
    Delete a role assignment.
61
    
62
    Parameters:
63
    - role_scope: KeyVaultRoleScope, scope of the assignment
64
    - role_assignment_name: str, name of the assignment to delete
65
    
66
    Returns:
67
    KeyVaultRoleAssignment: The deleted assignment details
68
    """
69

70
def list_role_assignments(self, role_scope: KeyVaultRoleScope, **kwargs) -> ItemPaged[KeyVaultRoleAssignment]:
71
    """
72
    List all role assignments within a scope.
73
    
74
    Parameters:
75
    - role_scope: KeyVaultRoleScope, scope to list assignments from
76
    
77
    Returns:
78
    ItemPaged[KeyVaultRoleAssignment]: Paged list of role assignments
79
    """
80
```
81

82
### Role Definition Management
83

84
Create, retrieve, and manage custom role definitions for fine-grained access control.
85

86
```python { .api }
87
def set_role_definition(self, role_scope: KeyVaultRoleScope, **kwargs) -> KeyVaultRoleDefinition:
88
    """
89
    Create or update a custom role definition.
90
    
91
    Parameters:
92
    - role_scope: KeyVaultRoleScope, scope for the role definition
93
    - role_name: str, name of the custom role
94
    - description: str, description of the role
95
    - permissions: List[KeyVaultPermission], list of permissions for the role
96
    - assignable_scopes: List[KeyVaultRoleScope], scopes where role can be assigned
97
    - role_definition_name: str, optional UUID for the role definition
98
    
99
    Returns:
100
    KeyVaultRoleDefinition: The created or updated role definition
101
    """
102

103
def get_role_definition(self, role_scope: KeyVaultRoleScope, role_definition_name: str, **kwargs) -> KeyVaultRoleDefinition:
104
    """
105
    Get a specific role definition.
106
    
107
    Parameters:
108
    - role_scope: KeyVaultRoleScope, scope to search within
109
    - role_definition_name: str, name of the role definition
110
    
111
    Returns:
112
    KeyVaultRoleDefinition: The role definition details
113
    """
114

115
def delete_role_definition(self, role_scope: KeyVaultRoleScope, role_definition_name: str, **kwargs) -> KeyVaultRoleDefinition:
116
    """
117
    Delete a custom role definition.
118
    
119
    Parameters:
120
    - role_scope: KeyVaultRoleScope, scope of the role definition
121
    - role_definition_name: str, name of the role definition to delete
122
    
123
    Returns:
124
    KeyVaultRoleDefinition: The deleted role definition details
125
    """
126

127
def list_role_definitions(self, role_scope: KeyVaultRoleScope, **kwargs) -> ItemPaged[KeyVaultRoleDefinition]:
128
    """
129
    List all role definitions within a scope.
130
    
131
    Parameters:
132
    - role_scope: KeyVaultRoleScope, scope to list definitions from
133
    
134
    Returns:
135
    ItemPaged[KeyVaultRoleDefinition]: Paged list of role definitions
136
    """
137
```
138

139
### Backup Client
140

141
Manages full HSM backup and restore operations for disaster recovery.
142

143
```python { .api }
144
class KeyVaultBackupClient:
145
    def __init__(self, vault_url: str, credential, **kwargs):
146
        """
147
        Initialize KeyVaultBackupClient for HSM backup operations.
148
        
149
        Parameters:
150
        - vault_url: str, Managed HSM URL (https://hsm-name.managedhsm.azure.net/)
151
        - credential: Azure credential object for authentication
152
        - api_version: ApiVersion, API version to use (default: latest)
153
        - **kwargs: Additional configuration options
154
        """
155

156
    def close(self) -> None:
157
        """Close the client and release resources."""
158
```
159

160
### HSM Backup Operations
161

162
Perform full HSM backup and restore operations.
163

164
```python { .api }
165
def begin_backup(self, blob_storage_url: str, sas_token: str, **kwargs) -> LROPoller[KeyVaultBackupResult]:
166
    """
167
    Begin a full backup of the HSM.
168
    
169
    Parameters:
170
    - blob_storage_url: str, URL of the Azure Blob Storage container
171
    - sas_token: str, SAS token for accessing the storage container
172
    - use_managed_identity: bool, whether to use managed identity for storage access
173
    
174
    Returns:
175
    LROPoller[KeyVaultBackupResult]: Long-running operation for the backup
176
    """
177

178
def begin_restore(self, blob_storage_url: str, sas_token: str, folder_name: str, **kwargs) -> LROPoller[None]:
179
    """
180
    Begin restoring from a full HSM backup.
181
    
182
    Parameters:
183
    - blob_storage_url: str, URL of the Azure Blob Storage container
184
    - sas_token: str, SAS token for accessing the storage container  
185
    - folder_name: str, name of the backup folder to restore from
186
    - use_managed_identity: bool, whether to use managed identity for storage access
187
    
188
    Returns:
189
    LROPoller[None]: Long-running operation for the restore
190
    """
191
```
192

193
## Administration Types
194

195
```python { .api }
196
# Role assignment models
197
class KeyVaultRoleAssignment:
198
    assignment_id: str
199
    name: str  
200
    properties: KeyVaultRoleAssignmentProperties
201
    role_definition_id: str
202
    scope: str
203
    type: str
204

205
class KeyVaultRoleAssignmentProperties:
206
    principal_id: str
207
    role_definition_id: str
208
    scope: str
209

210
# Role definition models
211
class KeyVaultRoleDefinition:
212
    assignable_scopes: List[str]
213
    description: str
214
    id: str
215
    name: str
216
    permissions: List[KeyVaultPermission]
217
    role_name: str
218
    role_type: str
219
    type: str
220

221
class KeyVaultPermission:
222
    actions: List[str]
223
    data_actions: List[KeyVaultDataAction]
224
    not_actions: List[str]
225
    not_data_actions: List[KeyVaultDataAction]
226

227
# Backup models
228
class KeyVaultBackupResult:
229
    folder_url: str
230
    start_time: datetime
231
    end_time: datetime
232

233
# Enums
234
class KeyVaultRoleScope(str, Enum):
235
    GLOBAL = "/"
236
    KEYS = "/keys"
237

238
class KeyVaultDataAction(str, Enum):
239
    # HSM key operations
240
    READ_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/read/action"
241
    WRITE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/write/action"
242
    DELETE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/delete/action"
243
    ENCRYPT_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/encrypt/action"
244
    DECRYPT_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/decrypt/action"
245
    SIGN_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/sign/action"
246
    VERIFY_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/verify/action"
247
    WRAP_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/wrap/action"
248
    UNWRAP_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/unwrap/action"
249
    CREATE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/create"
250
    IMPORT_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/import/action"
251
    EXPORT_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/export/action"
252
    RELEASE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/release/action"
253
    ROTATE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/rotate/action"
254
    BACKUP_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/backup/action"
255
    RESTORE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/restore/action"
256
    RECOVER_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/recover/action"
257
    PURGE_HSM_KEY = "Microsoft.KeyVault/managedHsm/keys/purge/action"
258
    
259
    # Role management
260
    READ_ROLE_DEFINITION = "Microsoft.KeyVault/managedHsm/roleDefinitions/read/action"
261
    WRITE_ROLE_DEFINITION = "Microsoft.KeyVault/managedHsm/roleDefinitions/write/action"
262
    DELETE_ROLE_DEFINITION = "Microsoft.KeyVault/managedHsm/roleDefinitions/delete/action"
263
    READ_ROLE_ASSIGNMENT = "Microsoft.KeyVault/managedHsm/roleAssignments/read/action"
264
    WRITE_ROLE_ASSIGNMENT = "Microsoft.KeyVault/managedHsm/roleAssignments/write/action"
265
    DELETE_ROLE_ASSIGNMENT = "Microsoft.KeyVault/managedHsm/roleAssignments/delete/action"
266
    
267
    # Backup operations  
268
    START_BACKUP = "Microsoft.KeyVault/managedHsm/backup/start/action"
269
    START_RESTORE = "Microsoft.KeyVault/managedHsm/restore/start/action"
270
    READ_BACKUP_STATUS = "Microsoft.KeyVault/managedHsm/backup/status/action"
271
    READ_RESTORE_STATUS = "Microsoft.KeyVault/managedHsm/restore/status/action"
272
```
273

274
## Usage Examples
275

276
### Setting up RBAC for HSM
277

278
```python
279
from azure.keyvault.administration import KeyVaultAccessControlClient
280
from azure.keyvault.administration import KeyVaultRoleScope, KeyVaultDataAction, KeyVaultPermission
281
from azure.identity import DefaultAzureCredential
282

283
# Initialize client
284
credential = DefaultAzureCredential()
285
client = KeyVaultAccessControlClient(
286
    vault_url="https://my-hsm.managedhsm.azure.net/",
287
    credential=credential
288
)
289

290
# Create a custom role for key operations
291
permissions = [KeyVaultPermission(
292
    data_actions=[
293
        KeyVaultDataAction.READ_HSM_KEY,
294
        KeyVaultDataAction.ENCRYPT_HSM_KEY,
295
        KeyVaultDataAction.DECRYPT_HSM_KEY
296
    ]
297
)]
298

299
role_definition = client.set_role_definition(
300
    role_scope=KeyVaultRoleScope.KEYS,
301
    role_name="KeyOperator",
302
    description="Can read and use keys for crypto operations",
303
    permissions=permissions
304
)
305

306
# Assign the role to a user
307
assignment = client.create_role_assignment(
308
    role_scope=KeyVaultRoleScope.KEYS,
309
    role_definition_id=role_definition.id,
310
    principal_id="user-object-id-here"
311
)
312
```
313

314
### HSM Backup and Restore
315

316
```python
317
from azure.keyvault.administration import KeyVaultBackupClient
318
from azure.identity import DefaultAzureCredential
319

320
# Initialize backup client
321
credential = DefaultAzureCredential()
322
backup_client = KeyVaultBackupClient(
323
    vault_url="https://my-hsm.managedhsm.azure.net/",
324
    credential=credential
325
)
326

327
# Start backup operation
328
backup_operation = backup_client.begin_backup(
329
    blob_storage_url="https://mystorageaccount.blob.core.windows.net/backups",
330
    sas_token="?sv=2019-12-12&ss=b&srt=sco&sp=rwdlacx&se=..."
331
)
332

333
# Wait for completion
334
backup_result = backup_operation.result()
335
print(f"Backup completed: {backup_result.folder_url}")
336

337
# Restore from backup
338
restore_operation = backup_client.begin_restore(
339
    blob_storage_url="https://mystorageaccount.blob.core.windows.net/backups",
340
    sas_token="?sv=2019-12-12&ss=b&srt=sco&sp=rwdlacx&se=...",
341
    folder_name="backup-folder-name"
342
)
343

344
restore_operation.result()  # Wait for restore to complete
345
```