Skip to content
Okta Spring Boot Starter
Java Groovy Shell
Branch: master
Clone or download
snyk-bot and bdemers fix: pom.xml to reduce vulnerabilities
The following vulnerabilities are fixed with an upgrade:
- https://snyk.io/vuln/SNYK-JAVA-ORGTESTNG-174823
Latest commit ab7a09c Nov 9, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.mvn/wrapper Cleanup CI build to match other Okta Java projects Apr 10, 2018
coverage [maven-release-plugin] prepare for next development iteration Oct 18, 2019
examples [maven-release-plugin] prepare for next development iteration Oct 18, 2019
integration-tests [maven-release-plugin] prepare for next development iteration Oct 18, 2019
oauth2 [maven-release-plugin] prepare for next development iteration Oct 18, 2019
okta-spring-boot-starter
sdk
src Tweaks to OWASP suppression based on pre-release scan Oct 18, 2019
.editorconfig Add .editorconfig Mar 16, 2018
.gitignore Initial import of code Aug 8, 2017
.travis.yml Update travis.yml to use openjdk8 Oct 9, 2019
CODE_OF_CONDUCT.md Add Code of Conduct from contributor-covenant.org Feb 26, 2019
README.md Fixed README header image Oct 18, 2019
mvnw Cleanup CI build to match other Okta Java projects Apr 10, 2018
mvnw.cmd Cleanup CI build to match other Okta Java projects Apr 10, 2018
pom.xml fix: pom.xml to reduce vulnerabilities Nov 9, 2019

README.md

Maven Central License Support

Okta Spring Boot Starter

Okta's Spring Boot Starter will enable your Spring Boot application to work with Okta via OAuth 2.0/OIDC. Jump to our quickstart to see how to configure various clients or follow along below to use curl.

NOTE: This library works with Spring Boot 2.1+. If you need support for Spring Boot 1.5.x, use version version 0.6.

What you need

Include the dependency

For Apache Maven:

<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-boot-starter</artifactId>
</dependency>

For Gradle:

compile 'com.okta.spring:okta-spring-boot-starter'

Supporting client side applications - OAuth Implicit flow

Are you writing a backend endpoints in order to support a client side application? If so follow along, otherwise skip to the next section.

Configure your properties

You can configure your applications properties with environment variables, system properties, or configuration files. Take a look at the Spring Boot documentation for more details.

Property Default Details
okta.oauth2.issuer N/A Authorization Server issuer URL, i.e.: https://{yourOktaDomain}/oauth2/default
okta.oauth2.clientId N/A The Client Id of your Okta OIDC application
okta.oauth2.audience api://default The audience of your Authorization Server
okta.oauth2.groupsClaim groups The claim key in the Access Token's JWT that corresponds to an array of the users groups.

Create a Controller

The above client makes a request to /hello-oauth, you simply need to create a Spring Boot application and Controller to handle the response:

@RestController
@SpringBootApplication
public class ExampleApplication {

    public static void main(String[] args) {
        SpringApplication.run(ExampleApplication.class, args);
    }

    @GetMapping("/hello-oauth")
    public String sayHello(Principal principal) {
        return "Hello, " + principal.getName();
    }
    
    @Configuration
    static class OktaOAuth2WebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {

        @Override
        protected void configure(HttpSecurity http) throws Exception {
            http
                .authorizeRequests().anyRequest().authenticated()
                .and()
                .oauth2ResourceServer().jwt();
                
            // Send a 401 message to the browser (w/o this, you'll see a blank page)
            Okta.configureResourceServer401ResponseBody(http);
        }
    }
}

Make sure to configure the WebSecurityConfigurerAdaptor with http.oauth2ResourceServer().jwt() to enable handling of access tokens.

That's it!

To test things out you can use curl:

$ curl http://localhost:8080/hello-oauth \
   --header "Authorization: Bearer ${accessToken}"

The result should look something like:

Hello, joe.coder@example.com

Okta's Spring Security integration will parse the JWT access token from the HTTP request's Authorization: Bearer header value.

Check out a minimal example that uses the Okta Signin Widget and JQuery or this blog post.

Spring WebFlux

To configure a resource server when using Spring WebFlux, you need to use a couple annotations, and define a SecurityWebFilterChain bean.

import com.okta.spring.boot.oauth.Okta;
import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.method.configuration.EnableReactiveMethodSecurity;
import org.springframework.security.config.annotation.web.reactive.EnableWebFluxSecurity;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.web.server.SecurityWebFilterChain;

@EnableWebFluxSecurity 
@EnableReactiveMethodSecurity 
public class SecurityConfiguration {

    @Bean 
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
        http
            .authorizeExchange()
                .anyExchange().authenticated()
                .and()
            .oauth2ResourceServer()
                .jwt();
                
        // Send a 401 message to the browser (w/o this, you'll see a blank page)
        Okta.configureResourceServer401ResponseBody(http);
                
        return http.build();
    }
}

If you want to support SSO and a resource server in the same application, you can do that too!

@EnableWebFluxSecurity 
@EnableReactiveMethodSecurity 
public class SecurityConfiguration {

    @Bean 
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
        http
            .authorizeExchange()
                .anyExchange().authenticated()
                .and()
            .oauth2Login()
                .and()
            .oauth2ResourceServer()
                .jwt();
        return http.build();
    }
}

Full Stack Reactive with Spring WebFlux, WebSockets, and React uses both SSO and a resource server. Its current code uses Spring Security's OIDC support. Changing it to use the Okta Spring Starter reduces the lines of code quite a bit.

Supporting server side applications - OAuth Code flow

Building a server side application and just need to redirect to a login page? This OAuth 2.0 code flow is for you.

Configure your properties

You can configure your applications properties with environment variables, system properties, or configuration files. Take a look at the Spring Boot documentation for more details.

Property Required Details
okta.oauth2.issuer true Authorization Server issuer URL, i.e.: https://{yourOktaDomain}/oauth2/default
okta.oauth2.clientId true The Client Id of your Okta OIDC application
okta.oauth2.clientSecret true The Client Secret of your Okta OIDC application

Create a simple application

Create a minimal Spring Boot application:

@RestController
@SpringBootApplication
public class ExampleApplication {

    public static void main(String[] args) {
        SpringApplication.run(ExampleApplication.class, args);
    }

    @GetMapping("/")
    public String getMessageOfTheDay(@AuthenticationPrincipal OidcUser user) {
        return user.getName() + ", this message of the day is boring";
    }
}

If you want to allow anonymous access to specific routes you can add a WebSecurityConfigurerAdapter:

@Configuration
static class WebConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                .antMatchers("/my-anon-page").permitAll()
                .anyRequest().authenticated()
            .and().oauth2Client()
            .and().oauth2Login();
    }
}

That's it!

Open up http://localhost:8080 in your favorite browser.

You'll be redirected automatically to an Okta login page. Once you successfully login, you will be redirected back to your app and you'll see the message of the day!

This module integrates with Spring Security's OAuth support, all you need is the mark your application with the standard @EnableOAuth2Client annotation.

Inject the Okta Java SDK

To integrate the Okta Java SDK into your Spring Boot application you just need to add a dependency:

<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-sdk</artifactId>
</dependency>

Then define the okta.client.token property. See creating an API token for more info.

All that is left is to inject the client (com.okta.sdk.client.Client)! Take a look at this post for more info on the best way to inject your beans.

Extra Credit

Want to build this project?

Just clone it and run:

$ git clone https://github.com/okta/okta-spring-boot.git
$ cd okta-spring-boot
$ mvn install
You can’t perform that action at this time.