Release v10.0.0 - Major SDK Refactoring with Enhanced API Organization and Test Coverage

[aniket-okta]

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

Overview

This PR introduces Okta .NET SDK v10.0.0, a major release that significantly improves the SDK's architecture, maintainability, and developer experience. The release includes a comprehensive refactoring of monolithic API clients into specialized, focused clients, along with extensive test coverage improvements.

Key Highlights

Major API Reorganization

• 4 Large APIs Split into 27+ specialized clients for better organization and maintainability
• 29 New API Clients for enhanced functionality and improved discoverability
• 60+ APIs Unchanged ensuring smooth migration for most use cases
• Comprehensive Migration Documentation with method-level mappings

Enhanced Test Coverage

• 38 API Integration Test Suites added/improved
• Given-When-Then naming convention adopted for better test readability
• Consolidated test patterns reducing redundancy while improving coverage

Breaking Changes

1. UserApi Split (Major Refactoring)

The monolithic UserApi has been split into 10 specialized APIs:

• UserApi - Core CRUD operations (Create, Get, Update, Delete, List)
• UserLifecycleApi - Lifecycle operations (Activate, Deactivate, Suspend, Unsuspend, Unlock, Reactivate)
• UserCredApi - Credential management (ChangePassword, ExpirePassword, ForgotPassword, ResetPassword, SetPassword)
• UserGrantApi - Grant operations (GetUserGrant, ListUserGrants, RevokeUserGrant)
• UserOAuthApi - OAuth token operations (ListGrants, RevokeGrants, Refresh tokens)
• UserSessionsApi - Session management (ClearUserSessions, ListUserSessions, GetUserSession, RevokeUserSession)
• UserLinkedObjectApi - Linked object operations
• UserResourcesApi - User resources (ListAppLinks, ListAssignedApplications)
• UserAuthenticatorEnrollmentsApi - Authenticator enrollments
• UserClassificationApi - User classification
• UserRiskApi - User risk operations

Migration Example:

// Before (v9.x)
var userApi = new UserApi();
await userApi.ActivateUserAsync(userId);

// After (v10.0.0)
var userLifecycleApi = new UserLifecycleApi();
await userLifecycleApi.ActivateUserAsync(userId);

2. OrgSettingApi Split

Organization settings divided into 7 specialized APIs:

• OrgSettingGeneralApi - General org settings
• OrgSettingAdminApi - Admin settings
• OrgSettingCommunicationApi - Communication preferences
• OrgSettingContactApi - Contact information
• OrgSettingCustomizationApi - Customization settings
• OrgSettingMetadataApi - Organization metadata
• OrgSettingSupportApi - Support settings

3. RoleApi Split

Role management reorganized into 8 specialized APIs:

• RoleAssignmentAUserApi - User role assignments
• RoleAssignmentBGroupApi - Group role assignments
• RoleAssignmentClientApi - Client role assignments
• RoleBTargetAdminApi - Admin role targets
• RoleBTargetBGroupApi - Group role targets
• RoleBTargetClientApi - Client role targets
• RoleECustomApi - Custom role management
• RoleECustomPermissionApi - Custom role permissions

4. ResourceSetApi Split

Resource set operations moved to 4 role-based APIs:

• RoleCResourceSetApi - Resource set CRUD operations
• RoleCResourceSetResourceApi - Resource set resource operations
• RoleDResourceSetBindingApi - Resource set binding operations
• RoleDResourceSetBindingMemberApi - Resource set binding member operations

5. Removed APIs

• ApplicationCredentialsApi - Functionality moved to ApplicationSSOApi and related SSO APIs

6. Parameter Changes

Some methods have gained new optional parameters:

• ApplicationApi.ListApplications() - Added useOptimization parameter
• UserApi.GetUserAsync() - Added contentType parameter
• UserApi.ListUsers() - Added contentType parameter

New API Clients (29 Total)

Application APIs

• ApplicationCrossAppAccessConnectionsApi - Manage cross-app access connections
• ApplicationSSOCredentialKeyApi - Manage SSO credential keys
• ApplicationSSOFederatedClaimsApi - Manage SSO federated claims
• ApplicationSSOPublicKeysApi - Manage SSO public keys

Device Management APIs

• DeviceAccessApi - Device access policies
• DeviceIntegrationsApi - Device integrations
• DevicePostureCheckApi - Device posture checks

Identity Provider APIs

• IdentityProviderKeysApi - Identity provider keys
• IdentityProviderSigningKeysApi - Identity provider signing keys
• IdentityProviderUsersApi - Identity provider users

Other New APIs

• AssociatedDomainCustomizationsApi
• EmailCustomizationApi
• GovernanceBundleApi
• GroupPushMappingApi
• GroupRuleApi
• OAuth2ResourceServerCredentialsKeysApi
• OktaPersonalSettingsApi
• OrgCreatorApi
• ServiceAccountApi
• WebAuthnPreregistrationApi

Integration Test Coverage

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

User Management APIs

• UserAndUserLifecycleApi
• UserAuthenticatorEnrollmentsApi
• UserClassificationApi
• UserCredApi
• UserFactorApi
• UserGrantApi
• UserLinkedObjectApi
• UserOAuthApi
• UserResourcesApi
• UserRiskApi
• UserSessionsApi
• UserTypeApi

Application APIs

• ApplicationApi
• ApplicationConnectionsApi
• ApplicationCrossAppAccessConnectionsApi
• ApplicationFeaturesApi
• ApplicationGrantsApi
• ApplicationGroupsApi
• ApplicationLogosApi
• ApplicationPoliciesApi
• ApplicationSSOApi
• ApplicationSSOCredentialKeyApi
• ApplicationSSOFederatedClaimsApi
• ApplicationTokensApi
• ApplicationUsersApi

Group APIs

• GroupApi
• GroupOwnerApi
• GroupPushMappingApi
• GroupRuleApi

Organization & Settings APIs

• ApiServiceIntegrationsApi
• ApiTokenApi
• OAuthApi
• OktaApplicationSettingsApi
• PolicyApi
• ProfileMappingApi
• RealmApi
• SchemaApi
• SessionApi

Documentation

Migration Guides

• MIGRATION_GUIDE_v10.0.0.md - Comprehensive method-level migration mappings for all 73 old API classes
• MIGRATING.md - Updated with "Migrating from 9.x to 10.x" section with examples
• README.md - Updated Release Status section and fixed code examples for v10.x

CHANGELOG

Comprehensive release notes documenting:

• All breaking changes
• New API clients
• Migration examples
• Benefits of the refactoring
• List of unchanged APIs

Technical Improvements

Test Enhancements

• Given-When-Then naming convention for improved test readability
• Test consolidation - Reduced GroupApi tests from 43 to 2 comprehensive suites
• Fixed failing tests - UserRiskApi, OAuthApi
• Uncommented and reorganized old unit tests
• Added DPoP JWT header bug fix in OAuth tests

Code Quality

• Removed nullable annotations causing CS8632 warnings
• Added CODEOWNERS file for better code ownership
• Removed Travis CI configuration and updated .gitignore
• Moved unused RequestResponseCollecting utilities to Assets folder

OpenAPI Spec Updates

• Regenerated SDK with OpenAPI spec v5.1.0
• Fixed OpenAPI spec for array attributes in Schema API

Impact Analysis

Changed APIs: 4

• UserApi (split into 10 APIs)
• OrgSettingApi (split into 7 APIs)
• RoleApi (split into 8 APIs)
• ResourceSetApi (split into 4 APIs)

New APIs: 29

Specialized APIs for improved functionality and organization

Unchanged APIs: 60+

Including: AgentPoolsApi, ApiServiceIntegrationsApi, ApiTokenApi, ApplicationFeaturesApi, AuthenticatorApi, AuthorizationServerApi, BehaviorApi, BrandsApi, CAPTCHAApi, CustomDomainApi, DeviceApi, EmailDomainApi, EventHookApi, FeatureApi, GroupApi, IdentityProviderApi, LinkedObjectApi, NetworkZoneApi, PolicyApi, SchemaApi, SessionApi, SystemLogApi, ThemesApi, TrustedOriginApi, UserFactorApi, and many more.

Benefits

• ** Better Organization** - Related operations grouped logically
• ** Improved Maintainability** - Smaller, focused API clients
• ** Enhanced Discoverability** - Clear API naming indicates purpose
• ** Easier Testing** - Focused clients are simpler to mock and test
• ** Reduced Complexity** - Smaller surface area per client
• ** Comprehensive Documentation** - Detailed migration guides and examples

Migration Path

1. Review the detailed migration guide
2. Identify affected code using UserApi, OrgSettingApi, RoleApi, or ResourceSetApi
3. Update API instantiations to use new specialized clients
4. Update method calls to use appropriate specialized clients
5. Update dependency injection configurations
6. Test thoroughly

Testing

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

Test Coverage Notes and Limitations

Some API endpoints have inherent testing limitations due to their authentication requirements or destructive nature:

Browser Session Cookie Requirements

• SessionAPI (6 methods): The following /me endpoints require browser-based authentication with session cookies and cannot be tested server-to-server:

  • CloseCurrentSessionAsync (DELETE /api/v1/sessions/me)
  • CloseCurrentSessionWithHttpInfoAsync (DELETE /api/v1/sessions/me)
  • GetCurrentSessionAsync (GET /api/v1/sessions/me)
  • GetCurrentSessionWithHttpInfoAsync (GET /api/v1/sessions/me)
  • RefreshCurrentSessionAsync (POST /api/v1/sessions/me/lifecycle/refresh)
  • RefreshCurrentSessionWithHttpInfoAsync (POST /api/v1/sessions/me/lifecycle/refresh)

  These endpoints are designed for client-side JavaScript applications where the browser automatically includes the session cookie in requests.

• UserSessionsAPI: EndUserSessionsAsync and EndUserSessionsWithHttpInfoAsync require a session cookie and cannot be tested with API Token authentication.

OAuth Flow Limitations

• UserOAuthAPI: Cannot test OAuth2RefreshToken properties (Status, ClientId, Created, ExpiresAt, Id, Issuer, LastUpdated, Scopes, UserId, Embedded, Links) as refresh tokens require browser-based user login/consent which cannot be automated in server-to-server tests.

• ApplicationTokensAPI: The following scenarios are not tested due to browser-based authentication requirements:

  • Actual OAuth token refresh scenarios (requires browser-based auth flow)
  • Authorization code flow with user consent
  • 403 Forbidden errors (requires permission issues)
  • Real pagination cursors (requires actual tokens)
  • Expand parameter effect (requires tokens with scopes)

Destructive Operations

• APITokenAPI: Revoke operations were tested negatively (error scenarios) as they are destructive and could cause other tests to fail if executed positively.

Organization Configuration Constraints

• UserFactorAPI: Tests use TOTP (token:software:totp) factors as they are the only factor type enabled in the test Okta organization. Other factor types (SMS, Call, Security Question, Push) are disabled in the org's MFA policy and cannot be tested without policy changes.

Known Issues

• ApplicationCrossAppAccessConnectionsAPI: 2 tests are currently skipped and need to be addressed in future work.
• ApplicationSSOPublicKeysAPI: Requires fixes from Management API end. A JIRA ticket has been created to track this issue.

Despite these limitations, the test suite provides comprehensive coverage for all testable API operations and validates the core functionality of the SDK.

Version Updates

• SDK Version: 9.2.3 → 10.0.0
• API Version: 5.1.0
• Updated in all configuration files and templates

🔗 Related Links

• Migration Guide - Method-level mappings
• Migrating from 9.x to 10.x - Examples and patterns
• CHANGELOG - Full release notes
• Developer Forum - Community support