Broadleaf Microservices
  • v1.0.0-latest-prod

Auth Release Notes for 2.0.1-GA

Tip
 The 2.x versions are Spring Boot 3 compatible.

Requirements

  • JDK 17 is required for Broadleaf release trains 2.0.0-GA, and beyond.

Notable Changes

Admin User Management via Third-Party Authentication Provider

Added support for managing Admin User roles and access from third-party OAuth2 providers like Okta, Google, or MS Entra. See Admin User Management via Third-Party Authentication Provider.

Upgrade to Spring Authorization Server 1.1.4

Spring Authorization Server 1.1.4 now scrutinizes parameters that are part of the query string versus parameters that come from form data.

Important

By default, this is technically a breaking API change. However, backwards compatibility is still an option.

  • The latest versions of the admin and commerce frontends have been updated to send OAuth request parameters with the expected placement. Thus, for clients who can upgrade to the latest frontends, the best course of action is to simply advance to those new versions.

  • For clients who cannot immediately upgrade their frontend (or other API clients) to send request parameters with the correct placement, AuthenticationServices can be configured to relax parameter validation.

    • Enable the new property broadleaf.auth.security.oauth2.relax-request-parameter-placement, which will engage the new RelaxedOAuth2RequestParameterPlacementFilter. This will allow requests with the older structure to proceed successfully as before. Once all clients are upgraded, simply remove the property to restore the Spring-default strict settings.

  • Updated PublicRefreshPublicClientAuthenticationConverter to match updates to PublicClientAuthenticationConverter

  • Updated OAuth2EndpointUtils to match updates to Spring’s version of the class

  • Updated DefaultOAuth2ParamFilter and DefaultOAuth2ParamHandler method contract to support producing a mutated request.getQueryString() result

Removal of UserContext

Important
 This is technically a breaking change, as some classes, methods, and fields are removed/replaced. However, most clients will not be affected. Remediation should be a short process to transition away from UserContext and onto JwtTokenEnhancerContext#getAdditionalContext().

  • Deleted the UserContext concept altogether in favor of new early-ordered CurrentUserCacheAccessTokenEnhancer that sets the current user in JwtTokenEnhancerContext#getAdditionalContext()

  • Updated AbstractUserAccessTokenEnhancer to get the user from JwtTokenEnhancerContext#getAdditionalContext() instead of relying on UserContext

    • Deleted all UserContext related fields and methods

    • Changed the parameter of getUser to JwtTokenEnhancerContext instead of Authentication

    • Reduced visibility of getUser to protected instead of public

  • Refactored DefaultUserOperationService to perform its own query for User instead of having a reference to AccountIdAccessTokenEnhancer

    • Deleted all references to AccountIdAccessTokenEnhancer

    • Added a direct dependency on UserService

User Operations Refactor

Same as in 1.8.15-GA.

OAuth2AuthorizedClient implementation rework

Same as in 1.8.15-GA.

Note
 There is a slight distinction specifically in 2.0.1 if coming from 2.0.0. The behavior in AuthenticationLogoutHandler is slightly different from before, where the BLC-ACS-* cookie was always deleted regardless of whether there was an existing session cookie. With the new behavior, only the current signed-in user can engage removal of this authorized client with the unique identifiers present in their session claims.

Anonymous Actuator Endpoint Configuration and ForwardedHeaderFilter Configuration

Background

Historically, AuthenticationServices never came with OOB configuration for ForwardedHeaderFilter or configuration to disable security on /actuator endpoints (anonymous access).

  • Clients with projects based on the Broadleaf Starter (from the Broadleaf Initializr) would have a local configuration file in their AuthenticationServices project called ForwardedHeaderSecurityConfiguration (auto-generated by the flex:generate plugin). This would define the required configuration for them.

  • Clients with projects not based on the Broadleaf Starter would have a file in their AuthenticationServices project called SampleAuthorizationServerWebSecurityConfiguration. This would define the required configuration for them.

There are new changes in AuthenticationServices and the Broadleaf Starter that eliminate this requirement altogether.

Changes and Migration Notes

Important

Clients with starter-based projects should remove the ForwardedHeaderSecurityConfiguration class from their AuthenticationServices project. The new StarterConfiguration will typically take over and provide the right configuration. It is highly recommended for clients to update their starter versions to get the latest starter changes.

Clients with non-starter based projects should remove the SampleAuthorizationServerWebSecurityConfiguration class from their AuthenticationServices project, and instead use the new broadleaf.auth.forward.header.enabled and broadleaf.auth.actuator.anonymous properties to engage the right behavior.

  • Introduced a new ForwardedHeaderFilterAutoConfiguration ordered with low precedence to serve as a fallback OOB ForwardedHeaderFilter configuration if StarterConfiguration is unavailable (for example, in non-starter-based projects).

    • This is enabled by default, and can be toggled via the broadleaf.auth.forward.header.enabled property

      Important
      		 Clients who disabled the relevant configuration in the Broadleaf starter via broadleafdemo.forward.header.enabled should also disable this property to keep the same behavior.

  • Introduced a new ActuatorAnonymousAutoConfiguration ordered with low precedence to serve as a fallback OOB actuator anonymous configuration if StarterConfiguration is unavailable (for example, in non-starter-based projects).

    • This is not enabled by default, and can be toggled via the broadleaf.auth.actuator.anonymous property

      Important
      		 Clients who disabled the relevant configuration in the Broadleaf starter via broadleafdemo.actuator.anonymous should also disable this property to keep the same behavior.

Bug Fixes

Miscellaneous

  • Added properties to configure post auth redirect URI defaults when handling Application creation events.

    • These are analogous to the previously present server creation default properties for setting OAuth redirect URIs when a new Authorized Client is created for a new Application.

    • See Configuration doc.

  • Allow requested redirect URI to include extra query parameters for impersonation and any other post-authentication success redirect URIs.

    • The previous validation of post auth redirect URIs is overly strict for expected usage outside of OAuth2 flows.

  • Allow user entities for CSRs impersonating themselves to be resolved by CurrentUserCacheAccessTokenEnhancer correctly or skipped in the case of CSRs impersonating guests (anonymous users).

  • Re-introduce legacy 'user_name' claim in access tokens for backwards compatibility with 1.X

  • Remove TokenEndpointFilterPostProcessor.LEGACY_USER_NAME_CLAIM constant and replace it with the new same-valued UserDataClaims.USER_NAME_1X constant

  • Update AccountIdAccessTokenEnhancer to gracefully handle case where there is no OAuth2Authorization - for example, when the grant type is not 'authorization_code' or 'refresh_token'

  • Fix possible DB connection pool deadlock with OAuth2 Authorization cleanup batch job.

  • Introduce properties inside AuthenticationStrategyDelegateProperties that will be utilized for determining if an ExternalAdminUserHandler needs to be injected for a particular implementation of AbstractOAuthClientAuthenticationStrategyDelegate such as DefaultOIDCAuthenticationStrategyDelegate. More on the properties is explained in Admin User Management via Third-Party Authentication Provider.

User Resource Locking

Same as in 1.8.15-GA.

Blank and Empty Public Key Property Value Handling

Same as in 1.8.15-GA.

New Seed Data

Permissions and Scopes for New Search Entities

These are included in Search Services 2.1.0.