0
# MSAL - Microsoft Authentication Library
1

2
The Microsoft Authentication Library (MSAL) for Python enables your app to access the Microsoft Cloud by supporting authentication of users with Microsoft Azure Active Directory accounts (AAD), Microsoft Accounts (MSA), External identities, and Azure AD B2C accounts using industry standard OAuth2 and OpenID Connect protocols.
3

4
MSAL Python provides both public client applications for desktop/mobile scenarios and confidential client applications for server-side scenarios, with automatic token caching, refresh capabilities, broker support for enhanced security, and extensive configuration options for different authentication flows.
5

6
## Package Information
7

8
- **Package Name**: msal
9
- **Language**: Python
10
- **Installation**: `pip install msal`
11
- **Optional broker support**: `pip install msal[broker]`
12

13
## Core Imports
14

15
```python
16
import msal
17
```
18

19
Common imports for different application types:
20

21
```python
22
from msal import PublicClientApplication, ConfidentialClientApplication
23
```
24

25
Token caching imports:
26

27
```python
28
from msal import TokenCache, SerializableTokenCache
29
```
30

31
Managed identity imports:
32

33
```python
34
from msal import ManagedIdentityClient, SystemAssignedManagedIdentity, UserAssignedManagedIdentity
35
```
36

37
Version information:
38

39
```python
40
import msal
41
print(msal.__version__)  # "1.33.0"
42
```
43

44
## Basic Usage
45

46
### Public Client Application (Desktop/Mobile)
47

48
```python
49
import msal
50

51
# Create a public client application
52
app = msal.PublicClientApplication(
53
    client_id="your-client-id",
54
    authority="https://login.microsoftonline.com/your-tenant-id"
55
)
56

57
# Get accounts from cache
58
accounts = app.get_accounts()
59

60
# Try silent authentication first
61
result = None
62
if accounts:
63
    result = app.acquire_token_silent(
64
        scopes=["User.Read"],
65
        account=accounts[0]
66
    )
67

68
# If silent fails, use interactive authentication
69
if not result:
70
    result = app.acquire_token_interactive(
71
        scopes=["User.Read"]
72
    )
73

74
if "access_token" in result:
75
    print("Authentication successful!")
76
    print(f"Access token: {result['access_token'][:20]}...")
77
else:
78
    print(f"Authentication failed: {result.get('error_description')}")
79
```
80

81
### Confidential Client Application (Server-side)
82

83
```python
84
import msal
85

86
# Create a confidential client application
87
app = msal.ConfidentialClientApplication(
88
    client_id="your-client-id",
89
    client_credential="your-client-secret",
90
    authority="https://login.microsoftonline.com/your-tenant-id"
91
)
92

93
# Acquire token for client (Client Credentials flow)
94
result = app.acquire_token_for_client(
95
    scopes=["https://graph.microsoft.com/.default"]
96
)
97

98
if "access_token" in result:
99
    print("Authentication successful!")
100
    access_token = result["access_token"]
101
else:
102
    print(f"Authentication failed: {result.get('error_description')}")
103
```
104

105
## Architecture
106

107
MSAL Python follows the OAuth2/OIDC protocol specifications with Microsoft identity platform extensions:
108

109
- **Application Types**: PublicClientApplication for native apps, ConfidentialClientApplication for server apps
110
- **Token Management**: Automatic caching, refresh, and persistence with TokenCache/SerializableTokenCache
111
- **Authentication Flows**: Interactive, device flow, authorization code, username/password, client credentials, on-behalf-of
112
- **Security Features**: Proof-of-Possession tokens, broker integration, certificate-based authentication
113
- **Azure Integration**: Managed identity support, Azure AD B2C, multi-tenant applications
114

115
The library handles protocol complexities like token refresh, scope validation, and error handling while providing a simple, consistent API across different authentication scenarios.
116

117
## Capabilities
118

119
### Public Client Applications
120

121
Desktop and mobile application authentication with interactive browser flows, device code authentication for browserless devices, and optional broker integration for enhanced security through device identity.
122

123
```python { .api }
124
class PublicClientApplication(ClientApplication):
125
    def __init__(
126
        self,
127
        client_id: str,
128
        client_credential=None,
129
        *,
130
        enable_broker_on_windows=None,
131
        enable_broker_on_mac=None,
132
        enable_broker_on_linux=None,
133
        enable_broker_on_wsl=None,
134
        **kwargs
135
    ): ...
136
    
137
    def acquire_token_interactive(
138
        self,
139
        scopes: list,
140
        prompt=None,
141
        login_hint=None,
142
        domain_hint=None,
143
        claims_challenge=None,
144
        timeout=None,
145
        port=None,
146
        extra_scopes_to_consent=None,
147
        max_age=None,
148
        parent_window_handle=None,
149
        on_before_launching_ui=None,
150
        auth_scheme=None,
151
        **kwargs
152
    ): ...
153
    
154
    def initiate_device_flow(self, scopes=None, **kwargs): ...
155
    
156
    def acquire_token_by_device_flow(self, flow, claims_challenge=None, **kwargs): ...
157
```
158

159
[Public Client Applications](./public-client.md)
160

161
### Confidential Client Applications
162

163
Server-side web application authentication with client credentials flow for service-to-service authentication, authorization code flow for web apps, and on-behalf-of flow for middle-tier services acting on behalf of users.
164

165
```python { .api }
166
class ConfidentialClientApplication(ClientApplication):
167
    def __init__(
168
        self,
169
        client_id: str,
170
        client_credential,
171
        authority=None,
172
        **kwargs
173
    ): ...
174
    
175
    def acquire_token_for_client(
176
        self,
177
        scopes: list,
178
        claims_challenge=None,
179
        **kwargs
180
    ): ...
181
    
182
    def acquire_token_on_behalf_of(
183
        self,
184
        user_assertion: str,
185
        scopes: list,
186
        claims_challenge=None,
187
        **kwargs
188
    ): ...
189
```
190

191
[Confidential Client Applications](./confidential-client.md)
192

193
### Token Caching
194

195
Unified token cache system supporting both in-memory caching for single-session applications and persistent caching for multi-session scenarios. Includes automatic token refresh, account management, and cross-application token sharing.
196

197
```python { .api }
198
class TokenCache:
199
    def __init__(self): ...
200
    
201
    def find(
202
        self,
203
        credential_type: str,
204
        target=None,
205
        query=None,
206
        now=None
207
    ) -> list: ...
208
    
209
    def add(self, event: dict, now=None): ...
210

211
class SerializableTokenCache(TokenCache):
212
    def serialize(self) -> str: ...
213
    
214
    def deserialize(self, state: str): ...
215
```
216

217
[Token Caching](./token-cache.md)
218

219
### Common Authentication Flows
220

221
Shared authentication functionality including silent token acquisition from cache, authorization code flow initiation and completion, username/password authentication, refresh token handling, and account management across all application types.
222

223
```python { .api }
224
class ClientApplication:
225
    def acquire_token_silent(
226
        self,
227
        scopes: list,
228
        account,
229
        authority=None,
230
        force_refresh=False,
231
        claims_challenge=None,
232
        **kwargs
233
    ): ...
234
    
235
    def initiate_auth_code_flow(
236
        self,
237
        scopes: list,
238
        redirect_uri=None,
239
        state=None,
240
        prompt=None,
241
        login_hint=None,
242
        **kwargs
243
    ): ...
244
    
245
    def acquire_token_by_auth_code_flow(
246
        self,
247
        auth_code_flow: dict,
248
        auth_response: dict,
249
        scopes=None,
250
        **kwargs
251
    ): ...
252
    
253
    def acquire_token_by_username_password(
254
        self,
255
        username: str,
256
        password: str,
257
        scopes: list,
258
        claims_challenge=None,
259
        auth_scheme=None,
260
        **kwargs
261
    ): ...
262
    
263
    def acquire_token_by_refresh_token(
264
        self,
265
        refresh_token: str,
266
        scopes: list,
267
        **kwargs
268
    ): ...
269
    
270
    def get_accounts(self, username=None) -> list: ...
271
    
272
    def remove_account(self, account): ...
273
```
274

275
[Common Authentication Flows](./common-auth-flows.md)
276

277
### Azure Managed Identity
278

279
Azure managed identity authentication for virtual machines, container instances, and other Azure services. Supports both system-assigned identities (automatically created with the resource) and user-assigned identities (standalone resources assigned to multiple services).
280

281
```python { .api }
282
class ManagedIdentityClient:
283
    def __init__(
284
        self,
285
        managed_identity,
286
        http_client=None,
287
        token_cache=None,
288
        **kwargs
289
    ): ...
290
    
291
    def acquire_token_for_client(
292
        self,
293
        resource: str,
294
        claims_challenge=None
295
    ): ...
296

297
class SystemAssignedManagedIdentity:
298
    def __init__(self): ...
299

300
class UserAssignedManagedIdentity:
301
    def __init__(
302
        self,
303
        client_id=None,
304
        object_id=None,
305
        resource_id=None
306
    ): ...
307
```
308

309
[Azure Managed Identity](./managed-identity.md)
310

311
### Security and Advanced Features
312

313
Advanced security features including Proof-of-Possession (PoP) token authentication for enhanced security, certificate-based authentication with X.509 certificates, custom authentication schemes, and comprehensive error handling with detailed error information.
314

315
```python { .api }
316
class PopAuthScheme:
317
    def __init__(
318
        self,
319
        http_method: str = None,
320
        url: str = None,
321
        nonce: str = None
322
    ): ...
323

324
def extract_certs(public_cert_content: str) -> list: ...
325

326
class Prompt:
327
    NONE = "none"
328
    LOGIN = "login"
329
    CONSENT = "consent"
330
    SELECT_ACCOUNT = "select_account"
331
    CREATE = "create"
332
```
333

334
[Security and Advanced Features](./security-advanced.md)
335

336
## Types
337

338
```python { .api }
339
# Authentication result dictionary
340
AuthResult = dict  # Contains 'access_token', 'token_type', 'expires_in', etc.
341

342
# Account dictionary from cache
343
Account = dict  # Contains 'home_account_id', 'environment', 'username', etc.
344

345
# Auth code flow state dictionary
346
AuthCodeFlow = dict  # Contains 'auth_uri', 'state', 'code_verifier', etc.
347

348
# Device flow state dictionary  
349
DeviceFlow = dict  # Contains 'device_code', 'user_code', 'verification_uri', etc.
350
```
351

352
## Exception Types
353

354
```python { .api }
355
class MsalError(Exception):
356
    """Base exception for MSAL errors."""
357

358
class MsalServiceError(MsalError):
359
    """Exception for errors from identity service."""
360
    def __init__(self, *args, error: str, error_description: str, **kwargs): ...
361

362
class IdTokenError(RuntimeError):
363
    """Exception for ID token validation errors."""
364

365
class IdTokenIssuerError(IdTokenError):
366
    """Exception for ID token issuer validation errors."""
367

368
class IdTokenAudienceError(IdTokenError):
369
    """Exception for ID token audience validation errors."""
370

371
class IdTokenNonceError(IdTokenError):
372
    """Exception for ID token nonce validation errors."""
373

374
class BrowserInteractionTimeoutError(RuntimeError):
375
    """Exception for browser interaction timeout."""
376

377
class ManagedIdentityError(ValueError):
378
    """Exception for managed identity errors."""
379

380
class ArcPlatformNotSupportedError(ManagedIdentityError):
381
    """Exception for unsupported Azure Arc platforms."""
382
```