1# OAuth 2.0 Flows
2 
3This document provides an illustration of OAuth 2.0 authentication flows supported by Microsoft Entra ID.
4 
5**Note:** All the following implementation steps are for illustration purposes. It's always recommended to use a library to handle the authentication flow.
6 
7## Authorization Code Flow
8 
9### Flow Steps
10 
11```
121. User → App: Navigate to app's web UI
132. App → User: Redirect to Microsoft login
143. User → Entra ID: Authenticate & consent
154. Entra ID → App: Authorization code (via redirect URI)
165. App → Entra ID: Exchange code for tokens (with client secret)
176. Entra ID → App: Access token + refresh token + ID token
187. App → API: Call API with access token
19```
20 
21### Implementation Steps
22 
23#### 1. Build Authorization URL
24 
25```
26https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
27  client_id={application_id}
28  &response_type=code
29  &redirect_uri={redirect_uri}
30  &response_mode=query
31  &scope={scopes}
32  &state={random_state}
33```
34 
35**Parameters:**
36- `tenant`: Your tenant ID or `common` for multi-tenant
37- `client_id`: Application (client) ID from app registration
38- `redirect_uri`: Must match exactly what's registered
39- `scope`: Space-separated permissions (e.g., `openid profile User.Read`)
40- `state`: Random value to prevent CSRF attacks
41 
42#### 2. User Authenticates
43 
44User is redirected to Microsoft login page, authenticates, and grants consent.
45 
46#### 3. Receive Authorization Code
47 
48App receives callback at redirect URI:
49```
50https://your-app.com/callback?
51  code={authorization_code}
52  &state={state_value}
53```
54 
55**Validation:**
56- Verify `state` matches what you sent
57- Extract `code` parameter
58 
59#### 4. Exchange Code for Tokens
60 
61```http
62POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
63Content-Type: application/x-www-form-urlencoded
64 
65client_id={application_id}
66&scope={scopes}
67&code={authorization_code}
68&redirect_uri={redirect_uri}
69&grant_type=authorization_code
70&client_secret={client_secret}
71```
72 
73**Response:**
74```json
75{
76  "access_token": "eyJ0eXAi...",
77  "token_type": "Bearer",
78  "expires_in": 3600,
79  "refresh_token": "M.R3_BAY...",
80  "id_token": "eyJ0eXAi..."
81}
82```
83 
84#### 5. Use Access Token
85 
86```http
87GET https://graph.microsoft.com/v1.0/me
88Authorization: Bearer {access_token}
89```
90 
91## Authorization Code Flow with PKCE
92 
93PKCE (Proof Key for Code Exchange) adds security for public clients that cannot securely store a client secret.
94 
95### Flow Steps
96 
97```
981. App: Generate code verifier (random string)
992. App: Generate code challenge (SHA256 hash of verifier)
1003. App → Entra ID: Authorization request with code challenge
1014. User → Entra ID: Authenticate & consent
1025. Entra ID → App: Authorization code
1036. App → Entra ID: Exchange code + code verifier for token
1047. Entra ID: Validates verifier matches challenge
1058. Entra ID → App: Access token + ID token
106```
107 
108### Implementation Steps
109 
110#### 1. Generate PKCE Values
111 
112**Code Verifier:** 43-128 character random string
113```javascript
114// JavaScript example
115const codeVerifier = generateRandomString(128);
116```
117 
118**Code Challenge:** Base64URL-encoded SHA256 hash of verifier
119```javascript
120const codeChallenge = base64URLEncode(sha256(codeVerifier));
121```
122 
123#### 2. Build Authorization URL
124 
125```
126https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
127  client_id={application_id}
128  &response_type=code
129  &redirect_uri={redirect_uri}
130  &scope={scopes}
131  &state={state}
132  &code_challenge={code_challenge}
133  &code_challenge_method=S256
134```
135 
136#### 3. Exchange Code for Tokens (No Secret)
137 
138```http
139POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
140Content-Type: application/x-www-form-urlencoded
141 
142client_id={application_id}
143&scope={scopes}
144&code={authorization_code}
145&redirect_uri={redirect_uri}
146&grant_type=authorization_code
147&code_verifier={code_verifier}
148```
149 
150## Client Credentials Flow
151 
152### Flow Steps
153 
154```
1551. App → Entra ID: Request token with client ID + secret
1562. Entra ID: Validate credentials
1573. Entra ID → App: Access token (application permissions)
1584. App → API: Call API with token
159```
160 
161### Implementation Steps
162 
163#### 1. Configure Application Permissions
164 
165In app registration:
1661. Go to "API permissions"
1672. Add **Application** permissions (not delegated)
1683. Grant admin consent (required for app permissions)
169 
170**Example permissions:**
171- `User.Read.All` (application) - Read all users
172- `Directory.Read.All` (application) - Read directory
173 
174#### 2. Request Access Token
175 
176```http
177POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
178Content-Type: application/x-www-form-urlencoded
179 
180client_id={application_id}
181&scope=https://graph.microsoft.com/.default
182&client_secret={client_secret}
183&grant_type=client_credentials
184```
185 
186**Parameters:**
187- `scope`: Use `{resource}/.default` format
188  - For Microsoft Graph: `https://graph.microsoft.com/.default`
189  - For your API: `api://{api_app_id}/.default`
190 
191**Response:**
192```json
193{
194  "access_token": "eyJ0eXAi...",
195  "token_type": "Bearer",
196  "expires_in": 3599
197}
198```
199 
200#### 3. Use Access Token
201 
202```http
203GET https://graph.microsoft.com/v1.0/users
204Authorization: Bearer {access_token}
205```
206 
207## Device Code Flow
208 
209**Use for:** Devices without browsers (IoT, CLIs), headless environments
210 
211### Flow Steps
212 
213```
2141. App → Entra ID: Request device code
2152. Entra ID → App: Device code + user code + verification URL
2163. App → User: Display code and URL
2174. User: Opens URL on another device, enters code
2185. User → Entra ID: Authenticates & consents
2196. App → Entra ID: Poll for token
2207. Entra ID → App: Access token (after user completes auth)
221```
222 
223### Implementation Steps
224 
225#### 1. Request Device Code
226 
227```http
228POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/devicecode
229Content-Type: application/x-www-form-urlencoded
230 
231client_id={application_id}
232&scope={scopes}
233```
234 
235**Response:**
236```json
237{
238  "user_code": "GTHK-QPMN",
239  "device_code": "GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
240  "verification_uri": "https://microsoft.com/devicelogin",
241  "expires_in": 900,
242  "interval": 5,
243  "message": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code GTHK-QPMN to authenticate."
244}
245```
246 
247#### 2. Display Instructions to User
248 
249```
250To sign in, open https://microsoft.com/devicelogin
251and enter code: GTHK-QPMN
252```
253 
254#### 3. Poll for Token
255 
256```http
257POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
258Content-Type: application/x-www-form-urlencoded
259 
260client_id={application_id}
261&grant_type=urn:ietf:params:oauth:grant-type:device_code
262&device_code={device_code}
263```
264 
265**Poll every 5 seconds (use `interval` from response)**
266 
267**Pending Response (user hasn't completed auth yet):**
268```json
269{
270  "error": "authorization_pending",
271  "error_description": "AADSTS70016: Pending end-user authorization..."
272}
273```
274 
275**Success Response:**
276```json
277{
278  "access_token": "eyJ0eXAi...",
279  "token_type": "Bearer",
280  "expires_in": 3600,
281  "refresh_token": "M.R3_BAY...",
282  "id_token": "eyJ0eXAi..."
283}
284```
285 
286## Refresh Token Flow
287 
288**Use for:** Refreshing expired access tokens without re-authentication
289 
290### When to Refresh
291 
292- Access tokens typically expire in 1 hour
293- Refresh tokens are long-lived (14-90 days)
294- Refresh before access token expires for seamless UX
295 
296### Implementation
297 
298```http
299POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
300Content-Type: application/x-www-form-urlencoded
301 
302client_id={application_id}
303&scope={scopes}
304&refresh_token={refresh_token}
305&grant_type=refresh_token
306&client_secret={client_secret}
307```
308 
309**Note:** `client_secret` only required for confidential clients
310 
311**Response:**
312```json
313{
314  "access_token": "eyJ0eXAi...",
315  "token_type": "Bearer",
316  "expires_in": 3600,
317  "refresh_token": "M.R3_BAY...",
318  "id_token": "eyJ0eXAi..."
319}
320```
321 
322**Important:** New refresh token is returned; use it for next refresh
323 
324## Token Types
325 
326### Access Token
327 
328- Used to call APIs
329- Contains claims (user ID, permissions, etc.)
330- Short-lived (typically 1 hour)
331- Format: JWT (JSON Web Token)
332 
333**Sample claims:**
334```json
335{
336  "aud": "https://graph.microsoft.com",
337  "iss": "https://sts.windows.net/{tenant}/",
338  "sub": "{user_object_id}",
339  "scp": "User.Read Mail.Read",
340  "exp": 1680000000
341}
342```
343 
344### Refresh Token
345 
346- Used to get new access tokens
347- Long-lived (days to months)
348- Opaque string (not JWT)
349- Single-use (new one issued with each refresh)
350 
351### ID Token
352 
353- Contains user identity information
354- Used by the app to authenticate user
355- Format: JWT
356 
357**Sample claims:**
358```json
359{
360  "sub": "{user_object_id}",
361  "name": "Jane Doe",
362  "preferred_username": "[email protected]",
363  "email": "[email protected]",
364  "oid": "{object_id}"
365}
366```
367 
368## Scopes and Permissions
369 
370### Scope Format
371 
372**Microsoft Graph:**
373```
374https://graph.microsoft.com/User.Read
375https://graph.microsoft.com/Mail.Send
376```
377 
378**Custom API:**
379```
380api://{api_application_id}/access_as_user
381```
382 
383## Security Considerations
384 
385| Practice | Why |
386|----------|-----|
387| **Use state parameter** | Prevents CSRF attacks |
388| **Use PKCE for public clients** | Prevents authorization code interception |
389| **Validate tokens** | Verify signature, issuer, audience, expiration |
390| **Use HTTPS only** | Protect tokens in transit |
391| **Store tokens securely** | Use secure storage, never in localStorage for sensitive apps |
392| **Implement token refresh** | Seamless UX without repeated logins |
393| **Handle token expiration** | Gracefully refresh or re-authenticate |
394| **Minimal scope principle** | Request only necessary permissions |
395 
396## Additional Resources
397 
398[OAuth 2.0 spec](https://www.rfc-editor.org/rfc/rfc6749)