0
# Authentication Flows
1

2
Core authentication functionality supporting all major OAuth2 flows for Azure Active Directory integration. Each flow is designed for specific use cases and security requirements.
3

4
## Capabilities
5

6
### AuthenticationContext Constructor
7

8
Creates a new authentication context for interacting with Azure Active Directory. The context manages authority validation, token caching, and HTTP client configuration.
9

10
```python { .api }
11
def __init__(self, authority, validate_authority=None, cache=None, 
12
             api_version=None, timeout=None, enable_pii=False, 
13
             verify_ssl=None, proxies=None):
14
    """
15
    Initialize authentication context.
16
    
17
    Parameters:
18
    - authority (str): Azure AD authority URL (e.g., 'https://login.microsoftonline.com/tenant-id')
19
    - validate_authority (bool, optional): Whether to validate authority URL (default: True)
20
    - cache (TokenCache, optional): Custom token cache instance
21
    - api_version (str, optional): Azure AD API version
22
    - timeout (int, optional): HTTP request timeout in seconds
23
    - enable_pii (bool, optional): Enable personally identifiable information in logs
24
    - verify_ssl (bool, optional): Verify SSL certificates (default: True)
25
    - proxies (dict, optional): HTTP proxy configuration
26
    """
27
```
28

29
### Options Property
30

31
Gets or sets global configuration options for the authentication context. This property manages context-wide settings that affect all token acquisition operations.
32

33
```python { .api }
34
@property
35
def options(self):
36
    """
37
    Get current context options.
38
    
39
    Returns:
40
    dict: Dictionary containing current context configuration
41
    """
42

43
@options.setter
44
def options(self, val):
45
    """
46
    Set context options.
47
    
48
    Parameters:
49
    - val (dict): Dictionary containing configuration options to set
50
    """
51
```
52

53
### Cache-based Token Acquisition
54

55
Retrieves tokens from cache with automatic refresh when needed. This is the most efficient method when tokens are already cached.
56

57
```python { .api }
58
def acquire_token(self, resource, user_id, client_id):
59
    """
60
    Get token from cache with refresh if needed.
61
    
62
    Parameters:
63
    - resource (str): URI identifying the target resource
64
    - user_id (str): Username or user identifier
65
    - client_id (str): OAuth2 client ID of the application
66
    
67
    Returns:
68
    dict: Authentication result with access token, refresh token, and metadata
69
    """
70
```
71

72
**Usage Example:**
73

74
```python
75
import adal
76

77
context = adal.AuthenticationContext('https://login.microsoftonline.com/tenant-id')
78
token = context.acquire_token(
79
    resource='https://management.azure.com/',
80
    user_id='user@tenant.com',
81
    client_id='your-client-id'
82
)
83
```
84

85
### Username/Password Flow
86

87
Authenticates using user credentials directly. This flow requires users to provide their username and password to the application.
88

89
```python { .api }
90
def acquire_token_with_username_password(self, resource, username, password, client_id):
91
    """
92
    Authenticate using username and password.
93
    
94
    Parameters:
95
    - resource (str): URI identifying the target resource
96
    - username (str): User's username or email address
97
    - password (str): User's password
98
    - client_id (str): OAuth2 client ID of the application
99
    
100
    Returns:
101
    dict: Authentication result with access token, refresh token, and metadata
102
    """
103
```
104

105
**Usage Example:**
106

107
```python
108
token = context.acquire_token_with_username_password(
109
    resource='https://graph.microsoft.com/',
110
    username='user@tenant.com',
111
    password='user-password',
112
    client_id='your-client-id'
113
)
114
```
115

116
### Client Credentials Flow
117

118
Server-to-server authentication using application credentials. This flow is used for daemon applications and background services.
119

120
```python { .api }
121
def acquire_token_with_client_credentials(self, resource, client_id, client_secret):
122
    """
123
    Authenticate using client credentials (application identity).
124
    
125
    Parameters:
126
    - resource (str): URI identifying the target resource
127
    - client_id (str): OAuth2 client ID of the application
128
    - client_secret (str): Client secret for the application
129
    
130
    Returns:
131
    dict: Authentication result with access token and metadata
132
    """
133
```
134

135
**Usage Example:**
136

137
```python
138
token = context.acquire_token_with_client_credentials(
139
    resource='https://management.azure.com/',
140
    client_id='your-client-id',
141
    client_secret='your-client-secret'
142
)
143
```
144

145
### Authorization Code Flow
146

147
Web application authentication flow where users are redirected to Azure AD for authentication and authorization code is exchanged for tokens.
148

149
```python { .api }
150
def acquire_token_with_authorization_code(self, authorization_code, redirect_uri, 
151
                                         resource, client_id, client_secret=None, 
152
                                         code_verifier=None):
153
    """
154
    Exchange authorization code for access token.
155
    
156
    Parameters:
157
    - authorization_code (str): Authorization code received from Azure AD
158
    - redirect_uri (str): Redirect URI used in authorization request
159
    - resource (str): URI identifying the target resource
160
    - client_id (str): OAuth2 client ID of the application
161
    - client_secret (str, optional): Client secret (required for confidential clients)
162
    - code_verifier (str, optional): PKCE code verifier for public clients
163
    
164
    Returns:
165
    dict: Authentication result with access token, refresh token, and metadata
166
    """
167
```
168

169
**Usage Example:**
170

171
```python
172
# After receiving authorization code from redirect
173
token = context.acquire_token_with_authorization_code(
174
    authorization_code='received-auth-code',
175
    redirect_uri='https://your-app.com/callback',
176
    resource='https://graph.microsoft.com/',
177
    client_id='your-client-id',
178
    client_secret='your-client-secret'
179
)
180
```
181

182
### Refresh Token Flow
183

184
Refreshes expired access tokens using a refresh token without requiring user interaction.
185

186
```python { .api }
187
def acquire_token_with_refresh_token(self, refresh_token, client_id, resource, 
188
                                    client_secret=None):
189
    """
190
    Use refresh token to get new access token.
191
    
192
    Parameters:
193
    - refresh_token (str): Valid refresh token
194
    - client_id (str): OAuth2 client ID of the application
195
    - resource (str): URI identifying the target resource
196
    - client_secret (str, optional): Client secret (required for confidential clients)
197
    
198
    Returns:
199
    dict: Authentication result with new access token, refresh token, and metadata
200
    """
201
```
202

203
**Usage Example:**
204

205
```python
206
token = context.acquire_token_with_refresh_token(
207
    refresh_token='stored-refresh-token',
208
    client_id='your-client-id',
209
    resource='https://management.azure.com/',
210
    client_secret='your-client-secret'
211
)
212
```
213

214
### Certificate-based Authentication
215

216
High-security authentication using X.509 certificates instead of client secrets. Commonly used in enterprise environments.
217

218
```python { .api }
219
def acquire_token_with_client_certificate(self, resource, client_id, certificate, 
220
                                         thumbprint, public_certificate=None):
221
    """
222
    Authenticate using client certificate.
223
    
224
    Parameters:
225
    - resource (str): URI identifying the target resource
226
    - client_id (str): OAuth2 client ID of the application
227
    - certificate (str): PEM-formatted private key certificate
228
    - thumbprint (str): SHA1 thumbprint of the certificate
229
    - public_certificate (str, optional): PEM-formatted public certificate
230
    
231
    Returns:
232
    dict: Authentication result with access token and metadata
233
    """
234
```
235

236
**Usage Example:**
237

238
```python
239
# Load certificate from file
240
with open('cert.pem', 'r') as cert_file:
241
    certificate = cert_file.read()
242

243
token = context.acquire_token_with_client_certificate(
244
    resource='https://management.azure.com/',
245
    client_id='your-client-id',
246
    certificate=certificate,
247
    thumbprint='certificate-thumbprint'
248
)
249
```
250

251
## Error Handling
252

253
All authentication methods may raise `AdalError` exceptions for various failure conditions:
254

255
- Invalid credentials
256
- Network connectivity issues
257
- Authority validation failures
258
- Token format errors
259
- Expired refresh tokens
260

261
```python
262
try:
263
    token = context.acquire_token_with_client_credentials(
264
        resource, client_id, client_secret
265
    )
266
except adal.AdalError as e:
267
    print(f"Authentication failed: {e}")
268
    if e.error_response:
269
        print(f"Error details: {e.error_response}")
270
```