Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
;
};
export const sections = [{
id: "define-permissions",
title: "Define permissions"
}, {
id: "configure-the-sample-project",
title: "Configure the sample project"
}, {
id: "install-dependencies",
title: "Install dependencies"
}, {
id: "configure-the-resource-server",
title: "Configure the resource server"
}, {
id: "create-the-domain-object",
title: "Create the Domain Object"
}, {
id: "create-the-api-controller",
title: "Create the API controller"
}, {
id: "run-the-application",
title: "Run the application"
}];
Auth0 allows you to quickly add authorization to your application. This guide demonstrates how to integrate Auth0
with any new or existing Spring Boot application.
If you have not created an API in your Auth0 dashboard yet, use the interactive selector to create a new Auth0 API
or select an existing API that represents the project you want to integrate with.
Review [our getting started
guide](https://auth0.com/docs/get-started/auth0-overview/set-up-apis) to set up your first API through the Auth0 dashboard.
Each Auth0 API uses the API Identifier, which your application needs to validate the access token.
**New to Auth0?** Learn [how Auth0 works](https://auth0.com/docs/overview)
and read about [implementing API authentication
and authorization](https://auth0.com/docs/api-auth) using the OAuth 2.0 framework.
Permissions let you define how resources can be accessed on behalf of the user with a given access token. For
example, you might choose to grant read access to the `messages` resource if users have the manager
access level, and a write access to that resource if they have the administrator access level.
You can define allowed permissions in the **Permissions** view of the Auth0 Dashboard's [APIs](https://manage.auth0.com/dashboard/us/dev-1-2s2aq0/apis) section.
This example uses the `read:messages` scope.
The sample project uses a `/src/main/resources/application.yml` file, which configures it to use the
correct Auth0 **domain** and **API Identifier** for your API. If you download the code from this page it
will be automatically configured. If you clone the example from GitHub, you will need to fill it in yourself.
If you are using Gradle, you can add the required dependencies using the [Spring Boot Gradle Plugin](https://docs.spring.io/spring-boot/docs/current/gradle-plugin/reference/html/) and the [Dependency Management Plugin](https://docs.spring.io/dependency-management-plugin/docs/current/reference/html/) to resolve dependency versions:
```gradle lines
// build.gradle
plugins {
id 'java'
id 'org.springframework.boot'
version '3.1.5'
id 'io.spring.dependency-management'
version '1.1.3'
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'com.okta.spring:okta-spring-boot-starter:3.0.5'
}
```
If you are using Maven, add the Spring dependencies to your `pom.xml` file:
```xml lines
// pom.xml
org.springframework.bootspring-boot-starter-parent3.1.5org.springframework.bootspring-boot-starter-webcom.okta.springokta-spring-boot-starter3.0.5
```
To configure the application as a Resource Server and validate the JWTs, create a class that will provide an
instance of `SecurityFilterChain`, and add the `@Configuration` annotation.
### Protect API endpoints
The routes shown below are available for the following requests:
* `GET /api/public`: available for non-authenticated requests
* `GET /api/private`: available for authenticated requests containing an access token with no
additional scopes
* `GET /api/private-scoped`: available for authenticated requests containing an access token with
the `read:messages`scope granted
The example below shows how to secure API methods using the `HttpSecurity` object provided in the
`filterChain()` method of the `SecurityConfig` class. Route matchers restrict access based
on the level of authorization required.
By default, Spring Security creates a `GrantedAuthority` for each scope in the
`scope` claim of the JWT. This scope enables using the
`hasAuthority("SCOPE_read:messages")` method to restrict access to a valid JWT that contains
the `read:messages` scope.
To make your endpoint return a JSON, you can use a Java record. The member variables of this object is serialized
into the key value for your JSON. Create a new record named `Message` as an example domain object to
return during the API calls.
Create a new class named `APIController` to handle requests to the endpoints. The
`APIController` has three routes as defined in the [Protect API Endpoints](https://auth0.com/docs/quickstart/backend/java-spring-security5/interactive#configure-the-resource-server) section. For this example, allow all origins through
`@CrossOrigin` annotation. Real applications should configure `CORS` for their use case.
To build and run the sample project, execute the `bootRun` Gradle task.
Linux or macOS:
```sh lines
./gradlew bootRun
```
Windows:
```sh lines
gradlew.bat bootRun
```
If you are configuring your own application using Maven and the [Spring Boot Maven Plugin](https://docs.spring.io/spring-boot/docs/current/reference/html/build-tool-plugins-maven-plugin.html), you can execute the
`spring-boot:run` goal.
Linux or macOS:
```sh lines
mvn spring-boot:run
```
Windows:
```sh lines
mvn.cmd spring-boot:run
```
##### Checkpoint
The sample application will be available at `http://localhost:3010/`. Read about how to test
and use your API in the [Using Your API](https://auth0.com/docs/quickstart/backend/java-spring-security5/02-using) article.
```yml application.yml lines highlight={}
okta:
oauth2:
# Replace with the domain of your Auth0 tenant.
issuer: https://dev-gja8kxz4ndtex3rq.us.auth0.com/
# Replace with the API Identifier for your Auth0 API.
audience: {yourApiIdentifier}
```
```java SecurityConfig.java lines highlight={}
package com.auth0.example.security;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
/**
* Configures our application with Spring Security to restrict access to our API endpoints.
*/
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
/*
This is where we configure the security required for our endpoints and setup our app to serve as
an OAuth2 Resource Server, using JWT validation.
*/
return http
.authorizeHttpRequests((authorize) -> authorize
.requestMatchers("/api/public").permitAll()
.requestMatchers("/api/private").authenticated()
.requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
)
.cors(withDefaults())
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(withDefaults())
)
.build();
}
}
```
```java APIController.java lines highlight={}
```
```yml application.yml lines highlight={}
okta:
oauth2:
# Replace with the domain of your Auth0 tenant.
issuer: https://dev-gja8kxz4ndtex3rq.us.auth0.com/
# Replace with the API Identifier for your Auth0 API.
audience: {yourApiIdentifier}
```
```java SecurityConfig.java lines highlight={}
package com.auth0.example.security;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
/**
* Configures our application with Spring Security to restrict access to our API endpoints.
*/
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
/*
This is where we configure the security required for our endpoints and setup our app to serve as
an OAuth2 Resource Server, using JWT validation.
*/
return http
.authorizeHttpRequests((authorize) -> authorize
.requestMatchers("/api/public").permitAll()
.requestMatchers("/api/private").authenticated()
.requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
)
.cors(withDefaults())
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(withDefaults())
)
.build();
}
}
```
```java APIController.java lines highlight={}
```
```java SecurityConfig.java lines highlight={}
package com.auth0.example.security;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
/**
* Configures our application with Spring Security to restrict access to our API endpoints.
*/
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
/*
This is where we configure the security required for our endpoints and setup our app to serve as
an OAuth2 Resource Server, using JWT validation.
*/
return http
.authorizeHttpRequests((authorize) -> authorize
.requestMatchers("/api/public").permitAll()
.requestMatchers("/api/private").authenticated()
.requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
)
.cors(withDefaults())
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(withDefaults())
)
.build();
}
}
```
```yml application.yml lines highlight={}
okta:
oauth2:
# Replace with the domain of your Auth0 tenant.
issuer: https://dev-gja8kxz4ndtex3rq.us.auth0.com/
# Replace with the API Identifier for your Auth0 API.
audience: {yourApiIdentifier}
```
```java APIController.java lines highlight={}
```
```yml application.yml lines highlight={}
okta:
oauth2:
# Replace with the domain of your Auth0 tenant.
issuer: https://dev-gja8kxz4ndtex3rq.us.auth0.com/
# Replace with the API Identifier for your Auth0 API.
audience: {yourApiIdentifier}
```
```java SecurityConfig.java lines highlight={}
package com.auth0.example.security;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
/**
* Configures our application with Spring Security to restrict access to our API endpoints.
*/
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
/*
This is where we configure the security required for our endpoints and setup our app to serve as
an OAuth2 Resource Server, using JWT validation.
*/
return http
.authorizeHttpRequests((authorize) -> authorize
.requestMatchers("/api/public").permitAll()
.requestMatchers("/api/private").authenticated()
.requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
)
.cors(withDefaults())
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(withDefaults())
)
.build();
}
}
```
```java APIController.java lines highlight={}
```
```java APIController.java lines highlight={}
```
```java SecurityConfig.java lines highlight={}
package com.auth0.example.security;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
/**
* Configures our application with Spring Security to restrict access to our API endpoints.
*/
@Configuration
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
/*
This is where we configure the security required for our endpoints and setup our app to serve as
an OAuth2 Resource Server, using JWT validation.
*/
return http
.authorizeHttpRequests((authorize) -> authorize
.requestMatchers("/api/public").permitAll()
.requestMatchers("/api/private").authenticated()
.requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
)
.cors(withDefaults())
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(withDefaults())
)
.build();
}
}
```
```yml application.yml lines highlight={}
okta:
oauth2:
# Replace with the domain of your Auth0 tenant.
issuer: https://dev-gja8kxz4ndtex3rq.us.auth0.com/
# Replace with the API Identifier for your Auth0 API.
audience: {yourApiIdentifier}
```
Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
