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
```