0
# Certificate Operations
1
2
Certificate management capabilities for adding, listing, and managing certificates used for authentication and secure communication in batch operations. Certificates enable secure access to external resources and can be installed on compute nodes for task execution.
3
4
## Capabilities
5
6
### Certificate Management
7
8
Add, list, retrieve, and delete certificates in the batch account.
9
10
```python { .api }
11
def add(certificate, certificate_add_options=None, custom_headers=None, raw=False, **operation_config):
12
"""
13
Add a certificate to the specified account.
14
15
Args:
16
certificate: The certificate to add (CertificateAddParameter)
17
certificate_add_options: Additional options for the operation
18
custom_headers: Custom headers to include in request
19
raw: Return raw response if True
20
21
Returns:
22
None
23
"""
24
25
def list(certificate_list_options=None, custom_headers=None, raw=False, **operation_config):
26
"""
27
List all certificates in the account.
28
29
Args:
30
certificate_list_options: Additional options for listing certificates
31
32
Returns:
33
ItemPaged[Certificate]: Paginated list of certificates
34
"""
35
36
def get(thumbprint_algorithm, thumbprint, certificate_get_options=None, custom_headers=None, raw=False, **operation_config):
37
"""
38
Get information about the specified certificate.
39
40
Args:
41
thumbprint_algorithm: Algorithm used for the thumbprint (typically 'sha1')
42
thumbprint: Thumbprint of the certificate
43
certificate_get_options: Additional options for the operation
44
45
Returns:
46
Certificate: Certificate information
47
"""
48
49
def delete(thumbprint_algorithm, thumbprint, certificate_delete_options=None, custom_headers=None, raw=False, **operation_config):
50
"""
51
Delete the specified certificate.
52
53
Args:
54
thumbprint_algorithm: Algorithm used for the thumbprint
55
thumbprint: Thumbprint of the certificate to delete
56
certificate_delete_options: Additional options for deletion
57
58
Returns:
59
None
60
"""
61
62
def cancel_deletion(thumbprint_algorithm, thumbprint, certificate_cancel_deletion_options=None, custom_headers=None, raw=False, **operation_config):
63
"""
64
Cancel a failed deletion of a certificate.
65
66
This can be used to cancel the deletion of a certificate if the delete operation
67
encountered an error (such as being used by a pool or compute node).
68
69
Args:
70
thumbprint_algorithm: Algorithm used for the thumbprint
71
thumbprint: Thumbprint of the certificate
72
certificate_cancel_deletion_options: Additional options
73
74
Returns:
75
None
76
"""
77
```
78
79
## Usage Examples
80
81
### Adding Certificates
82
83
```python
84
from azure.batch.models import CertificateAddParameter
85
import base64
86
87
# Add a PFX certificate with password
88
with open("mycert.pfx", "rb") as cert_file:
89
cert_data = base64.b64encode(cert_file.read()).decode('utf-8')
90
91
pfx_cert = CertificateAddParameter(
92
thumbprint="abcdef1234567890abcdef1234567890abcdef12",
93
thumbprint_algorithm="sha1",
94
data=cert_data,
95
certificate_format="pfx",
96
password="certificate_password"
97
)
98
99
client.certificate.add(pfx_cert)
100
101
# Add a CER certificate (public key only, no password)
102
with open("mycert.cer", "rb") as cert_file:
103
cert_data = base64.b64encode(cert_file.read()).decode('utf-8')
104
105
cer_cert = CertificateAddParameter(
106
thumbprint="1234567890abcdef1234567890abcdef12345678",
107
thumbprint_algorithm="sha1",
108
data=cert_data,
109
certificate_format="cer"
110
)
111
112
client.certificate.add(cer_cert)
113
```
114
115
### Listing and Retrieving Certificates
116
117
```python
118
# List all certificates
119
certificates = client.certificate.list()
120
for cert in certificates:
121
print(f"Certificate: {cert.thumbprint}")
122
print(f" State: {cert.state}")
123
print(f" Format: {cert.certificate_format}")
124
print(f" Subject: {cert.subject_name}")
125
if cert.delete_certificate_error:
126
print(f" Delete Error: {cert.delete_certificate_error.message}")
127
128
# Get specific certificate details
129
cert = client.certificate.get("sha1", "abcdef1234567890abcdef1234567890abcdef12")
130
print(f"Certificate Subject: {cert.subject_name}")
131
print(f"Expiry Date: {cert.expiry_date}")
132
print(f"State: {cert.state}")
133
```
134
135
### Using Certificates in Pool Configuration
136
137
```python
138
from azure.batch.models import (
139
PoolSpecification, CertificateReference,
140
CertificateStoreLocation, CertificateVisibility
141
)
142
143
# Reference certificates in pool configuration
144
cert_refs = [
145
CertificateReference(
146
thumbprint="abcdef1234567890abcdef1234567890abcdef12",
147
thumbprint_algorithm="sha1",
148
store_location="localmachine", # localmachine or currentuser (Windows)
149
store_name="My", # Certificate store name
150
visibility=["starttask", "task", "remoteuser"] # Who can access the cert
151
)
152
]
153
154
pool_spec = PoolSpecification(
155
id="secure-pool",
156
vm_size="Standard_D2s_v3",
157
target_dedicated_nodes=2,
158
certificate_references=cert_refs
159
)
160
161
client.pool.add(pool_spec)
162
```
163
164
### Managing Certificate Lifecycle
165
166
```python
167
# Check certificate state and handle deletion errors
168
cert = client.certificate.get("sha1", "abcdef1234567890abcdef1234567890abcdef12")
169
170
if cert.state == "deletefailed":
171
print("Certificate deletion failed, canceling deletion")
172
client.certificate.cancel_deletion("sha1", "abcdef1234567890abcdef1234567890abcdef12")
173
174
# Try deleting again after a delay
175
import time
176
time.sleep(30)
177
client.certificate.delete("sha1", "abcdef1234567890abcdef1234567890abcdef12")
178
179
elif cert.state == "active":
180
print("Certificate is active and ready to use")
181
182
elif cert.state == "deleting":
183
print("Certificate deletion in progress")
184
```
185
186
### Certificate Filtering and Management
187
188
```python
189
from azure.batch.models import CertificateListOptions
190
191
# List certificates with filtering
192
list_options = CertificateListOptions(
193
filter="state eq 'active'", # Only active certificates
194
select="thumbprint,state,subjectName", # Specific properties only
195
max_results=50
196
)
197
198
active_certs = client.certificate.list(list_options)
199
for cert in active_certs:
200
print(f"Active Certificate: {cert.thumbprint} - {cert.subject_name}")
201
202
# Batch certificate cleanup
203
def cleanup_expired_certificates():
204
"""Remove certificates that are expired or in error state."""
205
certificates = client.certificate.list()
206
207
for cert in certificates:
208
try:
209
if cert.state in ["deletefailed", "inactive"]:
210
print(f"Attempting to delete certificate: {cert.thumbprint}")
211
212
if cert.state == "deletefailed":
213
# Cancel previous failed deletion first
214
client.certificate.cancel_deletion(
215
cert.thumbprint_algorithm, cert.thumbprint
216
)
217
time.sleep(5)
218
219
# Delete the certificate
220
client.certificate.delete(cert.thumbprint_algorithm, cert.thumbprint)
221
222
except Exception as e:
223
print(f"Failed to delete certificate {cert.thumbprint}: {e}")
224
225
# Usage
226
cleanup_expired_certificates()
227
```
228
229
## Types
230
231
### Certificate Information Types
232
233
```python { .api }
234
class Certificate:
235
"""Certificate information and state."""
236
def __init__(self):
237
self.thumbprint: str
238
self.thumbprint_algorithm: str
239
self.url: str
240
self.state: str # active, deleting, deletefailed
241
self.state_transition_time: datetime.datetime
242
self.public_data: str
243
self.certificate_format: str # pfx, cer
244
self.provisioning_state: str
245
self.provisioning_state_transition_time: datetime.datetime
246
self.previous_provisioning_state: str
247
self.previous_provisioning_state_transition_time: datetime.datetime
248
self.subject_name: str
249
self.expiry_date: datetime.datetime
250
self.delete_certificate_error: DeleteCertificateError
251
252
class CertificateAddParameter:
253
"""Parameters for adding a certificate."""
254
def __init__(self):
255
self.thumbprint: str
256
self.thumbprint_algorithm: str
257
self.data: str # Base64 encoded certificate data
258
self.certificate_format: str # pfx, cer
259
self.password: str # Required for PFX certificates
260
261
class CertificateReference:
262
"""Reference to a certificate for use in pools/tasks."""
263
def __init__(self):
264
self.thumbprint: str
265
self.thumbprint_algorithm: str
266
self.store_location: str # localmachine, currentuser
267
self.store_name: str
268
self.visibility: List[str] # starttask, task, remoteuser
269
270
class DeleteCertificateError:
271
"""Error information for failed certificate deletion."""
272
def __init__(self):
273
self.code: str
274
self.message: str
275
self.values: List[NameValuePair]
276
```
277
278
### Certificate Operation Option Types
279
280
```python { .api }
281
class CertificateListOptions:
282
"""Options for listing certificates."""
283
def __init__(self):
284
self.filter: str
285
self.select: str
286
self.max_results: int
287
self.timeout: int
288
289
class CertificateGetOptions:
290
"""Options for getting certificate information."""
291
def __init__(self):
292
self.select: str
293
self.timeout: int
294
295
class CertificateAddOptions:
296
"""Options for adding certificates."""
297
def __init__(self):
298
self.timeout: int
299
300
class CertificateDeleteOptions:
301
"""Options for deleting certificates."""
302
def __init__(self):
303
self.timeout: int
304
305
class CertificateCancelDeletionOptions:
306
"""Options for canceling certificate deletion."""
307
def __init__(self):
308
self.timeout: int
309
```
310
311
## Notes
312
313
- Certificates must be in PFX or CER format and Base64 encoded
314
- PFX certificates can contain private keys and require a password
315
- CER certificates contain only public keys and don't require passwords
316
- Certificates are automatically deployed to compute nodes when referenced in pool configuration
317
- Certificate visibility controls which contexts can access the certificate (start task, regular tasks, remote users)
318
- Certificates in use by pools or nodes cannot be deleted until the resources are freed
319
- Use cancel_deletion to recover from failed deletion attempts