This checklist is based on KBA 3653999, the central SAP Knowledge Base Article for the JDK 21 Framework Update. It is intended for developers and architects as a structured preparation and execution guide covering all mandatory and conditional steps required before, during, and after upgrading SAP Commerce Cloud from JDK 17 to JDK 21 (Spring Framework 6.2 / Spring Security 6).
WHAT CHANGED
Component | JDK 17 | JDK 21 |
Java runtime | Java 17 | Java 21 |
Spring Framework | Spring 5.x | Spring Framework 6.2 |
Spring Security | Spring Security 5 | Spring Security 6 |
OAuth library | Spring Security OAuth (EOL 2022) | Spring Authorization Server |
OAuth extensions | oauth2 | authorizationserver, resourceserver, oauth2commons |
Servlet namespace | javax.servlet.* | jakarta.servlet.* |
JSTL | jakarta.servlet.jsp.jstl 1.2.6 | jakarta.servlet.jsp.jstl 3.0.1 |
NOTE: Every customization touching security config, servlet filters, OAuth clients, or javax.* imports requires review and likely modification.
PRE-UPGRADE ACTIONS
TIP: Run OpenRewrite recipe (KBA 3618495) first on a clean branch. It automate most javax→jakarta replacements and Spring API changes. Although Groovy, JSP, and security XML files still require manual review.
Action / Check | Applies to | KBA(s) | Category |
Take a full pre-upgrade snapshot (database + media/blob storage) | ALL customers | Pre-Upgrade | |
Clean up OAuth cleanup cron job log files before starting the upgrade | ALL customers – check log file count before deciding to skip (run SQL query in the KBA; potential high risk) | Pre-Upgrade | |
Set password.encoding.auto.update.enabled=true and allow a grace period for users to log in and rehash. Also set toggle.disallowTaeEncryptionFallback.enabled=true to prevent fallback to plaintext for TAE-encrypted attributes | Commerce Version below jdk21.5 / 2211.47 – prevents admin/user lockout when deprecated password encoders are removed | Pre-Upgrade | |
Run OpenRewrite recipes on all custom extensions | ALL customers with custom Java extensions | Code Migration | |
Update manifest.json: rename “oauth2” → “authorizationserver”; add resourceserver extension | ALL customers – missing this causes 404 on all OAuth token endpoints after upgrade | OAuth | |
Audit all OAuth clients: remove Password Flow and Implicit Flow usages; ensure each client has at least one authority and grant type | ALL customers – Password Flow removal also affects OOTB clients (SmartEdit, Backoffice). | OAuth | |
Enable authserver.client.validation.dry.run=true to surface OAuth config errors without breaking anything | ALL customers – disable (set to false) after migration is validated | OAuth | |
Verify storefront and API share the same base domain (eTLD+1) for custom login pages | Composable Storefront with custom login page on a separate domain from the API | OAuth | |
Enable authserver.enable.forwarded.header=true Requires patch 2211-jdk21.11 or later | API behind CDN + using Authorization Code Flow – prevents post-login redirect to internal domain. | OAuth | |
Update spring-security-config.xml: add use-authorization-manager=”true” use-expressions=”true”; replace IS_AUTHENTICATED_FULLY, SCOPE_xxx with EL expressions | Any custom extension with Spring Security XML config (Backoffice, resource server, custom web modules) | Spring Security | |
Add security-context-explicit-save=”false” to spring-security-config.xml | Accelerator Storefront with custom extension using SAML SSO – prevents ASM session loss after login | Spring Security | |
Set csrfTokenRequestAttributeHandler bean property csrfRequestAttributeName to “CSRFToken” | Accelerator Storefront with custom spring-security-config.xml – prevents 405 on all POST requests | Spring Security | |
Replace javax.servlet.* → jakarta.servlet.* in Groovy, JSP, and any files OpenRewrite did not cover | ALL customers with custom storefront or extensions using servlet APIs | javax→jakarta | |
Replace wro4j-core-1.8.x.jar with wro4j-core-2.1.1.jar in custom storefront lib directory | Custom Accelerator Storefront – old version causes WebResourceOptimizer crash on startup | javax→jakarta | |
Upgrade jakarta.servlet.jsp.jstl from 1.2.6 to 3.0.1 in custom storefront WEB-INF/lib | Custom Accelerator Storefront using JSP/JSTL tags | javax→jakarta | |
Remove ${ENV::KEYSTORE_ALIAS} from custom server.xml (variable removed in JDK 21) | Customer has a customised server.xml – causes SmartEdit blank login page if not removed | SmartEdit | |
Update SmartEdit OAuth client via ImpEx | ALL customers using SmartEdit | SmartEdit | |
Update PunchOut authentication flow to new OAuth implementation | B2B customers using PunchOut integration (Ariba, Coupa, Jaggaer) | B2B / PunchOut | |
For multi-site Composable Storefront with custom login pages: update loginPageUri config | Composable Storefront with multi-site setup where each site uses a different custom domain and a custom login page | OAuth / Multi-site | |
Fix custom ImpEx import scripts that have pre-existing errors (set the property back only as interim workaround) | Customers with custom ImpEx – JDK 21 now fails deployment on any import error (previously fails silently) | Deployment |
REQUIRED EXTENSION CHANGES
The oauth2 extension has been removed. Update your manifest.json before deploying:
// REMOVE:
{ “name”: “oauth2”, “contextPath”: “/authorizationserver” }
// ADD:
{ “name”: “authorizationserver”, “contextPath”: “/authorizationserver” },
{ “name”: “resourceserver”, “contextPath”: “/resourceserver” }
RELEVANT SECURITY VULNERABILITIES
Action / Check | Applies to | KBA(s) | Category |
Patch to 2211-jdk21.10 / 2211.51 / 2205.49 CVE-2026-34263 | ALL customers | Security | |
Patch to 2211-jdk21.10 / 2211.52 / 2205.50 CVE-2026-22732 (CVSS 9.1) | ALL customers | Security |
POST-UPGRADE VALIDATION
Action / Check | Applies to | KBA(s) | Category |
OAuth token endpoint returns token successfully (not 404 or redirect) | ALL customers | OAuth | |
Storefront login works in Chrome, Safari, Firefox, Edge (+ incognito) | ALL customers | OAuth | |
Authorization Code + PKCE flow completes end-to-end | ALL customers using storefront login | OAuth | |
Client Credentials flow returns a token (new token per request is intentional) | Integrations using Client Credentials | OAuth | |
Backoffice SSO login succeeds | SSO/SAML configured for Backoffice | OAuth | |
SmartEdit login succeeds | Customers using SmartEdit | SmartEdit | |
ASM agent login and customer emulation works | Accelerator Storefront with ASM + SAML SSO | Spring Security | |
POST requests on all storefront forms succeed (not 405) | Custom Accelerator Storefront | Spring Security | |
PunchOut setup request succeeds | B2B PunchOut integration | B2B | |
CDC/Gigya login endpoint returns 200 | Customers using SAP Customer Data Cloud | Spring 6 & Web | |
B2B API calls use /orgUsers/current (not /users/current) | B2B sites | B2B | |
Multi-site: each custom domain resolves to the correct base site | Composable Storefront multi-site with custom domains | OAuth / Multi-site | |
Disable authserver.client.validation.dry.run set back to false to enforce strict OAuth client validation in production | ALL customers who enabled it pre-upgrade | OAuth |
Source link
