Skip to content

Commit e491eb7

Browse files
hperlclaude
hperl
and
claude
committed
docs: address PR review feedback
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 686875b commit e491eb7

1 file changed

Lines changed: 7 additions & 19 deletions

File tree

‎docs/kratos/social-signin/93_upstream-mfa.mdx‎

Lines changed: 7 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -28,29 +28,17 @@ You configure two allowlists per provider:
2828
AAL2.
2929

3030
When neither list matches, the session stays at AAL1. If your project enforces `session.whoami.required_aal=highest_available`,
31-
the user is then prompted for a Kratos-managed second factor as usual. Both fields are optional; leaving them empty preserves the
32-
current behavior of always issuing AAL1 sessions through this provider.
31+
the user is then prompted for a Kratos-managed second factor as usual. Both fields are optional; leaving them empty causes Kratos
32+
to always issue AAL1 sessions through this provider.
3333

3434
The upstream `acr` and `amr` values are persisted on the session's `authentication_methods` entry as `upstream_acr` and
3535
`upstream_amr` for auditing. They appear on `/sessions/whoami` and in webhook payloads, so downstream systems can record which
3636
upstream factors were used.
3737

3838
## Provider support
3939

40-
Not every OIDC provider returns `acr` or `amr`. The table below lists the providers Ory ships with and whether their ID tokens
41-
include these claims.
42-
43-
| Provider | `acr` | `amr` | Notes |
44-
| --------------------------------------------------------------------------------------------------------- | ------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
45-
| Generic OIDC | Yes | Yes | Works with any OIDC-compliant IdP that emits these claims (Keycloak, Microsoft Entra v1, PingFederate, Auth0 federation, Okta federation, and many others). |
46-
| Microsoft (Entra ID / Azure AD) | v1.0 only | v1.0 only | v1.0 ID tokens include both. v2.0 tokens typically omit `acr` and `amr`. |
47-
| Auth0 | Yes | Yes | `amr` contains `mfa` once the user completed an MFA challenge. The standard step-up `acr` value is `http://schemas.openid.net/pape/policies/2007/06/multi-factor`. |
48-
| Okta (federation) | Yes | Yes | Predefined `acr` values such as `urn:okta:loa:1fa:any` and `urn:okta:loa:2fa:any`. `amr` values include `pwd`, `mfa`, `sms`, `hwk`, `fpt`, `face`. |
49-
| Keycloak | Yes | Yes (recent versions) | `acr` is mapped from the Level-of-Authentication config. `amr` is populated by the dedicated AMR protocol mapper. |
50-
| Ping Identity (PingAM, PingFederate, PingOne AIC) | Yes (opt-in) | Yes (opt-in) | Neither claim is added by default. Configure them through Authentication Journeys or "Force ACR in ID Token". |
51-
| Google | No | No | Google's OIDC implementation does not issue `acr` or `amr`. |
52-
| Apple (Sign in with Apple) | No | No | Not part of Apple's documented ID-token schema. |
53-
| Facebook, GitHub, GitLab, Discord, Slack, Spotify, Amazon, LinkedIn, Yandex, VK, NetID, Dingtalk, Patreon | No | No | OAuth2-only or non-standard OIDC; no `acr` or `amr` surfaced. |
40+
Not every OIDC provider returns `acr` or `amr`, and the values they emit vary widely. Check your provider's documentation to see
41+
whether it includes these claims in the ID token and which values map to a multi-factor authentication.
5442

5543
You can still configure the allowlist for any provider — Ory simply records the upstream values and never matches when the
5644
provider doesn't emit them.
@@ -194,14 +182,14 @@ still recorded under `upstream_acr` / `upstream_amr` for auditing.
194182

195183
## Troubleshooting
196184

197-
**The session is still AAL1 after a successful login.** Check that the upstream provider actually emits the claim. You can inspect
185+
The session is still AAL1 after a successful login: Check that the upstream provider actually emits the claim. You can inspect
198186
the raw ID token claims from the Jsonnet data mapper through `std.extVar('claims').raw_claims.acr` and
199187
`std.extVar('claims').raw_claims.amr`. If the provider doesn't surface the claim, request it explicitly through `acr_values` or
200188
`requested_claims`.
201189

202-
**The `upstream_acr` field is empty even though the upstream sent it.** Make sure your provider config has
190+
The `upstream_acr` field is empty even though the upstream sent it: Make sure your provider config has
203191
`claims_source: id_token` (the default) or, if you set `claims_source: userinfo`, that the userinfo endpoint also returns the
204192
`acr` claim. Some providers only include `acr`/`amr` in the ID token.
205193

206-
**The session is AAL2 but the user never completed MFA.** Audit the configured allowlists carefully. An `acr` value such as `0` or
194+
The session is AAL2 but the user never completed MFA: Audit the configured allowlists carefully. An `acr` value such as `0` or
207195
`urn:mace:incommon:iap:bronze` typically means "no MFA was performed" — do not include those values in `aal2_acr_values`.

0 commit comments

Comments
 (0)