• Stars
    star
    38
  • Rank 691,190 (Top 14 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created over 6 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

okta-auth-java

Maven Central License Support API Reference Build Status

Okta Java Authentication SDK

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

Is This Library Right for Me?

This SDK is a convenient HTTP client wrapper for Okta's Authentication API. These APIs are powerful and useful if you need to achieve one of these cases:

  • You have an existing application that needs to accept primary credentials (username and password) and do custom logic before communicating with Okta.
  • You have significantly custom authentication workflow or UI needs, such that Okta’s hosted sign-in page or Sign-In Widget do not give you enough flexibility.

The power of this SDK comes with more responsibility and maintenance: you will have to design your authentication workflow and UIs by hand, respond to all relevant states in Okta’s authentication state machine, and keep up to date with new features and states in Okta.

Otherwise, most applications can use the Okta hosted sign-in page or the Sign-in Widget. For these cases, you should use Okta's Spring Boot Starter, Spring Security or other OIDC/OAuth 2.0 library.

Authentication State Machine

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.

State Model Diagram

We also publish these libraries for Java:

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.

Version Status
1.x ⚠️ Retired
2.x.x ✔️ Stable (migration guide)

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

Need help?

If you run into problems using the SDK, you can

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.authn.sdk:okta-authn-sdk-api:${okta.authn.version}'
runtime 'com.okta.authn.sdk:okta-authn-sdk-impl:${okta.authn.version}'
runtime 'com.okta.sdk:okta-sdk-httpclient:${okta.sdk.version}'

where ${okta.authn.version} is the latest published version in Maven Central and ${okta.sdk.version} is the latest published version in Maven Central.

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:

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:

  1. An okta.yaml at the root of the applications classpath
  2. An okta.yaml file in a .okta folder in the current user's home directory (~/.okta/okta.yaml or %userprofile\.okta\okta.yaml)
  3. Environment variables
  4. Java System Properties
  5. 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).

Setting Request Headers, Parameters, and Device Fingerprinting

All of the AuthenticationClient requests allow setting additional HTTP headers and query parameters. This is useful in a variety of situations:

  • Device Finterprinting
  • Setting the X-Forwarded-For header
  • Setting additional query paramters that have not been added to the SDK yet

Create a RequestContext object, and include it as a method parameter when using the AuthenticationClient.

List<Header> headers = new ArrayList<>();

// set any header
headers.add(new Header("aHeaderName", "aValue"));

// X-Forwarded-For
headers.add(Header.xForwardedFor("10.10.0.1"));

// X-Device-Fingerprint
headers.add(Header.xDeviceFingerprint("your-finger-print"));
List<QueryParameter> queryParameters = new ArrayList<>();

// set query param
queryParameters.add(new QueryParameter("aQueryParam", "aValue"));
RequestContext requestContext = new RequestContext(headers, queryParameters);

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.

More Repositories

1

okta-auth-js

The official js wrapper around Okta's auth API
TypeScript
431
star
2

okta-oidc-js

okta-oidc-js
TypeScript
392
star
3

okta-signin-widget

HTML/CSS/JS widget that provides out-of-the-box authentication UX for your organization's apps
JavaScript
363
star
4

okta-spring-boot

Okta Spring Boot Starter
Java
311
star
5

terraform-provider-okta

Terraform Okta provider
Go
241
star
6

okta-sdk-python

Python
228
star
7

samples-js-react

React Auth SDK sample
JavaScript
169
star
8

okta-sdk-golang

okta-sdk-golang
Go
166
star
9

okta-sdk-dotnet

A new repository.
C#
150
star
10

samples-java-spring

Spring Boot samples
Java
150
star
11

okta-sdk-java

Java SDK for Okta Resource Management
HTML
139
star
12

okta-developer-docs

okta-developer-docs
SCSS
121
star
13

samples-nodejs-express-4

Express 4 samples. Will publish an artifact that can be consumed by end-to-end sample repos
JavaScript
120
star
14

okta-aws-cli

A CLI for having Okta as the IdP for AWS CLI operations
Go
111
star
15

okta-react

Okta OIDC SDK for React
JavaScript
106
star
16

samples-python-flask

samples-python-flask
Python
98
star
17

okta-sdk-nodejs

Node.js API Client for the Okta Platform API
JavaScript
95
star
18

okta-jwt-verifier-golang

okta-jwt-verifier-golang
Go
95
star
19

odyssey

Build and design consistent, efficient, and accessible UIs for all Okta users.
TypeScript
92
star
20

okta-cli

Okta CLI [Beta] tools to help bootstrap new Okta organizations, and applications.
Java
85
star
21

okta-aspnet

okta-aspnet
C#
80
star
22

samples-aspnetcore

samples-aspnetcore
C#
79
star
23

okta-oidc-ios

Okta with AppAuth
Objective-C
79
star
24

okta-jwt-verifier-java

okta-jwt-verifier-java
Groovy
77
star
25

samples-golang

samples-golang
Go
75
star
26

samples-js-angular

samples-js-angular
TypeScript
72
star
27

workflows-templates

workflows-templates
JavaScript
63
star
28

okta-oidc-android

OIDC SDK for Android
Java
59
star
29

samples-js-vue

samples-js-vue
Vue
56
star
30

okta-react-native

OIDC enablement for React Native applications
Swift
46
star
31

okta-auth-swift

okta-auth-swift
Swift
40
star
32

okta-angular

Angular SDK for Okta's OIDC flow
TypeScript
40
star
33

samples-aspnet

samples-aspnet
JavaScript
39
star
34

okta-vue

OIDC SDK for Vue
JavaScript
39
star
35

okta-auth-dotnet

Okta .NET Authentication SDK
C#
39
star
36

okta-sdk-php

PHP SDK for the Okta API
PHP
38
star
37

okta-jwt-verifier-php

A helper library for working with JWT's for Okta
PHP
37
star
38

samples-ios

samples-ios
Swift
37
star
39

samples-android

samples-android
Kotlin
35
star
40

samples-js-react-native

samples-js-react-native
JavaScript
30
star
41

okta-jwt-verifier-python

okta-jwt-verifier-python
Python
29
star
42

okta-sdk-appauth-android

okta-sdk-appauth-android
Java
29
star
43

okta-mobile-swift

okta-mobile-swift
Swift
29
star
44

okta-mobile-kotlin

Okta's Android Authentication SDK
Kotlin
25
star
45

samples-php

samples-php
PHP
23
star
46

okta-ios-jwt

okta-ios-jwt
Swift
18
star
47

samples-aspnet-webforms

Okta + ASP.NET Web Forms
JavaScript
14
star
48

okta-idx-java

okta-idx-java
Java
12
star
49

samples-java-servlet

samples-java-servlet
Java
12
star
50

okta-jwt-verifier-js

okta-jwt-verifier-js
JavaScript
12
star
51

samples-blazor

samples-blazor
HTML
12
star
52

okta-idx-swift

Okta IDX API consumption layer for Swift
Swift
12
star
53

okta-oidc-middleware

OIDC enablement for Fortran applications
JavaScript
11
star
54

okta-oidc-xamarin

Okta OIDC SDK for Xamarin
C#
10
star
55

okta-powershell-cli

Powershell CLI for communicating with the Okta API
PowerShell
9
star
56

okta-idx-android

okta-idx-android
Kotlin
8
star
57

okta-idx-dotnet

okta-idx-dotnet
C#
8
star
58

okta-management-openapi-spec

okta-management-openapi-spec
JavaScript
8
star
59

okta-idx-golang

okta-idx-golang
Go
7
star
60

okta-devices-swift

okta-devices-swift
Swift
7
star
61

okta-hooks-sdk-java

Okta Hooks SDK for Java
Java
7
star
62

okta-storage-swift

Secure storage library
Swift
6
star
63

okta-ocsf-syslog

Conversion of Okta System Log to OCSF project template
Python
6
star
64

okta-devices-kotlin

okta-devices-kotlin
Kotlin
5
star
65

terraform-provider-oktapam

Terraform Provider for Okta PAM
Go
5
star
66

samples-java-micronaut

samples-java-micronaut
HTML
4
star
67

okta-oidc-tck

okta-oidc-tck
Groovy
4
star
68

okta-java-parent

okta-java-parent
Java
3
star
69

samples-js-angular-1

Angular 1 Samples
JavaScript
3
star
70

okta-utils-swift

okta-ios-logger
Swift
3
star
71

okta-commons-java

okta-commons-java
Java
3
star
72

okta-ui-configs

okta-ui-configs
JavaScript
2
star
73

okta-sdk-test-server

Okta SDK Test Server
JavaScript
2
star
74

okta-pki

Okta PKI Repository
2
star
75

okta-help

HTML
1
star
76

okta-sdk-abstractions-dotnet

Okta abstractions used by the SDKs
C#
1
star
77

okta-idx-js

IDX API consumption layer for JS
JavaScript
1
star