Version v3.2.0
Upgrade: trusted context and claim disclosure
ProAuth keeps internal authentication context separately from externally disclosed claims. Review application expectations before upgrading.
Required application changes
pa_iss_* is no longer appended after claim rules. Applications needing an issuer identifier require an IssuerContext filter rule that permits it. The new defaults provide this permission for explicitly requested identifiers at ID-token and UserInfo destinations. Existing Enterprise rules are preserved; administrators must add the permission if their applications need it. Existing wildcard rules do not implicitly acquire issuer claims. UserInfo destinations must be configured explicitly; Both continues to mean access token plus ID token.
Persisted customer rules are not rewritten, including rules named “Forward all claims.” Existing broad federation rules continue to forward their configured inputs and destinations. Review them to minimize upstream data exposure. Profile claims and pa_external_unique_identifier removed by filtering are no longer restored afterward. Standard scope requests cannot override those decisions.
Newly generated defaults expose requested standard profile claims at the applicable ID-token/UserInfo destinations and explicitly enabled ProAuth capabilities. Additional requested-only rules permit canonical pa_iss_* identifiers and available fed_* claims at ID-token and UserInfo destinations. Applications must request exact claim names in the authorization request's claims parameter; standard scopes and wildcard names do not request these families. Without an explicit request, they remain omitted. Credential claims, private protocol state and the external unique identifier remain excluded.
Starter and Business editions use these immutable defaults, so applications can request the permitted claims without administrators adding rules. Enterprise installations retain their existing persisted rules; these are not supplemented or rewritten during upgrade.
The AdminApp subscription selector does not require pa_iss_subscription. It uses the subscriptions available through the Management API, preserves valid URL and remembered selections, and defaults to an available subscription. An unavailable explicit URL selection must be corrected before continuing. Deploy the updated AdminApp resources when upgrading; updating the Authorization Server alone does not update stored view definitions. Custom v3 subscription-filter definitions should use the authorized subscription choices and must not depend on an optional issuer-context claim.
The immutable defaults do not disclose optional issuer or federation claims in access tokens. Adding an ID-token or UserInfo claim request does not add that claim to an API access token. Before upgrading, check API authorization policies that depend on these claims. Enterprise administrators can configure explicit access-token disclosure rules; applications on other editions must adopt a supported claim contract before deployment. Do not substitute an ID token for an API access token.
Use the configuration examples for explicit issuer selection, selected federation forwarding, unconditional profile claims and requested-only claims. Configure through v2 APIs/DTOs. Legacy v1 reads show only the token destinations: UserInfo appears as None, AccessTokenAndUserInfo as AccessToken, IdentityTokenAndUserInfo as IdentityToken, and All as Both. Legacy v1 updates preserve the stored fields and destination extensions that v1 cannot represent. Use v2 to inspect or change the full disclosure configuration.
Preserving a customer's existing claim contract
For an Enterprise client that needs these claims without changing its authorization requests, configure two active, client-assigned filter rules (RuleLevel=ClientApp, RuleType=Filter, FilterTarget=Type, DisclosureMode=Always):
| InputSource | TypeEvaluationRule | Purpose |
|---|---|---|
IssuerContext | ^pa_iss_(customer|subscription|clientapp|tenant|idp_scheme)$ | Select the available canonical issuer identifiers |
Pipeline | ^fed_.+$ | Forward available upstream claims; narrow this expression to the claims the client needs |
Use Destination=Both for ID tokens and access tokens, or All if UserInfo must also expose them. Assign both rules only to the intended client. Place them in the appropriate priority group alongside the client's other permitted claims, and ensure later filters preserve the intended results. Issuer identifiers must come from IssuerContext; a pipeline wildcard alone cannot restore them. Credential and private protocol claims remain excluded.
If the client can explicitly request claims, use WhenRequested with IdentityTokenAndUserInfo instead and list every required claim name under id_token and/or userinfo in the claims parameter. Requests cannot override missing permissions or grant access-token disclosure. Start a new authorization after changing rules, then verify the initial tokens, UserInfo response and refreshed tokens.
Deployment order
- Back up configuration, database and data-protection keys. Export existing claim rules using v2 tooling.
- Apply the AdminApp schema migrations through
OptionDisplayGroups, followed by the incrementalTrustedContextClaimDisclosureandClientAuthenticationSecuritymigrations for SQL Server or PostgreSQL. Do not replace an already deployed v3 schema with a new initial migration. The v2-to-v3 bridge must be followed by incremental v3 migrations. - Upgrade application instances coherently. Maintain shared data-protection keys and compatible state-store configuration.
- Apply new disclosure configuration and verify each affected application.
Mixed application versions cannot guarantee the new disclosure semantics: older instances can still inject claims after rules. Schema compatibility does not make a mixed runtime rollout semantically equivalent.
Authentication and logout compatibility
Users with existing sessions may need to authenticate again after upgrading. Legacy authorization codes and refresh tokens without the required protected disclosure state require a new login. Applications must not use public or pairwise subject identifiers as local database identifiers.
This release derives acr and amr from verified authentication evidence. Claim rules cannot create or replace these values by renaming federation claims or assigning constants. Disclosure permissions remain separate from internal security context; ID-token ACR negotiation and authentication-time requirements are enforced by the protocol layer. Built-in password authentication earns baseline assurance; completed additional factors and user-verified passkeys can earn stronger assurance. Redeeming an MFA recovery code does not establish completion of the enrolled factor. See UserStore assurance.
acr_values supplies ordered voluntary preferences. An unsupported preference falls back to earned assurance. An essential claims.id_token.acr constraint must match the exact emitted value, including a configured tenant alias. Stronger authentication can emit a requested lower value only when that value is supported by the evidence. Unsatisfied essential requests fail with login_required after authentication; prompt=none cannot initiate interactive authentication. ProAuth does not automatically select a different provider or enroll a factor to satisfy a request.
Refresh preserves the original authentication time and recorded assurance; it does not perform a new authentication. Treat alias meanings as stable contracts. When changing the meaning of an existing assurance alias or tightening requirements for existing grants, revoke the affected sessions and renewable grants and require a new authorization. A configuration edit alone does not rewrite historical token context.
Built-in passkey evidence does not currently establish hardware or software key protection, so it does not emit phrh, hwk, or swk. Attestation trust and backup eligibility alone are insufficient. If upgrading from an interim deployment that inferred these values, or credited MFA recovery as a completed factor, revoke affected sessions and renewable grants before relying on the corrected assurance contract. Already issued self-contained tokens remain usable until expiry unless the resource server enforces revocation. Existing MFA browser state without account/provider binding requires authentication again.
Authorization codes issued with PKCE require the matching verifier, including for confidential clients. Those clients must also authenticate using their registered token-endpoint method. BFF applications using Auto with a client secret select ClientSecretBasic; upgrade the BFF package with the server and configure the same method on the client registration. See BFF client authentication.
Signed authorization request parameters remain protected through login and consent. In-flight JAR continuations created before this upgrade must be restarted. Token revocation remains effective when an originating identity provider is temporarily disabled and subsequently re-enabled.
Authentication completion is single-use and bound to its original authorization request. Replayed or expired MFA continuations require restarting login; revisiting a completion URL cannot satisfy a new prompt=login request.
Signing in as a different user or through a different identity provider in the same browser starts a separate OIDC session. A session created before identity binding was introduced receives a new session identifier on its next authorization. Existing tokens remain associated with their original session.
Existing authorizations retain their recorded ID-token and access-token disclosure results. Start a new authorization to apply changed rules. UserInfo evaluates its explicit destination using the authorization's stored claims and request context.
Logout accepts a cryptographically valid expired ID-token hint only when it is associated with a current or retained recent client session. Normal API access and token exchange still enforce lifetime. Removed token records do not invalidate surviving session correlation. Missing or mismatched browser sessions require confirmation bound to protected state; invalid hints cannot silently clear another session. Redirects must exactly match registered values after supported, validated tenant substitution. With client_id and no ID-token hint, and resolve from the tenant route or protected browser context; the confirmation requirement still applies. Both GET and form-encoded POST logout requests are supported. A matching browser hint can skip consent when configured; consent form submissions retain antiforgery validation.
BaseServiceSettings:LogoutRecentSessionRetentionHours defaults to 24 and accepts a positive duration in hours. Recent correlation expires after session closure or expiry; repeated logout must not renew it. Retain configured historical signature-verification material for the supported session lifetime plus this recent-session window. If a verification key is removed or unavailable, hints signed with it cannot be verified.
For encrypted ID tokens, retain data-protection keys as well as signature-verification keys so that logout hints remain usable. ProAuth retains logout evidence until the associated session correlation expires. Storage use grows with encrypted ID-token issuance during that period; account for this when sizing the state store.
Follow RP-Initiated Logout when updating clients.