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

📋 Summary

This PR introduces Okta Java SDK v25.0.0, a major release that significantly improves the SDK's architecture, test coverage, and developer experience based on the updated Okta Admin Management API (OpenAPI spec v5.1.0).

🎯 Key Highlights

Version Updates

🔴 Breaking Changes

Summary

Key Breaking Change: User Object Schema

The User object no longer includes the type property and its sub-properties in API responses.

Affected endpoints include:

• GET /api/v1/users
• POST /api/v1/users
• GET /api/v1/groups/{groupId}/users
• All user lifecycle operations

Migration Required: Applications using user.getType() must be updated. See MIGRATION-v25.0.0.md.

🆕 New Components

Custom Deserializers (9 Total)

Added to handle polymorphic API responses properly:

New Integration Test Suites (28 Total)

User Management APIs (12 Suites)

• UserLifecycleIT.groovy - Lifecycle operations
• UserCredIT.groovy - Password/credential operations
• UserGrantIT.groovy - User grants management
• UserOAuthIT.groovy - OAuth token operations
• UserSessionsIT.groovy - Session management
• UserLinkedObjectIT.groovy - Linked objects
• UserResourcesIT.groovy - App links, assigned apps
• UserAuthenticatorEnrollmentsIT.groovy - Authenticator enrollments
• UserClassificationIT.groovy - User classification
• UserRiskIT.groovy - Risk level operations
• UserFactorIT.groovy - Factor enrollment/verification
• UserTypeIT.groovy - User type management

Application APIs (9 Suites)

• ApplicationGrantsIT.groovy - OAuth grants
• ApplicationLogosIT.groovy - Logo management
• ApplicationPoliciesIT.groovy - Policy assignments
• ApplicationSSOIT.groovy - SSO operations
• ApplicationSSOCredentialKeyIT.groovy - SSO credential keys
• ApplicationSSOFederatedClaimIT.groovy - Federated claims
• ApplicationTokensIT.groovy - Token management
• ApplicationUsersIT.groovy - User assignments
• OktaApplicationSettingsIT.groovy - App settings

Organization & Settings APIs (7 Suites)

• AgentPoolsIT.groovy - Agent pool management
• ApiServiceIntegrationsIT.groovy - Service integrations
• ApiTokenIT.groovy - API token operations
• GroupPushMappingIT.groovy - Group push mappings
• ProfileMappingIT.groovy - Profile mappings
• RealmsIT.groovy - Realm operations
• PolicyCleanupIT.groovy - Policy cleanup utilities

New Unit Tests (8 Files)

New Configuration Files

📊 Integration Test Coverage

Total Test Suites: 35

Test Enhancements

• Retry Logic: Added for flaky API operations (rate limiting, eventual consistency)
• Cleanup Utilities: Proper test isolation and resource cleanup
• Map Parameter Variants: Comprehensive coverage of API method overloads
• Given-When-Then: Consistent test naming conventions

🔧 Technical Improvements

DefaultClientBuilder Updates

// Mix-ins registered for polymorphic types
mapper.addMixIn(ListGroupAssignedRoles200ResponseInner.class, IgnoreTypeInfoMixIn.class);
mapper.addMixIn(AssignRoleToClient200Response.class, IgnoreTypeInfoMixIn.class);
mapper.addMixIn(AssignRoleToGroup200Response.class, IgnoreTypeInfoMixIn.class);
mapper.addMixIn(AssignRoleToUser201Response.class, IgnoreTypeInfoMixIn.class);
mapper.addMixIn(ListJwk200ResponseInner.class, IgnoreTypeInfoMixIn.class);

// Custom deserializers registered
module.addDeserializer(ListGroupAssignedRoles200ResponseInner.class, new RoleAssignmentDeserializer());
module.addDeserializer(AssignRoleToClient200Response.class, new AssignRoleToClientResponseDeserializer());
module.addDeserializer(AssignRoleToGroup200Response.class, new AssignRoleToGroupResponseDeserializer());
module.addDeserializer(AssignRoleToUser201Response.class, new AssignRoleToUserResponseDeserializer());
module.addDeserializer(ListJwk200ResponseInner.class, new JwkResponseDeserializer());
module.addDeserializer(GroupOwner.class, new GroupOwnerDeserializer());
module.addDeserializer(OffsetDateTime.class, new FlexibleOffsetDateTimeDeserializer());

Pagination Improvements

New PagedIterable<T> class for automatic, thread-safe pagination:

// New recommended approach
PagedIterable<User> users = userApi.listUsersPagedIterable(null, null, 200, null, null, null, null);
for (User user : users) {
    System.out.println("User: " + user.getProfile().getLogin());
}

Note: PaginationUtil.getAfter() is deprecated (@Deprecated(forRemoval = true, since = "24.1.0"))

Code Quality Improvements

• ✅ PMD violation fixes
• ✅ Improved error handling in tests
• ✅ Better test isolation and cleanup
• ✅ Enhanced retry logic for API operations

📚 Documentation

New/Updated Files

🧪 Testing

Test Verification

• All 35 integration test suites passing
• All 8 unit test classes passing
• Code examples in README verified for v25.x compatibility
• Migration guide examples tested
• Custom deserializers validated with real API responses

How to Test

# Run all tests
mvn clean test

# Run integration tests only
mvn -pl integration-tests test

# Run specific test suite
mvn -pl integration-tests test -Dtest=UsersIT

# Run with coverage
mvn clean test jacoco:report

🔄 Migration Path

1. Review the detailed migration guide
2. Identify code using changed endpoints (User, Authenticator, Factor, Policy, IdP)
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
6. Update error handling for new response codes

✅ Checklist

PR Checklist

• Code follows project coding standards
• Tests added for new functionality
• All existing tests pass
• Documentation updated
• Breaking changes documented
• Migration guide provided
• CHANGELOG updated
• No PMD violations
• Version numbers updated

Files Changed Categories

🔗 Related Links

• MIGRATION-v25.0.0.md - Breaking change details
• CHANGELOG-v25.0.0.md - Full release notes
• MIGRATING.md - General migration patterns
• Developer Forum - Community support
• API Reference - Official documentation