Authorization parameters and legacy routing

Use acr_values for authentication assurance. Use dedicated ProAuth parameters for tenant, identity-provider and invitation selection, and the standard OIDC ui_locales parameter for the login language. These concerns can be combined in one authorization request.

acr_values is the standard parameter name; acr_params and acr_parameters are not OIDC request parameters. Under OpenID Connect Core, its values identify requested authentication contexts. ProAuth's older key:value routing tokens are a product-specific compatibility convention, not standard authentication contexts.

Parameter migration table

Purpose	Use for new integrations	Legacy token inside acr_values
Tenant selection	proauth_tenant=<tenant-id>	tenant:<tenant-id>
Explicit IdP selection or filtering	proauth_idp=<idp-id1>,<idp-id2>	idpfilter:<idp-id1>,<idp-id2>
Include selected hidden IdPs alongside visible IdPs	proauth_hidden_idp=<idp-id1>,<idp-id2>	hiddenidpfilter:<idp-id1>,<idp-id2>
Invitation identifier	proauth_invitation=<invitation-id>	invite:<invitation-id>
Login language preferences	ui_locales=de-CH de en	lang:de-CH
Authentication context	acr_values=phr https://proauth.net/acr/mfa	No migration: genuine assurance values stay in acr_values

The proauth_* names are ProAuth extensions. ui_locales, acr_values, max_age, prompt and login_hint are standard OIDC parameters. Use the standard parameters for their defined purposes rather than inventing additional routing tokens inside acr_values.

proauth_idp filters the providers already available to the tenant and client, including explicitly named hidden providers. A single available provider can be selected directly. proauth_hidden_idp includes the named hidden providers while retaining visible providers. Prefer one filter mode per request; explicit proauth_idp filtering takes precedence. Use explicit IDs with proauth_hidden_idp. The legacy empty token hiddenidpfilter: still includes all hidden providers otherwise allowed for the tenant and client. To migrate that form, list the intended provider IDs explicitly; keep the legacy token during migration if the application depends on its show-all behavior. Neither parameter grants access to a provider outside the tenant/client configuration. See IdP selection.

proauth_invitation selects an invitation; it does not replace any invitation secret or other validation required by the invitation flow. Keep the server-generated invitation link and its required parameters intact.

ui_locales is a space-separated language preference list, most preferred first. Language selection does not change the user's authentication assurance.

Before and after

The following fragments show only the routing and assurance portion of an authorization request. Keep the normal client ID, registered redirect URI, scopes, state, nonce and PKCE parameters. URL-encode parameter values when constructing the actual request.

Legacy request:

acr_values=tenant:11111111-1111-1111-1111-111111111111 idpfilter:22222222-2222-2222-2222-222222222222 lang:de-CH phr

Recommended request:

proauth_tenant=11111111-1111-1111-1111-111111111111
proauth_idp=22222222-2222-2222-2222-222222222222
ui_locales=de-CH
acr_values=phr

Use the same parameter names when submitting the authorization request through PAR or a signed request object. Put routing and assurance inside the protected request rather than appending different routing hints to the browser URL after creating it.

Compatibility during migration

Existing clients can continue to send the recognized legacy tokens listed above. Enabling an API assurance policy does not remove this compatibility. ProAuth separates these routing tokens from genuine assurance values before evaluating authentication requirements; routing tokens are not emitted as the achieved acr.

During a rolling migration, matching dedicated and legacy values may coexist. Conflicting values fail with invalid_request; ProAuth does not silently choose one. Matching is exact, including the order and spelling of a comma-separated IdP list. When ui_locales and legacy lang: are both present, the first locale must match the legacy language. Remove the legacy copy once the client uses the dedicated parameter consistently.

The compatibility guarantee applies to the five recognized legacy prefixes, not arbitrary key:value flags. Other values remain potential authentication-context identifiers. Their meaning depends on supported contexts and explicitly configured aliases.

Ordinary OIDC requests treat acr_values as preferences, subject to essential claims.id_token.acr constraints. For a matching enabled StepUp policy, genuine assurance values are enforced according to RFC 9470. A legacy routing-only request does not accidentally acquire an assurance requirement. See API authentication assurance.

The token endpoint also accepts proauth_tenant for tenant selection, including client-credentials requests to the root authority. Legacy acr_values=tenant:<tenant-id> remains supported. Matching dedicated and legacy tenant hints are accepted; conflicting or malformed dedicated hints are rejected with invalid_request. A dedicated hint cannot override the tenant bound to an authorization code, refresh token or device grant. Introspection and revocation keep their existing token-based routing.

ProAuth .NET client, native client and BFF settings

Use AuthenticationSettings.TenantId, ProAuthIdp, ProAuthHiddenIdp and ProAuthInvitation for their respective routing settings. Reserve AdditionalAcrValues for genuine assurance values. Set ui_locales on the authorization request (AuthRequest.UiLocales, or the host's OIDC protocol message).

ProAuth.Oidc.Client, ProAuth.Oidc.Client.Native and ProAuth.Bff use only the dedicated routing parameters by default. Setting TenantId sends proauth_tenant; it no longer adds tenant:<tenant-id> to acr_values. This applies to direct authorization, PAR and signed request objects. The clients send authentication-context preferences on authorization requests. Token requests forward only explicitly configured legacy routing values in acr_values. The .NET client uses proauth_tenant on client-credentials and refresh requests; the BFF also uses it for code redemption and logout. Exchanges that previously omitted tenant hints continue to rely on the existing grant or server routing. If no authentication contexts are explicitly configured or requested, no acr_values is sent. Step-up requests still send their required authentication contexts.

For example:

{
  "TenantId": "11111111-1111-1111-1111-111111111111",
  "ProAuthIdp": "22222222-2222-2222-2222-222222222222",
  "AdditionalAcrValues": "phr"
}

This emits proauth_tenant, proauth_idp and acr_values=phr on authorization requests, without legacy routing copies.

Upgrade the ProAuth server to a release supporting these dedicated authorization and token parameters before upgrading the client packages. Older client packages and customer integrations that send legacy routing values continue to work against the updated server. Explicit legacy values supplied in AdditionalAcrValues or AuthRequest.AcrValues are still forwarded; remove them as part of migration. During step-up, the BFF preserves recognized legacy routing hints explicitly configured in AdditionalAcrValues, while replacing assurance preferences with the selected step-up requirements.