0
# Policy Management
1
2
Certificate policy configuration and management for controlling certificate properties, key specifications, lifetime actions, and issuer settings. Policies define how certificates are created, renewed, and managed throughout their lifecycle.
3
4
## Capabilities
5
6
### Certificate Policy Retrieval
7
8
Get the current policy for a certificate to understand its configuration and management settings.
9
10
```python { .api }
11
def get_certificate_policy(certificate_name: str, **kwargs: Any) -> CertificatePolicy:
12
"""
13
Get the policy for a certificate.
14
15
Parameters:
16
- certificate_name: The name of the certificate
17
18
Returns:
19
CertificatePolicy: The certificate's management policy
20
21
Raises:
22
ResourceNotFoundError: If the certificate doesn't exist
23
HttpResponseError: For service-side errors
24
"""
25
```
26
27
### Certificate Policy Updates
28
29
Update the management policy for an existing certificate. Policy changes affect future operations and renewals.
30
31
```python { .api }
32
def update_certificate_policy(
33
certificate_name: str,
34
policy: CertificatePolicy,
35
**kwargs: Any
36
) -> CertificatePolicy:
37
"""
38
Update the policy for a certificate.
39
40
Parameters:
41
- certificate_name: The name of the certificate
42
- policy: The updated certificate policy
43
44
Returns:
45
CertificatePolicy: The updated policy
46
47
Raises:
48
ResourceNotFoundError: If the certificate doesn't exist
49
ValidationError: If the policy is invalid
50
HttpResponseError: For service-side errors
51
"""
52
```
53
54
## Policy Configuration
55
56
### Default Policy Creation
57
58
```python
59
from azure.keyvault.certificates import CertificatePolicy
60
61
# Get default policy
62
default_policy = CertificatePolicy.get_default()
63
print(f"Default issuer: {default_policy.issuer_name}")
64
print(f"Default key type: {default_policy.key_type}")
65
print(f"Default validity: {default_policy.validity_in_months} months")
66
```
67
68
### Custom Policy Creation
69
70
```python
71
from azure.keyvault.certificates import (
72
CertificatePolicy,
73
KeyType,
74
CertificateContentType,
75
KeyUsageType,
76
CertificatePolicyAction,
77
LifetimeAction,
78
WellKnownIssuerNames
79
)
80
81
# Create custom policy
82
custom_policy = CertificatePolicy(
83
issuer_name=WellKnownIssuerNames.self,
84
subject="CN=myapp.example.com",
85
san_dns_names=["myapp.example.com", "www.myapp.example.com"],
86
exportable=True,
87
key_type=KeyType.rsa,
88
key_size=2048,
89
reuse_key=False,
90
content_type=CertificateContentType.pkcs12,
91
validity_in_months=12,
92
key_usage=[
93
KeyUsageType.digital_signature,
94
KeyUsageType.key_encipherment
95
]
96
)
97
98
# Add lifetime action for auto-renewal
99
lifetime_action = LifetimeAction(
100
action=CertificatePolicyAction.auto_renew,
101
days_before_expiry=30
102
)
103
custom_policy.lifetime_actions = [lifetime_action]
104
```
105
106
### Subject Alternative Names (SAN) Configuration
107
108
```python
109
# DNS names
110
policy = CertificatePolicy.get_default()
111
policy.san_dns_names = [
112
"api.example.com",
113
"www.api.example.com",
114
"staging.api.example.com"
115
]
116
117
# Email addresses
118
policy.san_emails = [
119
"admin@example.com",
120
"security@example.com"
121
]
122
123
# User Principal Names (for internal certificates)
124
policy.san_upns = [
125
"service@company.com",
126
"app@company.com"
127
]
128
```
129
130
### Key Configuration
131
132
```python
133
# RSA key configuration
134
policy = CertificatePolicy.get_default()
135
policy.key_type = KeyType.rsa
136
policy.key_size = 4096 # Higher security
137
policy.reuse_key = False # Generate new key for each renewal
138
139
# Elliptic Curve key configuration
140
from azure.keyvault.certificates import KeyCurveName
141
142
policy.key_type = KeyType.ec
143
policy.key_curve_name = KeyCurveName.p_384
144
policy.key_usage = [
145
KeyUsageType.digital_signature,
146
KeyUsageType.key_agreement
147
]
148
149
# HSM-backed keys (for enhanced security)
150
policy.key_type = KeyType.rsa_hsm
151
policy.key_size = 2048
152
```
153
154
### Lifetime Actions Configuration
155
156
```python
157
# Auto-renewal 30 days before expiry
158
auto_renew_action = LifetimeAction(
159
action=CertificatePolicyAction.auto_renew,
160
days_before_expiry=30
161
)
162
163
# Email notification 60 days before expiry
164
email_action = LifetimeAction(
165
action=CertificatePolicyAction.email_contacts,
166
days_before_expiry=60
167
)
168
169
# Percentage-based trigger (e.g., at 80% of certificate lifetime)
170
percentage_action = LifetimeAction(
171
action=CertificatePolicyAction.email_contacts,
172
percentage_before_expiry=20 # 20% remaining = 80% expired
173
)
174
175
policy.lifetime_actions = [email_action, auto_renew_action]
176
```
177
178
## Usage Examples
179
180
### Complete Policy Management Workflow
181
182
```python
183
from azure.keyvault.certificates import CertificateClient, CertificatePolicy
184
185
# Create comprehensive policy
186
def create_production_policy(domain_name, additional_domains=None):
187
"""Create a production-ready certificate policy."""
188
189
policy = CertificatePolicy(
190
issuer_name=WellKnownIssuerNames.self, # Or external issuer
191
subject=f"CN={domain_name}",
192
exportable=True,
193
key_type=KeyType.rsa,
194
key_size=2048,
195
reuse_key=False,
196
content_type=CertificateContentType.pkcs12,
197
validity_in_months=12,
198
key_usage=[
199
KeyUsageType.digital_signature,
200
KeyUsageType.key_encipherment
201
]
202
)
203
204
# Configure SAN
205
san_domains = [domain_name]
206
if additional_domains:
207
san_domains.extend(additional_domains)
208
policy.san_dns_names = san_domains
209
210
# Configure lifetime actions
211
policy.lifetime_actions = [
212
LifetimeAction(
213
action=CertificatePolicyAction.email_contacts,
214
days_before_expiry=60
215
),
216
LifetimeAction(
217
action=CertificatePolicyAction.auto_renew,
218
days_before_expiry=30
219
)
220
]
221
222
return policy
223
224
# Create and apply policy
225
production_policy = create_production_policy(
226
"myapp.example.com",
227
["api.myapp.example.com", "www.myapp.example.com"]
228
)
229
230
# Create certificate with custom policy
231
create_poller = client.begin_create_certificate(
232
certificate_name="production-cert",
233
policy=production_policy
234
)
235
certificate = create_poller.result()
236
```
237
238
### Policy Inspection and Updates
239
240
```python
241
# Get and inspect current policy
242
current_policy = client.get_certificate_policy("production-cert")
243
244
print(f"Current issuer: {current_policy.issuer_name}")
245
print(f"Key type: {current_policy.key_type}")
246
print(f"Key size: {current_policy.key_size}")
247
print(f"Validity period: {current_policy.validity_in_months} months")
248
print(f"SAN DNS names: {current_policy.san_dns_names}")
249
print(f"Lifetime actions: {len(current_policy.lifetime_actions)}")
250
251
# Update policy to extend validity
252
current_policy.validity_in_months = 24 # 2 years
253
254
# Add email notification earlier
255
early_warning = LifetimeAction(
256
action=CertificatePolicyAction.email_contacts,
257
days_before_expiry=90
258
)
259
current_policy.lifetime_actions.insert(0, early_warning)
260
261
# Apply updated policy
262
updated_policy = client.update_certificate_policy(
263
certificate_name="production-cert",
264
policy=current_policy
265
)
266
267
print("Policy updated successfully")
268
```
269
270
### Policy Templates
271
272
```python
273
class CertificatePolicyTemplates:
274
"""Common certificate policy templates."""
275
276
@staticmethod
277
def web_server_ssl(domain, additional_domains=None):
278
"""Policy for web server SSL certificates."""
279
policy = CertificatePolicy.get_default()
280
policy.subject = f"CN={domain}"
281
policy.san_dns_names = [domain] + (additional_domains or [])
282
policy.key_type = KeyType.rsa
283
policy.key_size = 2048
284
policy.validity_in_months = 12
285
policy.key_usage = [
286
KeyUsageType.digital_signature,
287
KeyUsageType.key_encipherment
288
]
289
return policy
290
291
@staticmethod
292
def code_signing():
293
"""Policy for code signing certificates."""
294
policy = CertificatePolicy.get_default()
295
policy.key_type = KeyType.rsa
296
policy.key_size = 4096
297
policy.validity_in_months = 36
298
policy.key_usage = [KeyUsageType.digital_signature]
299
policy.enhanced_key_usage = ["1.3.6.1.5.5.7.3.3"] # Code signing OID
300
return policy
301
302
@staticmethod
303
def client_authentication(user_principal_name):
304
"""Policy for client authentication certificates."""
305
policy = CertificatePolicy.get_default()
306
policy.subject = f"CN={user_principal_name}"
307
policy.san_upns = [user_principal_name]
308
policy.key_type = KeyType.rsa
309
policy.key_size = 2048
310
policy.validity_in_months = 12
311
policy.key_usage = [
312
KeyUsageType.digital_signature,
313
KeyUsageType.key_agreement
314
]
315
return policy
316
317
# Usage
318
ssl_policy = CertificatePolicyTemplates.web_server_ssl(
319
"myapp.com",
320
["www.myapp.com", "api.myapp.com"]
321
)
322
323
code_sign_policy = CertificatePolicyTemplates.code_signing()
324
325
client_policy = CertificatePolicyTemplates.client_authentication(
326
"user@company.com"
327
)
328
```
329
330
### Policy Validation
331
332
```python
333
def validate_policy(policy):
334
"""Validate certificate policy configuration."""
335
issues = []
336
337
# Check required fields
338
if not policy.subject and not policy.san_dns_names:
339
issues.append("Either subject or SAN DNS names must be specified")
340
341
# Check key configuration
342
if policy.key_type == KeyType.rsa and policy.key_size < 2048:
343
issues.append("RSA key size should be at least 2048 bits")
344
345
# Check validity period
346
if policy.validity_in_months > 39:
347
issues.append("Validity period over 39 months may not be supported by some CAs")
348
349
# Check lifetime actions
350
if policy.lifetime_actions:
351
for action in policy.lifetime_actions:
352
if (action.days_before_expiry and
353
action.days_before_expiry > policy.validity_in_months * 30):
354
issues.append(f"Lifetime action triggers before certificate is issued")
355
356
return issues
357
358
# Validate before applying
359
issues = validate_policy(custom_policy)
360
if issues:
361
print("Policy validation issues:")
362
for issue in issues:
363
print(f"- {issue}")
364
else:
365
print("Policy validation passed")
366
```