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 README for specifics).

Split of Management and Authentication API

The authentication portion of the v0.0.4 has been redesigned and move to okta-auth-java.

Overall project structure change

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

For example:

client.listUsers();
client.listApplications();
// vs
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();
// instead of
userApiClient.getUserGroups("userId");

Paging is automatic

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

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

Authentication API

The concept of an AuthenticationStateHandler has been introduced to ease development when dealing with Okta's Authentication state machine see the README

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

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
}

NOTE: When possible we recommend using an OAuth 2.0 / OpenID Connect library such as our Spring Boot Integration or Spring Security directly.