Migration from v0.0.4 to 1.x

Version 0.0.4 will be retired on 2019-04-09.

This guide will cover the major differences between the versions.

Namespace Changes

The Maven coordinates and package names have changed. This will allow running both versions in parallel while you migrate between versions (see the readme for specifics).

Split up Management and Authentication APIs

The authentication portions of the SDK (methods that call the Okta Authentication API) have been redesigned as the Java authentication SDK.

Overall project structure change

The 0.0.4 version required creating of a client object for each API: AppGroupApiClient, FactorsApiClient, UserApiClient, etc. With the current version all operations start with a single client.

For example:

client.listUsers();
client.listApplications();

// Previously:
userApiClient.getUsers();
appInstanceApiClient.getAppInstances();

Object-specific methods have been moved to the appropriate model objects. For example:

To get the list of groups for a user you would call:

client.getUser("userId").getGroups();

// Previously:
userApiClient.getUserGroups("userId");

Paging is automatic

The next page of objects will be automatically retrieved as needed:

client.listUsers().stream().forEach(user -> {...})

Handling authentication requests

This portion of the migration guide applies only to the new Java authentication SDK.

The concept of an AuthenticationStateHandler has been introduced to make it easier to write code that works with Okta's authentication state machine.

Previously you would need to check the AuthResult for each request and deal with the appropriate state. Now you can create a AuthenticationStateHandler that looks like:

public class ExampleAuthenticationStateHandler extends AuthenticationStateHandlerAdapter {

    @Override
    public void handleUnknown(AuthenticationResponse unknownResponse) {
        // redirect to "/error"
    }

    @Override
    public void handleSuccess(AuthenticationResponse successResponse) {
        
        // a user is ONLY considered authenticated if a sessionToken exists
        if (Strings.hasLength(successResponse.getSessionToken())) {
            String relayState = successResponse.getRelayState();
            String dest = relayState != null ? relayState : "/";
            // redirect to dest    
        }
        // other state transition successful 
    }

    @Override
    public void handlePasswordExpired(AuthenticationResponse passwordExpired) {
        // redirect to "/login/change-password"
    }
    
    // Other implemented states here
}

For more examples, see the authentication SDK readme.

ℹ️ Note: Whenever possible we recommend using an OpenID Connect library such as our Spring Boot Integration or Spring Security instead of directly calling the Authentication API.