Okta's Spring Boot Starter will enable your Spring Boot application to work with Okta via OAuth 2.0. Jump to our quickstart to see how to configure various clients or follow along below to use curl.
- An Okta account (sign up for a forever-free developer account)
- An OIDC application (typically a 'SPA' application)
- An access token
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'
Are you writing a backend endpoints in order to support a client side application? If so follow along, otherwise skip to the next section.
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}.com/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.scopeClaim | scp | The scope claim key in the Access Token's JWT |
okta.oauth2.rolesClaim | groups | The claim key in the Access Token's JWT that corresponds to an array of the users groups. |
The above client makes a request to /hello-oauth
, you simply need to create a Spring Boot application and Controller
to handle the response:
@EnableResourceServer
@SpringBootApplication
@RestController
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();
}
}
Make sure to mark the application with Spring Security's @EnableResourceServer
annotation, to enable handing of access tokens.
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, [email protected]
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.
Building a server side application and just need to redirect to a login page? This OAuth 2.0 code flow is for you.
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}.com/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 minimal Spring Boot application:
@EnableOAuth2Sso
@SpringBootApplication
@RestController
public class ExampleApplication {
public static void main(String[] args) {
SpringApplication.run(ExampleApplication.class, args);
}
@GetMapping("/")
public String getMessageOfTheDay(Principal principal) {
return principal.getName() + ", this message of the day is boring";
}
}
Open up the this link in your browser: http://localhost:8080/
You will be redirected automatically to an Okta login page. Once you successfully login, you will be redirected back to 'http://localhost:8080/' and you will 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.
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
)!
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
- Add support to inject the Okta Java SDK (if on classpath)
- Fixed issue stopping configuration from being loaded from Spring Cloud Config
- Add support for authorization code flow
- Standardized Okta OAuth 2.0 properties as
okta.oauth2.*
- Added integration test suite