- v1.0.0-latest-prod
Starting with AuthenticationServices 3.0.0, it is possible to create an AuthorizedClient that authenticates/authorizes with API keys.
Please review API Key Grant Type documentation for more information.
At a high level, this release introduces the following:
Comprehensive API Key Management: Introduced the ApiKey domain along with supporting CRUD endpoints and repositories.
API keys are generated securely, stored as cryptographic hashes, and mapped to an AuthorizedClient (API Account) to utilize existing scope/permission/tenancy concepts.
Custom OAuth2 Grant Type & Authentication Method: Implemented a new custom grant type (urn:broadleaf:params:oauth:grant-type:api-key) as well as a new api_key authentication method.
Authentication/Authorization Flows: Added new authentication and authorization flows to support the /token endpoint accepting an api_key form parameter.
This flow validates the provided API key against stored values to both authenticate and authorize the client, issuing an OAuth2AccessToken with narrowed scopes upon success.
Visibility and Environment Controls: API keys are categorized by visibility (SECRET vs PUBLISHABLE) and environment (e.g., live, staging).
PUBLISHABLE keys support configuring whitelisted domains that are automatically injected into the token response envelope.
|
Note
|
The usage and enforcement of the visibility type, environment separation, and domain whitelisting are left as an implementation exercise for clients, as requirements can vary greatly. |
Admin UI Integration: Broadleaf Admin metadata has been updated to expose API key management in the AuthorizedClient edit page.
Strict Validation & Immutability Guardrails: Added validation rules to prevent the deletion of clients with outstanding API keys and enforce immutability on key visibility and environment settings once keys are generated.
Added @ConditionalOnMissingBean annotations to several auto-configured beans in AuthI18nAutoConfiguration and AuthServiceTemplateAutoConfiguration to support easier customization and overriding in client implementations:
Internationalization & Mapping:
authMessageSourcePostProcessor
authTranslationPostMapperMember
Thymeleaf & OAuth2 Template Engine / Resolvers:
oAuth2ClientIdTemplateEngine
viewResolverPostProcessor (updated to return the concrete ViewResolverPostProcessor type, which has been made public)
oAuth2DefaultTemplateResolver
broadleafTemplateResolver
broadleafOAuth2DefaultTemplateResolver
The OAuth2 Token Revocation Endpoint is now accessible to public clients. Please review OAuth2 Token Revocation endpoint documentation for more details.
Introduced a new PublicClientTokenRevocationAuthenticationConverter that specifically targets the token revocation endpoint and establishes a PublicClientTokenRevocationAuthenticationToken authentication
Updated PublicRefreshPublicClientAuthenticationProvider to handle PublicClientTokenRevocationAuthenticationToken
Add the IMPERSONATE security scope and its root permission-scope mapping to the required starter data.
This is the Authentication Services half of the admin change that hides the View Quote Details action from users who lack impersonation permissions — without the scope in place, the action is hidden from every user because there is nothing for the permission to map to.
The changesets are guarded by preconditions and will not insert rows that already exist, so a deployment that added the scope by hand needs no further action.
Please refer to Session Token Blacklisting documentation for more details on this feature.
Expanded the Application and JpaApplication domain models to include an environment property (backed by a new EnvironmentTypeEnum defaulting to PRODUCTION). Accompanying Liquibase changelogs were added for MariaDB, MySQL, Oracle, and PostgreSQL to introduce the environment VARCHAR column to the blc_application table.
Enhanced token verification within StatelessUtilImpl#verifyToken to explicitly throw a new custom UnverifiedTokenException if a JWT fails parsing or signature validation. The global AuthExceptionAdvisor has been updated to handle this specific exception, returning an HTTP 401 Unauthorized ApiError rather than a generic 500 server error.
Refactored API key environment and visibility options from string constants (DefaultApiKeyEnvironments, DefaultApiKeyVisibilityTypes) into strongly-typed Java Enums (DefaultApiKeyEnvironmentType, DefaultApiKeyVisibilityType). Entities such as AuthorizedClient, ApiKey, and JpaApiKey, along with their generators and validators, have been updated to utilize these enums. This resolves usability issues in the Broadleaf Admin metadata, bridging the gap between uppercase Admin UI select fields and backend representations.
Creating an API Key in the Admin now shows a success confirmation with the generated plaintext key, since the key cannot be retrieved again once the confirmation is dismissed.
Added a copyable plaintext-key field to the API Key creation success response.
Fixed the whitelisted-domains field incorrectly displaying for SECRET visibility keys; it now only displays for PUBLISHABLE keys, which is the only visibility type domain whitelisting applies to.
Fixed incorrect default Caffeine and EHCache heap/offheap size properties — they were previously specified in raw megabyte values (e.g. 500) under keys expecting a unit suffix, so the configured sizes were not actually being applied. The defaults now use unit-suffixed values (e.g. 500MB).
The database schema has changed as part of this version.
Create/update changes (new tables, new columns, etc) are automatically included in the updated *changelog-master.xml after you upgrade to the new Authentication Services JAR.
The new changesets inside will run automatically to migrate existing data.
| Database Platform | Create/Update Changelog File Name |
|---|---|
PostgreSQL |
|
MariaDB |
|
MySQL |
|
Oracle |
|