Interactive

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 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 and read about implementing API authentication and authorization 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 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 and the Dependency Management Plugin to resolve dependency versions:

// 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:

// pom.xml
<
parent
>
<
groupId
>
org.springframework.boot
</
groupId
>
<
artifactId
>
spring-boot-starter-parent
</
artifactId
>
<
version
>
3.1.5
</
version
>
<
relativePath
/>
</
parent
>
<
dependencies
>
<
dependency
>
<
groupId
>
org.springframework.boot
</
groupId
>
<
artifactId
>
spring-boot-starter-web
</
artifactId
>
</
dependency
>
<
dependency
>
<
groupId
>
com.okta.spring
</
groupId
>
<
artifactId
>
okta-spring-boot-starter
</
artifactId
>
<
version
>
3.0.5
</
version
>
</
dependency
>
</
dependencies
>

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:messagesscope 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 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:

./gradlew bootRun

Windows:

gradlew.bat bootRun

If you are configuring your own application using Maven and the Spring Boot Maven Plugin, you can execute the spring-boot:run goal.

Linux or macOS:

mvn spring-boot:run

Windows:

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 article.

Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

• Auth0 Dashboard - Learn how to configure and manage your Auth0 tenant and applications
• Okta Spring Boot Starter SDK - Explore the SDK used in this tutorial more fully
• Auth0 Marketplace - Discover integrations you can enable to extend Auth0’s functionality

Did it work?

Any suggestion or typo?

Define permissions

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 section.

This example uses the read:messages scope.

Configure the sample project

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.

Install dependencies

If you are using Gradle, you can add the required dependencies using the Spring Boot Gradle Plugin and the Dependency Management Plugin to resolve dependency versions:

// 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:

// pom.xml
<
parent
>
<
groupId
>
org.springframework.boot
</
groupId
>
<
artifactId
>
spring-boot-starter-parent
</
artifactId
>
<
version
>
3.1.5
</
version
>
<
relativePath
/>
</
parent
>
<
dependencies
>
<
dependency
>
<
groupId
>
org.springframework.boot
</
groupId
>
<
artifactId
>
spring-boot-starter-web
</
artifactId
>
</
dependency
>
<
dependency
>
<
groupId
>
com.okta.spring
</
groupId
>
<
artifactId
>
okta-spring-boot-starter
</
artifactId
>
<
version
>
3.0.5
</
version
>
</
dependency
>
</
dependencies
>

Configure the resource server

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:messagesscope 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.

Create the Domain Object

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 the API controller

Create a new class named APIController to handle requests to the endpoints. The APIController has three routes as defined in the Protect API Endpoints section. For this example, allow all origins through @CrossOrigin annotation. Real applications should configure CORS for their use case.

Run the application

To build and run the sample project, execute the bootRun Gradle task.

Linux or macOS:

./gradlew bootRun

Windows:

gradlew.bat bootRun

If you are configuring your own application using Maven and the Spring Boot Maven Plugin, you can execute the spring-boot:run goal.

Linux or macOS:

mvn spring-boot:run

Windows:

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 article.