Okta Java Authentication SDK

⚠️ Beta alert! This library is in beta. See release status for more information.

• Release status
• Need help?
• Getting started
• Usage guide
• Configuration reference
• Building the SDK
• Contributing

The Okta Authentication SDK is a convenience wrapper around Okta's Authentication API.

NOTE: Using OAuth 2.0 or OpenID Connect to integrate your application instead of this library will require much less work, and has a smaller risk profile. Please see this guide to see if using this API is right for your use case. You could also use our Spring Boot Integration, or Spring Security out of the box.

Okta's Authentication API is built around a state machine. In order to use this library you will need to be familiar with the available states. You will need to implement a handler for each state you want to support.

We also publish these libraries for Java:

• Spring Boot Integration
• Okta JWT Verifier for Java
• Management SDK

You can learn more on the Okta + Java page in our documentation.

Release status

This library uses semantic versioning and follows Okta's library version policy.

The latest release can always be found on the releases page.

Need help?

If you run into problems using the SDK, you can

• Ask questions on the Okta Developer Forums
• Post issues here on GitHub (for code errors)

Getting started

To use this SDK you will need to include the following dependencies:

For Apache Maven:

<dependency>
    <groupId>com.okta.authn.sdk</groupId>
    <artifactId>okta-authn-sdk-api</artifactId>
    <version>${okta.authn.version}</version>
</dependency>
<dependency>
    <groupId>com.okta.authn.sdk</groupId>
    <artifactId>okta-authn-sdk-impl</artifactId>
    <version>${okta.authn.version}</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>com.okta.sdk</groupId>
    <artifactId>okta-sdk-httpclient</artifactId>
    <version>${okta.sdk.version}</version>
    <scope>runtime</scope>
</dependency>

For Gradle:

compile 'com.okta.sdk:okta-authn-sdk-api:${okta.version}'
runtime 'com.okta.sdk:okta-authn-sdk-impl:${okta.version}'
runtime 'com.okta.sdk:okta-sdk-httpclient:${okta.version}'

SNAPSHOT Dependencies

Snapshots are deployed off of the 'master' branch to OSSRH and can be consumed using the following repository configured for Apache Maven or Gradle:

https://oss.sonatype.org/content/repositories/snapshots/

You'll also need:

• An Okta account, called an organization (sign up for a free developer organization if you need one)

Construct a client instance by passing it your Okta domain name and API token:

AuthenticationClient client = AuthenticationClients.builder()
    .setOrgUrl("https://{yourOktaDomain}")
    .build();

Hard-coding the Okta domain works for quick tests, but for real projects you should use a more secure way of storing these values (such as environment variables). This library supports a few different configuration sources, covered in the configuration reference section.

Usage guide

These examples will help you understand how to use this library. You can also browse the full API reference documentation.

Once you initialize a AuthenticationClient, you can call methods to make requests to the Okta Authentication API. To call other Okta APIs, see the Management SDK.

Authenticate a User

An authentication flow usually starts with a call to authenticate:

// could be where to redirect when authentication is done, a token, or null
String relayState = "/application/specific";
client.authenticate(username, password, relayState, stateHandler);

Everything looks pretty standard except for stateHandler. The AuthenticationStateHandler is a mechanism to fire an event for the given authentication state returned. Basically, it prevents you from needing to use something like a switch statement to check state of the AuthenticationResponse.

A typical AuthenticationStateHandler may look something 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
}

As noted in the above example, a user is ONLY considered authenticated if AuthenticationResponse.getSessionToken() is not null. This sessionToken can be exchanged via the Okta Sessions API to start an SSO session, but that is beyond the scope of this library.

NOTE: UNKNOWN is not an actual state in Okta's state model. The method handleUnknown is called when an unimplemented or unrecognized state is reached. This could happen if:

• Your handler doesn't have an implementation for the state that was just returned
• Your Okta organization configuration changed, and a new state is now possible (for example, an admin turned on multi-factor authentication)
• Okta added something new to the state model entirely

Configuration reference

This library looks for configuration in the following sources:

0. An okta.yaml at the root of the applications classpath
1. An okta.yaml file in a .okta folder in the current user's home directory (~/.okta/okta.yaml or %userprofile\.okta\okta.yaml)
2. Environment variables
3. Java System Properties
4. Configuration explicitly passed to the constructor (see the example in Getting started)

Higher numbers win. In other words, configuration passed via the constructor will override configuration found in environment variables, which will override configuration in okta.yaml (if any), and so on.

YAML configuration

The full YAML configuration looks like:

okta:
  client:
    connectionTimeout: 30 # seconds
    orgUrl: "https://{yourOktaDomain}" # i.e. https://dev-123456.oktapreview.com
    proxy:
      port: null
      host: null
      username: null
      password: null
    requestTimeout: 10 # seconds
    rateLimit:
      maxRetries: 2

Environment variables

Each one of the configuration values above can be turned into an environment variable name with the _ (underscore) character:

• OKTA_CLIENT_CONNECTIONTIMEOUT
• OKTA_CLIENT_RATELIMIT_MAXRETRIES
• and so on

System properties

Each one of of the configuration values written in 'dot' notation to be used as a Java system property:

• okta.client.connectionTimeout
• okta.client.rateLimt.maxRetries
• and so on

Connection Retry / Rate Limiting

By default this SDK will retry requests that are return with a 503, 504, 429, or socket/connection exceptions. To disable this functionality set the properties okta.client.requestTimeout and okta.client.rateLimit.maxRetries to 0.

Setting only one of the values to zero will disable that check. Meaning, by default, four retry attempts will be made. If you set okta.client.requestTimeout to 45 seconds and okta.client.rateLimit.maxRetries to 0. This SDK will continue to retry indefinitely for 45 seconds. If both values are non zero, this SDK will attempt to retry until either of the conditions are met (not both).

Building the SDK

In most cases, you won't need to build the SDK from source. If you want to build it yourself, take a look at the build instructions wiki (though just cloning the repo and running mvn install should get you going).

Contributing

We're happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.