Clarify Microsoft Entra validation modes for step-up auth#67
Clarify Microsoft Entra validation modes for step-up auth#67
Conversation
Update the step-up authentication doc to better explain the two validation modes available for Microsoft Entra: - OIDC mode: Uses max_age for re-authentication (simpler setup) - ACRS mode: Uses Authentication Context Class References (more control) Changes: - Update intro table to explain how each mode works - Rename tab titles to include mode names - Add note explaining ID tokens requirement for OIDC mode - Update FAQ with clearer guidance on which mode to choose Related: PR #13443 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR restructures the step-up authentication docs: numbered instructions were converted into structured / blocks, "approaches" were renamed to "validation modes" (OIDC and ACRS), tab titles and headings updated, new mode-specific notes and fields for Microsoft Entra were added, and troubleshooting/FAQ wording was revised. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
No actionable comments were generated in the recent review. 🎉 Comment |
Replace numbered procedural lists with <Steps> components for better visual formatting and consistency with other docs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@product/admin/step-up-auth.mdx`:
- Around line 164-166: Update the Note block that currently ties the "ID token
not found in response" error to the "ID tokens (implicit/hybrid)" setting:
clarify that for the authorization-code flow the ID token is returned by the
/token endpoint only when the openid scope is requested, and that enabling the
implicit/hybrid ID tokens setting is unnecessary for authorization-code flow (it
only affects implicit/hybrid flows); replace the misleading sentence inside the
<Note> with text that states the missing ID token usually means the openid scope
was not requested rather than the implicit/hybrid setting being disabled.
| <Note> | ||
| ID tokens are required for OIDC validation mode. Without this setting, you'll receive an "ID token not found in response" error. | ||
| </Note> |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Microsoft Entra ID OIDC authorization code flow ID token response openid scope
💡 Result:
In Microsoft Entra ID (Microsoft identity platform v2.0):
- If you use the authorization code flow (
response_type=code), you get only a code from the/authorizeendpoint, then you redeem it at the/tokenendpoint. (learn.microsoft.com) - The
/tokenresponse includes anid_tokenonly when you requested the OIDC scopeopenid(for example:scope=openid profile email ...). (learn.microsoft.com) - If you want an ID token returned immediately from
/authorize(along with the code), you must use the hybrid flow:response_type=code id_token, and includescope=openid ...and anonce. (learn.microsoft.com)
Citations:
- 1: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow?utm_source=openai
- 2: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow?utm_source=openai
- 3: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow?utm_source=openai
🌐 Web query:
Microsoft Entra "ID tokens" implicit hybrid flows required setting
💡 Result:
In Microsoft Entra ID App registrations → Authentication → “Implicit grant and hybrid flows” → “ID tokens”, you only need to enable this if your app requests an ID token from the /authorize endpoint (that is, you use an OAuth/OIDC response_type that includes id_token, such as implicit response_type=id_token or hybrid response_type=code id_token). If it’s not enabled and you request id_token, Entra ID returns an unsupported_response error (often “Expected value is ‘code’”). [1][2][4]
How to enable (two equivalent ways):
- Portal checkbox: App registration → Authentication → under your platform → Implicit grant and hybrid flows → check ID tokens. [1]
- Manifest: set
oauth2AllowIdTokenImplicitFlowtotrue. [1]
Rule of thumb: if you’re using authorization code flow (with PKCE) via MSAL, you typically do not need to enable implicit/hybrid ID tokens; enable it only when you truly need hybrid sign-in (for example, some server-side web apps using hybrid auth). [2][3]
🌐 Web query:
Microsoft Entra OIDC token endpoint ID token openid scope authorization code
💡 Result:
In Microsoft Entra ID (Microsoft identity platform v2.0):
/authorizeis where you get the authorization code (and optionally an ID token in hybrid flow). (learn.microsoft.com)/tokenis where you redeem the authorization code to get tokens. The OIDC discovery document lists the tenant-specifictoken_endpoint. (learn.microsoft.com)
Getting an ID token with the authorization code flow
When you sign in using OIDC, include openid in the scope (optionally profile, email). (learn.microsoft.com)
1) Authorization request (get code)
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?...
- Use
response_type=codefor pure auth-code flow. - If you want an ID token immediately from
/authorize, use hybrid:response_type=code id_tokenand includenonce. (learn.microsoft.com)
2) Token request (redeem code)
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
grant_type=authorization_codecode=...redirect_uri=...client_id=...- PKCE:
code_verifier=...(if used) - Include OIDC scopes like
openid(and optionallyprofile,email) in the flow so an ID token is issued for sign-in. (learn.microsoft.com)
Key point about where the ID token comes from
- Implicit/hybrid: ID tokens can be returned from
/authorize(not/token) whenresponse_typeincludesid_token. (learn.microsoft.com) - Auth code flow: you redeem the code at
/tokento get tokens (and commonly receive anid_tokenwhen using OIDC scopes likeopenid). (learn.microsoft.com)
If you tell me your exact request/response (minus secrets)—especially the response_type you’re using on /authorize and the scope you send—I can pinpoint why you are/aren’t seeing an id_token in the /token response.
Citations:
- 1: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow?utm_source=openai
- 2: https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc?utm_source=openai
- 3: https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc?utm_source=openai
- 4: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow?utm_source=openai
- 5: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow?utm_source=openai
- 6: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-implicit-grant-flow?utm_source=openai
- 7: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow?utm_source=openai
Clarify that openid scope, not implicit/hybrid setting, is required for ID token in authorization-code flow.
The current note ties the "ID token not found" error to the "ID tokens (implicit/hybrid)" setting, which is misleading. Microsoft Entra documentation confirms that for authorization-code flow, ID tokens are returned from the /token endpoint when the openid scope is requested—enabling the implicit/hybrid setting is not required for this flow and is only needed for implicit or hybrid flows. The missing ID token typically indicates the openid scope was not requested, not that the implicit/hybrid setting is disabled.
✏️ Suggested rewording
<Note>
-ID tokens are required for OIDC validation mode. Without this setting, you'll receive an "ID token not found in response" error.
+OIDC mode requires an ID token in the token response. If you see "ID token not found in response," confirm the request includes the `openid` scope and that your chosen flow returns ID tokens (enable implicit/hybrid only if you explicitly use those flows).
</Note>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <Note> | |
| ID tokens are required for OIDC validation mode. Without this setting, you'll receive an "ID token not found in response" error. | |
| </Note> | |
| <Note> | |
| OIDC mode requires an ID token in the token response. If you see "ID token not found in response," confirm the request includes the `openid` scope and that your chosen flow returns ID tokens (enable implicit/hybrid only if you explicitly use those flows). | |
| </Note> |
🤖 Prompt for AI Agents
In `@product/admin/step-up-auth.mdx` around lines 164 - 166, Update the Note block
that currently ties the "ID token not found in response" error to the "ID tokens
(implicit/hybrid)" setting: clarify that for the authorization-code flow the ID
token is returned by the /token endpoint only when the openid scope is
requested, and that enabling the implicit/hybrid ID tokens setting is
unnecessary for authorization-code flow (it only affects implicit/hybrid flows);
replace the misleading sentence inside the <Note> with text that states the
missing ID token usually means the openid scope was not requested rather than
the implicit/hybrid setting being disabled.
There was a problem hiding this comment.
Hey @degzhaus I've updated the step-up auth doc based on the changes in https://github.com/ductone/c1/pull/13443. Can you give the changes in this PR and this CodeRabbit flag a quick review and let me know if any changes are made before I publish? Many thanks.
There was a problem hiding this comment.
Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!
1 participant
Summary
Changes
Related
ductone/c1#13443
🤖 Generated with Claude Code
Summary by CodeRabbit