0
# Security Management
1
2
Comprehensive security management including X.509 certificate operations, shared access signature key management, and certificate verification workflows for device authentication. This module enables secure device-to-cloud and cloud-to-device communications through multiple authentication mechanisms.
3
4
## Capabilities
5
6
### Shared Access Signature Key Management
7
8
Management of shared access signature authorization rules that control access to IoT Hub operations with granular permission control.
9
10
```python { .api }
11
def list_keys(resource_group_name: str, resource_name: str, **kwargs) -> ItemPaged[SharedAccessSignatureAuthorizationRule]:
12
"""
13
Get security metadata for IoT hub including all shared access policies.
14
15
Args:
16
resource_group_name: Name of the resource group
17
resource_name: Name of the IoT hub resource
18
19
Returns:
20
ItemPaged[SharedAccessSignatureAuthorizationRule]: All access policies with keys and permissions
21
"""
22
23
def get_keys_for_key_name(
24
resource_group_name: str,
25
resource_name: str,
26
key_name: str,
27
**kwargs
28
) -> SharedAccessSignatureAuthorizationRule:
29
"""
30
Get shared access policy by name from IoT hub.
31
32
Args:
33
resource_group_name: Name of the resource group
34
resource_name: Name of the IoT hub resource
35
key_name: Name of the access policy
36
37
Returns:
38
SharedAccessSignatureAuthorizationRule: Access policy with keys and permissions
39
"""
40
```
41
42
### X.509 Certificate Management
43
44
Comprehensive X.509 certificate lifecycle management for device authentication including upload, verification, and deletion operations.
45
46
```python { .api }
47
def list_by_iot_hub(resource_group_name: str, resource_name: str, **kwargs) -> CertificateListDescription:
48
"""
49
Get list of certificates for IoT hub.
50
51
Args:
52
resource_group_name: Name of the resource group
53
resource_name: Name of the IoT hub resource
54
55
Returns:
56
CertificateListDescription: List of all certificates with metadata
57
"""
58
59
def get(
60
resource_group_name: str,
61
resource_name: str,
62
certificate_name: str,
63
**kwargs
64
) -> CertificateDescription:
65
"""
66
Get specific certificate details.
67
68
Args:
69
resource_group_name: Name of the resource group
70
resource_name: Name of the IoT hub resource
71
certificate_name: Name of the certificate
72
73
Returns:
74
CertificateDescription: Certificate details and metadata
75
"""
76
77
def create_or_update(
78
resource_group_name: str,
79
resource_name: str,
80
certificate_name: str,
81
certificate_description: CertificateDescription,
82
if_match: Optional[str] = None,
83
**kwargs
84
) -> CertificateDescription:
85
"""
86
Upload certificate to IoT hub - add new or replace existing certificate.
87
88
Args:
89
resource_group_name: Name of the resource group
90
resource_name: Name of the IoT hub resource
91
certificate_name: Name for the certificate
92
certificate_description: Certificate data and configuration
93
if_match: ETag for conditional updates (optional)
94
95
Returns:
96
CertificateDescription: Uploaded certificate details
97
"""
98
99
def delete(
100
resource_group_name: str,
101
resource_name: str,
102
certificate_name: str,
103
if_match: str,
104
**kwargs
105
) -> None:
106
"""
107
Delete X509 certificate.
108
109
Args:
110
resource_group_name: Name of the resource group
111
resource_name: Name of the IoT hub resource
112
certificate_name: Name of the certificate to delete
113
if_match: ETag for conditional deletion (required)
114
"""
115
```
116
117
### Certificate Verification Workflow
118
119
Proof of possession verification workflow for X.509 certificates to ensure certificate ownership before enabling device authentication.
120
121
```python { .api }
122
def generate_verification_code(
123
resource_group_name: str,
124
resource_name: str,
125
certificate_name: str,
126
if_match: str,
127
**kwargs
128
) -> CertificateWithNonceDescription:
129
"""
130
Generate verification code for proof of possession flow.
131
132
Args:
133
resource_group_name: Name of the resource group
134
resource_name: Name of the IoT hub resource
135
certificate_name: Name of the certificate
136
if_match: ETag for conditional operation (required)
137
138
Returns:
139
CertificateWithNonceDescription: Certificate details with verification code
140
"""
141
142
def verify(
143
resource_group_name: str,
144
resource_name: str,
145
certificate_name: str,
146
if_match: str,
147
certificate_verification_body: CertificateVerificationDescription,
148
**kwargs
149
) -> CertificateDescription:
150
"""
151
Verify certificate's private key possession.
152
153
Args:
154
resource_group_name: Name of the resource group
155
resource_name: Name of the IoT hub resource
156
certificate_name: Name of the certificate
157
if_match: ETag for conditional operation (required)
158
certificate_verification_body: Verification certificate signed with private key
159
160
Returns:
161
CertificateDescription: Verified certificate details
162
"""
163
```
164
165
## Usage Examples
166
167
### Managing shared access keys
168
169
```python
170
from azure.identity import DefaultAzureCredential
171
from azure.mgmt.iothub import IotHubClient
172
173
credential = DefaultAzureCredential()
174
client = IotHubClient(credential, "subscription-id")
175
176
# List all access policies
177
policies = list(client.iot_hub_resource.list_keys("my-resource-group", "my-iot-hub"))
178
179
for policy in policies:
180
print(f"Policy: {policy.key_name}")
181
print(f" Rights: {policy.rights}")
182
print(f" Primary Key: {policy.primary_key[:10]}...")
183
print(f" Secondary Key: {policy.secondary_key[:10]}...")
184
185
# Get specific policy
186
service_policy = client.iot_hub_resource.get_keys_for_key_name(
187
"my-resource-group",
188
"my-iot-hub",
189
"service"
190
)
191
print(f"Service policy has rights: {service_policy.rights}")
192
```
193
194
### Uploading and managing certificates
195
196
```python
197
from azure.mgmt.iothub.models import CertificateDescription, CertificateBodyDescription
198
199
# Read certificate from file
200
with open("device-ca.pem", "r") as cert_file:
201
cert_content = cert_file.read()
202
203
# Create certificate description
204
cert_body = CertificateBodyDescription(certificate=cert_content)
205
cert_description = CertificateDescription(properties=cert_body)
206
207
# Upload certificate
208
uploaded_cert = client.certificates.create_or_update(
209
"my-resource-group",
210
"my-iot-hub",
211
"device-ca-cert",
212
cert_description
213
)
214
215
print(f"Uploaded certificate: {uploaded_cert.name}")
216
print(f"Subject: {uploaded_cert.properties.subject}")
217
print(f"Thumbprint: {uploaded_cert.properties.thumbprint}")
218
print(f"Is Verified: {uploaded_cert.properties.is_verified}")
219
```
220
221
### Certificate verification workflow
222
223
```python
224
from azure.mgmt.iothub.models import CertificateVerificationDescription
225
226
# Step 1: Generate verification code
227
verification_cert = client.certificates.generate_verification_code(
228
"my-resource-group",
229
"my-iot-hub",
230
"device-ca-cert",
231
uploaded_cert.etag
232
)
233
234
print(f"Verification code: {verification_cert.properties.verification_code}")
235
236
# Step 2: Create leaf certificate signed with private key
237
# (This step happens outside of Azure - you create a leaf certificate
238
# with the verification code as the subject, signed with your private key)
239
240
# Step 3: Upload verification certificate
241
with open("verification-cert.pem", "r") as verify_file:
242
verify_cert_content = verify_file.read()
243
244
verification_body = CertificateVerificationDescription(
245
certificate=verify_cert_content
246
)
247
248
# Step 4: Complete verification
249
verified_cert = client.certificates.verify(
250
"my-resource-group",
251
"my-iot-hub",
252
"device-ca-cert",
253
verification_cert.etag,
254
verification_body
255
)
256
257
print(f"Certificate verified: {verified_cert.properties.is_verified}")
258
```
259
260
### Certificate lifecycle management
261
262
```python
263
# List all certificates
264
cert_list = client.certificates.list_by_iot_hub("my-resource-group", "my-iot-hub")
265
266
for cert in cert_list.value:
267
print(f"Certificate: {cert.name}")
268
print(f" Subject: {cert.properties.subject}")
269
print(f" Expiry: {cert.properties.expiry_time_utc}")
270
print(f" Verified: {cert.properties.is_verified}")
271
272
# Check if certificate is expiring soon
273
if cert.properties.expiry_time_utc:
274
days_until_expiry = (cert.properties.expiry_time_utc - datetime.utcnow()).days
275
if days_until_expiry < 30:
276
print(f" WARNING: Certificate expires in {days_until_expiry} days!")
277
278
# Delete expired certificates
279
expired_cert = client.certificates.get("my-resource-group", "my-iot-hub", "old-cert")
280
if expired_cert.properties.expiry_time_utc < datetime.utcnow():
281
client.certificates.delete(
282
"my-resource-group",
283
"my-iot-hub",
284
"old-cert",
285
expired_cert.etag
286
)
287
print("Deleted expired certificate")
288
```
289
290
## Types
291
292
```python { .api }
293
class SharedAccessSignatureAuthorizationRule:
294
"""
295
Shared access signature authorization rule.
296
297
Attributes:
298
key_name: Policy name (required)
299
primary_key: Primary access key
300
secondary_key: Secondary access key
301
rights: Access permissions (required)
302
"""
303
key_name: str
304
primary_key: Optional[str]
305
secondary_key: Optional[str]
306
rights: AccessRights
307
308
class CertificateDescription:
309
"""
310
X.509 certificate representation.
311
312
Attributes:
313
properties: Certificate properties and metadata
314
name: Certificate name (readonly)
315
etag: ETag for concurrency control (readonly)
316
type: Resource type (readonly)
317
"""
318
properties: Optional[CertificateProperties]
319
name: Optional[str]
320
etag: Optional[str]
321
type: Optional[str]
322
323
class CertificateProperties:
324
"""
325
X.509 certificate properties.
326
327
Attributes:
328
subject: Certificate subject (readonly)
329
expiry_time_utc: Certificate expiration time (readonly)
330
thumbprint: Certificate thumbprint (readonly)
331
is_verified: Whether certificate ownership is verified (readonly)
332
created: Certificate creation time (readonly)
333
updated: Certificate last update time (readonly)
334
certificate: Certificate content for upload
335
"""
336
subject: Optional[str]
337
expiry_time_utc: Optional[datetime]
338
thumbprint: Optional[str]
339
is_verified: Optional[bool]
340
created: Optional[datetime]
341
updated: Optional[datetime]
342
certificate: Optional[str]
343
344
class CertificateBodyDescription:
345
"""
346
Certificate upload payload.
347
348
Attributes:
349
certificate: Base64 encoded certificate content (required)
350
"""
351
certificate: str
352
353
class CertificateWithNonceDescription:
354
"""
355
Certificate with verification code.
356
357
Attributes:
358
properties: Certificate properties including verification code
359
name: Certificate name (readonly)
360
etag: ETag for concurrency control (readonly)
361
type: Resource type (readonly)
362
"""
363
properties: Optional[CertificatePropertiesWithNonce]
364
name: Optional[str]
365
etag: Optional[str]
366
type: Optional[str]
367
368
class CertificatePropertiesWithNonce:
369
"""
370
Certificate properties with verification code.
371
372
Attributes:
373
subject: Certificate subject (readonly)
374
expiry_time_utc: Certificate expiration time (readonly)
375
thumbprint: Certificate thumbprint (readonly)
376
is_verified: Whether certificate ownership is verified (readonly)
377
created: Certificate creation time (readonly)
378
updated: Certificate last update time (readonly)
379
verification_code: Code for proof of possession verification (readonly)
380
certificate: Certificate content
381
"""
382
subject: Optional[str]
383
expiry_time_utc: Optional[datetime]
384
thumbprint: Optional[str]
385
is_verified: Optional[bool]
386
created: Optional[datetime]
387
updated: Optional[datetime]
388
verification_code: Optional[str]
389
certificate: Optional[str]
390
391
class CertificateVerificationDescription:
392
"""
393
Certificate verification payload.
394
395
Attributes:
396
certificate: Verification certificate signed with private key (required)
397
"""
398
certificate: str
399
400
class CertificateListDescription:
401
"""
402
List of certificates.
403
404
Attributes:
405
value: Array of certificate descriptions
406
"""
407
value: Optional[List[CertificateDescription]]
408
```