0
# Secret Management
1

2
Secure storage and retrieval of sensitive data in Azure Key Vault. Supports text-based secrets with version management, expiration policies, access control, and content type specifications. Provides complete lifecycle management including creation, updating, soft deletion, and recovery.
3

4
## Capabilities
5

6
### Secret Client
7

8
Main client for secret management operations with synchronous and asynchronous support.
9

10
```python { .api }
11
class SecretClient:
12
    def __init__(self, vault_url: str, credential, **kwargs):
13
        """
14
        Initialize SecretClient for secret management operations.
15
        
16
        Parameters:
17
        - vault_url: str, Key Vault URL (https://vault-name.vault.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
### Secret Creation and Updates
28

29
Store and update secrets in the vault.
30

31
```python { .api }
32
def set_secret(self, name: str, value: str, **kwargs) -> KeyVaultSecret:
33
    """
34
    Create or update a secret in the Key Vault.
35
    
36
    Parameters:
37
    - name: str, unique secret name within the vault
38
    - value: str, secret value to store
39
    - content_type: str, MIME type or description of secret content
40
    - enabled: bool, whether secret is enabled for use
41
    - expires_on: datetime, expiration date
42
    - not_before: datetime, activation date
43
    - tags: Dict[str, str], custom metadata
44
    
45
    Returns:
46
    KeyVaultSecret with secret metadata (value not included)
47
    """
48
```
49

50
### Secret Retrieval
51

52
Retrieve secrets and their versions from the vault.
53

54
```python { .api }
55
def get_secret(self, name: str, version: str = None, **kwargs) -> KeyVaultSecret:
56
    """
57
    Get a secret from the vault.
58
    
59
    Parameters:
60
    - name: str, secret name
61
    - version: str, specific version (default: latest)
62
    
63
    Returns:
64
    KeyVaultSecret with secret value and metadata
65
    """
66

67
def list_properties_of_secrets(**kwargs) -> ItemPaged[SecretProperties]:
68
    """
69
    List all secrets in the vault.
70
    
71
    Parameters:
72
    - max_page_size: int, maximum items per page
73
    
74
    Returns:
75
    Paginated list of SecretProperties (values not included)
76
    """
77

78
def list_properties_of_secret_versions(self, name: str, **kwargs) -> ItemPaged[SecretProperties]:
79
    """
80
    List all versions of a specific secret.
81
    
82
    Parameters:
83
    - name: str, secret name
84
    - max_page_size: int, maximum items per page
85
    
86
    Returns:
87
    Paginated list of SecretProperties for all versions
88
    """
89
```
90

91
### Secret Operations
92

93
Update properties, delete, and manage secret lifecycle.
94

95
```python { .api }
96
def update_secret_properties(self, name: str, version: str = None, **kwargs) -> SecretProperties:
97
    """
98
    Update secret properties and metadata.
99
    
100
    Parameters:
101
    - name: str, secret name
102
    - version: str, specific version (default: latest)
103
    - content_type: str, MIME type or description
104
    - enabled: bool, enable/disable secret
105
    - expires_on: datetime, expiration date
106
    - not_before: datetime, activation date
107
    - tags: Dict[str, str], custom metadata
108
    
109
    Returns:
110
    SecretProperties with updated properties
111
    """
112

113
def begin_delete_secret(self, name: str, **kwargs) -> LROPoller[DeletedSecret]:
114
    """
115
    Delete a secret (soft delete) - long-running operation.
116
    
117
    Parameters:
118
    - name: str, secret name to delete
119
    
120
    Returns:
121
    LROPoller[DeletedSecret] for tracking deletion progress
122
    """
123

124
def get_deleted_secret(self, name: str, **kwargs) -> DeletedSecret:
125
    """
126
    Get properties of a deleted secret.
127
    
128
    Parameters:
129
    - name: str, deleted secret name
130
    
131
    Returns:
132
    DeletedSecret with deletion information and value
133
    """
134

135
def begin_recover_deleted_secret(self, name: str, **kwargs) -> LROPoller[KeyVaultSecret]:
136
    """
137
    Recover a deleted secret - long-running operation.
138
    
139
    Parameters:
140
    - name: str, deleted secret name
141
    
142
    Returns:
143
    LROPoller[KeyVaultSecret] for tracking recovery progress
144
    """
145

146
def purge_deleted_secret(self, name: str, **kwargs) -> None:
147
    """
148
    Permanently delete a secret.
149
    
150
    Parameters:
151
    - name: str, deleted secret name to purge
152
    """
153

154
def list_deleted_secrets(**kwargs) -> ItemPaged[DeletedSecret]:
155
    """
156
    List all deleted secrets.
157
    
158
    Returns:
159
    Paginated list of DeletedSecret objects
160
    """
161
```
162

163
### Secret Backup and Restore
164

165
Backup and restore secrets for disaster recovery.
166

167
```python { .api }
168
def backup_secret(self, name: str, **kwargs) -> bytes:
169
    """
170
    Create backup of a secret.
171
    
172
    Parameters:
173
    - name: str, secret name to backup
174
    
175
    Returns:
176
    bytes containing encrypted backup data
177
    """
178

179
def restore_secret_backup(self, backup: bytes, **kwargs) -> SecretProperties:
180
    """
181
    Restore secret from backup.
182
    
183
    Parameters:
184
    - backup: bytes, backup data from backup_secret()
185
    
186
    Returns:
187
    SecretProperties with restored secret metadata
188
    """
189
```
190

191
## Secret Model Classes
192

193
```python { .api }
194
class KeyVaultSecret:
195
    """Represents a secret stored in Azure Key Vault."""
196
    id: str
197
    name: str
198
    properties: SecretProperties
199
    value: str  # Only populated when retrieving secret value
200

201
class SecretProperties:
202
    """Secret metadata and properties."""
203
    id: str
204
    name: str
205
    version: str
206
    enabled: bool
207
    expires_on: datetime
208
    not_before: datetime
209
    created_on: datetime
210
    updated_on: datetime
211
    recovery_level: str
212
    vault_url: str
213
    content_type: str
214
    tags: Dict[str, str]
215

216
class DeletedSecret:
217
    """Represents a deleted secret."""
218
    id: str
219
    name: str
220
    properties: SecretProperties
221
    value: str
222
    deleted_on: datetime
223
    recovery_id: str
224
    scheduled_purge_date: datetime
225

226
class KeyVaultSecretIdentifier:
227
    """Identifier for Key Vault secrets."""
228
    source_id: str
229
    vault_url: str
230
    name: str
231
    version: str
232
```
233

234
## Usage Examples
235

236
### Basic Secret Management
237

238
```python
239
from azure.keyvault.secrets import SecretClient
240
from azure.identity import DefaultAzureCredential
241

242
# Initialize client
243
credential = DefaultAzureCredential()
244
client = SecretClient(vault_url="https://vault-name.vault.azure.net/", credential=credential)
245

246
# Store a secret
247
secret = client.set_secret("database-password", "super-secret-password")
248
print(f"Stored secret: {secret.name} (ID: {secret.id})")
249

250
# Retrieve secret value
251
retrieved_secret = client.get_secret("database-password")
252
print(f"Secret value: {retrieved_secret.value}")
253

254
# List all secrets
255
for secret_properties in client.list_properties_of_secrets():
256
    print(f"Secret: {secret_properties.name}")
257
```
258

259
### Secret with Metadata
260

261
```python
262
from datetime import datetime, timedelta
263

264
# Store secret with metadata and expiration
265
expiry_date = datetime.utcnow() + timedelta(days=365)
266

267
secret = client.set_secret(
268
    name="api-key",
269
    value="sk-1234567890abcdef",
270
    content_type="text/plain",
271
    expires_on=expiry_date,
272
    tags={
273
        "environment": "production",
274
        "service": "payment-api",
275
        "owner": "team-alpha"
276
    }
277
)
278

279
# Update secret properties
280
updated_properties = client.update_secret_properties(
281
    name="api-key",
282
    tags={
283
        "environment": "production", 
284
        "service": "payment-api",
285
        "owner": "team-beta",  # Changed owner
286
        "last-rotated": "2024-01-15"
287
    }
288
)
289
```
290

291
### Secret Versioning
292

293
```python
294
# Create initial version
295
secret_v1 = client.set_secret("connection-string", "Server=old-server;Database=app")
296

297
# Update secret (creates new version)
298
secret_v2 = client.set_secret("connection-string", "Server=new-server;Database=app")
299

300
# Get latest version
301
latest_secret = client.get_secret("connection-string")
302

303
# Get specific version
304
specific_secret = client.get_secret("connection-string", version=secret_v1.properties.version)
305

306
# List all versions
307
for version_properties in client.list_properties_of_secret_versions("connection-string"):
308
    print(f"Version: {version_properties.version}, Created: {version_properties.created_on}")
309
```
310

311
### Backup and Recovery
312

313
```python
314
# Backup secret
315
backup_data = client.backup_secret("important-secret")
316

317
# Delete secret (soft delete)
318
delete_poller = client.begin_delete_secret("important-secret")
319
deleted_secret = delete_poller.result()  # Wait for completion
320
print(f"Secret deleted on: {deleted_secret.deleted_on}")
321

322
# Restore from backup
323
restored_properties = client.restore_secret_backup(backup_data)
324

325
# Or recover deleted secret
326
recover_poller = client.begin_recover_deleted_secret("important-secret")
327
recovered_secret = recover_poller.result()  # Wait for completion
328

329
# Permanently delete
330
client.purge_deleted_secret("important-secret")
331
```
332

333
### Working with Different Content Types
334

335
```python
336
# JSON configuration
337
config = {
338
    "database_url": "postgresql://user:pass@host:5432/db",
339
    "redis_url": "redis://localhost:6379/0",
340
    "debug": False
341
}
342

343
client.set_secret(
344
    name="app-config",
345
    value=json.dumps(config),
346
    content_type="application/json"
347
)
348

349
# Certificate/PEM data
350
cert_data = """-----BEGIN CERTIFICATE-----
351
MIIDXTCCAkWgAwIBAgIJAKoK/heBjcOuMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV
352
...
353
-----END CERTIFICATE-----"""
354

355
client.set_secret(
356
    name="ssl-certificate", 
357
    value=cert_data,
358
    content_type="application/x-pem-file"
359
)
360

361
# Connection string
362
client.set_secret(
363
    name="storage-connection",
364
    value="DefaultEndpointsProtocol=https;AccountName=...",
365
    content_type="text/plain"
366
)
367
```
368

369
### Async Secret Operations
370

371
```python
372
from azure.keyvault.secrets.aio import SecretClient
373
import asyncio
374

375
async def manage_secrets():
376
    credential = DefaultAzureCredential()
377
    client = SecretClient(vault_url="https://vault-name.vault.azure.net/", credential=credential)
378
    
379
    try:
380
        # Async secret operations
381
        secret = await client.set_secret("async-secret", "async-value")
382
        retrieved = await client.get_secret("async-secret")
383
        
384
        # Async iteration
385
        async for secret_properties in client.list_properties_of_secrets():
386
            print(f"Secret: {secret_properties.name}")
387
            
388
    finally:
389
        await client.close()
390

391
# Run async function
392
asyncio.run(manage_secrets())
393
```