This quickstart demonstrates how to add Auth0 login to a Spring Boot web application. You’ll build a secure web app with login, logout, and a protected profile page using the Okta Spring Boot Starter, which auto-configures Spring Security’s OAuth2 login support.
1
Create a new project
Generate a Spring Boot project with the required dependencies.
Add the Okta Spring Boot Starter dependency to your project. This pulls in Spring Security OAuth2 login support with Auth0/Okta-specific auto-configuration.
Create a Regular Web Application in your Auth0 tenant and add the configuration to your project.You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:
CLI
Dashboard
Run the following shell command on your project’s root directory to create an Auth0 application and update your application.yml file:
Copy the Domain, Client ID, and Client Secret from the Application Settings tab.
Replace the placeholder values in application.yml.
The Callback URL must match exactly. Spring Security’s OAuth2 login uses the path /login/oauth2/code/okta by default.The Issuer must include https:// and a trailing /. Use only the domain and region. For example: https://dev-abc123.us.auth0.com/.
4
Configure authentication
Create a security configuration that enables OAuth2 login and handles Auth0 logout. Unauthenticated users are redirected to the Auth0 login page automatically.
Create the controllers and the Thymeleaf templates for the home and profile pages.
6
Run your application
Start the application using the Maven or Gradle wrapper.
Maven
Gradle
./mvnw spring-boot:run
./gradlew bootRun
Your application is now running on http://localhost:3000. Navigate to http://localhost:3000/profile to trigger the Auth0 login flow.
You should now have a fully functional Spring Boot web application with Auth0 login running on your localhost. The home page is public, and navigating to /profile redirects unauthenticated users to the Auth0 login page.
The @AuthenticationPrincipal OidcUser parameter gives you access to all claims from the ID token. Use getClaims() to retrieve the full set or individual getter methods for specific claims.
You can restrict access to pages based on Auth0 roles. First, add roles to the ID token using an Auth0 Action, then use hasAuthority() in your security configuration.
The Okta starter supports custom authority mapping through the AuthoritiesProvider interface. Register a bean to add custom GrantedAuthority objects based on user attributes or external data sources.
After selecting login, Auth0 shows an error about a callback URL mismatch.The Allowed Callback URLs in your Auth0 application must exactly match the callback URL used by Spring Security. The default is http://localhost:3000/login/oauth2/code/okta.
Under Allowed Callback URLs, add: http://localhost:3000/login/oauth2/code/okta.
Choose Save Changes.
Invalid issuer at startup
The application fails to start or login fails with an issuer mismatch.The okta.oauth2.issuer must be the full Auth0 tenant URL including https:// and a trailing /.
# ❌ WRONG - missing https:// or trailing slashokta: oauth2: issuer: "dev-abc123.us.auth0.com"# ✅ CORRECT - full URL with trailing slashokta: oauth2: issuer: "https://dev-abc123.us.auth0.com/"
OIDC discovery failure at startup
The application fails to start with a connection error when fetching /.well-known/openid-configuration.The Okta Spring Boot Starter fetches the OpenID Connect discovery document from your issuer URL at startup. Verify that the issuer URL is correct and reachable from your network. If behind a corporate firewall, configure the proxy:
The application starts but login fails because configuration properties are not being read.Ensure your application.yml uses the correct YAML indentation under the okta.oauth2 namespace:
After selecting logout, the user is immediately logged back in without seeing the Auth0 login page.Ensure your SecurityConfig includes the custom LogoutHandler that redirects to the Auth0 /v2/logout endpoint. Also verify that the Allowed Logout URLs in your Auth0 Application Settings includes http://localhost:3000/.
A complete sample application demonstrating login, profile display, and logout with Auth0 is available in the Auth0 samples repository.
MVC Login Sample
Includes login, logout, and profile page with Auth0 OAuth2 integration
Clone and run:
git clone https://github.com/auth0-samples/auth0-spring-boot-login-samples.gitcd auth0-spring-boot-login-samples/mvc-login# Update src/main/resources/application.yml with your Auth0 configuration# Then run:./gradlew bootRun
Open http://localhost:3000 in your browser and select the Login link to test the Auth0 login flow.