docs: document upstream MFA carry-over for OIDC social sign-in#2507
Open
docs: document upstream MFA carry-over for OIDC social sign-in#2507
Conversation
Adds a new page describing how Ory carries over upstream OIDC `acr` and `amr` claims into the resulting Ory session. Operators can configure per-provider `aal2_acr_values` and `aal2_amr_values` allowlists to mark sessions as AAL2 when the upstream identity provider has already performed multi-factor authentication. The new page covers: - How Ory reads the upstream `acr` / `amr` claims and decides the session AAL. - A provider support matrix (Generic OIDC, Auth0, Okta, Keycloak, Microsoft Entra v1, Ping Identity, Google, Apple, and others). - Console and CLI configuration examples. - How to ask the upstream provider for a specific `acr` value via `acr_values` or `requested_claims`. - Sample `/sessions/whoami` payload showing the new `upstream_acr` / `upstream_amr` audit fields. - Troubleshooting tips for empty upstream claims and accidental AAL2 elevation. The Dynamic MFA / step-up authentication doc gains a short section that links to the new page so customers enforcing AAL2 discover the option. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
hperl
requested review from
aeneasr,
piotrmsc,
unatasha8,
vinckr and
zepatrik
as code owners
vinckr
reviewed
Apr 13, 2026
|
|
||
| ## Troubleshooting | ||
|
|
||
| **The session is still AAL1 after a successful login.** Check that the upstream provider actually emits the claim. You can inspect |
Member
There was a problem hiding this comment.
Suggested change
| **The session is still AAL1 after a successful login.** Check that the upstream provider actually emits the claim. You can inspect | |
| The session is still AAL1 after a successful login: Check that the upstream provider actually emits the claim. You can inspect |
| `std.extVar('claims').raw_claims.amr`. If the provider doesn't surface the claim, request it explicitly through `acr_values` or | ||
| `requested_claims`. | ||
|
|
||
| **The `upstream_acr` field is empty even though the upstream sent it.** Make sure your provider config has |
Member
There was a problem hiding this comment.
Suggested change
| **The `upstream_acr` field is empty even though the upstream sent it.** Make sure your provider config has | |
| The `upstream_acr` field is empty even though the upstream sent it: Make sure your provider config has |
| `claims_source: id_token` (the default) or, if you set `claims_source: userinfo`, that the userinfo endpoint also returns the | ||
| `acr` claim. Some providers only include `acr`/`amr` in the ID token. | ||
|
|
||
| **The session is AAL2 but the user never completed MFA.** Audit the configured allowlists carefully. An `acr` value such as `0` or |
Member
There was a problem hiding this comment.
Suggested change
| **The session is AAL2 but the user never completed MFA.** Audit the configured allowlists carefully. An `acr` value such as `0` or | |
| The session is AAL2 but the user never completed MFA: Audit the configured allowlists carefully. An `acr` value such as `0` or |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the new upstream OIDC
acr/amrcarry-over feature shipped in ory-corp/cloud#11499.When a user signs in through a social sign-in provider that already enforces MFA, Ory can now trust the upstream factor instead of asking the user to complete a second factor again. This PR adds:
docs/kratos/social-signin/93_upstream-mfa.mdx) covering:acr/amrclaims and decides the resulting session AAL.aal2_acr_valuesandaal2_amr_values.acrvalue viaacr_valuesorrequested_claims./sessions/whoamipayload showing the newupstream_acr/upstream_amraudit fields.Test plan
npx prettier --checkpasses for changed filesnpm run build) — please verify in CIRelated
🤖 Generated with Claude Code