0
# Azure Key Vault Certificates
1
2
A comprehensive Python client library for Azure Key Vault certificate management operations, enabling developers to securely create, store, manage, and deploy SSL/TLS certificates through Azure's cloud-based key management service. It offers both synchronous and asynchronous APIs for certificate lifecycle operations with extensive error handling and detailed logging capabilities.
3
4
## Package Information
5
6
- **Package Name**: azure-keyvault-certificates
7
- **Language**: Python
8
- **Installation**: `pip install azure-keyvault-certificates azure-identity`
9
10
## Core Imports
11
12
```python
13
from azure.keyvault.certificates import CertificateClient
14
from azure.identity import DefaultAzureCredential
15
```
16
17
Common models and enums:
18
19
```python
20
from azure.keyvault.certificates import (
21
CertificatePolicy,
22
KeyVaultCertificate,
23
CertificateProperties,
24
CertificateContentType,
25
KeyType,
26
WellKnownIssuerNames
27
)
28
```
29
30
For async operations:
31
32
```python
33
from azure.keyvault.certificates.aio import CertificateClient
34
```
35
36
## Basic Usage
37
38
```python
39
import os
40
from azure.identity import DefaultAzureCredential
41
from azure.keyvault.certificates import CertificateClient, CertificatePolicy
42
43
# Create client
44
VAULT_URL = os.environ["VAULT_URL"]
45
credential = DefaultAzureCredential()
46
client = CertificateClient(vault_url=VAULT_URL, credential=credential)
47
48
# Create a certificate
49
create_poller = client.begin_create_certificate(
50
certificate_name="my-certificate",
51
policy=CertificatePolicy.get_default()
52
)
53
certificate = create_poller.result()
54
55
# Get a certificate
56
certificate = client.get_certificate("my-certificate")
57
print(f"Certificate: {certificate.name}")
58
print(f"Version: {certificate.properties.version}")
59
60
# List all certificates
61
for cert_props in client.list_properties_of_certificates():
62
print(f"Certificate: {cert_props.name}")
63
64
# Update certificate properties
65
updated_cert = client.update_certificate_properties(
66
certificate_name="my-certificate",
67
enabled=False,
68
tags={"environment": "test"}
69
)
70
71
# Delete certificate
72
delete_poller = client.begin_delete_certificate("my-certificate")
73
deleted_cert = delete_poller.result()
74
```
75
76
## Architecture
77
78
The library follows Azure SDK design patterns with clear separation of concerns:
79
80
- **CertificateClient**: Primary interface for all certificate operations (sync and async versions)
81
- **Models**: Strongly-typed data structures for certificates, policies, issuers, and operations
82
- **Enums**: Type-safe constants for key types, content types, policy actions, and well-known issuers
83
- **Long-Running Operations**: Polling support for certificate creation, deletion, and recovery
84
- **Paging**: Efficient iteration over certificate collections with ItemPaged/AsyncItemPaged
85
86
The client integrates seamlessly with Azure identity services through DefaultAzureCredential for authentication, supports advanced certificate chain preservation, implements proper async context management patterns, and provides comprehensive error handling for production environments.
87
88
## Capabilities
89
90
### Certificate Lifecycle Management
91
92
Core certificate operations including creation, retrieval, updating, deletion, and recovery. Supports both self-signed certificates and external issuer integration with comprehensive policy management.
93
94
```python { .api }
95
def begin_create_certificate(
96
certificate_name: str,
97
policy: CertificatePolicy,
98
*,
99
enabled: Optional[bool] = None,
100
tags: Optional[Dict[str, str]] = None,
101
preserve_order: Optional[bool] = None
102
) -> LROPoller[Union[KeyVaultCertificate, CertificateOperation]]: ...
103
104
def get_certificate(certificate_name: str) -> KeyVaultCertificate: ...
105
106
def update_certificate_properties(
107
certificate_name: str,
108
version: Optional[str] = None,
109
*,
110
enabled: Optional[bool] = None,
111
tags: Optional[Dict[str, str]] = None
112
) -> KeyVaultCertificate: ...
113
114
def begin_delete_certificate(certificate_name: str) -> LROPoller[DeletedCertificate]: ...
115
```
116
117
[Certificate Operations](./certificate-operations.md)
118
119
### Certificate Import and Export
120
121
Import existing certificates from various formats and export certificates for external use. Supports PKCS#12 and PEM formats with backup and restore capabilities.
122
123
```python { .api }
124
def import_certificate(
125
certificate_name: str,
126
certificate_bytes: bytes,
127
*,
128
policy: Optional[CertificatePolicy] = None,
129
enabled: Optional[bool] = None,
130
tags: Optional[Dict[str, str]] = None,
131
preserve_order: Optional[bool] = None
132
) -> KeyVaultCertificate: ...
133
134
def backup_certificate(certificate_name: str) -> bytes: ...
135
136
def restore_certificate_backup(backup: bytes) -> KeyVaultCertificate: ...
137
```
138
139
[Import and Export](./import-export.md)
140
141
### Certificate Policy Management
142
143
Comprehensive policy configuration for certificate properties, key specifications, lifetime actions, and issuer settings. Supports custom policies and default policy templates.
144
145
```python { .api }
146
def get_certificate_policy(certificate_name: str) -> CertificatePolicy: ...
147
148
def update_certificate_policy(
149
certificate_name: str,
150
policy: CertificatePolicy
151
) -> CertificatePolicy: ...
152
```
153
154
[Policy Management](./policy-management.md)
155
156
### Certificate Issuer Management
157
158
Manage certificate authorities and issuers for automated certificate provisioning. Configure issuer credentials, organizational information, and administrator contacts.
159
160
```python { .api }
161
def create_issuer(
162
issuer_name: str,
163
provider: str,
164
*,
165
enabled: Optional[bool] = None,
166
account_id: Optional[str] = None,
167
password: Optional[str] = None,
168
organization_id: Optional[str] = None,
169
admin_contacts: Optional[List[AdministratorContact]] = None
170
) -> CertificateIssuer: ...
171
172
def get_issuer(issuer_name: str) -> CertificateIssuer: ...
173
174
def update_issuer(issuer_name: str, **kwargs) -> CertificateIssuer: ...
175
176
def delete_issuer(issuer_name: str) -> CertificateIssuer: ...
177
```
178
179
[Issuer Management](./issuer-management.md)
180
181
### Certificate Listing and Discovery
182
183
Efficiently browse and discover certificates with filtering, paging, and version management. List active certificates, deleted certificates, and certificate versions.
184
185
```python { .api }
186
def list_properties_of_certificates(
187
*,
188
include_pending: Optional[bool] = None,
189
max_page_size: Optional[int] = None
190
) -> ItemPaged[CertificateProperties]: ...
191
192
def list_deleted_certificates(
193
*, max_page_size: Optional[int] = None
194
) -> ItemPaged[DeletedCertificate]: ...
195
196
def list_properties_of_certificate_versions(
197
certificate_name: str,
198
*, max_page_size: Optional[int] = None
199
) -> ItemPaged[CertificateProperties]: ...
200
```
201
202
[Listing Operations](./listing-operations.md)
203
204
### Deleted Certificate Recovery
205
206
Manage soft-deleted certificates with recovery and purge operations. Supports Azure Key Vault's soft-delete feature for accidental deletion protection.
207
208
```python { .api }
209
def get_deleted_certificate(certificate_name: str) -> DeletedCertificate: ...
210
211
def begin_recover_deleted_certificate(
212
certificate_name: str
213
) -> LROPoller[KeyVaultCertificate]: ...
214
215
def purge_deleted_certificate(certificate_name: str) -> None: ...
216
```
217
218
[Recovery Operations](./recovery-operations.md)
219
220
### Certificate Contact Management
221
222
Manage certificate contacts for notifications and administrative purposes. Configure email contacts for certificate lifecycle events and expiration warnings.
223
224
```python { .api }
225
def set_contacts(contacts: List[CertificateContact]) -> List[CertificateContact]: ...
226
227
def get_contacts() -> List[CertificateContact]: ...
228
229
def delete_contacts() -> List[CertificateContact]: ...
230
```
231
232
[Contact Management](./contact-management.md)
233
234
### Certificate Operation Management
235
236
Monitor and manage long-running certificate operations including creation status, cancellation, and manual certificate merging for external issuers.
237
238
```python { .api }
239
def get_certificate_operation(certificate_name: str) -> CertificateOperation: ...
240
241
def cancel_certificate_operation(certificate_name: str) -> CertificateOperation: ...
242
243
def delete_certificate_operation(certificate_name: str) -> CertificateOperation: ...
244
245
def merge_certificate(
246
certificate_name: str,
247
x509_certificates: List[bytes],
248
*,
249
enabled: Optional[bool] = None,
250
tags: Optional[Dict[str, str]] = None
251
) -> KeyVaultCertificate: ...
252
```
253
254
[Operation Management](./operation-management.md)
255
256
### Async Operations
257
258
Asynchronous versions of all certificate operations for high-performance applications. Includes async context managers and direct async results for long-running operations.
259
260
```python { .api }
261
async def create_certificate(
262
certificate_name: str,
263
policy: CertificatePolicy,
264
**kwargs
265
) -> Union[KeyVaultCertificate, CertificateOperation]: ...
266
267
async def get_certificate(certificate_name: str) -> KeyVaultCertificate: ...
268
```
269
270
[Async Operations](./async-operations.md)
271
272
## Types
273
274
### Core Certificate Types
275
276
```python { .api }
277
class KeyVaultCertificate:
278
"""Represents a certificate stored in Azure Key Vault."""
279
id: str
280
name: str
281
properties: CertificateProperties
282
policy: CertificatePolicy
283
cer: bytes
284
key_id: str
285
secret_id: str
286
287
class CertificateProperties:
288
"""Certificate metadata and properties."""
289
id: str
290
name: str
291
version: str
292
enabled: bool
293
not_before: datetime
294
expires_on: datetime
295
created_on: datetime
296
updated_on: datetime
297
recovery_level: str
298
vault_url: str
299
tags: Dict[str, str]
300
x509_thumbprint: bytes
301
302
class DeletedCertificate(KeyVaultCertificate):
303
"""A deleted certificate with recovery information."""
304
deleted_on: datetime
305
recovery_id: str
306
scheduled_purge_date: datetime
307
```
308
309
### Certificate Policy Types
310
311
```python { .api }
312
class CertificatePolicy:
313
"""Certificate management policy."""
314
issuer_name: str
315
subject: str
316
san_emails: List[str]
317
san_dns_names: List[str]
318
san_upns: List[str]
319
exportable: bool
320
key_type: KeyType
321
key_size: int
322
reuse_key: bool
323
key_curve_name: KeyCurveName
324
enhanced_key_usage: List[str]
325
key_usage: List[KeyUsageType]
326
content_type: CertificateContentType
327
validity_in_months: int
328
lifetime_actions: List[LifetimeAction]
329
certificate_type: str
330
certificate_transparency: bool
331
332
@classmethod
333
def get_default() -> CertificatePolicy: ...
334
335
class LifetimeAction:
336
"""Automated action for certificate lifecycle."""
337
action: CertificatePolicyAction
338
days_before_expiry: int
339
percentage_before_expiry: int
340
```
341
342
### Certificate Operation Types
343
344
```python { .api }
345
class CertificateOperation:
346
"""Long-running certificate operation."""
347
certificate_type: str
348
certificate_transparency: bool
349
csr: bytes
350
cancellation_requested: bool
351
status: str
352
status_details: str
353
error: CertificateOperationError
354
target: str
355
request_id: str
356
id: str
357
issuer_name: str
358
359
class CertificateOperationError:
360
"""Certificate operation error details."""
361
code: str
362
message: str
363
inner_error: CertificateOperationError
364
```
365
366
### Issuer Types
367
368
```python { .api }
369
class CertificateIssuer:
370
"""Certificate issuer configuration."""
371
provider: str
372
account_id: str
373
admin_contacts: List[AdministratorContact]
374
enabled: bool
375
created_on: datetime
376
updated_on: datetime
377
id: str
378
name: str
379
380
class IssuerProperties:
381
"""Certificate issuer basic properties."""
382
id: str
383
name: str
384
provider: str
385
386
class AdministratorContact:
387
"""Issuer administrator contact."""
388
first_name: str
389
last_name: str
390
email: str
391
phone: str
392
```
393
394
### Contact Types
395
396
```python { .api }
397
class CertificateContact:
398
"""Certificate contact information."""
399
email: str
400
name: str
401
phone: str
402
```
403
404
### Identifier Types
405
406
```python { .api }
407
class KeyVaultCertificateIdentifier:
408
"""Certificate identifier parser."""
409
source_id: str
410
vault_url: str
411
name: str
412
version: str
413
414
@classmethod
415
def from_certificate_id(cls, certificate_id: str) -> KeyVaultCertificateIdentifier: ...
416
```
417
418
### Enum Types
419
420
```python { .api }
421
class ApiVersion(str, Enum):
422
"""Supported API versions."""
423
V7_6 = "7.6" # Default
424
V7_5 = "7.5"
425
V7_4 = "7.4"
426
V7_3 = "7.3"
427
V7_2 = "7.2"
428
V7_1 = "7.1"
429
V7_0 = "7.0"
430
V2016_10_01 = "2016-10-01"
431
432
class KeyType(str, Enum):
433
"""Supported key types."""
434
ec = "EC"
435
ec_hsm = "EC-HSM"
436
rsa = "RSA"
437
rsa_hsm = "RSA-HSM"
438
oct = "oct"
439
oct_hsm = "oct-HSM"
440
441
class KeyCurveName(str, Enum):
442
"""Elliptic curve names."""
443
p_256 = "P-256"
444
p_384 = "P-384"
445
p_521 = "P-521"
446
p_256_k = "P-256K"
447
448
class CertificateContentType(str, Enum):
449
"""Certificate content formats."""
450
pkcs12 = "application/x-pkcs12"
451
pem = "application/x-pem-file"
452
453
class KeyUsageType(str, Enum):
454
"""Key usage types."""
455
digital_signature = "digitalSignature"
456
non_repudiation = "nonRepudiation"
457
key_encipherment = "keyEncipherment"
458
data_encipherment = "dataEncipherment"
459
key_agreement = "keyAgreement"
460
key_cert_sign = "keyCertSign"
461
crl_sign = "cRLSign"
462
encipher_only = "encipherOnly"
463
decipher_only = "decipherOnly"
464
465
class CertificatePolicyAction(str, Enum):
466
"""Certificate policy actions."""
467
email_contacts = "EmailContacts"
468
auto_renew = "AutoRenew"
469
470
class WellKnownIssuerNames(str, Enum):
471
"""Well-known certificate issuers."""
472
self = "Self"
473
unknown = "Unknown"
474
```