Java SDK Refresh - v25.0.0

[prachi-okta]

Release v25.0.0 - Major SDK Refactoring and Enhanced Test Coverage

📋 Overview

This PR introduces Okta Java SDK v25.0.0, a major release that significantly improves the SDK's architecture, maintainability, and developer experience. The release includes comprehensive OpenAPI spec updates, custom deserializers for polymorphic type handling, and extensive test coverage improvements.

🎯 Key Highlights

Major API Updates

• OpenAPI Spec v5.1.0 - Updated from previous version with +29,934 lines of changes
• 6 Custom Deserializers added for polymorphic type handling
• 36 OpenAPI Schema Fixes for proper type: object declarations
• Comprehensive Migration Documentation with breaking change details

Enhanced Test Coverage

• 38 API Integration Test Suites added/improved
• 5 New Unit Test Classes for helper utilities and retry logic

🔴 Breaking Changes

1. User Object Schema Changes (Major)

The structure of the User object has changed. Many endpoints now no longer include the type object and its sub-properties in the response.

Affected Endpoints:

• GET /api/v1/devices
• GET /api/v1/devices/{deviceId}/users
• GET /api/v1/groups/{groupId}/users
• GET /api/v1/users
• POST /api/v1/users
• GET /api/v1/users/{id}
• PUT /api/v1/users/{id}
• POST /api/v1/users/{userId}/lifecycle/expire_password

Action Required: Audit your code for any dependencies on user.type properties and remove them.

2. Authenticator Endpoint Schema Changes

Response schemas for authenticator endpoints have breaking compatibility changes:

• GET /api/v1/authenticators
• POST /api/v1/authenticators
• GET /api/v1/authenticators/{authenticatorId}
• PUT /api/v1/authenticators/{authenticatorId}
• Lifecycle operations (activate/deactivate)
• Method operations

3. User Factor Endpoint Schema Changes

Request and/or response schemas changed for:

• GET /api/v1/users/{userId}/factors
• POST /api/v1/users/{userId}/factors
• GET /api/v1/users/{userId}/factors/catalog
• Factor lifecycle and verification operations

Notable Change: The _links.resend property type has changed.

4. Policy Endpoint Schema Changes

The status property type has changed in request/response for:

• GET /api/v1/policies
• POST /api/v1/policies
• GET /api/v1/policies/{policyId}
• Policy rules operations

5. Role Assignment Response Changes

Polymorphic type handling required custom deserializers due to Jackson deserialization issues with @JsonSubTypes annotations.

Migration Example:

// The SDK now handles polymorphic types automatically via custom deserializers
// No code changes required - deserializers are registered automatically

🆕 New Components

Custom Deserializers (6 Total)

Added to handle polymorphic type deserialization issues:

Deserializer	Purpose
RoleAssignmentDeserializer	Handles ListGroupAssignedRoles200ResponseInner
AssignRoleToGroupResponseDeserializer	Handles AssignRoleToGroup200Response
AssignRoleToUserResponseDeserializer	Handles AssignRoleToUser201Response
AssignRoleToClientResponseDeserializer	Handles AssignRoleToClient200Response
JwkResponseDeserializer	Handles ListJwk200ResponseInner
IgnoreTypeInfoMixIn	Mix-in to disable @JsonTypeInfo annotations

New Integration Test Suites (28 Total)

User Management APIs

Test Suite	Lines Added
UserLifecycleIT.groovy	+550
UserAuthenticatorEnrollmentsIT.groovy	+487
UserClassificationIT.groovy	+223
UserCredIT.groovy	+527
UserFactorIT.groovy	+1,274
UserGrantIT.groovy	+660
UserLinkedObjectIT.groovy	+553
UserOAuthIT.groovy	+538
UserResourcesIT.groovy	+511
UserRiskIT.groovy	+205
UserSessionsIT.groovy	+428
UserTypeIT.groovy	+597

Application APIs

Test Suite	Lines Added
ApplicationGrantsIT.groovy	+577
ApplicationLogosIT.groovy	+490
ApplicationPoliciesIT.groovy	+500
ApplicationSSOCredentialKeyIT.groovy	+475
ApplicationSSOFederatedClaimIT.groovy	+667
ApplicationSSOIT.groovy	+376
ApplicationTokensIT.groovy	+308
ApplicationUsersIT.groovy	+621

Organization & Settings APIs

Test Suite	Lines Added
AgentPoolsIT.groovy	+383
ApiServiceIntegrationsIT.groovy	+396
ApiTokenIT.groovy	+362
GroupPushMappingIT.groovy	+736
OktaApplicationSettingsIT.groovy	+517
PolicyCleanupIT.groovy	+114
ProfileMappingIT.groovy	+318
RealmsIT.groovy	+366

New Unit Tests (5 Classes)

Test Class	Lines Added	Purpose
ApiExceptionHelperTest.java	+64	API exception handling
HelperConstantsTest.java	+64	Helper constants validation
PaginationUtilTest.java	+294	Pagination utility testing
DPoPInterceptorTest.java	+379	DPoP JWT handling
RetryUtilTest.java	+133	Retry logic validation

New Configuration Files

File	Purpose
.mvn/jvm.config	JVM configuration for large YAML parsing
.mvn/maven.config	Maven configuration
clean-generated-sources.sh	Cleanup script for generated sources
MIGRATION-v25.0.0.md	Comprehensive migration guide

📊 Integration Test Coverage

This release includes comprehensive integration test coverage for 38+ API clients:

User Management APIs

• UsersIT (enhanced)
• UserLifecycleIT
• UserAuthenticatorEnrollmentsIT
• UserClassificationIT
• UserCredIT
• UserFactorIT
• UserGrantIT
• UserLinkedObjectIT
• UserOAuthIT
• UserResourcesIT
• UserRiskIT
• UserSessionsIT
• UserTypeIT

Application APIs

• AppsIT (enhanced +3,384 lines)
• ApplicationGrantsIT
• ApplicationLogosIT
• ApplicationPoliciesIT
• ApplicationSSOIT
• ApplicationSSOCredentialKeyIT
• ApplicationSSOFederatedClaimIT
• ApplicationTokensIT
• ApplicationUsersIT

Group APIs

• GroupsIT (enhanced +2,345 lines)
• GroupPushMappingIT

Identity Provider APIs

• IdpIT (enhanced +1,607 lines)

Organization & Settings APIs

• AgentPoolsIT
• ApiServiceIntegrationsIT
• ApiTokenIT
• OktaApplicationSettingsIT
• PoliciesIT (enhanced +843 lines)
• PolicyCleanupIT
• ProfileMappingIT
• RealmsIT
• PaginationIT

📚 Documentation

Migration Guides

• MIGRATION-v25.0.0.md - Comprehensive breaking change documentation (467 lines)
• MIGRATING.md - Updated with "Migrating to v25.x" section
• README.md - Updated Release Status section and fixed code examples

🔧 Technical Improvements

Deserializer Architecture

Custom deserializers handle polymorphic type issues where Jackson's @JsonSubTypes annotations fail:

// Example: RoleAssignmentDeserializer handles StandardRole vs CustomRole
public class RoleAssignmentDeserializer extends StdDeserializer<ListGroupAssignedRoles200ResponseInner> {
    @Override
    public ListGroupAssignedRoles200ResponseInner deserialize(JsonParser p, DeserializationContext ctxt) {
        // Detects role type from JSON and creates appropriate instance
        // Uses reflection to set read-only fields
    }
}

DefaultClientBuilder Updates

// Mix-ins registered for polymorphic types
mapper.addMixIn(ListGroupAssignedRoles200ResponseInner.class, IgnoreTypeInfoMixIn.class);
mapper.addMixIn(AssignRoleToGroup200Response.class, IgnoreTypeInfoMixIn.class);
// ... and more

// Custom deserializers registered
SimpleModule module = new SimpleModule();
module.addDeserializer(ListGroupAssignedRoles200ResponseInner.class, new RoleAssignmentDeserializer());
// ... and more
mapper.registerModule(module);

Test Enhancements

• Retry logic added for flaky API operations
• Cleanup utilities for test isolation
• Map parameter variant tests for comprehensive coverage

Code Quality

• PMD violation fixes
• Improved error handling in tests
• Better test isolation and cleanup

📈 Impact Analysis

Files Changed: 77

Category	Count
Integration Tests (New)	28
Integration Tests (Enhanced)	10
Unit Tests (New)	5
Source Files (New/Modified)	15
Configuration Files	8
Documentation	4
OpenAPI Spec	1

Lines Changed

• +48,495 insertions
• -7,943 deletions

Major File Changes

File	Changes
src/swagger/api.yaml	+29,934 lines
AppsIT.groovy	+3,384 lines
GroupsIT.groovy	+2,345 lines
IdpIT.groovy	+1,607 lines
UsersIT.groovy	+1,169 lines
UserFactorIT.groovy	+1,274 lines

✅ Benefits

• 🎯 Better Type Safety - Custom deserializers handle polymorphic types correctly
• 📈 Improved Test Coverage - 38+ integration test suites
• 📚 Comprehensive Documentation - Detailed migration guides
• 🔧 Enhanced Maintainability - Cleaner test patterns and code organization
• 🚀 Updated API Support - OpenAPI spec v5.1.0 with latest Okta APIs

🔄 Migration Path

1. Review the detailed migration guide
2. Identify code using changed endpoints (User, Authenticator, Factor, Policy)
3. Update any dependencies on removed user.type properties
4. Test thoroughly with the new SDK version
5. Review custom deserializer behavior for role assignments

🧪 Testing

• All 38+ API integration test suites passing
• Unit tests updated and passing
• Code examples in README verified for v25.x compatibility
• Migration guide examples tested

📦 Version Updates

• SDK Version: 24.x → 25.0.0
• OpenAPI Spec Version: → 5.1.0
• Updated in all configuration files and templates

🔗 Related Links

• Migration Guide - Breaking change details
• Migrating Documentation - General migration patterns
• Developer Forum - Community support
• GitHub Issues - Report issues