0
# Authentication Guide
1

2
Azure Container Instance Management Client uses Azure Active Directory (Azure AD) for authentication. This guide covers all supported authentication methods and configuration options.
3

4
## Prerequisites
5

6
- Azure subscription
7
- Appropriate Azure roles (Contributor or Container Instance Contributor)
8
- Python 3.7+ and `azure-identity` package installed
9

10
```bash
11
pip install azure-identity
12
```
13

14
## Authentication Methods
15

16
### Default Azure Credential (Recommended) { .api }
17

18
```python
19
from azure.identity import DefaultAzureCredential
20
from azure.mgmt.containerinstance import ContainerInstanceManagementClient
21
import os
22

23
def create_client_with_default_credential():
24
    """
25
    Create client using DefaultAzureCredential - tries multiple auth methods in sequence.
26
    
27
    Authentication chain:
28
    1. Environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET)
29
    2. Managed Identity (when running on Azure services)
30
    3. Azure CLI (when logged in via 'az login')
31
    4. Azure PowerShell
32
    5. Interactive browser login
33
    
34
    Returns:
35
        ContainerInstanceManagementClient: Authenticated client instance
36
    """
37
    
38
    # Get subscription ID from environment
39
    subscription_id = os.getenv("AZURE_SUBSCRIPTION_ID")
40
    if not subscription_id:
41
        raise ValueError("AZURE_SUBSCRIPTION_ID environment variable is required")
42
    
43
    # Create credential
44
    credential = DefaultAzureCredential()
45
    
46
    # Create client
47
    client = ContainerInstanceManagementClient(
48
        credential=credential,
49
        subscription_id=subscription_id
50
    )
51
    
52
    return client
53

54
# Usage
55
client = create_client_with_default_credential()
56
```
57

58
### Service Principal Authentication { .api }
59

60
```python
61
from azure.identity import ClientSecretCredential
62
from azure.mgmt.containerinstance import ContainerInstanceManagementClient
63

64
def create_client_with_service_principal(tenant_id, client_id, client_secret, subscription_id):
65
    """
66
    Create client using service principal credentials.
67
    
68
    Args:
69
        tenant_id (str): Azure AD tenant ID
70
        client_id (str): Application (client) ID of the service principal
71
        client_secret (str): Client secret of the service principal
72
        subscription_id (str): Azure subscription ID
73
        
74
    Returns:
75
        ContainerInstanceManagementClient: Authenticated client instance
76
        
77
    Example:
78
        client = create_client_with_service_principal(
79
            tenant_id="your-tenant-id",
80
            client_id="your-client-id", 
81
            client_secret="your-client-secret",
82
            subscription_id="your-subscription-id"
83
        )
84
    """
85
    
86
    credential = ClientSecretCredential(
87
        tenant_id=tenant_id,
88
        client_id=client_id,
89
        client_secret=client_secret
90
    )
91
    
92
    client = ContainerInstanceManagementClient(
93
        credential=credential,
94
        subscription_id=subscription_id
95
    )
96
    
97
    return client
98

99
# Usage with environment variables
100
import os
101
client = create_client_with_service_principal(
102
    tenant_id=os.getenv("AZURE_TENANT_ID"),
103
    client_id=os.getenv("AZURE_CLIENT_ID"),
104
    client_secret=os.getenv("AZURE_CLIENT_SECRET"),
105
    subscription_id=os.getenv("AZURE_SUBSCRIPTION_ID")
106
)
107
```
108

109
### Certificate-Based Authentication { .api }
110

111
```python
112
from azure.identity import CertificateCredential
113
from azure.mgmt.containerinstance import ContainerInstanceManagementClient
114

115
def create_client_with_certificate(tenant_id, client_id, certificate_path, subscription_id):
116
    """
117
    Create client using certificate-based authentication.
118
    
119
    Args:
120
        tenant_id (str): Azure AD tenant ID
121
        client_id (str): Application (client) ID
122
        certificate_path (str): Path to certificate file (.pem or .pfx)
123
        subscription_id (str): Azure subscription ID
124
        
125
    Returns:
126
        ContainerInstanceManagementClient: Authenticated client instance
127
        
128
    Example:
129
        client = create_client_with_certificate(
130
            tenant_id="your-tenant-id",
131
            client_id="your-client-id",
132
            certificate_path="/path/to/cert.pem",
133
            subscription_id="your-subscription-id"
134
        )
135
    """
136
    
137
    credential = CertificateCredential(
138
        tenant_id=tenant_id,
139
        client_id=client_id,
140
        certificate_path=certificate_path
141
    )
142
    
143
    client = ContainerInstanceManagementClient(
144
        credential=credential,
145
        subscription_id=subscription_id
146
    )
147
    
148
    return client
149
```
150

151
### Managed Identity Authentication { .api }
152

153
```python
154
from azure.identity import ManagedIdentityCredential
155
from azure.mgmt.containerinstance import ContainerInstanceManagementClient
156

157
def create_client_with_managed_identity(subscription_id, client_id=None):
158
    """
159
    Create client using Managed Identity (for Azure-hosted applications).
160
    
161
    Args:
162
        subscription_id (str): Azure subscription ID
163
        client_id (str, optional): Client ID of user-assigned managed identity
164
        
165
    Returns:
166
        ContainerInstanceManagementClient: Authenticated client instance
167
        
168
    Example:
169
        # System-assigned managed identity
170
        client = create_client_with_managed_identity("your-subscription-id")
171
        
172
        # User-assigned managed identity
173
        client = create_client_with_managed_identity(
174
            subscription_id="your-subscription-id",
175
            client_id="managed-identity-client-id"
176
        )
177
    """
178
    
179
    if client_id:
180
        # User-assigned managed identity
181
        credential = ManagedIdentityCredential(client_id=client_id)
182
    else:
183
        # System-assigned managed identity
184
        credential = ManagedIdentityCredential()
185
    
186
    client = ContainerInstanceManagementClient(
187
        credential=credential,
188
        subscription_id=subscription_id
189
    )
190
    
191
    return client
192

193
# Usage in Azure-hosted environment (VM, App Service, etc.)
194
client = create_client_with_managed_identity(
195
    subscription_id=os.getenv("AZURE_SUBSCRIPTION_ID")
196
)
197
```
198

199
### Interactive Browser Authentication { .api }
200

201
```python
202
from azure.identity import InteractiveBrowserCredential
203
from azure.mgmt.containerinstance import ContainerInstanceManagementClient
204

205
def create_client_with_browser_auth(tenant_id, subscription_id):
206
    """
207
    Create client using interactive browser authentication.
208
    
209
    Args:
210
        tenant_id (str): Azure AD tenant ID
211
        subscription_id (str): Azure subscription ID
212
        
213
    Returns:
214
        ContainerInstanceManagementClient: Authenticated client instance
215
        
216
    Note:
217
        This method opens a web browser for user authentication.
218
        Suitable for development and interactive scenarios.
219
        
220
    Example:
221
        client = create_client_with_browser_auth(
222
            tenant_id="your-tenant-id",
223
            subscription_id="your-subscription-id"
224
        )
225
    """
226
    
227
    credential = InteractiveBrowserCredential(tenant_id=tenant_id)
228
    
229
    client = ContainerInstanceManagementClient(
230
        credential=credential,
231
        subscription_id=subscription_id
232
    )
233
    
234
    return client
235
```
236

237
## Client Configuration Options
238

239
### Custom Base URL { .api }
240

241
```python
242
def create_client_with_custom_endpoint(credential, subscription_id, base_url):
243
    """
244
    Create client with custom Azure endpoint (for sovereign clouds).
245
    
246
    Args:
247
        credential: Azure credential object
248
        subscription_id (str): Azure subscription ID
249
        base_url (str): Custom Azure Resource Manager endpoint
250
        
251
    Returns:
252
        ContainerInstanceManagementClient: Client configured for custom endpoint
253
        
254
    Example:
255
        # Azure Government Cloud
256
        client = create_client_with_custom_endpoint(
257
            credential=DefaultAzureCredential(),
258
            subscription_id="your-subscription-id",
259
            base_url="https://management.usgovcloudapi.net"
260
        )
261
        
262
        # Azure China Cloud
263
        client = create_client_with_custom_endpoint(
264
            credential=DefaultAzureCredential(),
265
            subscription_id="your-subscription-id", 
266
            base_url="https://management.chinacloudapi.cn"
267
        )
268
    """
269
    
270
    client = ContainerInstanceManagementClient(
271
        credential=credential,
272
        subscription_id=subscription_id,
273
        base_url=base_url
274
    )
275
    
276
    return client
277
```
278

279
### API Version Configuration { .api }
280

281
```python
282
def create_client_with_api_version(credential, subscription_id, api_version):
283
    """
284
    Create client with specific API version.
285
    
286
    Args:
287
        credential: Azure credential object
288
        subscription_id (str): Azure subscription ID
289
        api_version (str): Azure Container Instance API version
290
        
291
    Returns:
292
        ContainerInstanceManagementClient: Client configured for specific API version
293
        
294
    Example:
295
        client = create_client_with_api_version(
296
            credential=DefaultAzureCredential(),
297
            subscription_id="your-subscription-id",
298
            api_version="2023-05-01"
299
        )
300
    """
301
    
302
    client = ContainerInstanceManagementClient(
303
        credential=credential,
304
        subscription_id=subscription_id,
305
        api_version=api_version
306
    )
307
    
308
    return client
309
```
310

311
## Environment Variable Setup
312

313
### Required Environment Variables
314

315
```bash
316
# Service Principal Authentication
317
export AZURE_CLIENT_ID="your-client-id"
318
export AZURE_CLIENT_SECRET="your-client-secret"  
319
export AZURE_TENANT_ID="your-tenant-id"
320
export AZURE_SUBSCRIPTION_ID="your-subscription-id"
321

322
# Alternative for certificate-based auth
323
export AZURE_CLIENT_CERTIFICATE_PATH="/path/to/certificate.pem"
324
export AZURE_CLIENT_CERTIFICATE_PASSWORD="certificate-password"  # if encrypted
325
```
326

327
### Environment Configuration Script
328

329
```python
330
import os
331
from azure.identity import DefaultAzureCredential
332
from azure.mgmt.containerinstance import ContainerInstanceManagementClient
333

334
def validate_environment_and_create_client():
335
    """
336
    Validate required environment variables and create authenticated client.
337
    
338
    Returns:
339
        ContainerInstanceManagementClient: Authenticated client instance
340
        
341
    Raises:
342
        ValueError: If required environment variables are missing
343
    """
344
    
345
    # Check required variables
346
    subscription_id = os.getenv("AZURE_SUBSCRIPTION_ID")
347
    if not subscription_id:
348
        raise ValueError("AZURE_SUBSCRIPTION_ID environment variable is required")
349
    
350
    # Check for at least one authentication method
351
    has_service_principal = all([
352
        os.getenv("AZURE_CLIENT_ID"),
353
        os.getenv("AZURE_TENANT_ID"),
354
        os.getenv("AZURE_CLIENT_SECRET") or os.getenv("AZURE_CLIENT_CERTIFICATE_PATH")
355
    ])
356
    
357
    if not has_service_principal:
358
        print("Warning: Service principal environment variables not found.")
359
        print("Will attempt authentication via Azure CLI or interactive methods.")
360
    
361
    # Create client with DefaultAzureCredential
362
    credential = DefaultAzureCredential()
363
    client = ContainerInstanceManagementClient(
364
        credential=credential,
365
        subscription_id=subscription_id
366
    )
367
    
368
    # Test authentication
369
    try:
370
        # Attempt a simple API call to validate authentication
371
        list(client.container_groups.list())
372
        print("Authentication successful!")
373
    except Exception as e:
374
        print(f"Authentication failed: {e}")
375
        raise
376
    
377
    return client
378

379
# Usage
380
try:
381
    client = validate_environment_and_create_client()
382
    print("Client created successfully!")
383
except ValueError as e:
384
    print(f"Configuration error: {e}")
385
except Exception as e:
386
    print(f"Authentication error: {e}")
387
```
388

389
## Authentication Best Practices
390

391
### Production Environments
392

393
```python
394
def create_production_client():
395
    """
396
    Recommended authentication setup for production environments.
397
    
398
    Priority order:
399
    1. Managed Identity (preferred for Azure-hosted apps)
400
    2. Service Principal with certificate
401
    3. Service Principal with secret
402
    """
403
    
404
    subscription_id = os.getenv("AZURE_SUBSCRIPTION_ID")
405
    
406
    try:
407
        # Try Managed Identity first
408
        credential = ManagedIdentityCredential()
409
        client = ContainerInstanceManagementClient(credential, subscription_id)
410
        # Test the credential
411
        list(client.container_groups.list())
412
        print("Using Managed Identity authentication")
413
        return client
414
    except Exception:
415
        pass
416
    
417
    try:
418
        # Try certificate-based service principal
419
        if os.getenv("AZURE_CLIENT_CERTIFICATE_PATH"):
420
            credential = CertificateCredential(
421
                tenant_id=os.getenv("AZURE_TENANT_ID"),
422
                client_id=os.getenv("AZURE_CLIENT_ID"),
423
                certificate_path=os.getenv("AZURE_CLIENT_CERTIFICATE_PATH")
424
            )
425
            client = ContainerInstanceManagementClient(credential, subscription_id)
426
            print("Using certificate-based service principal authentication")
427
            return client
428
    except Exception:
429
        pass
430
    
431
    # Fallback to client secret
432
    credential = ClientSecretCredential(
433
        tenant_id=os.getenv("AZURE_TENANT_ID"),
434
        client_id=os.getenv("AZURE_CLIENT_ID"),
435
        client_secret=os.getenv("AZURE_CLIENT_SECRET")
436
    )
437
    client = ContainerInstanceManagementClient(credential, subscription_id)
438
    print("Using client secret service principal authentication")
439
    return client
440
```
441

442
### Development Environments
443

444
```python
445
def create_development_client():
446
    """
447
    Recommended authentication setup for development environments.
448
    """
449
    
450
    # Use DefaultAzureCredential for maximum flexibility
451
    credential = DefaultAzureCredential(
452
        # Enable logging for debugging authentication issues
453
        logging_enable=True
454
    )
455
    
456
    subscription_id = os.getenv("AZURE_SUBSCRIPTION_ID")
457
    client = ContainerInstanceManagementClient(credential, subscription_id)
458
    
459
    return client
460
```