Legacy Applications

What is a legacy application?

When creating an interactive application or a client-side application in Bizzkit User Management, the application can optionally be configured as a legacy application. This setting relaxes certain modern OAuth 2.0 security requirements to maintain compatibility with older applications that were built before these standards became widely adopted.

How legacy mode affects application behavior

PKCE (Proof Key for Code Exchange)

PKCE is a security extension to the OAuth 2.0 authorization code flow that protects against authorization code interception attacks. It is recommended by the OAuth 2.0 Security Best Current Practice for all OAuth clients.

When legacy mode is enabled, PKCE is not required for both interactive applications and client-side applications. When legacy mode is disabled (the default), PKCE is required.

User claims in ID token

In legacy mode, user claims are always embedded directly in the ID token for interactive applications. In modern mode, the ID token contains only essential identity information, and additional user claims are retrieved via the UserInfo endpoint. This follows the OpenID Connect recommendation to keep ID tokens compact.

This setting applies to interactive applications only. Client-side applications are not affected.

Default logout behavior for interactive applications

When an interactive application does not have explicit logout paths configured via FrontChannelLogoutPath or PostLogoutRedirectPath, the legacy flag determines the default logout URIs that are registered with the OpenID Connect provider:

These are URIs on the downstream application's domain that the OpenID Connect provider redirects the browser to during the logout flow.

Client-side applications always use https://{BaseDomain} as the post-logout redirect URI, regardless of the legacy flag.

Migrating from legacy applications

To migrate an existing legacy application to use modern security settings:

1. Enable PKCE in your application. Most modern OAuth 2.0 / OpenID Connect client libraries support PKCE out of the box. Ensure your library is configured to use PKCE with the authorization code flow.

2. Update claims retrieval (interactive applications). If your interactive application reads user claims directly from the ID token, update it to call the UserInfo endpoint instead. The ID token will still contain the sub (subject) claim and other essential identity information.

3. Verify logout paths. If your interactive application does not have explicit logout paths configured, ensure that it handles the modern default paths (/signout-oidc for front-channel logout and /signout-callback-oidc for post-logout redirect). Alternatively, set explicit FrontChannelLogoutPath and PostLogoutRedirectPath values on the downstream client to match your application's actual endpoints.

4. Recreate the downstream client. Using the version 26 API, create a new downstream client without the legacy flag. The version 26 API does not support the legacy setting — all clients created through it use modern security settings by default.

5. Test the integration. Verify that login, token retrieval, claims access, and logout all work correctly with the updated configuration.