mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
109 lines
4.1 KiB
Plaintext
109 lines
4.1 KiB
Plaintext
---
|
||
title: Spring Boot
|
||
description: "Integrate ZITADEL authentication into Spring Boot applications using the OAuth 2.0 PKCE flow."
|
||
sidebar_label: Spring Boot
|
||
framework_url: https://spring.io/projects/spring-boot
|
||
auth_library: "Spring Security"
|
||
auth_library_url: https://spring.io/projects/spring-security
|
||
example_repo: https://github.com/zitadel/example-auth-spring
|
||
auth_flow: pkce
|
||
status: stable
|
||
---
|
||
|
||
## Overview
|
||
|
||
[Spring Boot](https://spring.io/projects/spring-boot) is a powerful, production-ready framework for building Java applications. This example shows how to integrate **Zitadel** into a Spring Boot web application using **OpenID Connect (OIDC)** and the **Authorization Code Flow + PKCE**.
|
||
|
||
It demonstrates a common web app pattern: users start on a public landing page, authenticate with Zitadel via a login button, and are then redirected to a protected profile page that displays user information. Logout is also implemented to end both the local session and the Zitadel session.
|
||
|
||
#### Auth library
|
||
|
||
This example uses **[Spring Security](https://spring.io/projects/spring-security)**, the standard framework for authentication and access control in Spring applications. Spring Security supports OIDC natively and manages the PKCE flow for you.
|
||
|
||
---
|
||
|
||
## What this example demonstrates
|
||
|
||
This example shows a complete authentication implementation using Spring Security’s OAuth 2.0 / OIDC support:
|
||
|
||
- **Public landing page** (`/`) accessible without authentication.
|
||
- **Sign-in with Zitadel** via Spring Security’s OAuth2 login entrypoint.
|
||
- **Route protection** so authenticated access is required for protected routes (e.g. `/profile`).
|
||
- **Profile page** that renders the authenticated user’s OIDC claims.
|
||
- **Server-side session management** handled by the servlet container + Spring Security.
|
||
- **Federated logout** that clears the local session and triggers RP-initiated logout against Zitadel, returning the user to a post-logout callback route.
|
||
|
||
---
|
||
|
||
## Getting started
|
||
|
||
### Prerequisites
|
||
|
||
Before you begin, ensure you have the following:
|
||
|
||
#### System Requirements
|
||
|
||
- Java Development Kit (JDK) 17 or later
|
||
- Maven (or use the included `mvnw` wrapper)
|
||
|
||
#### Account Setup
|
||
|
||
You’ll need a Zitadel account and an application configured for a Web app using Authorization Code + PKCE.
|
||
|
||
> **Important:** Configure the following URLs in your Zitadel application settings:
|
||
>
|
||
> - **Redirect URIs:** `http://localhost:3000/auth/callback`
|
||
> - **Post Logout Redirect URIs:** `http://localhost:3000/auth/logout/callback`
|
||
>
|
||
> These URLs must exactly match what your Spring Boot application uses. For production, add your production URLs.
|
||
|
||
### Run the example
|
||
|
||
1. Clone the repository.
|
||
2. Copy `.env.example` to `.env` and fill in your Zitadel details.
|
||
|
||
```dotenv
|
||
# Port number where your Spring Boot server will listen for incoming HTTP requests.
|
||
PORT=3000
|
||
|
||
# Session timeout in seconds. Users will be automatically logged out after this
|
||
# duration of inactivity. 3600 seconds = 1 hour.
|
||
SESSION_DURATION=3600
|
||
|
||
# Your Zitadel instance domain URL. Include the full https:// URL.
|
||
ZITADEL_DOMAIN="https://your-zitadel-domain"
|
||
|
||
# Application Client ID from your Zitadel application settings.
|
||
ZITADEL_CLIENT_ID="your-client-id"
|
||
|
||
# Provide a randomly generated string here.
|
||
ZITADEL_CLIENT_SECRET="your-randomly-generated-client-secret"
|
||
```
|
||
|
||
3. Build and start the server:
|
||
|
||
```bash
|
||
# 1. Clone the repository
|
||
git clone [email protected]:zitadel/example-auth-spring.git
|
||
cd example-auth-spring
|
||
|
||
# 2. Build the project and download dependencies
|
||
mvn clean install
|
||
|
||
# 3. Start the development server
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
4. Open `http://localhost:3000` and walk through login → profile → logout.
|
||
|
||
---
|
||
|
||
## Learn more and resources
|
||
|
||
* [PKCE concept](https://oauth.net/2/pkce/)
|
||
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
|
||
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
|
||
* [Spring Boot documentation](https://spring.io/projects/spring-boot)
|
||
* [Spring Security documentation](https://spring.io/projects/spring-security)
|
||
* [Example repository](https://github.com/zitadel/example-auth-spring)
|